# jlouros/padel_analytics architecture

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

- Interactive diagram: https://gitdiagram.com/jlouros/padel_analytics
- Repository: https://github.com/jlouros/padel_analytics

## Overview

##### Main components
- Entry Point & Configuration:
- The project is started via main.py (and there’s also an app.py, possibly used for different modes or serving a UI). The config.py file centralizes configuration, including model weights and inference parameters.
- Input & UI:
- A dedicated UI component (ui.py) handles tasks like selecting court keypoints when the application is started.
- The examples folder gives an idea of how demonstrations (e.g., keypoints selection video) are used.
- Tracking Modules:
- The trackers directory is subdivided into specific trackers:
- ball_tracker: Handles ball tracking (ball_tracker.py, dataset.py, iterative routines, and model in ball_tracker/models.py).
- keypoints_tracker: Processes keypoints from the game.
- players_keypoints_tracker and players_tracker: Handle tracking and possibly player pose estimation.
- An overarching runner/driver (trackers/runner.py and trackers/tracker.py) orchestrates execution of these modules.
- Analytics & Data Processing:
- The analytics folder contains modules like data_analytics.py and projected_court.py for processing results from the trackers and calculating metrics (positions, velocities, etc.).
- Constants & Utilities:
- The constants directory holds reference data such as court dimensions and player heights, which are crucial for proper scaling and conversion.
- The utils package enforces operations on conversions (e.g., unit and coordinate conversions, video handling, etc.).
- Visualization:
- The visualizations folder renders outputs. For example, visualizations/padel_court.py probably draws the court layout, while player_centric_graphs.py creates performance graphs.

##### Logical data flow and component relationships
- main.py (or app.py) uses the configuration from config.py to initialize the system.
- The video and selected keypoints are fed into the trackers (ball_tracker, keypoints_tracker, etc.) that process different aspects of the game.
- The tracking outputs (ball positions, player positions/poses, etc.) are passed to the analytics module where calculations for velocities, projections, heatmaps, and error rates are computed.
- Finally, the visualization module takes the computed analytics and overlays graphics (like 2D projections, heatmaps, and graphs) onto the video or generates separate plots.
- Throughout this pipeline, utilities (conversions, video processing, etc.) assist with data formatting and coordinate transformations.
- External libraries (like PyTorch for the model inference) and dependencies (OpenCV for video processing) are implicitly used in these layers.

##### Highlighting architectural patterns and design principles
- This project uses a pipeline-based design where data flows from video input to tracking to analytics and finally visualization.
- There’s a separation of concerns: each module/package has a clear responsibility (e.g., tracking, analytics, visualization).
- The use of constant directories and configuration files indicates that the system is configurable and decoupled from fixed parameters.
- The modular design (with separate trackers for ball, keypoints, players) suggests potential for extension and maintainability.

