# chgyglin/tracknetv2-pytorch architecture

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

- Interactive diagram: https://gitdiagram.com/chgyglin/tracknetv2-pytorch
- Repository: https://github.com/chgyglin/tracknetv2-pytorch

## Overview

1. Repository purpose  
This is a shuttlecock-tracking project built around TrackNetV2, with three main execution paths: PyTorch training/evaluation, PyTorch video inference, and a separate lightweight C++/NCNN deployment path.

2. Core model boundary  
`models/tracknet.py` contains the central network definition. The rest of the repo surrounds this model with data preparation, dataset loading, training loops, evaluation, and inference wrappers rather than introducing multiple model families.

3. Data preparation pipeline  
Raw badminton videos and labels are transformed into a training-ready layout by the scripts in `tools/`. `handle_tracknet_dataset.py`, `Frame_Generator*.py`, and the label utilities convert source datasets into frame sequences plus CSV label files, matching the directory structure shown in `example_dataset/`.

4. Expected dataset shape  
The example dataset shows the repo expects each rally/video sample to be organized into `videos/`, `images/`, and `labels/` under a match-specific directory. The YAML dataset config in `data/` points training and validation code to these folders.

5. Training path  
`train.py` is the main orchestrator for PyTorch training. It reads dataset configuration, builds dataloaders and augmentations from `utils/`, instantiates the TrackNet model, and writes checkpoints and experiment outputs into `runs/`.

6. Validation and offline evaluation  
`val.py` is the separate evaluation entrypoint. It uses the same dataset/config machinery as training but runs inference over held-out data to measure performance from a saved weight file.

7. Single-video inference path  
`detect.py` handles end-user inference on a source video. It loads a trained `.pt` model, processes video frames, and can render results interactively with `--view-img`. This is the simplest “application” path in the repo.

8. Shared training/inference utilities  
`utils/augmentations.py`, `utils/dataloaders.py`, and `utils/general.py` provide the common infrastructure for preprocessing, batching, and general helpers used by train/val/detect. These utilities are the main glue between raw frame data and model execution.

9. Deployment path  
`deploy/app.py` and `deploy/test_app.py` form a separate serving/client pair for model deployment. The README shows a server process and a test client, so this boundary is distinct from the standalone `detect.py` workflow.

10. Native C++ inference path  
`ncnn_inference/` is an alternate runtime path for edge/embedded deployment. It converts the model through `tf2torch/convert_pnnx.py` and uses `tracknet.cpp` with NCNN, built via the included `Makefile`. This is a major architectural branch because it bypasses Python/PyTorch at runtime.

11. TensorFlow compatibility/conversion artifacts  
`tf2torch/` contains conversion assets, including a converted `.pt` weight and a diff file for reproducing compatibility with TensorFlow-originated TrackNet weights. This signals that the repo supports both native PyTorch training and imported legacy weights.

12. Operational artifacts  
`runs/` stores training outputs, `example_dataset/` provides a concrete folder layout for understanding the expected inputs, and `requirements.txt` defines the Python runtime dependencies. Together these define the project’s operational boundary around reproducible experiments.

