# ssunsonic/basketball architecture

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

- Interactive diagram: https://gitdiagram.com/ssunsonic/basketball
- Repository: https://github.com/ssunsonic/basketball

## Overview

VizBuckets processes basketball video or camera input to detect players, the ball, rim and shot events; it tracks player identities, attributes attempts and makes, draws trajectory and score overlays, and writes an annotated video. SORT supplies multi-object identity tracking. The README also describes single-player/1v1 tracking and shot-trajectory mapping. Source excerpts show the main processing and SORT calls, but omit some wiring; the court-line utility is not documented as an active workflow, so it is not connected here.

Main entry points: [`src/main.py`](https://github.com/ssunsonic/basketball/blob/main/src/main.py) (Tracking application), [`sort/sort.py`](https://github.com/ssunsonic/basketball/blob/main/sort/sort.py) (SORT tracker), [`src/utils/output.py`](https://github.com/ssunsonic/basketball/blob/main/src/utils/output.py) (Output naming), [`src/utils/distances.py`](https://github.com/ssunsonic/basketball/blob/main/src/utils/distances.py) (Distance helpers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Video tracking"]
  node_main["Tracking application<br/>[main.py]"]
  node_detector["YOLO detection"]
  node_filename["Output naming<br/>[output.py]"]
end

subgraph group_logic["Shot analysis"]
  node_shot["Shot event logic<br/>[main.py]"]
  node_metrics["Player shot metrics<br/>[main.py]"]
  node_distance["Distance helpers<br/>[distances.py]"]
end

subgraph group_tracking["Player tracking"]
  node_sort["SORT tracker<br/>[sort.py]"]
  node_positions["Player positions<br/>[main.py]"]
end

subgraph group_visual["Visualization"]
  node_trajectory["Shot trajectory<br/>[trajectory.py]"]
  node_overlay["Frame overlays<br/>[main.py]"]
end

node_input(("Video or camera"))
node_videoout["Annotated video"]

node_input -->|"supplies frames"| node_main
node_main -->|"runs detection"| node_detector
node_main -->|"handles detections"| node_shot
node_main -->|"updates tracks"| node_sort
node_sort -->|"returns identities"| node_positions
node_main -->|"updates positions"| node_positions
node_shot -->|"checks distances"| node_distance
node_shot -->|"updates counts"| node_metrics
node_main -->|"draws trajectory"| node_trajectory
node_main -->|"draws interface"| node_overlay
node_main -->|"chooses output path"| node_filename
node_main -->|"writes frames"| node_videoout

click node_main "https://github.com/ssunsonic/basketball/blob/main/src/main.py"
click node_shot "https://github.com/ssunsonic/basketball/blob/main/src/main.py"
click node_metrics "https://github.com/ssunsonic/basketball/blob/main/src/main.py"
click node_sort "https://github.com/ssunsonic/basketball/blob/main/sort/sort.py"
click node_positions "https://github.com/ssunsonic/basketball/blob/main/src/main.py"
click node_distance "https://github.com/ssunsonic/basketball/blob/main/src/utils/distances.py"
click node_trajectory "https://github.com/ssunsonic/basketball/blob/main/src/utils/trajectory.py"
click node_overlay "https://github.com/ssunsonic/basketball/blob/main/src/main.py"
click node_filename "https://github.com/ssunsonic/basketball/blob/main/src/utils/output.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_main,node_detector,node_filename toneBlue
class node_shot,node_metrics,node_distance toneAmber
class node_sort,node_positions toneMint
class node_trajectory,node_overlay toneRose
class node_input,node_videoout toneIndigo
```

## Components

### Video tracking

- [Tracking application](https://github.com/ssunsonic/basketball/blob/main/src/main.py): `src/main.py`
- **YOLO detection**
- [Output naming](https://github.com/ssunsonic/basketball/blob/main/src/utils/output.py): `src/utils/output.py`

### Shot analysis

- [Shot event logic](https://github.com/ssunsonic/basketball/blob/main/src/main.py): `src/main.py`
- [Player shot metrics](https://github.com/ssunsonic/basketball/blob/main/src/main.py): `src/main.py`
- [Distance helpers](https://github.com/ssunsonic/basketball/blob/main/src/utils/distances.py): `src/utils/distances.py`

### Player tracking

- [SORT tracker](https://github.com/ssunsonic/basketball/blob/main/sort/sort.py): `sort/sort.py`
- [Player positions](https://github.com/ssunsonic/basketball/blob/main/src/main.py): `src/main.py`

### Visualization

- [Shot trajectory](https://github.com/ssunsonic/basketball/blob/main/src/utils/trajectory.py): `src/utils/trajectory.py`
- [Frame overlays](https://github.com/ssunsonic/basketball/blob/main/src/main.py): `src/main.py`

### Other components

- **Video or camera**
- **Annotated video**

## Connections

- Video or camera → Tracking application: supplies frames
- Tracking application → YOLO detection: runs detection
- Tracking application → Shot event logic: handles detections
- Tracking application → SORT tracker: updates tracks
- SORT tracker → Player positions: returns identities
- Tracking application → Player positions: updates positions
- Shot event logic → Distance helpers: checks distances
- Shot event logic → Player shot metrics: updates counts
- Tracking application → Shot trajectory: draws trajectory
- Tracking application → Frame overlays: draws interface
- Tracking application → Output naming: chooses output path
- Tracking application → Annotated video: writes frames