# yastrebksv/tennisproject architecture

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

- Interactive diagram: https://gitdiagram.com/yastrebksv/tennisproject
- Repository: https://github.com/yastrebksv/tennisproject

## Overview

##### Project type and purpose
- This is a single‐language (Python) data processing/analysis pipeline, not a web app or microservices architecture.
- Purpose: take an input tennis match video (1280×720), detect and track the ball, detect court geometry, infer bounces, and produce analytics/annotated output.

##### File structure
- Top‐level Python scripts each encapsulate one stage of the pipeline:
- main.py – orchestrator
- tracknet.py & ball_detector.py – tennis ball detection using a TrackNet model
- court_detection_net.py & court_reference.py – court landmark detection/building perspective reference
- homography.py – compute perspective transforms
- person_detector.py – (optional) detect players
- bounce_detector.py – predict bounce events via a CatBoostRegressor
- postprocess.py – assemble results, annotate frames
- utils.py – shared helper functions
- pics/ – sample court images and demo GIFs
- requirements.txt declares dependencies (Deep Learning libs, CatBoost, OpenCV, etc.).

##### README for additional insights
- External pretrained weights are fetched from GitHub and Google Drive.
- Three major ML components: TrackNet for ball tracking, TennisCourtDetector for court points, CatBoost for bounce prediction.

##### Elements
- Clear labels: “Video Reader”, “Court Detector”, etc.
- Blue rectangles for Python modules

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Inputs & Dependencies
    InputVideo[(Input Video \n1280×720)]:::dataStore
    weightsGitHub["Pretrained Weights \n(GitHub)"]:::external
    weightsDrive["Pretrained Weights \n(Google Drive)"]:::external
    pics["Sample Images & Demos"]:::dataStore
    requirements["requirements.txt"]:::dataStore

    %% Main Pipeline
    subgraph "Tennis Project Pipeline"
        direction TB
        main["Orchestrator\n(main.py)"]:::module
        utils["Shared Utilities\n(utils.py)"]:::util

        %% Geometry Preprocessing
        subgraph "Geometry Preprocessing"
            direction TB
            courtNet["Court Detection Net\n(court_detection_net.py)"]:::module
            courtRef["Court Reference\n(court_reference.py)"]:::module
            homography["Homography Service\n(homography.py)"]:::module
        end

        %% Ball Detection Stage
        subgraph "Ball Detection"
            direction TB
            trackNet["TrackNet Model\n(tracknet.py)"]:::module
            ballDetector["Ball Detector\n(ball_detector.py)"]:::module
        end

        %% Person Detection (Optional)
        personDetector["Person Detector\n(person_detector.py)"]:::module

        %% Bounce Detection & Post-processing
        bounceDetector["Bounce Detector\n(bounce_detector.py)"]:::module
        postprocess["Post-processing & Annotation\n(postprocess.py)"]:::module

        %% Output
        OutputVideo[(Annotated Video)]:::dataStore
        OutputData[(Analytics Data)]:::dataStore
    end

    %% Dependencies Flow
    InputVideo -->main
    main -->courtNet
    main -->trackNet
    main -->personDetector
    courtNet -->courtRef
    courtRef -->homography
    homography -->ballDetector
    trackNet -->ballDetector
    ballDetector -->bounceDetector
    bounceDetector -->postprocess
    personDetector -->postprocess
    postprocess -->OutputVideo
    postprocess -->OutputData

    %% External Weights
    weightsGitHub -->courtNet
    weightsDrive -->courtNet
    weightsGitHub -->trackNet
    weightsDrive -->trackNet
    weightsGitHub -->courtRef
    weightsDrive -->courtRef

    %% Utilities Imports
    utils -.-> main
    utils -.-> courtNet
    utils -.-> courtRef
    utils -.-> homography
    utils -.-> trackNet
    utils -.-> ballDetector
    utils -.-> personDetector
    utils -.-> bounceDetector
    utils -.-> postprocess

    %% Additional Resources
    pics -->courtNet
    pics -->trackNet
    requirements -->main

    %% Click Events
    click main "https://github.com/yastrebksv/tennisproject/blob/main/main.py"
    click courtNet "https://github.com/yastrebksv/tennisproject/blob/main/court_detection_net.py"
    click courtRef "https://github.com/yastrebksv/tennisproject/blob/main/court_reference.py"
    click homography "https://github.com/yastrebksv/tennisproject/blob/main/homography.py"
    click trackNet "https://github.com/yastrebksv/tennisproject/blob/main/tracknet.py"
    click ballDetector "https://github.com/yastrebksv/tennisproject/blob/main/ball_detector.py"
    click personDetector "https://github.com/yastrebksv/tennisproject/blob/main/person_detector.py"
    click bounceDetector "https://github.com/yastrebksv/tennisproject/blob/main/bounce_detector.py"
    click postprocess "https://github.com/yastrebksv/tennisproject/blob/main/postprocess.py"
    click utils "https://github.com/yastrebksv/tennisproject/blob/main/utils.py"
    click pics "https://github.com/yastrebksv/tennisproject/tree/main/pics/"
    click requirements "https://github.com/yastrebksv/tennisproject/blob/main/requirements.txt"

    %% Styles
    classDef module fill:#ADD8E6,stroke:#036,stroke-width:1px
    classDef dataStore fill:#98FB98,stroke:#060,stroke-width:1px
    classDef external fill:#F0E68C,stroke:#DAA520,stroke-width:1px
    classDef util fill:#FFEFD5,stroke:#DAA520,stroke-width:1px
```
