# ispgroupucl/deepsportlab architecture

> Architecture diagram of the GitHub repository ispgroupucl/deepsportlab, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ispgroupucl/deepsportlab
- Repository: https://github.com/ispgroupucl/deepsportlab

## Overview

##### Project type and purpose
- DeepSportLab is a unified, full-stack machine-learning framework focusing on three tasks in team sports scenes: ball detection, player instance segmentation, and pose estimation.
- It provides both training and inference pipelines (Python CLI, notebooks) and exposes C++ examples for embedding/integration.

##### File structure
- Top-level:
- openpifpaf/            ← Core Python package
- cpp/                   ← C++ examples using the library
- docs/, guide/         ← Documentation and tutorials
- tests/                 ← Unit and integration tests
- predict.py, train.py  ← CLI entry points for inference and training
- export_onnx.py        ← Model export for production
- openpifpaf/ sub-packages:
- datasets/             ← Data loading and collate functions
- transforms/           ← Preprocessing pipelines
- encoder/ decoder/     ← Task-specific encoding (part intensity fields) and decoding (spatial embeddings)
- network/              ← Model definition, loss computation, training loop
- visualizer/ show/     ← Output visualization and CLI helpers
- Configuration & tooling:
- setup.py, setup.cfg   ← Packaging
- requirements.txt      ← Python dependencies
- CI/CD workflows (.github/, .travis.yml)
- notebooks (.ipynb)    ← EDA, guide examples

