Lib.rs

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

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.

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

Run a Python example:

python examples/python/byte_track_demo.py

Rust 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

DeepSORT

OC-SORT

SORT

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.