# pirroux/tennisproject architecture

> Architecture diagram of the GitHub repository pirroux/tennisproject, 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/pirroux/tennisproject
- Repository: https://github.com/pirroux/tennisproject

## Overview

##### Project Type and Purpose
- This is an end-to-end computer vision and deep learning project focused on analyzing official tennis match videos.
- Its purpose is to automate tasks such as:
- Detecting and tracking the tennis court.
- Detecting and tracking the players and ball.
- Extracting player skeleton (pose estimation).
- Recognizing the precise moment and type of strokes.
- Generating a top-view gameplay map.
- Computing gameplay statistics (heatmaps, distances, etc.).
- The README and file structure indicate this project is built mainly in Python using OpenCV and PyTorch, demonstrating a blend of classical computer vision and deep learning modules.

##### File Structure Analysis
- The top-level files include project-level items such as README.md, setup.py, and a .gitignore.
- The main implementation lies within the "src" directory, which includes:
- The entry point (process.py) where the main video processing function (video_process) is defined.
- Specialized modules:
- court_detection.py, court_configurations, and court_reference.py for tennis court detection and configuration.
- ball_detection.py and ball_tracker_net.py for ball detection and tracking.
- stroke_recognition.py, pose.py, and my_statistics.py for player pose estimation, stroke detection, and gameplay statistics.
- fast_api.py suggests an interface layer which might expose some functionality, perhaps for a web API.
- datasets.py, create_data.py, and trainer.py that hint at data preparation and model training components.
- Utility modules (utils.py, smooth.py, sort.py) which provide supporting functions.
- Additional supportive artifacts like saved model weights in the "saved states" directory.
- The Makefile in src indicates build or task automation, suggesting configurable pipelines during development.

a. Main Components:
- Video Input & Preprocessing: Entry via process.py initiates video processing.
- Court Detection: Modules (court_detection.py, court_configurations, court_reference.py) responsible for detecting and defining the court within the video frame.
- Ball Detection & Tracking: ball_detection.py and ball_tracker_net.py handle identifying and tracking the ball.
- Player and Pose Estimation: pose.py likely extracts the bottom player’s skeleton, combined with stroke recognition.
- Stroke Recognition: stroke_recognition.py classifies potential tennis strokes.
- Data Processing & Statistics: my_statistics.py and datasets.py to compute gameplay statistics and manage datasets.
- Data Creation & Model Training: create_data.py and trainer.py facilitate data augmentation and model updates.
- API/Interface Layer: fast_api.py exposes functionalities, possibly for real-time inference or monitoring.
- Auxiliary Modules: modules such as smooth.py, sort.py, and utils.py provide necessary calculation, filtering, or ordering operations.
b. Relationships and Interactions:
- Process Flow: Start from the video input (process.py) → Court detection → Ball and player detection modules → Pose estimation and stroke recognition → Statistical computation and data processing.
- Inter-module Communication: The detection modules feed results into tracking and recognition components. For example, outputs from court_detection.py may be used to transform coordinates in ball_detection.py or stroke_recognition.py.
- Data and Model Dependencies: Model weights stored in “saved states” are loaded by ball_tracker_net.py and stroke_recognition.py during inference.
- API Integration: The fast_api.py module might serve as an endpoint that aggregates and serves processed data.
c. Architectural Patterns & Design Principles:
- Modular Design: Each functionality (detection, tracking, pose estimation, statistics) is encapsulated in its own module, facilitating easier maintenance and potential reusability.
- Pipeline Flow: The project implements a clear, sequential data processing pipeline, processing raw video frames through several stages.
- Separation of Concerns: The codebase distinguishes between preprocessing, detection, classification, and statistical analysis.
d. Relevant Technologies:
- Python 3.4 – the runtime environment.
- OpenCV (cv2) – for image/video processing.
- PyTorch – for deep learning model training and inference.
- Possibly additional libraries as per the src/requirements.txt.

