# abdullahtarek/tennis_analysis architecture

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

- Interactive diagram: https://gitdiagram.com/abdullahtarek/tennis_analysis
- Repository: https://github.com/abdullahtarek/tennis_analysis

## Overview

##### Project Type and Purpose
- This is a standalone Python-based computer-vision pipeline (not a web app) that processes tennis match videos. It performs video input → court keypoint detection → player and ball detection → tracking → statistical analysis → annotated video output.
- Key use cases: measure player speed, ball speed, shot count; produce annotated videos.

##### Top‐Level Components
- Video Input/Output (input_videos/, output_videos/)
- Model Inference
- YOLO v8/v5 for player and ball detection (yolo_inference.py)
- CNN for court keypoints (court_line_detector/)
- Tracking
- ball_tracker.py
- player_tracker.py
- Analysis
- ball_analysis.ipynb & analysis/ball_analysis.ipynb
- mini_court.py (court coordinate transform)
- Utilities
- utils/video_utils.py, bbox_utils.py, conversions.py, player_stats_drawer_utils.py
- constants/ (configuration)
- Orchestration
- Training (not part of runtime flow but crucial for model updates)
- training/*.ipynb and training dataset directories.

##### Relationships and Data Flow
1. Video Input component reads raw .mp4.
2. Court Keypoint Detector computes homography and court layout.
4. Tracker stubs or real trackers consume detections to maintain IDs and trajectories.
5. Analysis module computes speeds and shot counts using trajectories and court geometry.
6. Drawer utilities annotate frames.
7. Video Output writes an .avi annotated file and optionally CSV or JSON stats.
8. Configuration (constants/) and utils are shared across all components.

##### Important Patterns and Principles
- Modular pipeline: each stage is a separate module.
- Single-process orchestration (main.py) that sequentially invokes stages.
- Separation of concerns: detection vs. tracking vs. analysis vs. drawing.
- File‐system based data flow: intermediate results aren’t persisted to a DB, but passed in memory.

##### Technologies, Frameworks, Libraries
- ultralytics YOLO v8/v5 for detection
- OpenCV for video I/O, drawing, homography
- PyTorch for court keypoint CNN
- pandas, numpy for analysis
- Jupyter notebooks for training and exploratory analysis

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Video I/O
    subgraph "I/O Components"
        direction TB
        VideoInput["Video Input"]:::io
        VideoOutput["Video Output"]:::io
    end

    %% Compute Pipeline
    subgraph "Pipeline Stages"
        direction TB
        CourtKeypoint["Court Keypoint Detector\n(PyTorch, OpenCV)"]:::compute
        YOLOInf["YOLO Inference\n(Ultralyitcs YOLO)"]:::compute
        subgraph "Tracking"
            direction TB
            BallTrack["Ball Tracker"]:::compute
            PlayerTrack["Player Tracker"]:::compute
        end
        subgraph "Analysis"
            direction TB
            BallAnalysis["Ball Analysis\n(pandas, numpy)"]:::compute
            MiniCourt["Court Coord Transform"]:::compute
        end
        Drawer["Drawer/Visualization\n(OpenCV)"]:::compute
    end

    %% Utilities and Config
    subgraph "Utilities & Config"
        direction TB
        VideoUtils["Video Utils"]:::util
        BBoxUtils["BBox Utils"]:::util
        ConvUtils["Conversions"]:::util
        StatsDrawerUtils["Player Stats Drawer Utils"]:::util
        Constants["Constants/Config"]:::config
    end

    %% Offline Training
    subgraph "Offline Training" 
        direction TB
        TrainBallNB["Ball Detection Notebook"]:::train
        TrainCourtNB["Court Keypoints Notebook"]:::train
        TrainData["Training Dataset"]:::storage
    end

    %% Connections
    VideoInput -->|reads raw .mp4| CourtKeypoint
    CourtKeypoint -->|homography| YOLOInf
    YOLOInf -->|detections| BallTrack
    YOLOInf -->|detections| PlayerTrack
    BallTrack -->|trajectories| BallAnalysis
    PlayerTrack -->|trajectories| BallAnalysis
    MiniCourt -->|court geometry| BallAnalysis
    BallAnalysis --> Drawer
    Drawer -->|annotated frames| VideoOutput

    %% Utilities usage
    VideoUtils -.-> CourtKeypoint
    VideoUtils -.-> YOLOInf
    VideoUtils -.-> BallTrack
    VideoUtils -.-> PlayerTrack
    VideoUtils -.-> BallAnalysis
    BBoxUtils -.-> YOLOInf
    ConvUtils -.-> MiniCourt
    StatsDrawerUtils -.-> Drawer
    Constants -.-> CourtKeypoint
    Constants -.-> YOLOInf
    Constants -.-> BallTrack
    Constants -.-> PlayerTrack
    Constants -.-> BallAnalysis
    Constants -.-> Drawer

    %% Offline training connections
    TrainBallNB -->|model updates| YOLOInf
    TrainCourtNB -->|model updates| CourtKeypoint
    TrainData --> TrainBallNB
    TrainData --> TrainCourtNB

    %% Click events
    click VideoInput "https://github.com/abdullahtarek/tennis_analysis/tree/main/input_videos/"
    click VideoOutput "https://github.com/abdullahtarek/tennis_analysis/tree/main/output_videos/"
    click CourtKeypoint "https://github.com/abdullahtarek/tennis_analysis/blob/main/court_line_detector/court_line_detector.py"
    click YOLOInf "https://github.com/abdullahtarek/tennis_analysis/blob/main/yolo_inference.py"
    click BallTrack "https://github.com/abdullahtarek/tennis_analysis/blob/main/trackers/ball_tracker.py"
    click PlayerTrack "https://github.com/abdullahtarek/tennis_analysis/blob/main/trackers/player_tracker.py"
    click BallAnalysis "https://github.com/abdullahtarek/tennis_analysis/blob/main/analysis/ball_analysis.ipynb"
    click MiniCourt "https://github.com/abdullahtarek/tennis_analysis/blob/main/mini_court/mini_court.py"
    click VideoUtils "https://github.com/abdullahtarek/tennis_analysis/blob/main/utils/video_utils.py"
    click BBoxUtils "https://github.com/abdullahtarek/tennis_analysis/blob/main/utils/bbox_utils.py"
    click ConvUtils "https://github.com/abdullahtarek/tennis_analysis/blob/main/utils/conversions.py"
    click StatsDrawerUtils "https://github.com/abdullahtarek/tennis_analysis/blob/main/utils/player_stats_drawer_utils.py"
    click Constants "https://github.com/abdullahtarek/tennis_analysis/tree/main/constants/"
    click TrainBallNB "https://github.com/abdullahtarek/tennis_analysis/blob/main/training/tennis_ball_detector_training.ipynb"
    click TrainCourtNB "https://github.com/abdullahtarek/tennis_analysis/blob/main/training/tennis_court_keypoints_training.ipynb"
    click TrainData "https://github.com/abdullahtarek/tennis_analysis/tree/main/training/tennis-ball-detection-6/"

    %% Styles
    classDef io fill:#88CC88,stroke:#333,stroke-width:1px
    classDef compute fill:#88BBDD,stroke:#333,stroke-width:1px
    classDef util fill:#FFCC66,stroke:#333,stroke-width:1px
    classDef config fill:#CCCCCC,stroke:#333,stroke-width:1px
    classDef train fill:#DDDDDD,stroke:#333,stroke-width:1px
    classDef storage fill:#AAAAAA,stroke:#333,stroke-width:1px
```
