# alvaronovillo/ds_padel architecture

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

- Interactive diagram: https://gitdiagram.com/alvaronovillo/ds_padel
- Repository: https://github.com/alvaronovillo/ds_padel

## Overview

##### Project type and purpose
- This is a specialized computer‐vision pipeline (a Python framework) for automatically tracking padel games in two dimensions from a single camera feed.
- Its goal is to detect the court, players, and ball; compute a homography to map detections onto a standardized 2D court; and output player/ball trajectories.

##### File structure
- Top‐level orchestrator:
- main.py – entry point that ties modules together.
- Core packages:
- minicourt/mini_court.py – court detection and homography calculation.
- trackers/ – three tracker modules:
– court_tracker.py (court contours & homography)
– player_tracker.py (YOLOv8 detection + homography transform)
– ball_tracknet.py (TrackNet-based ball detection)
- Support code:
- models/model.py – definitions or wrappers for loading detection models.
- tracker_stubs/ – serialized detection results for demo/testing.
- Configuration & data artifacts:
- .pkl files in tracker_stubs for offline demos.
- Potential external config (YOLO weights, TrackNet weights) referenced but not in repo.

##### README for additional insights
- The three‐block methodology: Court Detection → Player Detection → Ball Detection.
- Uses OpenCV for preprocessing/contours, YOLOv8 for players, TrackNet for balls.
- Outputs 2D court‐aligned positions via homography.

a. Main components
1. Video Input
2. Image Preprocessing
3. Court Detection Module
4. Homography Calculator
5. Player Detection & Tracker
6. Ball Detection & Tracker
7. Data Fusion & Output (overlay, trajectory export)
8. Model Loader (YOLOv8, TrackNet)
9. Utility Layer (bbox_utils, video_utils, conversions)
b. Relationships & interactions
- Video Input → Image Preprocessing → Court Detection → Homography Calculator
- Homography feeds into Player Tracker (to map player bbox → 2D court)
- Image Preprocessing also feeds Player Tracker and Ball Tracker directly for raw frame detections
- Model Loader is invoked by each tracker to load weights
- Utility functions are imported by all modules for I/O and conversions
- Tracker outputs (player positions, ball positions) go to Data Fusion, which generates final visualizations or data exports
c. Architectural patterns & design principles
- Pipeline pattern: clear flow from raw input through detection, transformation, and output
- Modular separation: each detection/tracking task is in its own module
- Single‐responsibility: utils vs. core logic vs. orchestration
- Use of dependency injection: main.py configures models and passes them to trackers
d. Key technologies & libraries
- Python 3.x, OpenCV, NumPy
- YOLOv8 (via ultralytics or custom wrapper)
- TrackNet
- pickle for stubs; standard Python logging

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Input & Preprocessing"
        VideoInput["Video Input"]:::io
        Preprocess["Image Preprocessing"]:::io
    end

    subgraph "Detection Modules"
        CourtDetect["Court Detection"]:::detect
        CourtTrack["Court Tracker"]:::detect
        Homography["Homography Calculator"]:::transform
        PlayerTrack["Player Detection & Tracker"]:::detect
        BallTrack["Ball Detection & Tracker"]:::detect
    end

    subgraph "Resources"
        ModelLoader["Model Loader"]:::util
        BBoxUtil["BBox Utils"]:::util
        ConvUtil["Coordinate Conversions"]:::util
        Stubs["Tracker Stubs"]:::util
    end

    DataFusion["Orchestration & Data Fusion"]:::io
    Legend["Legend:\nBlue=I/O, Green=Detection, Orange=Transform, Gray=Utility"]:::util

    VideoInput -->|"frame"| Preprocess
    Preprocess -->|"preprocessed frame"| CourtDetect
    CourtDetect -->|"contours"| CourtTrack
    CourtTrack -->|"homography matrix"| Homography
    Homography -->|"2D coords"| PlayerTrack
    Preprocess -->|"preprocessed frame"| PlayerTrack
    Preprocess -->|"preprocessed frame"| BallTrack

    ModelLoader -.->|"loads models"| PlayerTrack
    ModelLoader -.->|"loads models"| BallTrack

    BBoxUtil -.-> CourtTrack
    BBoxUtil -.-> PlayerTrack
    BBoxUtil -.-> BallTrack

    ConvUtil -.-> Homography
    ConvUtil -.-> PlayerTrack
    ConvUtil -.-> BallTrack

    Stubs -.-> CourtTrack
    Stubs -.-> PlayerTrack
    Stubs -.-> BallTrack

    CourtTrack --> DataFusion
    PlayerTrack --> DataFusion
    BallTrack --> DataFusion

    click VideoInput "https://github.com/alvaronovillo/ds_padel/blob/main/utils/video_utils.py"
    click Preprocess "https://github.com/alvaronovillo/ds_padel/blob/main/utils/image_processor.py"
    click CourtDetect "https://github.com/alvaronovillo/ds_padel/blob/main/minicourt/mini_court.py"
    click CourtTrack "https://github.com/alvaronovillo/ds_padel/blob/main/trackers/court_tracker.py"
    click Homography "https://github.com/alvaronovillo/ds_padel/blob/main/minicourt/mini_court.py"
    click PlayerTrack "https://github.com/alvaronovillo/ds_padel/blob/main/trackers/player_tracker.py"
    click BallTrack "https://github.com/alvaronovillo/ds_padel/blob/main/trackers/ball_tracknet.py"
    click ModelLoader "https://github.com/alvaronovillo/ds_padel/blob/main/models/model.py"
    click BBoxUtil "https://github.com/alvaronovillo/ds_padel/blob/main/utils/bbox_utils.py"
    click ConvUtil "https://github.com/alvaronovillo/ds_padel/blob/main/utils/conversions.py"
    click Stubs "https://github.com/alvaronovillo/ds_padel/tree/main/tracker_stubs/"
    click DataFusion "https://github.com/alvaronovillo/ds_padel/blob/main/main.py"

    classDef io fill:#cce5ff,stroke:#1e70bf,color:#000;
    classDef detect fill:#d4edda,stroke:#28a745,color:#000;
    classDef transform fill:#fff3cd,stroke:#ffc107,color:#000;
    classDef util fill:#e2e3e5,stroke:#6c757d,color:#000;
```
