# hoangviet252006/tennis-analysis architecture

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

- Interactive diagram: https://gitdiagram.com/hoangviet252006/tennis-analysis
- Repository: https://github.com/hoangviet252006/tennis-analysis

## Overview

##### Main Components
- Input / Data Acquisition:
- The project accepts an input video (located in the input_videos directory) and outputs processed videos (in the output_video directory).
- Preprocessing and Core Processing Flow:
- main.py acts as the entry point, orchestrating the processing workflow.
- Detection and Tracking:
- Player and ball detection are performed using pretrained models (instructions mention YOLOv8x and YOLOv5, although training scripts and model files are external).
- The trackers (found under the trackers directory) contain ball_tracker.py and player_tracker.py to maintain tracking across frames.
- Tracker stubs (in tracker_stubs) are likely used either as sample data or for testing purposes.
- Analysis & Visualization:
- The analysis directory (with ball_analysis.py) processes data such as player statistics (player.csv) and bounce events (e.g. bounce directory with bounce.py and related CSVs).
- The mini_court module generates a minimap visualization of court events.
- Court Boundary Detection:
- The court_line_detector module detects court lines which might be essential for understanding positions relative to the court layout.
- Constants and Utility Modules:
- The constants module provides configuration values and parameters.

##### Interactions and Data Flow
- The video input is first read into main.py.
- Frames are processed and detection modules (in trackers and court_line_detector) are applied to detect players, ball, and court lines.
- These detections are passed to tracking modules which maintain consistent IDs and generate positional data over time.
- Analysis modules then compute speeds, distances, and ball bounces.
- The mini_court module uses outputs from the tracking and analysis modules to create a minimap visualization.
- Finally, the processed frames and visual overlays are written to the output video.

##### Architectural Patterns
- Modularity: The code is organized into several modules (detection, tracking, analysis, visualization, audio) so that each responsibility is cleanly separated.
- Pipeline Pattern: The design follows a sequential pipeline where video data flows through multiple processing stages (detection → tracking → analysis → visualization).
- Extensibility: Training scripts in the training directory allow for re-training models, thus indicating that detection components are pluggable and can be updated independently of the main pipeline.

##### Specify Key Technologies and Libraries
- Python is the primary language.
- Utilizes deep learning models (YOLO-based models - as mentioned in the README – for detection tasks).
- Likely uses OpenCV or similar libraries for video processing within utils/video_utils.py.
- Data handling: CSV files for storing analysis outputs (e.g., player.csv, df_bounce.csv).
- Other libraries may include NumPy, possibly Matplotlib or similar for visualization – check requirements.txt for further details.

