trackforge 0.2.0

A unified, high-performance computer vision tracking library.

Trackforge is a unified, high-performance computer vision tracking library implemented in Rust with Python bindings. It provides real-time multi-object tracking algorithms, optimized for speed and designed as the CPU "glue" between GPU-based object detectors and your tracking pipeline.

Supported Trackers

Tracker	Type	Appearance (Re-ID)	Language	Status
ByteTrack	IoU + confidence association	No	Python & Rust	✅ Implemented
DeepSORT	IoU + cosine distance	Yes (pluggable)	Python & Rust	✅ Implemented
OC-SORT	IoU + velocity direction (OCM)	No	Python & Rust	✅ Implemented
SORT	IoU + Kalman filter	No	Python & Rust	✅ Implemented

Features

• 🚀 Native Rust Core Blazingly fast tracking (< 1ms/frame for ByteTrack) with full memory safety
• 🐍 Python Bindings First-class pip install trackforge support via PyO3
• 🎯 Multi-Algorithm ByteTrack, OC-SORT, DeepSORT, and SORT with a unified API
• 🔌 Pluggable Re-ID DeepSORT's appearance extractor is a trait; plug in any feature model
• 📐 Generic Kalman Filter Configurable position/velocity weighting, gating distance computation

Architecture

┌──────────────────┐   bboxes    ┌──────────────────┐   tracks    ┌──────────────────┐
│  GPU Detectors   │ ──────────▶ │    Trackforge    │ ──────────▶ │      Tracks      │
│ YOLO / RT-DETR / │             │  (CPU, no GPU    │             │   ID + bbox +    │
│     custom       │             │   round-trip)    │             │      class       │
└──────────────────┘             └──────────────────┘             └──────────────────┘

Trackforge is intentionally CPU-bound. It receives bounding boxes from GPU detectors and handles association on the CPU no costly device transfers needed. Algorithms like ByteTrack run in under 1ms per frame.

[!IMPORTANT] Under active development. APIs and features are subject to change. MSRV: Rust 1.88.

Installation

Python

pip install trackforge

Rust

Add to your Cargo.toml:

[dependencies]
trackforge = "0.1.9"

To build the Python bindings from source (e.g. via maturin develop), enable the python feature:

[dependencies]
trackforge = { version = "0.1.9", features = ["python"] }

Quick Start

Python - ByteTrack

from trackforge import BYTETRACK

tracker = BYTETRACK(track_thresh=0.5, track_buffer=30, match_thresh=0.8, det_thresh=0.6)

# Format: ([x, y, w, h], confidence, class_id)
detections = [
    ([100.0, 100.0, 50.0, 100.0], 0.9, 0),
    ([200.0, 200.0, 60.0, 120.0], 0.85, 0),
]

tracks = tracker.update(detections)

for track_id, tlwh, score, class_id in tracks:
    print(f"ID: {track_id}, Box: {tlwh}")

Python - DeepSORT

from trackforge import DEEPSORT

tracker = DEEPSORT(
    max_age=30,
    n_init=3,
    max_iou_distance=0.7,
    max_cosine_distance=0.2,
    nn_budget=100,
)

detections = [([100.0, 100.0, 50.0, 100.0], 0.9, 0)]
embeddings = [[0.1, 0.2, 0.3, ...]]  # appearance feature vectors

tracks = tracker.update(detections, embeddings)

for track_id, tlwh, score, class_id in tracks:
    print(f"ID: {track_id}, Box: {tlwh}, Score: {score}")

Python - OC-SORT

from trackforge import OCSORT

tracker = OCSORT(
    max_age=30,
    min_hits=3,
    iou_threshold=0.3,
    delta_t=3,
    inertia=0.2,
)

detections = [
    ([100.0, 100.0, 50.0, 100.0], 0.9, 0),
    ([200.0, 200.0, 60.0, 120.0], 0.85, 0),
]

tracks = tracker.update(detections)

for track_id, tlwh, score, class_id in tracks:
    print(f"ID: {track_id}, Box: {tlwh}")

Rust ByteTrack

use trackforge::trackers::byte_track::ByteTrack;

