# joao-m-silva/padel_analytics architecture

> Architecture diagram of the GitHub repository joao-m-silva/padel_analytics, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/joao-m-silva/padel_analytics
- Repository: https://github.com/joao-m-silva/padel_analytics

## Overview

##### Project type and purpose
- This is an open-source computer-vision analytics tool for padel match recordings. It ingests a raw video, allows manual court keypoint selection (homography), runs several trained vision models (player detection, pose estimation, classifier, ball tracker), computes statistics, and renders visualizations (heatmaps, velocity plots, 2D projections).

##### File structure
- Top-level orchestration:
- main.py / app.py – entry points.
- config.py – location of model weights, batch sizes, I/O paths.
- Core modules:
- trackers/ – individual tracker implementations (ball, players, keypoints) and a runner to chain them.
- analytics/ – code for physical projections, velocity/position statistics, aggregated data analytics.
- Helpers:
- utils/ – video I/O, unit conversions, homography helpers.
- constants/ – court dimensions, player-height data.
- UI:
- ui.py – interactive keypoint selector for court calibration.
- Examples and docs:
- examples/videos/ – sample inputs & demos.
- README, CONTRIBUTING, .github/ – contribution & issue templates.

##### README for additional insights
- States a fixed-camera assumption requiring 12 court keypoints, uses PyTorch models (pose/net/classifier), and produces a sequence: keypoint selection → tracking → analytics → visualization.
- Describes VRAM requirements, inference command (`python main.py`), and weight-download process.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Dependencies
    subgraph "External Dependencies"
        Torch["PyTorch"]:::ext
        OpenCV["OpenCV"]:::ext
        NumPy["NumPy"]:::ext
        Matplotlib["Matplotlib"]:::ext
        Checkpoints["Model Checkpoints"]:::ext
    end

    %% Entry Points
    subgraph "Entry Points"
        MainPy["main.py"]:::io
        AppPy["app.py"]:::io
    end

    %% Input & UI
    subgraph "Input & UI" 
        Video["Input Video Source"]:::io
        UI["UI Module (Keypoint Selection)"]:::io
        MainPy --> Video
        MainPy --> UI
        Video -->|"video frames"| UI
    end

    %% Configuration
    subgraph "Configuration"
        Config["Configuration Loader"]:::processing
        Constants1["Court Dimensions"]:::processing
        Constants2["Player Heights"]:::processing
        UI -->|"calibration data"| Config
        Constants1 --> Config
        Constants2 --> Config
    end

    %% Tracker Pipeline
    subgraph "Tracker Pipeline"
        Runner["Pipeline Runner"]:::processing
        Base["Tracker Base Interface"]:::processing
        Players["Player Detector & Tracker"]:::processing
        Pose["Pose Estimator & Classifier"]:::processing
        Keypoint["Keypoint Tracker"]:::processing
        Ball["Ball Tracker"]:::processing
        Velocity["Velocity Tracker"]:::processing

        MainPy --> Runner
        Config --> Runner
        Runner --> Base
        Base --> Players
        Base --> Pose
        Base --> Keypoint
        Base --> Ball
        Base --> Velocity
    end

    %% Analytics Engine
    subgraph "Analytics Engine"
        Projected["Projected Court Computations"]:::processing
        DataStats["Data/Velocity Statistics"]:::processing

        Runner --> Projected
        Runner --> DataStats
        Projected --> DataStats
    end

    %% Visualization Module
    subgraph "Visualization Module"
        CourtOverlay["Court Overlay & Heatmaps"]:::processing
        PlayerGraphs["Player-Centric Graphs"]:::processing

        DataStats --> CourtOverlay
        DataStats --> PlayerGraphs
    end

    %% Output Storage/Display
    subgraph "Output Storage/Display"
        Output["PNG/Video Overlays & CSV/JSON"]:::io
        Examples["Example Videos & Demos"]:::io

        CourtOverlay --> Output
        PlayerGraphs --> Output
        AppPy --> Output
        Examples --> Output
    end

    %% Connections to External Dependencies
    Torch --> Runner
    OpenCV --> Runner
    NumPy --> DataStats
    Matplotlib --> CourtOverlay
    Checkpoints --> Config

    %% Click Events
    click Video "https://github.com/joao-m-silva/padel_analytics/blob/main/utils/video.py"
    click UI "https://github.com/joao-m-silva/padel_analytics/blob/main/ui.py"
    click Config "https://github.com/joao-m-silva/padel_analytics/blob/main/config.py"
    click Constants1 "https://github.com/joao-m-silva/padel_analytics/blob/main/constants/court_dimensions.py"
    click Constants2 "https://github.com/joao-m-silva/padel_analytics/blob/main/constants/player_heights.py"
    click Runner "https://github.com/joao-m-silva/padel_analytics/blob/main/trackers/runner.py"
    click Base "https://github.com/joao-m-silva/padel_analytics/blob/main/trackers/tracker.py"
    click Players "https://github.com/joao-m-silva/padel_analytics/blob/main/trackers/players_tracker/players_tracker.py"
    click Pose "https://github.com/joao-m-silva/padel_analytics/blob/main/trackers/players_keypoints_tracker/players_keypoints_tracker.py"
    click Keypoint "https://github.com/joao-m-silva/padel_analytics/blob/main/trackers/keypoints_tracker/keypoints_tracker.py"
    click Ball "https://github.com/joao-m-silva/padel_analytics/blob/main/trackers/ball_tracker/ball_tracker.py"
    click Velocity "https://github.com/joao-m-silva/padel_analytics/blob/main/trackers/velocity_in_time.py"
    click Projected "https://github.com/joao-m-silva/padel_analytics/blob/main/analytics/projected_court.py"
    click DataStats "https://github.com/joao-m-silva/padel_analytics/blob/main/analytics/data_analytics.py"
    click CourtOverlay "https://github.com/joao-m-silva/padel_analytics/blob/main/visualizations/padel_court.py"
    click PlayerGraphs "https://github.com/joao-m-silva/padel_analytics/blob/main/visualizations/player_centric_graphs.py"
    click Examples "https://github.com/joao-m-silva/padel_analytics/tree/main/examples/videos/"
    click MainPy "https://github.com/joao-m-silva/padel_analytics/blob/main/main.py"
    click AppPy "https://github.com/joao-m-silva/padel_analytics/blob/main/app.py"

    %% Styles
    classDef processing fill:#cfe2f3,stroke:#0366d6,color:#0366d6;
    classDef io fill:#d1e7dd,stroke:#0f5132,color:#0f5132;
    classDef ext fill:#ffe5d9,stroke:#d00000,color:#d00000;
```