- Within this, create three layers:
- Data Ingestion: "Input Video", "Video Utils", and "main.py".
- Processing Chain: Show branches from "main.py" connecting to (a) Detection Modules (players/ball via trackers, YOLO model integration info), (b) Court Detection Module ("court_line_detector"), (c) Analysis Modules (ball_analysis.py in analysis, bounce processing from bounce/).
- Visualization & Output: "Mini Court Visualization (mini_court)" and "Output Video".
- Additionally, include a side module for "Training" where you show:
- "Training Data (Tennis datasets)" → "Training Scripts (training/tennis_court_keypoints_training.py, potentially train.py for player detection)" → updates feeding back into the Detection Modules.
- To include constants and utilities supporting every stage.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Ingestion Layer
    subgraph "Data Ingestion"
        IV["Input Video"]:::data_ingestion
        ME["Main Entry (main.py)"]:::data_ingestion
        subgraph "Video Utilities"
            VU1["Video Utils (utils/video_utils.py)"]:::data_ingestion
            VU2["Bbox Utils (utils/bbox_utils.py)"]:::data_ingestion
            VU3["Conversions (utils/conversions.py)"]:::data_ingestion
            VU4["Player Stats Drawer (utils/player_stats_drawer_utils.py)"]:::data_ingestion
        end
    end

    %% Processing Chain Layer
    subgraph "Processing Chain"
        subgraph "Detection & Tracking"
            subgraph "Trackers"
                PT["Player Tracker (trackers/player_tracker.py)"]:::processing
                BT["Ball Tracker (trackers/ball_tracker.py)"]:::processing
                PDS["Player Detections (tracker_stubs/player_detections.pkl)"]:::processing
                BDS["Ball Detections (tracker_stubs/ball_detections.pkl)"]:::processing
            end
        end
        subgraph "Court Detection"
            CD["Court Detector (court_line_detector/court_line_detector.py)"]:::processing
        end
        subgraph "Analysis"
            BA["Ball Analysis (analysis/ball_analysis.py)"]:::processing
            BAn["Bounce Analysis (bounce/bounce.py)"]:::processing
            PS["Player Stats CSV (analysis/player.csv)"]:::processing
            BD["Bounce Data (bounce/df_bounce.csv)"]:::processing
        end
    end

    %% Visualization & Output Layer
    subgraph "Visualization & Output"
        MMR["Mini Map Renderer (mini_court/mini_court.py)"]:::visualization
        OV["Output Video (output_video/output_video.mp4)"]:::visualization
        MOP["Minimap Output (output_video/minimap.mp4)"]:::visualization
    end

    %% Training Subsystem
    subgraph "Training Subsystem"
        TS["Training Scripts (training/tennis_court_keypoints_training.py)"]:::training
    end

    %% Constants Module (supporting all layers)
    CONST["Constants (constants/__init__.py)"]:::misc

    %% Connections for Data Ingestion
    IV -->|"feeds"| ME
    ME -->|"invokes"| VU1
    ME -->|"invokes"| VU2
    ME -->|"invokes"| VU3
    ME -->|"invokes"| VU4
    ME -->|"orchestrates"| PT
    ME -->|"orchestrates"| BT
    ME -->|"orchestrates"| CD

    %% Tracker Stubs connection
    PDS -->|"sample data"| PT
    BDS -->|"sample data"| BT

    %% Flow from Detection to Analysis
    PT -->|"detection results"| BA
    BT -->|"detection results"| BA
    CD -->|"court lines"| BA

    BA -->|"bounce triggers"| BAn
    BA -->|"analysis output"| MMR
    BAn -->|"enhanced analysis"| MMR

    %% Visualization Output
    MMR -->|"renders"| OV
    MMR -->|"renders"| MOP

    %% Training updates detection models
    TS -->|"updates"| PT
    TS -->|"updates"| BT
    TS -->|"updates"| CD

    %% Constants support
    CONST -.-> ME
    CONST -.-> VU1
    CONST -.-> PT
    CONST -.-> CD
    CONST -.-> BA

    %% Click Events
    click IV "https://github.com/hoangviet252006/tennis-analysis/blob/main/input_videos/input_video.mp4"
    click OV "https://github.com/hoangviet252006/tennis-analysis/blob/main/output_video/output_video.mp4"
    click MOP "https://github.com/hoangviet252006/tennis-analysis/blob/main/output_video/minimap.mp4"
    click ME "https://github.com/hoangviet252006/tennis-analysis/blob/main/main.py"
    click VU1 "https://github.com/hoangviet252006/tennis-analysis/blob/main/utils/video_utils.py"
    click VU2 "https://github.com/hoangviet252006/tennis-analysis/blob/main/utils/bbox_utils.py"
    click VU3 "https://github.com/hoangviet252006/tennis-analysis/blob/main/utils/conversions.py"
    click VU4 "https://github.com/hoangviet252006/tennis-analysis/blob/main/utils/player_stats_drawer_utils.py"
    click PT "https://github.com/hoangviet252006/tennis-analysis/blob/main/trackers/player_tracker.py"
    click BT "https://github.com/hoangviet252006/tennis-analysis/blob/main/trackers/ball_tracker.py"
    click PDS "https://github.com/hoangviet252006/tennis-analysis/blob/main/tracker_stubs/player_detections.pkl"
    click BDS "https://github.com/hoangviet252006/tennis-analysis/blob/main/tracker_stubs/ball_detections.pkl"
    click BA "https://github.com/hoangviet252006/tennis-analysis/blob/main/analysis/ball_analysis.py"
    click PS "https://github.com/hoangviet252006/tennis-analysis/blob/main/analysis/player.csv"
    click BAn "https://github.com/hoangviet252006/tennis-analysis/blob/main/bounce/bounce.py"
    click BD "https://github.com/hoangviet252006/tennis-analysis/blob/main/bounce/df_bounce.csv"
    click MMR "https://github.com/hoangviet252006/tennis-analysis/blob/main/mini_court/mini_court.py"
    click CD "https://github.com/hoangviet252006/tennis-analysis/blob/main/court_line_detector/court_line_detector.py"
    click CONST "https://github.com/hoangviet252006/tennis-analysis/blob/main/constants/__init__.py"
    click TS "https://github.com/hoangviet252006/tennis-analysis/blob/main/training/tennis_court_keypoints_training.py"

    %% Styles
    classDef data_ingestion fill:#add8e6,stroke:#000,stroke-width:2px;
    classDef processing fill:#90ee90,stroke:#000,stroke-width:2px;
    classDef visualization fill:#f5deb3,stroke:#000,stroke-width:2px;
    classDef training fill:#dda0dd,stroke:#000,stroke-width:2px;
    classDef misc fill:#d3d3d3,stroke:#000,stroke-width:2px;
```