fn main() -> anyhow::Result<()> {
    let mut tracker = ByteTrack::new(0.5, 30, 0.8, 0.6);

    let detections = vec![
        ([100.0, 100.0, 50.0, 100.0], 0.9, 0),
        ([200.0, 200.0, 60.0, 120.0], 0.85, 0),
    ];

    let tracks = tracker.update(detections);

    for t in tracks {
        println!("ID: {}, Box: {:?}", t.track_id, t.tlwh);
    }

    Ok(())
}

Examples

Complete working examples are included in the repository:

Python Examples

Example	Description	Requirements
ByteTrack + YOLO	ByteTrack with Ultralytics YOLO11 on video	ultralytics, opencv-python
DeepSORT + YOLO	DeepSORT with YOLO + ResNet18 embeddings	ultralytics, torch, torchvision
SORT + RT-DETR	SORT with Hugging Face RT-DETR	transformers, torch
SORT + YOLO	SORT with Ultralytics YOLO	ultralytics, opencv-python
Tracker Comparison	side-by-side tracker benchmark	varies

Run a Python example:

python examples/python/byte_track_demo.py

Rust Examples

Example	Description	Feature Flag
ByteTrack Demo	Basic ByteTrack with simulated detections	none
DeepSORT (simple)	DeepSORT with a mock appearance extractor	none
DeepSORT + ONNX	DeepSORT with RT-DETR + ONNX Re-ID	advanced_examples

Run a Rust example:

cargo run --example byte_track_demo
cargo run --example deepsort_simple
cargo run --example deepsort_ort --features advanced_examples

API Reference

• Python API Full PyO3 class reference
• Rust API Generated rustdoc

Parameters

ByteTrack

Parameter	Type	Default	Description
track_thresh	float	0.5	High confidence detection threshold
track_buffer	int	30	Frames to keep lost tracks alive
match_thresh	float	0.8	IoU threshold for matching
det_thresh	float	0.6	Minimum detection confidence for initialization

DeepSORT

Parameter	Type	Default	Description
max_age	int	70	Max frames to keep a track without detection
n_init	int	3	Consecutive detections needed to confirm a track
max_iou_distance	float	0.7	Max IoU distance for association
max_cosine_distance	float	0.2	Max cosine distance for Re-ID matching
nn_budget	int	100	Max appearance feature library size per track

OC-SORT

Parameter	Type	Default	Description
max_age	int	30	Max frames to keep a lost track alive before deletion
min_hits	int	3	Consecutive matched frames required to confirm a track
iou_threshold	float	0.3	IoU threshold for matching
delta_t	int	3	Observation window (frames) for velocity computation
inertia	float	0.2	Weight for the direction-consistency cost bonus (OCM)

SORT

Parameter	Type	Default	Description
max_age	int	1	Max frames to keep a track without detection
min_hits	int	3	Minimum hits before a track is confirmed
iou_threshold	float	0.3	IoU threshold for matching

Development

Prerequisites

• Rust 1.88+ (MSRV)
• Python 3.8+
• maturin for Python bindings

Build

# Build Python bindings in development mode
maturin develop

# Run Rust tests
cargo test

# Format code
cargo fmt

Run Python Examples

# After `maturin develop`:
python examples/python/deepsort_demo.py --video your_video.mp4

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

• For major changes, open an issue first to discuss what you would like to change.
• PRs should pass CI: cargo fmt, cargo clippy -- -D warnings, cargo test.
• Use Commitizen for commit messages: cz commit.

Roadmap

Completed

• SORT
• ByteTrack
• OC-SORT
• DeepSORT
• Python bindings & PyPI package
• Rust & Python examples

Planned

• Norfair Lightweight distance-based tracking
• StrongSORT Improved DeepSORT with stronger Re-ID
• StrongSORT++ With camera motion compensation
• BoT-SORT ByteTrack + Re-ID + camera motion compensation
• DeepOCSORT (OC-SORT + appearance)
• Joint detection & tracking (FairMOT, CenterTrack)
• Transformer-based trackers (TrackFormer, MOTR)
• TrackTrack: Focusing on Tracks for Online Multi-Object Tracking

License

Distributed under the MIT License. See LICENSE for details.