How chgyglin/tracknetv2-pytorch works
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: handle_tracknet_dataset.py Build Dataset · tracknet.py TrackNet · train.py Train · general.py General Utils
Components 22
Data Prep
Scripts and sample layout for turning raw shuttlecock videos into training data.
- Build Dataset · Transforms raw TrackNet-style sources into training-ready samples.
tools/handle_tracknet_dataset.py - Frame Generator · Creates frame sequences from source videos.
tools/Frame_Generator.py - Batch Frames · Batch-oriented frame generation workflow.
tools/Frame_Generator_batch.py - Rally Frames · Rally-specific frame generation workflow.
tools/Frame_Generator_rally.py - Label Tools · Label inspection and conversion utilities.
tools/label_tool.py
PyTorch Pipeline
Training, validation, and single-video inference around the TrackNet model.
Shared Utils
Common preprocessing and batching helpers used by the PyTorch entrypoints.
- Augment · Training and inference augmentations.
utils/augmentations.py - Load Data · Dataset loading and batching for video-frame samples.
utils/dataloaders.py - General Utils · Shared helper functions and common repo glue.
utils/general.py
Deployment
Separate server/client path for serving model predictions.
- Server App · Deployment server for model inference.
deploy/app.py - Client Test · Test client for the deployment service.
deploy/test_app.py
Native Runtime
C++/NCNN inference branch for edge or embedded execution.
- NCNN App · C++ inference implementation for alternate runtime deployment.
ncnn_inference/tracknet.cpp - Build NCNN · Makefile for the native inference build.
ncnn_inference/Makefile
Conversion
Artifacts and scripts for converting legacy weights into repo-compatible formats.
- Convert PNNX · Converts model artifacts for NCNN deployment.
ncnn_inference/convert_pnnx.py - ONNX to PT · Compatibility conversion from imported model format to PyTorch weights.
tf2torch/onnx2pt.py - Legacy Weights · Converted TrackNet weight artifact.
tf2torch/track.pt
Ops
Operational files and experiment outputs.
- Dataset Config · Dataset path configuration used by training and validation.
data/test.yaml - Example Dataset · Concrete example of the expected match/videos/images/labels layout.
example_dataset/match - Runs · Training outputs, checkpoints, and experiment artifacts.
runs
Connections 22
- 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.