# namanhvu29/football-player-analysis architecture

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

- Interactive diagram: https://gitdiagram.com/namanhvu29/football-player-analysis
- Repository: https://github.com/namanhvu29/football-player-analysis

## Overview

This is a football-video analytics application. Its main workflow reads footage, detects and tracks players, referees, and the ball, then enriches tracks with camera compensation, pitch coordinates, team identity, possession, and movement statistics before rendering and saving an annotated video. The graph emphasizes the orchestration in main.py and the README’s major capabilities. Some subsystems, including model inference details beyond the sampled tracker source, are represented only where supported by the README or repository tree.

Main entry points: [`main.py`](https://github.com/namanhvu29/football-player-analysis/blob/main/main.py) (Analysis orchestration), [`trackers/tracker.py`](https://github.com/namanhvu29/football-player-analysis/blob/main/trackers/tracker.py) (Detection and tracking), [`utils/video_utils.py`](https://github.com/namanhvu29/football-player-analysis/blob/main/utils/video_utils.py) (Video I/O), [`input_videos`](https://github.com/namanhvu29/football-player-analysis/tree/main/input_videos) (Input footage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Video workflow"]
  node_main["Analysis orchestration<br/>[main.py]"]
  node_video_io["Video I/O<br/>[video_utils.py]"]
  node_tracker["Detection and tracking<br/>[tracker.py]"]
  node_model_weights["YOLO weights<br/>[best.pt]"]
  node_track_cache["Track cache<br/>[track_stubs.pkl]"]
end

subgraph group_analysis["Track analysis"]
  node_camera["Camera motion"]
  node_view["Pitch transformation"]
  node_speed["Speed and distance"]
  node_teams["Team assignment<br/>[team_assign.py]"]
  node_possession["Ball possession"]
  node_geometry["Bounding-box utilities<br/>[bbox_utils.py]"]
end

subgraph group_rendering["Output rendering"]
  node_renderer["Track annotations<br/>[tracker.py]"]
  node_camera_overlay["Camera overlay"]
  node_stats_overlay["Statistics overlay"]
end

node_operator(("Analyst"))
node_input_video["Input footage"]
node_output_video["Annotated video"]

node_operator -->|"runs analysis"| node_main
node_main -->|"calls read"| node_video_io
node_input_video -->|"provides frames"| node_video_io
node_main -->|"requests tracks"| node_tracker
node_tracker -->|"loads weights"| node_model_weights
node_tracker -.->|"reads or writes"| node_track_cache
node_tracker -->|"uses geometry"| node_geometry
node_main -->|"estimates motion"| node_camera
node_main -->|"transforms positions"| node_view
node_main -->|"calculates statistics"| node_speed
node_main -->|"assigns teams"| node_teams
node_main -->|"assigns possession"| node_possession
node_main -->|"draws tracks"| node_renderer
node_main -->|"draws motion"| node_camera_overlay
node_main -->|"draws statistics"| node_stats_overlay
node_main -->|"calls save"| node_video_io
node_video_io -->|"writes video"| node_output_video

click node_input_video "https://github.com/namanhvu29/football-player-analysis/tree/main/input_videos"
click node_main "https://github.com/namanhvu29/football-player-analysis/blob/main/main.py"
click node_video_io "https://github.com/namanhvu29/football-player-analysis/blob/main/utils/video_utils.py"
click node_tracker "https://github.com/namanhvu29/football-player-analysis/blob/main/trackers/tracker.py"
click node_model_weights "https://github.com/namanhvu29/football-player-analysis/blob/main/models/best.pt"
click node_track_cache "https://github.com/namanhvu29/football-player-analysis/blob/main/stubs/track_stubs.pkl"
click node_camera "https://github.com/namanhvu29/football-player-analysis/blob/main/camera_movement_estimator/camera_movement_estimator.py"
click node_view "https://github.com/namanhvu29/football-player-analysis/blob/main/view_transformer/view_transformer.py"
click node_speed "https://github.com/namanhvu29/football-player-analysis/blob/main/speed_and_distance_estimator/speed_and_distance_estimator.py"
click node_teams "https://github.com/namanhvu29/football-player-analysis/blob/main/team_assigment/team_assign.py"
click node_possession "https://github.com/namanhvu29/football-player-analysis/blob/main/player_ball_assigner/player_ball_assigner.py"
click node_geometry "https://github.com/namanhvu29/football-player-analysis/blob/main/utils/bbox_utils.py"
click node_renderer "https://github.com/namanhvu29/football-player-analysis/blob/main/trackers/tracker.py"
click node_camera_overlay "https://github.com/namanhvu29/football-player-analysis/blob/main/camera_movement_estimator/camera_movement_estimator.py"
click node_stats_overlay "https://github.com/namanhvu29/football-player-analysis/blob/main/speed_and_distance_estimator/speed_and_distance_estimator.py"
click node_output_video "https://github.com/namanhvu29/football-player-analysis/tree/main/output_videos"

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_tracker,node_model_weights,node_track_cache toneBlue
class node_camera,node_view,node_speed,node_teams,node_possession,node_geometry toneAmber
class node_renderer,node_camera_overlay,node_stats_overlay toneMint
class node_operator toneIndigo
class node_input_video,node_output_video toneTeal
```

## Components

### Video workflow

- [Analysis orchestration](https://github.com/namanhvu29/football-player-analysis/blob/main/main.py): `main.py`
- [Video I/O](https://github.com/namanhvu29/football-player-analysis/blob/main/utils/video_utils.py): `utils/video_utils.py`
- [Detection and tracking](https://github.com/namanhvu29/football-player-analysis/blob/main/trackers/tracker.py): `trackers/tracker.py`
- [YOLO weights](https://github.com/namanhvu29/football-player-analysis/blob/main/models/best.pt): `models/best.pt`
- [Track cache](https://github.com/namanhvu29/football-player-analysis/blob/main/stubs/track_stubs.pkl): `stubs/track_stubs.pkl`

### Track analysis

- [Camera motion](https://github.com/namanhvu29/football-player-analysis/blob/main/camera_movement_estimator/camera_movement_estimator.py): `camera_movement_estimator/camera_movement_estimator.py`
- [Pitch transformation](https://github.com/namanhvu29/football-player-analysis/blob/main/view_transformer/view_transformer.py): `view_transformer/view_transformer.py`
- [Speed and distance](https://github.com/namanhvu29/football-player-analysis/blob/main/speed_and_distance_estimator/speed_and_distance_estimator.py): `speed_and_distance_estimator/speed_and_distance_estimator.py`
- [Team assignment](https://github.com/namanhvu29/football-player-analysis/blob/main/team_assigment/team_assign.py): `team_assigment/team_assign.py`
- [Ball possession](https://github.com/namanhvu29/football-player-analysis/blob/main/player_ball_assigner/player_ball_assigner.py): `player_ball_assigner/player_ball_assigner.py`
- [Bounding-box utilities](https://github.com/namanhvu29/football-player-analysis/blob/main/utils/bbox_utils.py): `utils/bbox_utils.py`

### Output rendering

- [Track annotations](https://github.com/namanhvu29/football-player-analysis/blob/main/trackers/tracker.py): `trackers/tracker.py`
- [Camera overlay](https://github.com/namanhvu29/football-player-analysis/blob/main/camera_movement_estimator/camera_movement_estimator.py): `camera_movement_estimator/camera_movement_estimator.py`
- [Statistics overlay](https://github.com/namanhvu29/football-player-analysis/blob/main/speed_and_distance_estimator/speed_and_distance_estimator.py): `speed_and_distance_estimator/speed_and_distance_estimator.py`

### Other components

- **Analyst**
- [Input footage](https://github.com/namanhvu29/football-player-analysis/tree/main/input_videos): `input_videos`
- [Annotated video](https://github.com/namanhvu29/football-player-analysis/tree/main/output_videos): `output_videos`

## Connections

- Analyst → Analysis orchestration: runs analysis
- Analysis orchestration → Video I/O: calls read
- Input footage → Video I/O: provides frames
- Analysis orchestration → Detection and tracking: requests tracks
- Detection and tracking → YOLO weights: loads weights
- Detection and tracking → Track cache: reads or writes
- Detection and tracking → Bounding-box utilities: uses geometry
- Analysis orchestration → Camera motion: estimates motion
- Analysis orchestration → Pitch transformation: transforms positions
- Analysis orchestration → Speed and distance: calculates statistics
- Analysis orchestration → Team assignment: assigns teams
- Analysis orchestration → Ball possession: assigns possession
- Analysis orchestration → Track annotations: draws tracks
- Analysis orchestration → Camera overlay: draws motion
- Analysis orchestration → Statistics overlay: draws statistics
- Analysis orchestration → Video I/O: calls save
- Video I/O → Annotated video: writes video