# abdullahtarek/basketball_analysis architecture

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

- Interactive diagram: https://gitdiagram.com/abdullahtarek/basketball_analysis
- Repository: https://github.com/abdullahtarek/basketball_analysis

## Overview

This is a basketball video-analysis application: a user supplies game footage, and the pipeline produces an annotated video with tracked players and ball, court keypoints, team assignments, possession and event statistics, and movement metrics. The README documents the overall orchestration; the sampled source confirms several detector, tracker, and analytics responsibilities. Some main.py sections and several drawer implementations were not sampled, so those connections rely on README documentation rather than direct call excerpts.

Main entry points: [`main.py`](https://github.com/abdullahtarek/basketball_analysis/blob/main/main.py) (Pipeline orchestration), [`utils/stubs_utils.py`](https://github.com/abdullahtarek/basketball_analysis/blob/main/utils/stubs_utils.py) (Stub cache), [`trackers/player_tracker.py`](https://github.com/abdullahtarek/basketball_analysis/blob/main/trackers/player_tracker.py) (Player tracking), [`trackers/ball_tracker.py`](https://github.com/abdullahtarek/basketball_analysis/blob/main/trackers/ball_tracker.py) (Ball tracking)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_pipeline["Video pipeline"]
  node_main["Pipeline orchestration<br/>[main.py]"]
  node_video_io["Video I/O<br/>[video_utils.py]"]
  node_stubs["Stub cache<br/>[stubs_utils.py]"]
end

subgraph group_tracking["Detection and tracking"]
  node_player_tracker["Player tracking<br/>[player_tracker.py]"]
  node_ball_tracker["Ball tracking<br/>[ball_tracker.py]"]
  node_court_detector["Court keypoints"]
end

subgraph group_analysis["Game analysis"]
  node_team_assigner["Team assignment<br/>[team_assigner.py]"]
  node_possession["Ball possession"]
  node_pass_interception["Passes and interceptions"]
  node_tactical_converter["Tactical court mapping"]
  node_homography["Homography<br/>[homography.py]"]
  node_speed_distance["Speed and distance"]
  node_bbox_utils["Bounding-box geometry<br/>[bbox_utils.py]"]
end

subgraph group_visualization["Visualization"]
  node_player_drawer["Player overlays"]
  node_ball_drawer["Ball overlays"]
  node_court_drawer["Court overlays"]
  node_team_control_drawer["Team control overlay"]
  node_pass_drawer["Event statistics overlay"]
  node_speed_drawer["Movement metrics overlay"]
  node_tactical_drawer["Tactical view overlay"]
  node_frame_drawer["Frame numbering"]
end

node_user(("Video analyst"))

node_user -->|"supplies video"| node_main
node_main -->|"reads and saves"| node_video_io
node_main -->|"tracks players"| node_player_tracker
node_main -->|"tracks ball"| node_ball_tracker
node_main -->|"detects keypoints"| node_court_detector
node_main -->|"assigns teams"| node_team_assigner
node_main -->|"finds possession"| node_possession
node_main -->|"detects events"| node_pass_interception
node_main -->|"maps court positions"| node_tactical_converter
node_main -->|"calculates movement"| node_speed_distance
node_main -->|"draws annotations"| node_player_drawer
node_main -->|"draws annotations"| node_ball_drawer
node_main -->|"draws annotations"| node_court_drawer
node_main -->|"draws annotations"| node_team_control_drawer
node_main -->|"draws event stats"| node_pass_drawer
node_main -->|"draws movement stats"| node_speed_drawer
node_main -->|"draws tactical view"| node_tactical_drawer
node_main -->|"draws frame numbers"| node_frame_drawer
node_player_tracker -->|"reads and writes"| node_stubs
node_ball_tracker -->|"reads and writes"| node_stubs
node_court_detector -->|"reads and writes"| node_stubs
node_team_assigner -->|"reads and writes"| node_stubs
node_possession -->|"uses geometry"| node_bbox_utils
node_tactical_converter -->|"uses transform"| node_homography
node_speed_distance -->|"uses distance"| node_bbox_utils

click node_main "https://github.com/abdullahtarek/basketball_analysis/blob/main/main.py"
click node_video_io "https://github.com/abdullahtarek/basketball_analysis/blob/main/utils/video_utils.py"
click node_stubs "https://github.com/abdullahtarek/basketball_analysis/blob/main/utils/stubs_utils.py"
click node_player_tracker "https://github.com/abdullahtarek/basketball_analysis/blob/main/trackers/player_tracker.py"
click node_ball_tracker "https://github.com/abdullahtarek/basketball_analysis/blob/main/trackers/ball_tracker.py"
click node_court_detector "https://github.com/abdullahtarek/basketball_analysis/blob/main/court_keypoint_detector/court_keypoint_detector.py"
click node_team_assigner "https://github.com/abdullahtarek/basketball_analysis/blob/main/team_assigner/team_assigner.py"
click node_possession "https://github.com/abdullahtarek/basketball_analysis/blob/main/ball_aquisition/ball_aquisition_detector.py"
click node_pass_interception "https://github.com/abdullahtarek/basketball_analysis/blob/main/pass_and_interception_detector/pass_and_interception_detector.py"
click node_tactical_converter "https://github.com/abdullahtarek/basketball_analysis/blob/main/tactical_view_converter/tactical_view_converter.py"
click node_homography "https://github.com/abdullahtarek/basketball_analysis/blob/main/tactical_view_converter/homography.py"
click node_speed_distance "https://github.com/abdullahtarek/basketball_analysis/blob/main/speed_and_distance_calculator/speed_and_distance_calculator.py"
click node_bbox_utils "https://github.com/abdullahtarek/basketball_analysis/blob/main/utils/bbox_utils.py"
click node_player_drawer "https://github.com/abdullahtarek/basketball_analysis/blob/main/drawers/player_tracks_drawer.py"
click node_ball_drawer "https://github.com/abdullahtarek/basketball_analysis/blob/main/drawers/ball_tracks_drawer.py"
click node_court_drawer "https://github.com/abdullahtarek/basketball_analysis/blob/main/drawers/court_key_points_drawer.py"
click node_team_control_drawer "https://github.com/abdullahtarek/basketball_analysis/blob/main/drawers/team_ball_control_drawer.py"
click node_pass_drawer "https://github.com/abdullahtarek/basketball_analysis/blob/main/drawers/pass_and_interceptions_drawer.py"
click node_speed_drawer "https://github.com/abdullahtarek/basketball_analysis/blob/main/drawers/speed_and_distance_drawer.py"
click node_tactical_drawer "https://github.com/abdullahtarek/basketball_analysis/blob/main/drawers/tactical_view_drawer.py"
click node_frame_drawer "https://github.com/abdullahtarek/basketball_analysis/blob/main/drawers/frame_number_drawer.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_video_io,node_stubs toneBlue
class node_player_tracker,node_ball_tracker,node_court_detector toneAmber
class node_team_assigner,node_possession,node_pass_interception,node_tactical_converter,node_homography,node_speed_distance,node_bbox_utils toneMint
class node_player_drawer,node_ball_drawer,node_court_drawer,node_team_control_drawer,node_pass_drawer,node_speed_drawer,node_tactical_drawer,node_frame_drawer toneRose
class node_user toneIndigo
```

## Components

### Video pipeline

- [Pipeline orchestration](https://github.com/abdullahtarek/basketball_analysis/blob/main/main.py): `main.py`
- [Video I/O](https://github.com/abdullahtarek/basketball_analysis/blob/main/utils/video_utils.py): `utils/video_utils.py`
- [Stub cache](https://github.com/abdullahtarek/basketball_analysis/blob/main/utils/stubs_utils.py): `utils/stubs_utils.py`

### Detection and tracking

- [Player tracking](https://github.com/abdullahtarek/basketball_analysis/blob/main/trackers/player_tracker.py): `trackers/player_tracker.py`
- [Ball tracking](https://github.com/abdullahtarek/basketball_analysis/blob/main/trackers/ball_tracker.py): `trackers/ball_tracker.py`
- [Court keypoints](https://github.com/abdullahtarek/basketball_analysis/blob/main/court_keypoint_detector/court_keypoint_detector.py): `court_keypoint_detector/court_keypoint_detector.py`

### Game analysis

- [Team assignment](https://github.com/abdullahtarek/basketball_analysis/blob/main/team_assigner/team_assigner.py): `team_assigner/team_assigner.py`
- [Ball possession](https://github.com/abdullahtarek/basketball_analysis/blob/main/ball_aquisition/ball_aquisition_detector.py): `ball_aquisition/ball_aquisition_detector.py`
- [Passes and interceptions](https://github.com/abdullahtarek/basketball_analysis/blob/main/pass_and_interception_detector/pass_and_interception_detector.py): `pass_and_interception_detector/pass_and_interception_detector.py`
- [Tactical court mapping](https://github.com/abdullahtarek/basketball_analysis/blob/main/tactical_view_converter/tactical_view_converter.py): `tactical_view_converter/tactical_view_converter.py`
- [Homography](https://github.com/abdullahtarek/basketball_analysis/blob/main/tactical_view_converter/homography.py): `tactical_view_converter/homography.py`
- [Speed and distance](https://github.com/abdullahtarek/basketball_analysis/blob/main/speed_and_distance_calculator/speed_and_distance_calculator.py): `speed_and_distance_calculator/speed_and_distance_calculator.py`
- [Bounding-box geometry](https://github.com/abdullahtarek/basketball_analysis/blob/main/utils/bbox_utils.py): `utils/bbox_utils.py`

### Visualization

- [Player overlays](https://github.com/abdullahtarek/basketball_analysis/blob/main/drawers/player_tracks_drawer.py): `drawers/player_tracks_drawer.py`
- [Ball overlays](https://github.com/abdullahtarek/basketball_analysis/blob/main/drawers/ball_tracks_drawer.py): `drawers/ball_tracks_drawer.py`
- [Court overlays](https://github.com/abdullahtarek/basketball_analysis/blob/main/drawers/court_key_points_drawer.py): `drawers/court_key_points_drawer.py`
- [Team control overlay](https://github.com/abdullahtarek/basketball_analysis/blob/main/drawers/team_ball_control_drawer.py): `drawers/team_ball_control_drawer.py`
- [Event statistics overlay](https://github.com/abdullahtarek/basketball_analysis/blob/main/drawers/pass_and_interceptions_drawer.py): `drawers/pass_and_interceptions_drawer.py`
- [Movement metrics overlay](https://github.com/abdullahtarek/basketball_analysis/blob/main/drawers/speed_and_distance_drawer.py): `drawers/speed_and_distance_drawer.py`
- [Tactical view overlay](https://github.com/abdullahtarek/basketball_analysis/blob/main/drawers/tactical_view_drawer.py): `drawers/tactical_view_drawer.py`
- [Frame numbering](https://github.com/abdullahtarek/basketball_analysis/blob/main/drawers/frame_number_drawer.py): `drawers/frame_number_drawer.py`

### Other components

- **Video analyst**

## Connections

- Video analyst → Pipeline orchestration: supplies video (evidence: `README.md`)
- Pipeline orchestration → Video I/O: reads and saves (evidence: `main.py`)
- Pipeline orchestration → Player tracking: tracks players (evidence: `main.py`)
- Pipeline orchestration → Ball tracking: tracks ball (evidence: `main.py`)
- Pipeline orchestration → Court keypoints: detects keypoints (evidence: `main.py`)
- Pipeline orchestration → Team assignment: assigns teams (evidence: `main.py`)
- Pipeline orchestration → Ball possession: finds possession (evidence: `README.md`)
- Pipeline orchestration → Passes and interceptions: detects events (evidence: `README.md`)
- Pipeline orchestration → Tactical court mapping: maps court positions (evidence: `main.py`)
- Pipeline orchestration → Speed and distance: calculates movement (evidence: `main.py`)
- Pipeline orchestration → Player overlays: draws annotations (evidence: `README.md`)
- Pipeline orchestration → Ball overlays: draws annotations (evidence: `README.md`)
- Pipeline orchestration → Court overlays: draws annotations (evidence: `README.md`)
- Pipeline orchestration → Team control overlay: draws annotations (evidence: `README.md`)
- Pipeline orchestration → Event statistics overlay: draws event stats (evidence: `README.md`)
- Pipeline orchestration → Movement metrics overlay: draws movement stats (evidence: `README.md`)
- Pipeline orchestration → Tactical view overlay: draws tactical view (evidence: `README.md`)
- Pipeline orchestration → Frame numbering: draws frame numbers (evidence: `README.md`)
- Player tracking → Stub cache: reads and writes (evidence: `trackers/player_tracker.py`)
- Ball tracking → Stub cache: reads and writes (evidence: `trackers/ball_tracker.py`)
- Court keypoints → Stub cache: reads and writes (evidence: `court_keypoint_detector/court_keypoint_detector.py`)
- Team assignment → Stub cache: reads and writes (evidence: `team_assigner/team_assigner.py`)
- Ball possession → Bounding-box geometry: uses geometry (evidence: `ball_aquisition/ball_aquisition_detector.py`)
- Tactical court mapping → Homography: uses transform (evidence: `tactical_view_converter/tactical_view_converter.py`)
- Speed and distance → Bounding-box geometry: uses distance (evidence: `speed_and_distance_calculator/speed_and_distance_calculator.py`)
