# harshtomar1234/tennis-vision architecture

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

- Interactive diagram: https://gitdiagram.com/harshtomar1234/tennis-vision
- Repository: https://github.com/harshtomar1234/tennis-vision

## Overview

Tennis-Vision is a single-camera tennis video analysis pipeline. A broadcast video is analyzed for court geometry, players, and ball motion; event candidates are decoded and checked against court, player, and physics evidence before serve/shot measurements and 3-D flight reconstruction are reported. The annotated-video and interactive-viewer branches expose the results. README-level pipeline relationships are shown; sampled source excerpts do not expose the full orchestration, so finer call details are omitted.

Main entry points: [`main.py`](https://github.com/harshtomar1234/tennis-vision/blob/main/main.py) (Analysis pipeline), [`utils/shot_physics.py`](https://github.com/harshtomar1234/tennis-vision/blob/main/utils/shot_physics.py) (Physics validation), [`utils/shot_classifier.py`](https://github.com/harshtomar1234/tennis-vision/blob/main/utils/shot_classifier.py) (Shot classification), [`utils/trajectory_3d.py`](https://github.com/harshtomar1234/tennis-vision/blob/main/utils/trajectory_3d.py) (3-D reconstruction)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_detection["Detection"]
  node_pipeline["Analysis pipeline<br/>[main.py]"]
  node_players["Player tracking<br/>[player_tracker.py]"]
  node_ball["Ball tracking"]
  node_court["Court keypoints"]
  node_fps["FPS support<br/>[fps_support.py]"]
end

subgraph group_evidence["Evidence and events"]
  node_candidates["Event candidates"]
  node_event_classifier["Hit/bounce classifier"]
  node_rally["Rally decoding<br/>[rally_decode.py]"]
  node_court_gate["Court validity gate<br/>[court_validity.py]"]
  node_player_gate["Player selection"]
  node_physics["Physics validation<br/>[shot_physics.py]"]
end

subgraph group_measurement["Measurement"]
  node_homography["Court homography<br/>[mini_court.py]"]
  node_serve["Serve detection<br/>[serve_detector.py]"]
  node_serve_landing["Serve landing<br/>[serve_landing.py]"]
  node_serve_speed["Serve speed<br/>[serve_speed.py]"]
  node_shot["Shot classification<br/>[shot_classifier.py]"]
  node_trajectory["3-D reconstruction<br/>[trajectory_3d.py]"]
  node_audit["Rally evidence audit<br/>[rally_audit.py]"]
end

subgraph group_presentation["Results"]
  node_annotated["Annotated video<br/>[main.py]"]
  node_viewer["Interactive 3-D viewer<br/>[viewer_3d.py]"]
end

node_video(("Broadcast video"))

node_video -->|"analyzed by"| node_pipeline
node_pipeline -->|"checks frame rate"| node_fps
node_pipeline -->|"tracks players"| node_players
node_pipeline -->|"tracks ball"| node_ball
node_pipeline -->|"detects keypoints"| node_court
node_pipeline -->|"validates court"| node_court_gate
node_pipeline -->|"selects players"| node_player_gate
node_pipeline -->|"generates candidates"| node_candidates
node_pipeline -->|"decodes events"| node_rally
node_candidates -->|"classifies events"| node_event_classifier
node_pipeline -->|"classifies events"| node_event_classifier
node_pipeline -->|"maps court geometry"| node_homography
node_pipeline -->|"detects serves"| node_serve
node_pipeline -->|"checks landing"| node_serve_landing
node_pipeline -->|"measures serve speed"| node_serve_speed
node_pipeline -->|"classifies shots"| node_shot
node_pipeline -->|"validates measurements"| node_physics
node_pipeline -->|"reconstructs flights"| node_trajectory
node_pipeline -->|"audits evidence"| node_audit
node_rally -->|"supplies events"| node_shot
node_court_gate -->|"gates geometry"| node_homography
node_player_gate -->|"gates geometry"| node_homography
node_shot -->|"checks evidence"| node_physics
node_physics -->|"validates flight"| node_trajectory
node_pipeline -->|"renders analysis"| node_annotated
node_pipeline -->|"creates viewer"| node_viewer
node_trajectory -->|"shows reconstruction"| node_viewer

click node_pipeline "https://github.com/harshtomar1234/tennis-vision/blob/main/main.py"
click node_players "https://github.com/harshtomar1234/tennis-vision/blob/main/trackers/player_tracker.py"
click node_ball "https://github.com/harshtomar1234/tennis-vision/blob/main/trackers/tracknet_ball_tracker.py"
click node_court "https://github.com/harshtomar1234/tennis-vision/blob/main/court_line_detector/court_line_detector.py"
click node_fps "https://github.com/harshtomar1234/tennis-vision/blob/main/utils/fps_support.py"
click node_candidates "https://github.com/harshtomar1234/tennis-vision/blob/main/utils/bounce_candidates.py"
click node_event_classifier "https://github.com/harshtomar1234/tennis-vision/blob/main/utils/hit_bounce_classifier.py"
click node_rally "https://github.com/harshtomar1234/tennis-vision/blob/main/utils/rally_decode.py"
click node_court_gate "https://github.com/harshtomar1234/tennis-vision/blob/main/utils/court_validity.py"
click node_player_gate "https://github.com/harshtomar1234/tennis-vision/blob/main/utils/player_selection.py"
click node_physics "https://github.com/harshtomar1234/tennis-vision/blob/main/utils/shot_physics.py"
click node_homography "https://github.com/harshtomar1234/tennis-vision/blob/main/mini_visual_court/mini_court.py"
click node_serve "https://github.com/harshtomar1234/tennis-vision/blob/main/utils/serve_detector.py"
click node_serve_landing "https://github.com/harshtomar1234/tennis-vision/blob/main/utils/serve_landing.py"
click node_serve_speed "https://github.com/harshtomar1234/tennis-vision/blob/main/utils/serve_speed.py"
click node_shot "https://github.com/harshtomar1234/tennis-vision/blob/main/utils/shot_classifier.py"
click node_trajectory "https://github.com/harshtomar1234/tennis-vision/blob/main/utils/trajectory_3d.py"
click node_audit "https://github.com/harshtomar1234/tennis-vision/blob/main/utils/rally_audit.py"
click node_annotated "https://github.com/harshtomar1234/tennis-vision/blob/main/main.py"
click node_viewer "https://github.com/harshtomar1234/tennis-vision/blob/main/utils/viewer_3d.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_pipeline,node_players,node_ball,node_court,node_fps toneBlue
class node_candidates,node_event_classifier,node_rally,node_court_gate,node_player_gate,node_physics toneAmber
class node_homography,node_serve,node_serve_landing,node_serve_speed,node_shot,node_trajectory,node_audit toneMint
class node_annotated,node_viewer toneRose
class node_video toneIndigo
```

## Components

### Detection

- [Analysis pipeline](https://github.com/harshtomar1234/tennis-vision/blob/main/main.py): `main.py`
- [Player tracking](https://github.com/harshtomar1234/tennis-vision/blob/main/trackers/player_tracker.py): `trackers/player_tracker.py`
- [Ball tracking](https://github.com/harshtomar1234/tennis-vision/blob/main/trackers/tracknet_ball_tracker.py): `trackers/tracknet_ball_tracker.py`
- [Court keypoints](https://github.com/harshtomar1234/tennis-vision/blob/main/court_line_detector/court_line_detector.py): `court_line_detector/court_line_detector.py`
- [FPS support](https://github.com/harshtomar1234/tennis-vision/blob/main/utils/fps_support.py): `utils/fps_support.py`

### Evidence and events

- [Event candidates](https://github.com/harshtomar1234/tennis-vision/blob/main/utils/bounce_candidates.py): `utils/bounce_candidates.py`
- [Hit/bounce classifier](https://github.com/harshtomar1234/tennis-vision/blob/main/utils/hit_bounce_classifier.py): `utils/hit_bounce_classifier.py`
- [Rally decoding](https://github.com/harshtomar1234/tennis-vision/blob/main/utils/rally_decode.py): `utils/rally_decode.py`
- [Court validity gate](https://github.com/harshtomar1234/tennis-vision/blob/main/utils/court_validity.py): `utils/court_validity.py`
- [Player selection](https://github.com/harshtomar1234/tennis-vision/blob/main/utils/player_selection.py): `utils/player_selection.py`
- [Physics validation](https://github.com/harshtomar1234/tennis-vision/blob/main/utils/shot_physics.py): `utils/shot_physics.py`

### Measurement

- [Court homography](https://github.com/harshtomar1234/tennis-vision/blob/main/mini_visual_court/mini_court.py): `mini_visual_court/mini_court.py`
- [Serve detection](https://github.com/harshtomar1234/tennis-vision/blob/main/utils/serve_detector.py): `utils/serve_detector.py`
- [Serve landing](https://github.com/harshtomar1234/tennis-vision/blob/main/utils/serve_landing.py): `utils/serve_landing.py`
- [Serve speed](https://github.com/harshtomar1234/tennis-vision/blob/main/utils/serve_speed.py): `utils/serve_speed.py`
- [Shot classification](https://github.com/harshtomar1234/tennis-vision/blob/main/utils/shot_classifier.py): `utils/shot_classifier.py`
- [3-D reconstruction](https://github.com/harshtomar1234/tennis-vision/blob/main/utils/trajectory_3d.py): `utils/trajectory_3d.py`
- [Rally evidence audit](https://github.com/harshtomar1234/tennis-vision/blob/main/utils/rally_audit.py): `utils/rally_audit.py`

### Results

- [Annotated video](https://github.com/harshtomar1234/tennis-vision/blob/main/main.py): `main.py`
- [Interactive 3-D viewer](https://github.com/harshtomar1234/tennis-vision/blob/main/utils/viewer_3d.py): `utils/viewer_3d.py`

### Other components

- **Broadcast video**

## Connections

- Broadcast video → Analysis pipeline: analyzed by (evidence: `README.md`)
- Analysis pipeline → FPS support: checks frame rate (evidence: `README.md`)
- Analysis pipeline → Player tracking: tracks players (evidence: `README.md`)
- Analysis pipeline → Ball tracking: tracks ball (evidence: `README.md`)
- Analysis pipeline → Court keypoints: detects keypoints (evidence: `README.md`)
- Analysis pipeline → Court validity gate: validates court (evidence: `README.md`)
- Analysis pipeline → Player selection: selects players (evidence: `README.md`)
- Analysis pipeline → Event candidates: generates candidates (evidence: `README.md`)
- Analysis pipeline → Rally decoding: decodes events (evidence: `README.md`)
- Event candidates → Hit/bounce classifier: classifies events (evidence: `README.md`)
- Analysis pipeline → Hit/bounce classifier: classifies events (evidence: `README.md`)
- Analysis pipeline → Court homography: maps court geometry (evidence: `README.md`)
- Analysis pipeline → Serve detection: detects serves (evidence: `README.md`)
- Analysis pipeline → Serve landing: checks landing (evidence: `README.md`)
- Analysis pipeline → Serve speed: measures serve speed (evidence: `README.md`)
- Analysis pipeline → Shot classification: classifies shots (evidence: `README.md`)
- Analysis pipeline → Physics validation: validates measurements (evidence: `README.md`)
- Analysis pipeline → 3-D reconstruction: reconstructs flights (evidence: `README.md`)
- Analysis pipeline → Rally evidence audit: audits evidence (evidence: `README.md`)
- Rally decoding → Shot classification: supplies events (evidence: `README.md`)
- Court validity gate → Court homography: gates geometry (evidence: `README.md`)
- Player selection → Court homography: gates geometry (evidence: `README.md`)
- Shot classification → Physics validation: checks evidence (evidence: `README.md`)
- Physics validation → 3-D reconstruction: validates flight (evidence: `README.md`)
- Analysis pipeline → Annotated video: renders analysis (evidence: `README.md`)
- Analysis pipeline → Interactive 3-D viewer: creates viewer (evidence: `README.md`)
- 3-D reconstruction → Interactive 3-D viewer: shows reconstruction (evidence: `README.md`)