##### README for additional insights
- Describes the unified single-model approach combining part intensity fields and spatial embeddings.
- Mentions evaluation on the DeepSport basketball dataset, export options, and licensing.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Sources
    subgraph "Data Sources"
        DS1(("COCO Dataset")):::data
        DS2(("DeepSport Dataset")):::data
        DS3(("User Images")):::data
        DS4["Dataset Factory"]:::data
        DS5["Constants"]:::data
    end
    click DS1 "https://github.com/ispgroupucl/deepsportlab/blob/main/openpifpaf/datasets/coco.py"
    click DS2 "https://github.com/ispgroupucl/deepsportlab/blob/main/openpifpaf/datasets/deepsport.py"
    click DS4 "https://github.com/ispgroupucl/deepsportlab/blob/main/openpifpaf/datasets/factory.py"
    click DS5 "https://github.com/ispgroupucl/deepsportlab/blob/main/openpifpaf/datasets/constants.py"

    %% Data Pipeline
    subgraph "Data Pipeline"
        T["Transforms"]:::data
        C["Collate"]:::data
    end
    click T "https://github.com/ispgroupucl/deepsportlab/tree/main/openpifpaf/transforms/"
    click C "https://github.com/ispgroupucl/deepsportlab/blob/main/openpifpaf/datasets/collate.py"

    %% Model Core
    subgraph "Model Core"
        subgraph "Encoder"
            EFac["Encoder Factory"]:::model
            ECIF["CIF"]:::model
            ECIFB["CIF Ball"]:::model
            ECAF["CAF"]:::model
            ESEG["Segmentation"]:::model
            ER1["AnnRescaler"]:::model
            ER2["AnnRescaler Ball"]:::model
        end
        subgraph "Backbone & Heads"
            NF["Network Factory"]:::model
            NB["Base Networks"]:::model
            NN["Networks"]:::model
            NH["Heads"]:::model
            NAS["ASPP"]:::model
        end
        subgraph "Decoder"
            DFac["Decoder Factory"]:::model
            D1["CIF Seeds"]:::model
            D2["CAF Scored"]:::model
            DUtil["Utils"]:::model
            DGen["Generators"]:::model
        end
    end
    click EFac "https://github.com/ispgroupucl/deepsportlab/blob/main/openpifpaf/encoder/factory.py"
    click ECIF "https://github.com/ispgroupucl/deepsportlab/blob/main/openpifpaf/encoder/cif.py"
    click ECIFB "https://github.com/ispgroupucl/deepsportlab/blob/main/openpifpaf/encoder/cif_ball.py"
    click ECAF "https://github.com/ispgroupucl/deepsportlab/blob/main/openpifpaf/encoder/caf.py"
    click ESEG "https://github.com/ispgroupucl/deepsportlab/blob/main/openpifpaf/encoder/seg.py"
    click ER1 "https://github.com/ispgroupucl/deepsportlab/blob/main/openpifpaf/encoder/annrescaler.py"
    click ER2 "https://github.com/ispgroupucl/deepsportlab/blob/main/openpifpaf/encoder/annrescaler_ball.py"
    click NF "https://github.com/ispgroupucl/deepsportlab/blob/main/openpifpaf/network/factory.py"
    click NB "https://github.com/ispgroupucl/deepsportlab/blob/main/openpifpaf/network/basenetworks.py"
    click NN "https://github.com/ispgroupucl/deepsportlab/blob/main/openpifpaf/network/nets.py"
    click NH "https://github.com/ispgroupucl/deepsportlab/blob/main/openpifpaf/network/heads.py"
    click NAS "https://github.com/ispgroupucl/deepsportlab/blob/main/openpifpaf/network/aspp.py"
    click DFac "https://github.com/ispgroupucl/deepsportlab/blob/main/openpifpaf/decoder/factory.py"
    click D1 "https://github.com/ispgroupucl/deepsportlab/blob/main/openpifpaf/decoder/cif_seeds.py"
    click D2 "https://github.com/ispgroupucl/deepsportlab/blob/main/openpifpaf/decoder/caf_scored.py"
    click DUtil "https://github.com/ispgroupucl/deepsportlab/blob/main/openpifpaf/decoder/utils.py"
    click DGen "https://github.com/ispgroupucl/deepsportlab/tree/main/openpifpaf/decoder/generator/"

    %% Training & Evaluation
    subgraph "Training & Evaluation"
        Loss["Losses"]:::model
        Trainer["Trainer"]:::model
        TI["Instance Scorer"]:::model
        TrainCLI["train.py"]:::cli
        TrainMod["openpifpaf/train.py"]:::cli
        Eval1["eval_coco.py"]:::cli
        Eval2["eval_oks_pq.py"]:::cli
        Eval3["oks_abolfazl.py"]:::cli
    end
    click Loss "https://github.com/ispgroupucl/deepsportlab/blob/main/openpifpaf/network/losses.py"
    click Trainer "https://github.com/ispgroupucl/deepsportlab/blob/main/openpifpaf/network/trainer.py"
    click TI "https://github.com/ispgroupucl/deepsportlab/blob/main/openpifpaf/train_instance_scorer.py"
    click TrainCLI "https://github.com/ispgroupucl/deepsportlab/blob/main/train.py"
    click TrainMod "https://github.com/ispgroupucl/deepsportlab/blob/main/openpifpaf/train.py"
    click Eval1 "https://github.com/ispgroupucl/deepsportlab/blob/main/openpifpaf/eval_coco.py"
    click Eval2 "https://github.com/ispgroupucl/deepsportlab/blob/main/openpifpaf/eval_oks_pq.py"
    click Eval3 "https://github.com/ispgroupucl/deepsportlab/blob/main/openpifpaf/oks_abolfazl.py"

    %% Inference & Export
    subgraph "Inference & Export"
        PCLI["predict.py"]:::cli
        PPython["openpifpaf/predict.py"]:::cli
        PPan["openpifpaf/predict_pan.py"]:::cli
        Export["export_onnx.py"]:::cli
        ONNX[("ONNX Model")]:::tool
    end
    click PCLI "https://github.com/ispgroupucl/deepsportlab/blob/main/predict.py"
    click PPython "https://github.com/ispgroupucl/deepsportlab/blob/main/openpifpaf/predict.py"
    click PPan "https://github.com/ispgroupucl/deepsportlab/blob/main/openpifpaf/predict_pan.py"
    click Export "https://github.com/ispgroupucl/deepsportlab/blob/main/openpifpaf/export_onnx.py"

    %% Visualization & CLI
    subgraph "Visualization & CLI"
        Viz["Visualizer"]:::cli
        ShowCLI["Show CLI"]:::cli
    end
    click Viz "https://github.com/ispgroupucl/deepsportlab/tree/main/openpifpaf/visualizer/"
    click ShowCLI "https://github.com/ispgroupucl/deepsportlab/blob/main/openpifpaf/show/cli.py"

    %% Integration & Docs
    subgraph "Integration & Documentation"
        CPP["C++ Examples"]:::demo
        NBKs["Notebooks Guide"]:::demo
        DocsNB["Docs Notebooks"]:::demo
    end
    click CPP "https://github.com/ispgroupucl/deepsportlab/tree/main/cpp/examples/cifcafdecoder/"
    click NBKs "https://github.com/ispgroupucl/deepsportlab/tree/main/guide/"
    click DocsNB "https://github.com/ispgroupucl/deepsportlab/blob/main/docs/predict.ipynb"

    %% Packaging & Tooling
    subgraph "Packaging & Tooling"
        SP["setup.py"]:::tool
        SC["setup.cfg"]:::tool
        Req["requirements.txt"]:::tool
        GH[".github/workflows"]:::tool
        Travis[".travis.yml"]:::tool
    end

    %% Connections
    DS1 --> T
    DS2 --> T
    DS3 --> T
    DS4 --> T
    DS5 --> T
    T --> C
    C --> EFac
    EFac --> ECIF & ECIFB & ECAF & ESEG & ER1 & ER2
    ECIF --> NF
    ECIFB --> NF
    ECAF --> NF
    ESEG --> NF
    ER1 --> NF
    ER2 --> NF
    NF --> NB --> NN --> NH --> NAS
    NAS --> DFac
    DFac --> D1 --> DGen
    DFac --> D2 --> DGen
    DFac --> DUtil --> DGen
    DGen --> Loss --> Trainer --> TrainCLI
    Trainer --> TrainMod
    TrainCLI --> Eval1 & Eval2 & Eval3
    DGen --> PCLI
    DGen --> PPython
    PPython --> ShowCLI
    PCLI --> Viz
    Export --> ONNX
    ONNX --> CPP
    NBKs --> DS1 & EFac & NF & DGen & TrainCLI & PCLI
    DocsNB --> PPython

    %% Styles
    classDef data fill:#BBE0FE,stroke:#1E3A8A,color:#1E3A8A
    classDef model fill:#C2FABC,stroke:#065F46,color:#065F46
    classDef cli fill:#FFD8A8,stroke:#C2410C,color:#C2410C
    classDef demo fill:#E0BBE4,stroke:#6B21A8,color:#6B21A8
    classDef tool fill:#F0F0F0,stroke:#374151,color:#374151
```