- Trackers as modular components—a block for ball tracking, another for keypoints tracking, and additional blocks for player tracking.
- Tracker outputs into a unified analytics block which processes positions, velocities, and derived statistics.
- External dependencies (like PyTorch) in a smaller “external services” or “libraries” section.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry & Configuration
    subgraph "Entry & Configuration"
        M["main.py"]:::entry
        A["app.py"]:::entry
        C["config.py"]:::config
    end

    %% Input & UI
    subgraph "Input & UI"
        U["ui.py"]:::ui
        EX["Demo Video"]:::demo
    end

    %% Video Input Node (aggregates video frames and keypoints)
    VI["Video Input"]:::input

    %% Tracking Modules
    subgraph "Tracking Modules"
        subgraph "Ball Tracker"
            BT["ball_tracker.py"]:::tracker
            BD["dataset.py"]:::tracker
            BI["iterable.py"]:::tracker
            BM["models.py"]:::tracker
            BP["predict.py"]:::tracker
        end
        subgraph "Keypoints Tracker"
            KP["keypoints_tracker.py"]:::tracker
            KI["iterable.py"]:::tracker
        end
        P_KP["players_keypoints_tracker.py"]:::tracker
        PT["players_tracker.py"]:::tracker
        subgraph "Orchestration"
            TR["runner.py"]:::orchestrator
            TC["tracker.py"]:::orchestrator
            TV["velocity_in_time.py"]:::orchestrator
        end
    end

    %% Analytics & Data Processing
    subgraph "Analytics & Data Processing"
        DA["data_analytics.py"]:::analytics
        PC["projected_court.py"]:::analytics
    end

    %% Visualization
    subgraph "Visualization"
        VC["padel_court.py"]:::visualization
        PG["player_centric_graphs.py"]:::visualization
    end

    %% Constants & Utilities
    subgraph "Constants & Utilities"
        subgraph "Constants"
            CD["court_dimensions.py"]:::utility
            PH["player_heights.py"]:::utility
        end
        subgraph "Utilities"
            CONV["conversions.py"]:::utility
            CONV2["converters.py"]:::utility
            VID["video.py"]:::utility
        end
    end

    %% External Libraries
    subgraph "External Libraries"
        PTorch["PyTorch"]:::external
        OCV["OpenCV"]:::external
    end

    %% Connections
    M -->|"init_config"| C
    A -->|"init_config"| C
    C -->|"load_settings"| U

    U -->|"select_keypoints"| VI
    EX -->|"video_frames"| VI

    VI -->|"input_data"| TR

    TR -->|"orchestrates"| BT
    TR -->|"orchestrates"| KP
    TR -->|"orchestrates"| P_KP
    TR -->|"orchestrates"| PT
    TR -->|"coordinates"| TC
    TR -->|"calculates_velocity"| TV

    TR -->|"tracking_data"| DA

    DA -->|"analytics_metrics"| VC
    DA -->|"analytics_metrics"| PG
    PC -->|"court_projection"| VC
    PC -->|"court_projection"| PG

    CD ---|"court_dimensions"| DA
    PH ---|"player_heights"| DA

    CONV ---|"convert_coordinates"| VI
    CONV2 ---|"convert_formats"| VI
    VID ---|"process_video"| VI

    PTorch -.->|"model_inference"| BT
    PTorch -.->|"model_inference"| KP
    OCV -.->|"video_processing"| VI

    %% Styles
    classDef entry fill:#FFCC00,stroke:#333,stroke-width:2px;
    classDef config fill:#FFD54F,stroke:#333,stroke-width:2px;
    classDef ui fill:#B3E5FC,stroke:#333,stroke-width:2px;
    classDef demo fill:#81D4FA,stroke:#333,stroke-width:2px;
    classDef input fill:#C5CAE9,stroke:#333,stroke-width:2px;
    classDef tracker fill:#E1BEE7,stroke:#333,stroke-width:2px;
    classDef orchestrator fill:#CE93D8,stroke:#333,stroke-width:2px;
    classDef analytics fill:#C8E6C9,stroke:#333,stroke-width:2px;
    classDef visualization fill:#FFCDD2,stroke:#333,stroke-width:2px;
    classDef utility fill:#FFF9C4,stroke:#333,stroke-width:2px;
    classDef external fill:#D7CCC8,stroke:#333,stroke-width:2px;

    %% Click Events
    click M "https://github.com/jlouros/padel_analytics/blob/main/main.py"
    click A "https://github.com/jlouros/padel_analytics/blob/main/app.py"
    click C "https://github.com/jlouros/padel_analytics/blob/main/config.py"
    click U "https://github.com/jlouros/padel_analytics/blob/main/ui.py"
    click EX "https://github.com/jlouros/padel_analytics/blob/main/examples/videos/select_keypoints.mp4"
    click BT "https://github.com/jlouros/padel_analytics/blob/main/trackers/ball_tracker/ball_tracker.py"
    click BD "https://github.com/jlouros/padel_analytics/blob/main/trackers/ball_tracker/dataset.py"
    click BI "https://github.com/jlouros/padel_analytics/blob/main/trackers/ball_tracker/iterable.py"
    click BM "https://github.com/jlouros/padel_analytics/blob/main/trackers/ball_tracker/models.py"
    click BP "https://github.com/jlouros/padel_analytics/blob/main/trackers/ball_tracker/predict.py"
    click KP "https://github.com/jlouros/padel_analytics/blob/main/trackers/keypoints_tracker/keypoints_tracker.py"
    click KI "https://github.com/jlouros/padel_analytics/blob/main/trackers/keypoints_tracker/iterable.py"
    click P_KP "https://github.com/jlouros/padel_analytics/blob/main/trackers/players_keypoints_tracker/players_keypoints_tracker.py"
    click PT "https://github.com/jlouros/padel_analytics/blob/main/trackers/players_tracker/players_tracker.py"
    click TR "https://github.com/jlouros/padel_analytics/blob/main/trackers/runner.py"
    click TC "https://github.com/jlouros/padel_analytics/blob/main/trackers/tracker.py"
    click TV "https://github.com/jlouros/padel_analytics/blob/main/trackers/velocity_in_time.py"
    click DA "https://github.com/jlouros/padel_analytics/blob/main/analytics/data_analytics.py"
    click PC "https://github.com/jlouros/padel_analytics/blob/main/analytics/projected_court.py"
    click CD "https://github.com/jlouros/padel_analytics/blob/main/constants/court_dimensions.py"
    click PH "https://github.com/jlouros/padel_analytics/blob/main/constants/player_heights.py"
    click CONV "https://github.com/jlouros/padel_analytics/blob/main/utils/conversions.py"
    click CONV2 "https://github.com/jlouros/padel_analytics/blob/main/utils/converters.py"
    click VID "https://github.com/jlouros/padel_analytics/blob/main/utils/video.py"
    click VC "https://github.com/jlouros/padel_analytics/blob/main/visualizations/padel_court.py"
    click PG "https://github.com/jlouros/padel_analytics/blob/main/visualizations/player_centric_graphs.py"
```
