# yuyaox122/tennis_ml_analysis architecture

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

- Interactive diagram: https://gitdiagram.com/yuyaox122/tennis_ml_analysis
- Repository: https://github.com/yuyaox122/tennis_ml_analysis

## Overview

This repository is a tennis-video analysis application. Its main workflow reads a match video, detects and filters players, detects and interpolates the ball, identifies court keypoints, maps detections to a mini-court, computes shot and player speeds, overlays visualizations, and saves a processed video. The graph reflects the sampled `main.py` orchestration and core modules; README documentation is only a title and link, and unsampled GUI and inference modules are not assigned unverified behavior.

Main entry points: [`main.py`](https://github.com/yuyaox122/tennis_ml_analysis/blob/main/main.py) (Analysis workflow), [`mini_court/mini_court.py`](https://github.com/yuyaox122/tennis_ml_analysis/blob/main/mini_court/mini_court.py) (Mini-court mapping), [`utilities/video_utilities.py`](https://github.com/yuyaox122/tennis_ml_analysis/blob/main/utilities/video_utilities.py) (Video I/O), [`utilities/bbox_utilities.py`](https://github.com/yuyaox122/tennis_ml_analysis/blob/main/utilities/bbox_utilities.py) (Bounding-box geometry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_input["Video input"]
  node_video_io["Video I/O<br/>[video_utilities.py]"]
end

subgraph group_vision["Detection and tracking"]
  node_orchestrator["Analysis workflow<br/>[main.py]"]
  node_player_tracker["Player tracking<br/>[player_tracker.py]"]
  node_ball_tracker["Ball tracking<br/>[ball_tracker.py]"]
end

subgraph group_analysis["Court analysis"]
  node_court_detector["Court keypoints"]
  node_mini_court["Mini-court mapping<br/>[mini_court.py]"]
  node_geometry["Bounding-box geometry<br/>[bbox_utilities.py]"]
  node_conversion["Distance conversion"]
  node_court_constants["Court dimensions<br/>[__init__.py]"]
end

subgraph group_output["Statistics and output"]
  node_speed_stats["Shot and player speeds<br/>[main.py]"]
  node_bbox_overlay["Detection overlays<br/>[player_tracker.py]"]
  node_court_overlay["Court overlay"]
  node_mini_overlay["Mini-court overlay<br/>[mini_court.py]"]
  node_stats_overlay["Statistics overlay"]
end

node_user(("Video operator"))

node_user -->|"starts processing"| node_orchestrator
node_orchestrator -->|"reads frames"| node_video_io
node_orchestrator -->|"detects and filters"| node_player_tracker
node_orchestrator -->|"detects and interpolates"| node_ball_tracker
node_orchestrator -->|"predicts keypoints"| node_court_detector
node_orchestrator -->|"maps detections"| node_mini_court
node_mini_court -->|"uses positions"| node_geometry
node_mini_court -->|"converts distances"| node_conversion
node_mini_court -->|"uses dimensions"| node_court_constants
node_orchestrator -->|"calculates speeds"| node_speed_stats
node_speed_stats -->|"measures distances"| node_geometry
node_speed_stats -->|"converts distances"| node_conversion
node_speed_stats -->|"uses dimensions"| node_court_constants
node_orchestrator -->|"draws detections"| node_bbox_overlay
node_orchestrator -->|"draws keypoints"| node_court_overlay
node_orchestrator -->|"draws mapped points"| node_mini_overlay
node_orchestrator -->|"draws statistics"| node_stats_overlay
node_orchestrator -->|"saves result"| node_video_io

click node_video_io "https://github.com/yuyaox122/tennis_ml_analysis/blob/main/utilities/video_utilities.py"
click node_orchestrator "https://github.com/yuyaox122/tennis_ml_analysis/blob/main/main.py"
click node_player_tracker "https://github.com/yuyaox122/tennis_ml_analysis/blob/main/trackers/player_tracker.py"
click node_ball_tracker "https://github.com/yuyaox122/tennis_ml_analysis/blob/main/trackers/ball_tracker.py"
click node_court_detector "https://github.com/yuyaox122/tennis_ml_analysis/blob/main/court_line_detector/court_line_detector.py"
click node_mini_court "https://github.com/yuyaox122/tennis_ml_analysis/blob/main/mini_court/mini_court.py"
click node_geometry "https://github.com/yuyaox122/tennis_ml_analysis/blob/main/utilities/bbox_utilities.py"
click node_conversion "https://github.com/yuyaox122/tennis_ml_analysis/blob/main/utilities/conversion_utilities.py"
click node_court_constants "https://github.com/yuyaox122/tennis_ml_analysis/blob/main/constants/__init__.py"
click node_speed_stats "https://github.com/yuyaox122/tennis_ml_analysis/blob/main/main.py"
click node_bbox_overlay "https://github.com/yuyaox122/tennis_ml_analysis/blob/main/trackers/player_tracker.py"
click node_court_overlay "https://github.com/yuyaox122/tennis_ml_analysis/blob/main/court_line_detector/court_line_detector.py"
click node_mini_overlay "https://github.com/yuyaox122/tennis_ml_analysis/blob/main/mini_court/mini_court.py"
click node_stats_overlay "https://github.com/yuyaox122/tennis_ml_analysis/blob/main/utilities/stats_drawer_utilities.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_video_io toneBlue
class node_orchestrator,node_player_tracker,node_ball_tracker toneAmber
class node_court_detector,node_mini_court,node_geometry,node_conversion,node_court_constants toneMint
class node_speed_stats,node_bbox_overlay,node_court_overlay,node_mini_overlay,node_stats_overlay toneRose
class node_user toneIndigo
```

## Components

### Video input

- [Video I/O](https://github.com/yuyaox122/tennis_ml_analysis/blob/main/utilities/video_utilities.py): `utilities/video_utilities.py`

### Detection and tracking

- [Analysis workflow](https://github.com/yuyaox122/tennis_ml_analysis/blob/main/main.py): `main.py`
- [Player tracking](https://github.com/yuyaox122/tennis_ml_analysis/blob/main/trackers/player_tracker.py): `trackers/player_tracker.py`
- [Ball tracking](https://github.com/yuyaox122/tennis_ml_analysis/blob/main/trackers/ball_tracker.py): `trackers/ball_tracker.py`

### Court analysis

- [Court keypoints](https://github.com/yuyaox122/tennis_ml_analysis/blob/main/court_line_detector/court_line_detector.py): `court_line_detector/court_line_detector.py`
- [Mini-court mapping](https://github.com/yuyaox122/tennis_ml_analysis/blob/main/mini_court/mini_court.py): `mini_court/mini_court.py`
- [Bounding-box geometry](https://github.com/yuyaox122/tennis_ml_analysis/blob/main/utilities/bbox_utilities.py): `utilities/bbox_utilities.py`
- [Distance conversion](https://github.com/yuyaox122/tennis_ml_analysis/blob/main/utilities/conversion_utilities.py): `utilities/conversion_utilities.py`
- [Court dimensions](https://github.com/yuyaox122/tennis_ml_analysis/blob/main/constants/__init__.py): `constants/__init__.py`

### Statistics and output

- [Shot and player speeds](https://github.com/yuyaox122/tennis_ml_analysis/blob/main/main.py): `main.py`
- [Detection overlays](https://github.com/yuyaox122/tennis_ml_analysis/blob/main/trackers/player_tracker.py): `trackers/player_tracker.py`
- [Court overlay](https://github.com/yuyaox122/tennis_ml_analysis/blob/main/court_line_detector/court_line_detector.py): `court_line_detector/court_line_detector.py`
- [Mini-court overlay](https://github.com/yuyaox122/tennis_ml_analysis/blob/main/mini_court/mini_court.py): `mini_court/mini_court.py`
- [Statistics overlay](https://github.com/yuyaox122/tennis_ml_analysis/blob/main/utilities/stats_drawer_utilities.py): `utilities/stats_drawer_utilities.py`

### Other components

- **Video operator**

## Connections

- Video operator → Analysis workflow: starts processing (evidence: `main.py`)
- Analysis workflow → Video I/O: reads frames (evidence: `main.py`)
- Analysis workflow → Player tracking: detects and filters (evidence: `main.py`)
- Analysis workflow → Ball tracking: detects and interpolates (evidence: `main.py`)
- Analysis workflow → Court keypoints: predicts keypoints (evidence: `main.py`)
- Analysis workflow → Mini-court mapping: maps detections (evidence: `main.py`)
- Mini-court mapping → Bounding-box geometry: uses positions (evidence: `mini_court/mini_court.py`)
- Mini-court mapping → Distance conversion: converts distances (evidence: `mini_court/mini_court.py`)
- Mini-court mapping → Court dimensions: uses dimensions (evidence: `mini_court/mini_court.py`)
- Analysis workflow → Shot and player speeds: calculates speeds (evidence: `main.py`)
- Shot and player speeds → Bounding-box geometry: measures distances (evidence: `main.py`)
- Shot and player speeds → Distance conversion: converts distances (evidence: `main.py`)
- Shot and player speeds → Court dimensions: uses dimensions (evidence: `main.py`)
- Analysis workflow → Detection overlays: draws detections (evidence: `main.py`)
- Analysis workflow → Court overlay: draws keypoints (evidence: `main.py`)
- Analysis workflow → Mini-court overlay: draws mapped points (evidence: `main.py`)
- Analysis workflow → Statistics overlay: draws statistics (evidence: `main.py`)
- Analysis workflow → Video I/O: saves result (evidence: `main.py`)
