# sriramsohanbasa/tennis_analysis architecture

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

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

## Overview

Based on our analysis of both the file structure and the README, this project is a computer vision– and deep learning–based Tennis Analysis System. It is designed to process input videos of tennis matches, detect players and the tennis ball using YOLO (along with a dedicated tennis-ball detector training pipeline), track these objects across video frames, and analyze aspects such as court keypoints and court lines. The project also includes separate modules for training the models used in detection and for analyzing the results.

##### Input & Data Sources
- Component: Input Videos (located in the “input_videos” directory)
- Role: Provides the raw video files that will be processed.
- Data Flow: Input video files are fed into the processing pipeline.

##### Preprocessing & Core Detection
- Module: yolo_inference.py
- Uses Ultralytics YOLOv8 to detect tennis players and tennis balls.
- Module: court_line_detector (including court_line_detector.py)
- Focuses on detecting court lines and possibly boundaries.
- Module: mini_court
- Likely contains code handling the detection of key courtpoints or related computations, possibly using a CNN.
- Data Flow: Processed frames are passed to these detection modules; results are gathered and logged for further processing.

##### Object Tracking
- Directory: trackers (ball_tracker.py, player_tracker.py)
- Implements tracking logic to follow detected objects (players/ball) across frames.
- Supporting Data: tracker_stubs contains sample detection data (using .pkl files) that may be used for testing or calibration.
- Role: Maintains a consistent track of detected objects across video frames.
- Data Flow: Receives detection outputs from the core detection modules and produces tracking output.

##### Utilities & Supporting Functions
- Directory: utils
- Role: Provides re-usable functionality that supports both the detection and tracking processes.
- Relationship: Used across modules (e.g., during inference, tracking, and analysis).

##### Analysis & Visualization
- Directory: analysis (includes Jupyter notebooks like ball_analysis.ipynb)
- Provides a layer where the results (detections and tracking data) are analyzed, and insights are visualized using libraries like Matplotlib.
- Directory: runs
- May store output logs or detection results from processing.
- Data Flow: Takes tracking and detection results from earlier stages to create visual insights and performance metrics.

##### Training Infrastructure
- Directory: training
- Contains training data (JSON files, image datasets) and notebooks (e.g., tennis_ball_detector_training.ipynb, tennis_court_keypoints_training.ipynb) that guide the training and fine-tuning of the detection models.
- Role: Enables model training and adjustments via a structured dataset.
- Data Flow: Provides trained models to be used in the Detection module (e.g., yolo_inference, mini_court, court_line_detector).

##### Coordination & Orchestration
- File: main.py
- Likely acts as the entry point that orchestrates the overall workflow from video ingestion through detection, tracking, and analysis.
- Role: To integrate and drive the entire pipeline.
- Data Flow: Depending on triggers or run modes (e.g., training mode vs. inference mode), main.py coordinates data movement between the components.

- Libraries and technologies associated with each component. For instance, note “YOLOv8 (Ultralytics)”, “OpenCV”, “PyTorch”, “NumPy” in the detection area; “Matplotlib” in the analysis area; correspondingly annotate the use of Jupyter notebooks in testing and training.

e. Important architectural patterns:
- The separation between the training environment and the inference runtime.
- The modular design where each stage (detection, tracking, analysis) works independently but is orchestrated via main.py.

- Flow from raw video input, through a multi-stage detection pipeline that uses deep learning (YOLO and a custom CNN) and computer vision techniques, to object tracking, and finally to analysis/visualization.
- Connection between training components (where models are built and refined) and the production inference components (which use these models).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input & Data Sources
    subgraph "Input & Data Sources"
        InputVideos["Input Videos"]:::input
    end

    %% Preprocessing & Core Detection
    subgraph "Preprocessing & Core Detection"
        YOLO["YOLO Inference (YOLOv8, Ultralytics, OpenCV, NumPy)"]:::detection
        Court["Court Line Detection (court_line_detector)"]:::detection
        MiniCourt["Mini Court Keypoints (CNN based)"]:::detection
    end

    %% Object Tracking
    subgraph "Object Tracking"
        Tracking["Player & Ball Tracking (trackers)"]:::tracking
    end

    %% Utilities & Supporting Functions
    subgraph "Utilities & Supporting Functions"
        Utils["Utilities Functions (helper routines)"]:::utils
    end

    %% Analysis & Visualization
    subgraph "Analysis & Visualization"
        Analysis["Analysis & Visualization (Jupyter, Matplotlib)"]:::analysis
    end

    %% Model Training
    subgraph "Model Training"
        Training["Model Training (Notebooks & datasets)"]:::training
    end

    %% Coordination & Orchestration
    subgraph "Coordination & Orchestration"
        Orchestration["Coordination & Orchestration (main.py)"]:::orchestration
    end

    %% Data Flow Connections
    InputVideos -->|"feeds"| YOLO
    InputVideos -->|"feeds"| Court
    InputVideos -->|"feeds"| MiniCourt

    YOLO -->|"detection_output"| Tracking
    Court -->|"detection_output"| Tracking
    MiniCourt -->|"detection_output"| Tracking

    Tracking -->|"tracking_results"| Analysis

    Training -->|"provides_trained_models"| YOLO
    Training -->|"provides_trained_models"| Court
    Training -->|"provides_trained_models"| MiniCourt

    YOLO ---|"uses"| Utils
    Court ---|"uses"| Utils
    MiniCourt ---|"uses"| Utils
    Tracking ---|"uses"| Utils

    Orchestration -->|"orchestrates"| InputVideos
    Orchestration -->|"orchestrates"| YOLO
    Orchestration -->|"orchestrates"| Court
    Orchestration -->|"orchestrates"| MiniCourt
    Orchestration -->|"orchestrates"| Tracking
    Orchestration -->|"orchestrates"| Analysis
    Orchestration -->|"orchestrates"| Training

    %% Click Events
    click InputVideos "https://github.com/sriramsohanbasa/tennis_analysis/tree/main/input_videos/"
    click YOLO "https://github.com/sriramsohanbasa/tennis_analysis/blob/main/yolo_inference.py"
    click Court "https://github.com/sriramsohanbasa/tennis_analysis/blob/main/court_line_detector/court_line_detector.py"
    click MiniCourt "https://github.com/sriramsohanbasa/tennis_analysis/blob/main/mini_court/mini_court.py"
    click Tracking "https://github.com/sriramsohanbasa/tennis_analysis/tree/main/trackers/"
    click Utils "https://github.com/sriramsohanbasa/tennis_analysis/tree/main/utils/"
    click Analysis "https://github.com/sriramsohanbasa/tennis_analysis/tree/main/analysis/"
    click Training "https://github.com/sriramsohanbasa/tennis_analysis/tree/main/training/"
    click Orchestration "https://github.com/sriramsohanbasa/tennis_analysis/blob/main/main.py"

    %% Styling Classes
    classDef input fill:#A2DCEE,stroke:#000,stroke-width:2px;
    classDef detection fill:#F8E71C,stroke:#000,stroke-width:2px;
    classDef tracking fill:#BD10E0,stroke:#000,stroke-width:2px;
    classDef utils fill:#F5A623,stroke:#000,stroke-width:2px;
    classDef analysis fill:#7ED321,stroke:#000,stroke-width:2px;
    classDef training fill:#D0021B,stroke:#000,stroke-width:2px;
    classDef orchestration fill:#50E3C2,stroke:#000,stroke-width:2px;
```