Main entry points: [`tools/handle_tracknet_dataset.py`](https://github.com/chgyglin/tracknetv2-pytorch/blob/main/tools/handle_tracknet_dataset.py) (Build Dataset), [`models/tracknet.py`](https://github.com/chgyglin/tracknetv2-pytorch/blob/main/models/tracknet.py) (TrackNet), [`train.py`](https://github.com/chgyglin/tracknetv2-pytorch/blob/main/train.py) (Train), [`utils/general.py`](https://github.com/chgyglin/tracknetv2-pytorch/blob/main/utils/general.py) (General Utils)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_data["Data Prep"]
  node_node_tools_handle["Build Dataset<br/>prep-script"]
  node_node_tools_frames["Frame Generator<br/>prep-script<br/>[Frame_Generator.py]"]
  node_node_tools_batch["Batch Frames<br/>prep-script"]
  node_node_tools_rally["Rally Frames<br/>prep-script"]
  node_node_tools_labels["Label Tools<br/>prep-script<br/>[label_tool.py]"]
end

subgraph group_group_pytorch["PyTorch Pipeline"]
  node_node_model["TrackNet<br/>model<br/>[tracknet.py]"]
  node_node_train["Train<br/>entrypoint<br/>[train.py]"]
  node_node_val["Validate<br/>entrypoint<br/>[val.py]"]
  node_node_detect["Detect<br/>entrypoint<br/>[detect.py]"]
end

subgraph group_group_utils["Shared Utils"]
  node_node_aug["Augment<br/>preprocess<br/>[augmentations.py]"]
  node_node_data["Load Data<br/>dataloader<br/>[dataloaders.py]"]
  node_node_general["General Utils<br/>helpers<br/>[general.py]"]
end

subgraph group_group_deploy["Deployment"]
  node_node_deploy_app["Server App<br/>[app.py]"]
  node_node_deploy_test["Client Test<br/>[test_app.py]"]
end

subgraph group_group_native["Native Runtime"]
  node_node_ncnn_cpp["NCNN App<br/>native-inference<br/>[tracknet.cpp]"]
  node_node_ncnn_build["Build NCNN"]
end

subgraph group_group_convert["Conversion"]
  node_node_convert["Convert PNNX<br/>conversion<br/>[convert_pnnx.py]"]
  node_node_tf2pt["ONNX to PT<br/>conversion<br/>[onnx2pt.py]"]
  node_node_trackpt["Legacy Weights<br/>artifact<br/>[track.pt]"]
end

subgraph group_group_ops["Ops"]
  node_node_dataset_yaml["Dataset Config<br/>[test.yaml]"]
  node_node_example[("Example Dataset<br/>sample-data")]
  node_node_runs[("Runs<br/>output")]
end

node_node_tools_frames -->|"frames into dataset"| node_node_tools_handle
node_node_tools_batch -->|"batch prep"| node_node_tools_handle
node_node_tools_rally -->|"rally prep"| node_node_tools_handle
node_node_tools_labels -->|"labels"| node_node_tools_handle
node_node_tools_handle -->|"layout"| node_node_example
node_node_dataset_yaml -->|"configures"| node_node_train
node_node_dataset_yaml -->|"configures"| node_node_val
node_node_example -->|"sample shape"| node_node_data
node_node_data -->|"batch prep"| node_node_aug
node_node_general -->|"helpers"| node_node_train
node_node_general -->|"helpers"| node_node_val
node_node_general -->|"helpers"| node_node_detect
node_node_train -->|"builds"| node_node_model
node_node_val -->|"evaluates"| node_node_model
node_node_detect -->|"loads"| node_node_model
node_node_train -->|"writes"| node_node_runs
node_node_model -->|"exports"| node_node_convert
node_node_convert -->|"feeds runtime"| node_node_ncnn_cpp
node_node_ncnn_build -->|"builds"| node_node_ncnn_cpp
node_node_tf2pt -->|"produces"| node_node_trackpt
node_node_deploy_app -->|"serves"| node_node_model
node_node_deploy_test -->|"calls"| node_node_deploy_app

click node_node_model "https://github.com/chgyglin/tracknetv2-pytorch/blob/main/models/tracknet.py"
click node_node_train "https://github.com/chgyglin/tracknetv2-pytorch/blob/main/train.py"
click node_node_val "https://github.com/chgyglin/tracknetv2-pytorch/blob/main/val.py"
click node_node_detect "https://github.com/chgyglin/tracknetv2-pytorch/blob/main/detect.py"
click node_node_aug "https://github.com/chgyglin/tracknetv2-pytorch/blob/main/utils/augmentations.py"
click node_node_data "https://github.com/chgyglin/tracknetv2-pytorch/blob/main/utils/dataloaders.py"
click node_node_general "https://github.com/chgyglin/tracknetv2-pytorch/blob/main/utils/general.py"
click node_node_tools_handle "https://github.com/chgyglin/tracknetv2-pytorch/blob/main/tools/handle_tracknet_dataset.py"
click node_node_tools_frames "https://github.com/chgyglin/tracknetv2-pytorch/blob/main/tools/Frame_Generator.py"
click node_node_tools_batch "https://github.com/chgyglin/tracknetv2-pytorch/blob/main/tools/Frame_Generator_batch.py"
click node_node_tools_rally "https://github.com/chgyglin/tracknetv2-pytorch/blob/main/tools/Frame_Generator_rally.py"
click node_node_tools_labels "https://github.com/chgyglin/tracknetv2-pytorch/blob/main/tools/label_tool.py"
click node_node_deploy_app "https://github.com/chgyglin/tracknetv2-pytorch/blob/main/deploy/app.py"
click node_node_deploy_test "https://github.com/chgyglin/tracknetv2-pytorch/blob/main/deploy/test_app.py"
click node_node_ncnn_cpp "https://github.com/chgyglin/tracknetv2-pytorch/blob/main/ncnn_inference/tracknet.cpp"
click node_node_ncnn_build "https://github.com/chgyglin/tracknetv2-pytorch/tree/main/ncnn_inference/Makefile"
click node_node_convert "https://github.com/chgyglin/tracknetv2-pytorch/blob/main/ncnn_inference/convert_pnnx.py"
click node_node_tf2pt "https://github.com/chgyglin/tracknetv2-pytorch/blob/main/tf2torch/onnx2pt.py"
click node_node_trackpt "https://github.com/chgyglin/tracknetv2-pytorch/blob/main/tf2torch/track.pt"
click node_node_dataset_yaml "https://github.com/chgyglin/tracknetv2-pytorch/blob/main/data/test.yaml"
click node_node_example "https://github.com/chgyglin/tracknetv2-pytorch/tree/main/example_dataset/match"
click node_node_runs "https://github.com/chgyglin/tracknetv2-pytorch/tree/main/runs"

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_node_tools_handle,node_node_tools_frames,node_node_tools_batch,node_node_tools_rally,node_node_tools_labels,node_node_dataset_yaml,node_node_example,node_node_runs toneBlue
class node_node_model,node_node_train,node_node_val,node_node_detect toneAmber
class node_node_aug,node_node_data,node_node_general toneMint
class node_node_deploy_app,node_node_deploy_test toneRose
class node_node_ncnn_cpp,node_node_ncnn_build toneIndigo
class node_node_convert,node_node_tf2pt,node_node_trackpt toneTeal
```

## Components

### Data Prep

Scripts and sample layout for turning raw shuttlecock videos into training data.

- [Build Dataset](https://github.com/chgyglin/tracknetv2-pytorch/blob/main/tools/handle_tracknet_dataset.py): prep-script · Transforms raw TrackNet-style sources into training-ready samples. · `tools/handle_tracknet_dataset.py`
- [Frame Generator](https://github.com/chgyglin/tracknetv2-pytorch/blob/main/tools/Frame_Generator.py): prep-script · Creates frame sequences from source videos. · `tools/Frame_Generator.py`
- [Batch Frames](https://github.com/chgyglin/tracknetv2-pytorch/blob/main/tools/Frame_Generator_batch.py): prep-script · Batch-oriented frame generation workflow. · `tools/Frame_Generator_batch.py`
- [Rally Frames](https://github.com/chgyglin/tracknetv2-pytorch/blob/main/tools/Frame_Generator_rally.py): prep-script · Rally-specific frame generation workflow. · `tools/Frame_Generator_rally.py`
- [Label Tools](https://github.com/chgyglin/tracknetv2-pytorch/blob/main/tools/label_tool.py): prep-script · Label inspection and conversion utilities. · `tools/label_tool.py`

### PyTorch Pipeline

Training, validation, and single-video inference around the TrackNet model.

- [TrackNet](https://github.com/chgyglin/tracknetv2-pytorch/blob/main/models/tracknet.py): model · Central network definition used by the Python pipeline. · `models/tracknet.py`
- [Train](https://github.com/chgyglin/tracknetv2-pytorch/blob/main/train.py): entrypoint · Main training orchestrator for PyTorch experiments. · `train.py`
- [Validate](https://github.com/chgyglin/tracknetv2-pytorch/blob/main/val.py): entrypoint · Held-out evaluation entrypoint for saved weights. · `val.py`
- [Detect](https://github.com/chgyglin/tracknetv2-pytorch/blob/main/detect.py): entrypoint · Single-video inference and optional visualized output. · `detect.py`

### Shared Utils

Common preprocessing and batching helpers used by the PyTorch entrypoints.

- [Augment](https://github.com/chgyglin/tracknetv2-pytorch/blob/main/utils/augmentations.py): preprocess · Training and inference augmentations. · `utils/augmentations.py`
- [Load Data](https://github.com/chgyglin/tracknetv2-pytorch/blob/main/utils/dataloaders.py): dataloader · Dataset loading and batching for video-frame samples. · `utils/dataloaders.py`
- [General Utils](https://github.com/chgyglin/tracknetv2-pytorch/blob/main/utils/general.py): helpers · Shared helper functions and common repo glue. · `utils/general.py`

### Deployment

Separate server/client path for serving model predictions.

- [Server App](https://github.com/chgyglin/tracknetv2-pytorch/blob/main/deploy/app.py): service · Deployment server for model inference. · `deploy/app.py`
- [Client Test](https://github.com/chgyglin/tracknetv2-pytorch/blob/main/deploy/test_app.py): client · Test client for the deployment service. · `deploy/test_app.py`

### Native Runtime

C++/NCNN inference branch for edge or embedded execution.

- [NCNN App](https://github.com/chgyglin/tracknetv2-pytorch/blob/main/ncnn_inference/tracknet.cpp): native-inference · C++ inference implementation for alternate runtime deployment. · `ncnn_inference/tracknet.cpp`
- [Build NCNN](https://github.com/chgyglin/tracknetv2-pytorch/tree/main/ncnn_inference/Makefile): build · Makefile for the native inference build. · `ncnn_inference/Makefile`

### Conversion

Artifacts and scripts for converting legacy weights into repo-compatible formats.

- [Convert PNNX](https://github.com/chgyglin/tracknetv2-pytorch/blob/main/ncnn_inference/convert_pnnx.py): conversion · Converts model artifacts for NCNN deployment. · `ncnn_inference/convert_pnnx.py`
- [ONNX to PT](https://github.com/chgyglin/tracknetv2-pytorch/blob/main/tf2torch/onnx2pt.py): conversion · Compatibility conversion from imported model format to PyTorch weights. · `tf2torch/onnx2pt.py`
- [Legacy Weights](https://github.com/chgyglin/tracknetv2-pytorch/blob/main/tf2torch/track.pt): artifact · Converted TrackNet weight artifact. · `tf2torch/track.pt`

### Ops

Operational files and experiment outputs.

- [Dataset Config](https://github.com/chgyglin/tracknetv2-pytorch/blob/main/data/test.yaml): config · Dataset path configuration used by training and validation. · `data/test.yaml`
- [Example Dataset](https://github.com/chgyglin/tracknetv2-pytorch/tree/main/example_dataset/match): sample-data · Concrete example of the expected match/videos/images/labels layout. · `example_dataset/match`
- [Runs](https://github.com/chgyglin/tracknetv2-pytorch/tree/main/runs): output · Training outputs, checkpoints, and experiment artifacts. · `runs`

## Connections

- Frame Generator → Build Dataset: frames into dataset · Frame extraction feeds dataset assembly.
- Batch Frames → Build Dataset: batch prep · Batch frame generation supports dataset building.
- Rally Frames → Build Dataset: rally prep · Rally-specific preprocessing contributes to dataset assembly.
- Label Tools → Build Dataset: labels · Label utilities support dataset construction.
- Build Dataset → Example Dataset: layout · Produces the expected match-level folder structure.
- Dataset Config → Train: configures · Dataset config is consumed by training.
- Dataset Config → Validate: configures · Dataset config is consumed by validation.
- Example Dataset → Load Data: sample shape · Example data illustrates what the loaders expect.
- Load Data → Augment: batch prep · Dataloaders and augmentations work together in the PyTorch path.
- General Utils → Train: helpers · General helpers support training orchestration.
- General Utils → Validate: helpers · General helpers support evaluation.
- General Utils → Detect: helpers · General helpers support inference.
- Train → TrackNet: builds · Training instantiates the TrackNet model.
- Validate → TrackNet: evaluates · Validation runs the TrackNet model on held-out data.
- Detect → TrackNet: loads · Inference loads a trained TrackNet weight file.
- Train → Runs: writes · Training emits checkpoints and experiment outputs.
- TrackNet → Convert PNNX: exports · The model is converted for native deployment.
- Convert PNNX → NCNN App: feeds runtime · Conversion artifacts are used by the C++ inference path.
- Build NCNN → NCNN App: builds · Makefile builds the native inference binary.
- ONNX to PT → Legacy Weights: produces · Conversion path yields compatible weight artifacts.
- Server App → TrackNet: serves · Deployment server wraps model inference.
- Client Test → Server App: calls · Test client exercises the serving app.