##### Elements
- Clear and concise labels on every component. For example:
– "Video Processing (process.py)"
– "Court Detection (court_detection.py etc.)"
– "Ball Detection & Tracking (ball_detection.py, ball_tracker_net.py)"
– "Pose & Stroke Recognition (pose.py, stroke_recognition.py)"
– "Statistical Analysis (my_statistics.py)"
– "API Access (fast_api.py)"
– "Model Weights (saved states)"
– Data flow from entry (video input in process.py) through various processing stages.
– Dependencies between modules (e.g., outputs of detection modules are inputs for the tracking or classification modules).
– If helpful, include notes on the side that reference key libraries like OpenCV and PyTorch.
- On modular connections to capture the essence of the data pipeline and how each module interacts with others.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Video Processing
    VP["Video Processing (process.py)"]:::video

    %% Detection Modules Subgraph
    subgraph "Detection Modules"
        subgraph "Court Detection"
            CD["Court Detection (court_detection.py)"]:::detection
            CC["Court Configurations (court_configurations)"]:::detection
            CRF["Court Reference (court_reference.py)"]:::detection
        end
        subgraph "Ball Detection & Tracking"
            BD["Ball Detection (ball_detection.py)"]:::detection
            BTN["Ball Tracker Net (ball_tracker_net.py)"]:::detection
        end
    end

    %% Processing Modules
    POSE["Player Pose Estimation (pose.py)"]:::classification
    STROKE["Stroke Recognition (stroke_recognition.py)"]:::classification
    STATS["Statistical Analysis (my_statistics.py)"]:::analysis

    %% API Layer
    API["API Access (fast_api.py)"]:::api

    %% Data Creation & Model Training Subgraph
    subgraph "Data Creation & Model Training"
        CDT["Create Data (create_data.py)"]:::training
        TRAIN["Trainer (trainer.py)"]:::training
        DATA["Datasets (datasets.py)"]:::training
    end

    %% Auxiliary Utilities Subgraph
    subgraph "Auxiliary Utilities"
        SM["Smooth (smooth.py)"]:::utils
        SORT["Sort (sort.py)"]:::utils
        UTIL["Utils (utils.py)"]:::utils
    end

    %% Model Weights
    WEIGHTS["Model Weights (saved states)"]:::weights

    %% Data Flow Connections
    VP -->|"initiates"| CD
    VP -->|"initiates"| BD

    CD -->|"coordinates"| STROKE

    BD --> BTN
    BTN --> POSE
    POSE --> STROKE
    STROKE --> STATS
    STATS --> API

    %% Model Dependencies
    WEIGHTS --> BTN
    WEIGHTS --> STROKE
    TRAIN --> WEIGHTS

    %% Styles for clarity: Utility nodes are support modules (dashed link example)
    SM ---|"support"| BD
    SORT ---|"support"| BTN
    UTIL ---|"support"| POSE

    %% Click Events
    click VP "https://github.com/pirroux/tennisproject/blob/main/src/process.py"
    click CD "https://github.com/pirroux/tennisproject/blob/main/src/court_detection.py"
    click CC "https://github.com/pirroux/tennisproject/tree/main/src/court_configurations"
    click CRF "https://github.com/pirroux/tennisproject/blob/main/src/court_reference.py"
    click BD "https://github.com/pirroux/tennisproject/blob/main/src/ball_detection.py"
    click BTN "https://github.com/pirroux/tennisproject/blob/main/src/ball_tracker_net.py"
    click POSE "https://github.com/pirroux/tennisproject/blob/main/src/pose.py"
    click STROKE "https://github.com/pirroux/tennisproject/blob/main/src/stroke_recognition.py"
    click STATS "https://github.com/pirroux/tennisproject/blob/main/src/my_statistics.py"
    click CDT "https://github.com/pirroux/tennisproject/blob/main/src/create_data.py"
    click TRAIN "https://github.com/pirroux/tennisproject/blob/main/src/trainer.py"
    click DATA "https://github.com/pirroux/tennisproject/blob/main/src/datasets.py"
    click API "https://github.com/pirroux/tennisproject/blob/main/src/fast_api.py"
    click SM "https://github.com/pirroux/tennisproject/blob/main/src/smooth.py"
    click SORT "https://github.com/pirroux/tennisproject/blob/main/src/sort.py"
    click UTIL "https://github.com/pirroux/tennisproject/blob/main/src/utils.py"

    %% Style Definitions
    classDef video fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef detection fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef classification fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef analysis fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef api fill:#E6E6FA,stroke:#000,stroke-width:2px;
    classDef training fill:#FFA07A,stroke:#000,stroke-width:2px;
    classDef utils fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef weights fill:#FFE4B5,stroke:#000,stroke-width:2px;
```
