# thaonan/tracknetv5-sdk architecture

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

- Interactive diagram: https://gitdiagram.com/thaonan/tracknetv5-sdk
- Repository: https://github.com/thaonan/tracknetv5-sdk

## Overview

TrackNetV5 SDK supports tennis-ball detection and tracking, with V2/V4/WASB variants, Gaussian-heatmap data preparation, model training and video inference. The documented inference workflow processes video with a selected architecture and exports coordinates and visualizations; a separate core pipeline explicitly sequences detection, trajectory refinement and rendering. Training is configured through the factory-based runner. Edges are limited to README statements and shown calls or references; unsampled implementation details are not assumed.

Main entry points: [`models_factory/builder.py`](https://github.com/thaonan/tracknetv5-sdk/blob/main/models_factory/builder.py) (Model Factory), [`train.py`](https://github.com/thaonan/tracknetv5-sdk/blob/main/train.py) (Training Entry), [`engine/runner.py`](https://github.com/thaonan/tracknetv5-sdk/blob/main/engine/runner.py) (Training Runner), [`core/pipeline.py`](https://github.com/thaonan/tracknetv5-sdk/blob/main/core/pipeline.py) (Tennis Pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inference["Inference and Tracking"]
  node_track_cli["Video Inference<br/>[track.py]"]
  node_infer_cli["Inference Module<br/>[infer.py]"]
  node_coords_metric["Heatmap Metrics"]
end

subgraph group_data["Data Preparation"]
  node_prep["Gaussian Preprocessing"]
  node_dataset["Tennis Dataset<br/>[tennis_dataset.py]"]
  node_transforms["Frame Transforms"]
  node_data_factory["Dataset Factory<br/>[builder.py]"]
end

subgraph group_models["Model Components"]
  node_model_factory["Model Factory<br/>[builder.py]"]
  node_tracknet_v2["TrackNet V2<br/>[tracknetv2.py]"]
  node_tracknet_v4["TrackNet V4<br/>[tracknetv4.py]"]
  node_tracknet_v5["TrackNet V5<br/>[tracknetv5.py]"]
  node_wasb["WASB Model<br/>[wasb.py]"]
  node_hrnet["WASB HRNet"]
  node_mdd["Motion Decoupling<br/>[mdd.py]"]
  node_residual_head["Residual Refinement Head<br/>[r_strhead.py]"]
end

subgraph group_training["Training and Evaluation"]
  node_train_cli["Training Entry<br/>[train.py]"]
  node_configs["Model Configurations"]
  node_runner["Training Runner<br/>[runner.py]"]
  node_engine_factory["Engine Factory<br/>[builder.py]"]
  node_loss["Training Loss<br/>[tracknetv2_loss.py]"]
  node_metric["Training Metric"]
  node_optimizer_factory["Optimizer Factory<br/>[builder.py]"]
  node_hooks["Visualization Hook"]
end

subgraph group_pipeline["Detection Pipeline"]
  node_pipeline["Tennis Pipeline<br/>[pipeline.py]"]
  node_detector["Video Detector<br/>[detector.py]"]
  node_tracker["Trajectory Tracker<br/>[base.py]"]
  node_visualizer["Video Visualizer<br/>[visualizer.py]"]
end

node_user(("Video User"))
node_video_user(("Pipeline Caller"))
node_video_results["Video Results"]
node_inference_results["Inference Exports"]

node_user -->|"runs on videos"| node_track_cli
node_track_cli -->|"builds architecture"| node_model_factory
node_track_cli -->|"uses transforms"| node_transforms
node_track_cli -->|"exports coordinates and video"| node_inference_results
node_infer_cli -->|"builds model"| node_model_factory
node_infer_cli -->|"uses transforms"| node_transforms
node_data_factory -->|"builds dataset"| node_dataset
node_data_factory -->|"builds transform pipeline"| node_transforms
node_model_factory -->|"registers model"| node_tracknet_v2
node_model_factory -->|"registers model"| node_tracknet_v4
node_model_factory -->|"registers model"| node_tracknet_v5
node_model_factory -->|"registers model"| node_wasb
node_train_cli -->|"starts training"| node_runner
node_train_cli -->|"loads configurations"| node_configs
node_train_cli -->|"constructs data"| node_data_factory
node_train_cli -->|"constructs model"| node_model_factory
node_train_cli -->|"constructs optimizer"| node_optimizer_factory
node_runner -.->|"computes loss"| node_loss
node_runner -.->|"evaluates predictions"| node_metric
node_runner -.->|"configures hooks"| node_engine_factory
node_runner -.->|"invokes hooks"| node_hooks
node_metric -->|"extracts centroids"| node_coords_metric
node_video_user -.->|"submits video"| node_pipeline
node_pipeline -->|"detects points"| node_detector
node_pipeline -->|"refines trajectory"| node_tracker
node_pipeline -->|"renders frames"| node_visualizer
node_pipeline -->|"saves refined video"| node_video_results
node_detector -->|"builds model"| node_model_factory
node_detector -->|"uses transforms"| node_transforms

click node_track_cli "https://github.com/thaonan/tracknetv5-sdk/blob/main/track.py"
click node_infer_cli "https://github.com/thaonan/tracknetv5-sdk/blob/main/infer.py"
click node_coords_metric "https://github.com/thaonan/tracknetv5-sdk/blob/main/metrics_factory/metrics/tracknetv2_metric.py"
click node_prep "https://github.com/thaonan/tracknetv5-sdk/blob/main/tools/preprocess_data_gauss.py"
click node_dataset "https://github.com/thaonan/tracknetv5-sdk/blob/main/datasets_factory/datasets/tennis_dataset.py"
click node_transforms "https://github.com/thaonan/tracknetv5-sdk/blob/main/datasets_factory/transforms/tracknet_transforms.py"
click node_data_factory "https://github.com/thaonan/tracknetv5-sdk/blob/main/datasets_factory/builder.py"
click node_model_factory "https://github.com/thaonan/tracknetv5-sdk/blob/main/models_factory/builder.py"
click node_tracknet_v2 "https://github.com/thaonan/tracknetv5-sdk/blob/main/models_factory/models/tracknetv2.py"
click node_tracknet_v4 "https://github.com/thaonan/tracknetv5-sdk/blob/main/models_factory/models/tracknetv4.py"
click node_tracknet_v5 "https://github.com/thaonan/tracknetv5-sdk/blob/main/models_factory/models/tracknetv5.py"
click node_wasb "https://github.com/thaonan/tracknetv5-sdk/blob/main/models_factory/models/wasb.py"
click node_hrnet "https://github.com/thaonan/tracknetv5-sdk/blob/main/models_factory/backbones/wasb_hrnet_backbone.py"
click node_mdd "https://github.com/thaonan/tracknetv5-sdk/blob/main/models_factory/basic/mdd.py"
click node_residual_head "https://github.com/thaonan/tracknetv5-sdk/blob/main/models_factory/heads/r_strhead.py"
click node_train_cli "https://github.com/thaonan/tracknetv5-sdk/blob/main/train.py"
click node_configs "https://github.com/thaonan/tracknetv5-sdk/tree/main/configs"
click node_runner "https://github.com/thaonan/tracknetv5-sdk/blob/main/engine/runner.py"
click node_engine_factory "https://github.com/thaonan/tracknetv5-sdk/blob/main/engine/builder.py"
click node_loss "https://github.com/thaonan/tracknetv5-sdk/blob/main/losses_factory/losses/tracknetv2_loss.py"
click node_metric "https://github.com/thaonan/tracknetv5-sdk/blob/main/metrics_factory/metrics/tracknetv2_metric.py"
click node_optimizer_factory "https://github.com/thaonan/tracknetv5-sdk/blob/main/optimizers_factory/builder.py"
click node_hooks "https://github.com/thaonan/tracknetv5-sdk/blob/main/engine/hooks/visualizer_v2_hook.py"
click node_pipeline "https://github.com/thaonan/tracknetv5-sdk/blob/main/core/pipeline.py"
click node_detector "https://github.com/thaonan/tracknetv5-sdk/blob/main/core/detector.py"
click node_tracker "https://github.com/thaonan/tracknetv5-sdk/blob/main/tracker/base.py"
click node_visualizer "https://github.com/thaonan/tracknetv5-sdk/blob/main/core/visualizer.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_track_cli,node_infer_cli,node_coords_metric,node_user toneBlue
class node_prep,node_dataset,node_transforms,node_data_factory toneAmber
class node_model_factory,node_tracknet_v2,node_tracknet_v4,node_tracknet_v5,node_wasb,node_hrnet,node_mdd,node_residual_head toneMint
class node_train_cli,node_configs,node_runner,node_engine_factory,node_loss,node_metric,node_optimizer_factory,node_hooks toneRose
class node_pipeline,node_detector,node_tracker,node_visualizer,node_video_user,node_video_results,node_inference_results toneIndigo
```

## Components

### Inference and Tracking

- [Video Inference](https://github.com/thaonan/tracknetv5-sdk/blob/main/track.py): `track.py`
- [Inference Module](https://github.com/thaonan/tracknetv5-sdk/blob/main/infer.py): `infer.py`
- [Heatmap Metrics](https://github.com/thaonan/tracknetv5-sdk/blob/main/metrics_factory/metrics/tracknetv2_metric.py): `metrics_factory/metrics/tracknetv2_metric.py`

### Data Preparation

- [Gaussian Preprocessing](https://github.com/thaonan/tracknetv5-sdk/blob/main/tools/preprocess_data_gauss.py): `tools/preprocess_data_gauss.py`
- [Tennis Dataset](https://github.com/thaonan/tracknetv5-sdk/blob/main/datasets_factory/datasets/tennis_dataset.py): `datasets_factory/datasets/tennis_dataset.py`
- [Frame Transforms](https://github.com/thaonan/tracknetv5-sdk/blob/main/datasets_factory/transforms/tracknet_transforms.py): `datasets_factory/transforms/tracknet_transforms.py`
- [Dataset Factory](https://github.com/thaonan/tracknetv5-sdk/blob/main/datasets_factory/builder.py): `datasets_factory/builder.py`

### Model Components

- [Model Factory](https://github.com/thaonan/tracknetv5-sdk/blob/main/models_factory/builder.py): `models_factory/builder.py`
- [TrackNet V2](https://github.com/thaonan/tracknetv5-sdk/blob/main/models_factory/models/tracknetv2.py): `models_factory/models/tracknetv2.py`
- [TrackNet V4](https://github.com/thaonan/tracknetv5-sdk/blob/main/models_factory/models/tracknetv4.py): `models_factory/models/tracknetv4.py`
- [TrackNet V5](https://github.com/thaonan/tracknetv5-sdk/blob/main/models_factory/models/tracknetv5.py): `models_factory/models/tracknetv5.py`
- [WASB Model](https://github.com/thaonan/tracknetv5-sdk/blob/main/models_factory/models/wasb.py): `models_factory/models/wasb.py`
- [WASB HRNet](https://github.com/thaonan/tracknetv5-sdk/blob/main/models_factory/backbones/wasb_hrnet_backbone.py): `models_factory/backbones/wasb_hrnet_backbone.py`
- [Motion Decoupling](https://github.com/thaonan/tracknetv5-sdk/blob/main/models_factory/basic/mdd.py): `models_factory/basic/mdd.py`
- [Residual Refinement Head](https://github.com/thaonan/tracknetv5-sdk/blob/main/models_factory/heads/r_strhead.py): `models_factory/heads/r_strhead.py`

### Training and Evaluation

- [Training Entry](https://github.com/thaonan/tracknetv5-sdk/blob/main/train.py): `train.py`
- [Model Configurations](https://github.com/thaonan/tracknetv5-sdk/tree/main/configs): `configs`
- [Training Runner](https://github.com/thaonan/tracknetv5-sdk/blob/main/engine/runner.py): `engine/runner.py`
- [Engine Factory](https://github.com/thaonan/tracknetv5-sdk/blob/main/engine/builder.py): `engine/builder.py`
- [Training Loss](https://github.com/thaonan/tracknetv5-sdk/blob/main/losses_factory/losses/tracknetv2_loss.py): `losses_factory/losses/tracknetv2_loss.py`
- [Training Metric](https://github.com/thaonan/tracknetv5-sdk/blob/main/metrics_factory/metrics/tracknetv2_metric.py): `metrics_factory/metrics/tracknetv2_metric.py`
- [Optimizer Factory](https://github.com/thaonan/tracknetv5-sdk/blob/main/optimizers_factory/builder.py): `optimizers_factory/builder.py`
- [Visualization Hook](https://github.com/thaonan/tracknetv5-sdk/blob/main/engine/hooks/visualizer_v2_hook.py): `engine/hooks/visualizer_v2_hook.py`

### Detection Pipeline

- [Tennis Pipeline](https://github.com/thaonan/tracknetv5-sdk/blob/main/core/pipeline.py): `core/pipeline.py`
- [Video Detector](https://github.com/thaonan/tracknetv5-sdk/blob/main/core/detector.py): `core/detector.py`
- [Trajectory Tracker](https://github.com/thaonan/tracknetv5-sdk/blob/main/tracker/base.py): `tracker/base.py`
- [Video Visualizer](https://github.com/thaonan/tracknetv5-sdk/blob/main/core/visualizer.py): `core/visualizer.py`

### Other components

- **Video User**
- **Pipeline Caller**
- **Video Results**
- **Inference Exports**

## Connections

- Video User → Video Inference: runs on videos (evidence: `README.md`)
- Video Inference → Model Factory: builds architecture (evidence: `track.py`)
- Video Inference → Frame Transforms: uses transforms (evidence: `track.py`)
- Video Inference → Inference Exports: exports coordinates and video (evidence: `README.md`)
- Inference Module → Model Factory: builds model (evidence: `infer.py`)
- Inference Module → Frame Transforms: uses transforms (evidence: `infer.py`)
- Dataset Factory → Tennis Dataset: builds dataset (evidence: `datasets_factory/datasets/tennis_dataset.py`)
- Dataset Factory → Frame Transforms: builds transform pipeline (evidence: `datasets_factory/transforms/tracknet_transforms.py`)
- Model Factory → TrackNet V2: registers model (evidence: `models_factory/models/tracknetv2.py`)
- Model Factory → TrackNet V4: registers model (evidence: `models_factory/models/tracknetv4.py`)
- Model Factory → TrackNet V5: registers model (evidence: `models_factory/models/tracknetv5.py`)
- Model Factory → WASB Model: registers model (evidence: `models_factory/models/wasb.py`)
- Training Entry → Training Runner: starts training (evidence: `train.py`)
- Training Entry → Model Configurations: loads configurations (evidence: `README.md`)
- Training Entry → Dataset Factory: constructs data (evidence: `train.py`)
- Training Entry → Model Factory: constructs model (evidence: `train.py`)
- Training Entry → Optimizer Factory: constructs optimizer (evidence: `train.py`)
- Training Runner → Training Loss: computes loss
- Training Runner → Training Metric: evaluates predictions
- Training Runner → Engine Factory: configures hooks
- Training Runner → Visualization Hook: invokes hooks
- Training Metric → Heatmap Metrics: extracts centroids (evidence: `engine/hooks/visualizer_v2_hook.py`)
- Pipeline Caller → Tennis Pipeline: submits video
- Tennis Pipeline → Video Detector: detects points (evidence: `core/pipeline.py`)
- Tennis Pipeline → Trajectory Tracker: refines trajectory (evidence: `core/pipeline.py`)
- Tennis Pipeline → Video Visualizer: renders frames (evidence: `core/pipeline.py`)
- Tennis Pipeline → Video Results: saves refined video (evidence: `core/pipeline.py`)
- Video Detector → Model Factory: builds model (evidence: `core/detector.py`)
- Video Detector → Frame Transforms: uses transforms (evidence: `core/detector.py`)
