trackforge 0.1.4

A unified, high-performance computer vision tracking library.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122

# Trackforge

[![Crates.io](https://img.shields.io/crates/v/trackforge.svg)](https://crates.io/crates/trackforge)
[![PyPI](https://img.shields.io/pypi/v/trackforge.svg)](https://pypi.org/project/trackforge/)
[![docs.rs](https://img.shields.io/docsrs/trackforge)](https://docs.rs/trackforge)
[![codecov](https://codecov.io/gh/onuralpszr/trackforge/branch/main/graph/badge.svg?token=DHMFYRLJW1)](https://codecov.io/gh/onuralpszr/trackforge)
[![CI](https://github.com/onuralpszr/trackforge/actions/workflows/CI.yml/badge.svg)](https://github.com/onuralpszr/trackforge/actions/workflows/CI.yml)
[![Dependabot Updates](https://github.com/onuralpszr/trackforge/actions/workflows/dependabot/dependabot-updates/badge.svg)](https://github.com/onuralpszr/trackforge/actions/workflows/dependabot/dependabot-updates)
[![Security audit](https://github.com/onuralpszr/trackforge/actions/workflows/security-audit.yml/badge.svg)](https://github.com/onuralpszr/trackforge/actions/workflows/security-audit.yml)
[![MSRV](https://img.shields.io/badge/rustc-1.60+-ab6000.svg)](https://blog.rust-lang.org/2022/04/07/Rust-1.60.0.html)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)


> [!IMPORTANT]
> **This project is currently under active development.** APIs and features are subject to change.

**Trackforge** is a unified, high-performance computer vision tracking library, implemented in Rust and exposed as a Python package. It provides state-of-the-art tracking algorithms like **ByteTrack**, optimized for speed and ease of use in both Rust and Python environments.

## Features

- 🚀 **High Performance**: Native Rust implementation for maximum speed and memory safety.
- 🐍 **Python Bindings**: Seamless integration with the Python ecosystem using `pyo3`.
- 🛠 **Unified API**: Consistent interface for tracking tasks across both languages.
- 📸 **ByteTrack**: Robust multi-object tracking using Kalman filters and IoU matching.

## Installation

### Python

```bash
pip install trackforge
```
*(Note: Released on PyPI soon. For now, build from source).*

### Rust

Add `trackforge` to your `Cargo.toml`:

```toml
[dependencies]
trackforge = "0.1.1" # Check crates.io for latest version
```

## Usage

### 🐍 Python

```python
import trackforge

# Initialize ByteTrack
# track_thresh: High confidence detection threshold (e.g., 0.5)
# track_buffer: Frames to keep lost tracks alive (e.g., 30)
# match_thresh: IoU matching threshold (e.g., 0.8)
# det_thresh: Initialization threshold (e.g., 0.6)
tracker = trackforge.ByteTrack(0.5, 30, 0.8, 0.6)

# Detections: List of (TLWH_Box, Score, ClassID)
detections = [
    ([100.0, 100.0, 50.0, 100.0], 0.9, 0),
    ([200.0, 200.0, 60.0, 120.0], 0.85, 0)
]

# Update tracker
tracks = tracker.update(detections)

for t in tracks:
    # t is (track_id, tlwh_box, score, class_id)
    print(f"ID: {t[0]}, Box: {t[1]}")
```

### 🦀 Rust

```rust
use trackforge::trackers::byte_track::ByteTrack;

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

    // Detections: Vec<([f32; 4], f32, i64)>
    let detections = vec![
        ([100.0, 100.0, 50.0, 100.0], 0.9, 0),
    ];

    // Update
    let tracks = tracker.update(detections);

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

## Development

This project uses `maturin` to manage the Rust/Python interop.

### Prerequisites

- Rust & Cargo
- Python 3.8+
- `maturin`: `pip install maturin`

### Build

```bash
# Build Python bindings
maturin develop

# Run Rust tests
cargo test
```

## Contributing

Pull requests are welcome! For major changes, please open an issue first to discuss what you would like to change.

## License

[MIT](https://choosealicense.com/licenses/mit/)