Metadata-Version: 2.4
Name: tracktors
Version: 2.6.0.dev1
Summary: Tensor-native multi-object tracking for Roboflow Inference
Author-email: "Roboflow et al." <develop@roboflow.com>
Maintainer-email: Piotr Skalski <piotr@roboflow.com>
License: Apache License 2.0
Project-URL: Homepage, https://github.com/roboflow/tracktors
Project-URL: Repository, https://github.com/roboflow/tracktors
Project-URL: Issues, https://github.com/roboflow/tracktors/issues
Keywords: tracking,mot,sort,bytetrack,machine-learning,deep-learning,vision,ML,DL,AI,DETR,YOLO,Roboflow
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Classifier: Operating System :: POSIX
Classifier: Operating System :: Unix
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=2.0.2
Requires-Dist: superiorvision>=0.30.0.dev0
Requires-Dist: torch
Requires-Dist: scipy>=1.13.1
Requires-Dist: opencv-python>=4.8.0
Requires-Dist: rich>=13.0.0
Requires-Dist: requests>=2.28.0
Requires-Dist: pydeprecate>=0.7.0
Provides-Extra: detection
Requires-Dist: inference-models>=0.19.0; extra == "detection"
Provides-Extra: tune
Requires-Dist: optuna>=3.0.0; extra == "tune"
Dynamic: license-file

<div align="center">
    <img width="200" src="https://raw.githubusercontent.com/roboflow/trackers/main/docs/assets/logo-trackers-violet.svg" alt="tracktors logo">
    <h1>tracktors</h1>
    <p>Trackers, after the coordinates discovered tensors.</p>

[![license](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)

</div>

Tracktors is Roboflow's private, tensor-native fork of
[Trackers](https://github.com/roboflow/trackers), scoped to the four tracker
paths used by Inference: SORT, ByteTrack, OC-SORT, and BoT-SORT. It consumes
SuperiorVision's tensor-native `supervision.Detections` without making the
boxes take a ceremonial trip through NumPy first.

Both `from tracktors import ...` and the legacy `from trackers import ...`
interface are supported while Inference migrates. Same API, same algorithms,
fewer surprise CPU field trips.

Turning a GPU tensor into NumPy so a Kalman filter can immediately rebuild the
same numbers somewhere else is not object tracking. It is luggage handling.
Tracktors is retiring the carousel.

## Why Tracktors?

- **Clean-room implementations.** Every algorithm is re-implemented from the original paper — not a thin wrapper around someone else's code. You can read it, understand it, and modify it.
- **Detector-agnostic.** Works with YOLO, DETR, RT-DETR, or any model that produces bounding boxes. No inference library required or assumed.
- **SuperiorVision tensor native.** Pass tensor-backed `sv.Detections` in and get tensor-backed tracked detections back on the same device—zero glue code and zero NumPy exit tax.
- **Benchmarked across four datasets.** MOT17, SportsMOT, SoccerNet, and DanceTrack — at default parameters and after hyperparameter tuning, so you know what to expect before you deploy.
- **Tunable out of the box.** Built-in Optuna-based hyperparameter search via `tracktors tune` (or the compatible `trackers tune`) so you can optimize for your specific scene and detector.
- **Camera motion compensation.** BoT-SORT handles moving cameras natively, keeping track IDs stable even when the whole frame shifts.

## Install

```bash
pip install tracktors
```

<details>
<summary>Install from source</summary>

```bash
git clone git@github.com:roboflow/tracktors.git
cd tracktors
uv sync
```

</details>

The package is published on [PyPI](https://pypi.org/project/tracktors/); the
source repository remains private.

[![Watch: Building Real-Time Multi-Object Tracking with RF-DETR and Trackers](https://storage.googleapis.com/com-roboflow-marketing/trackers/docs/roboflow-piotr-rf-detr-trackers-v1b-callout.png)](https://www.youtube.com/watch?v=u0k2dTZ0vfs)

## Quick Start

Add tracking to your existing detection pipeline in a few lines. Every tracker shares the same `update(detections, frame=None)` interface, so switching algorithms later is a one-line change. The example below uses `inference` as the detector — swap it for any detector that returns `supervision.Detections`.

```python
import cv2
import supervision as sv
from inference import get_model
from tracktors import ByteTrackTracker

model = get_model(model_id="rfdetr-medium")
tracker = ByteTrackTracker()

cap = cv2.VideoCapture("video.mp4")
while cap.isOpened():
    ret, frame = cap.read()
    if not ret:
        break

    result = model.infer(frame)[0]
    detections = sv.Detections.from_inference(result)
    tracked = tracker.update(detections)
```

For more examples, see the [tracking guide](https://trackers.roboflow.com/develop/learn/track/).

## Track from CLI

Prefer the terminal? Point `tracktors track` at a video, webcam feed, RTSP stream, or image directory and it handles detection, tracking, and annotated output in one command — no Python script required.

```bash
tracktors track \
    --source video.mp4 \
    --output output.mp4 \
    --model rfdetr-medium \
    --tracker bytetrack \
    --show-labels \
    --show-trajectories
```

For all CLI options, see the [tracking guide](https://trackers.roboflow.com/develop/learn/track/).

## Algorithms

Each tracker below is a faithful implementation of its original paper. Pick the one that fits your scene, or run the benchmark to find out which performs best on your data.

|                                                                           Algorithm                                                                           |                           Description                           | MOT17 HOTA | SportsMOT HOTA | SoccerNet HOTA | DanceTrack HOTA |
| :-----------------------------------------------------------------------------------------------------------------------------------------------------------: | :-------------------------------------------------------------: | :--------: | :------------: | :------------: | :-------------: |
|                                                           [SORT](https://arxiv.org/abs/1602.00763)                                                            |          Kalman filter + Hungarian matching baseline.           |    58.4    |      70.9      |      81.6      |      47.2       |
|                                                         [ByteTrack](https://arxiv.org/abs/2110.06864)                                                         | Two-stage association using high and low confidence detections. |    60.1    |      73.0      |      84.0      |      53.3       |
|                                                          [OC-SORT](https://arxiv.org/abs/2203.14360)                                                          |          Observation-centric recovery for lost tracks.          |    61.9    |      71.7      |      78.4      |      54.1       |
|                                                         [BoT-SORT](https://arxiv.org/abs/2206.14651)                                                          |                   Camera motion compensation                    |  **63.7**  |    **73.8**    |    **84.5**    |    **57.8**     |
| [C-BIoU](https://openaccess.thecvf.com/content/WACV2023/papers/Yang_Hard_To_Track_Objects_With_Irregular_Motions_and_Similar_Appearances_WACV_2023_paper.pdf) |  Cascaded buffered IoU matching for fast or irregular motion.   |    63.0    |      73.1      |      82.6      |      56.7       |

All scores use default parameters on the standard split. See the [tracker comparison](https://trackers.roboflow.com/develop/trackers/comparison/) for tuned numbers and methodology.

## Evaluate

Once you have tracking results, you want to know how good they are. `trackers eval` computes CLEAR, HOTA, and Identity metrics against ground-truth annotations and prints a per-sequence breakdown alongside the combined score.

```bash
tracktors eval \
    --gt-dir ./data/mot17/val \
    --tracker-dir results \
    --metrics CLEAR HOTA Identity \
    --columns MOTA HOTA IDF1
```

```
Sequence                        MOTA    HOTA    IDF1
----------------------------------------------------
MOT17-02-FRCNN                30.192  35.475  38.515
MOT17-04-FRCNN                48.912  55.096  61.854
MOT17-05-FRCNN                52.755  45.515  55.705
MOT17-09-FRCNN                51.441  50.108  57.038
MOT17-10-FRCNN                51.832  49.648  55.797
MOT17-11-FRCNN                55.501  49.401  55.061
MOT17-13-FRCNN                60.488  58.651  69.884
----------------------------------------------------
COMBINED                      47.406  50.355  56.600
```

For the full evaluation workflow, see the [evaluation guide](https://trackers.roboflow.com/develop/learn/evaluate/).

## Download Datasets

Need benchmark data to evaluate against? `trackers download` pulls MOT17, SportsMOT, and other supported datasets with a single command, handling splits and assets selectively so you only download what you need.

```bash
tracktors download mot17 \
    --split val \
    --asset annotations,detections
```

|   Dataset   |                               Description                               |         Splits         |                Assets                 |     License     |
| :---------: | :---------------------------------------------------------------------: | :--------------------: | :-----------------------------------: | :-------------: |
|   `mot17`   |    Pedestrian tracking with crowded scenes and frequent occlusions.     | `train`, `val`, `test` | `frames`, `annotations`, `detections` | CC BY-NC-SA 3.0 |
| `sportsmot` | Sports broadcast tracking with fast motion and similar-looking targets. | `train`, `val`, `test` |        `frames`, `annotations`        |    CC BY 4.0    |

For more download options, see the [download guide](https://trackers.roboflow.com/develop/learn/download/).

## Try It

Want to see it in action before writing any code? Try trackers in your browser with our [Hugging Face Playground](https://huggingface.co/spaces/roboflow/trackers) — no install required.

## Where to go next

- **New to tracking?** Start with the [tracking guide](https://trackers.roboflow.com/develop/learn/track/) — it walks through the Python API and CLI end to end.
- **Want benchmarks?** The [tracker comparison](https://trackers.roboflow.com/develop/trackers/comparison/) covers all four algorithms across all four datasets, at default and tuned parameters, with guidance on which to pick for your scene.
- **Building a research pipeline?** The [evaluation guide](https://trackers.roboflow.com/develop/learn/evaluate/) and [download guide](https://trackers.roboflow.com/develop/learn/download/) cover the full offline benchmarking workflow.
- **Upstream API reference** → [trackers.roboflow.com](https://trackers.roboflow.com)
- **Try without installing** → [Hugging Face Playground](https://huggingface.co/spaces/roboflow/trackers)
- **Questions?** Find us on [Discord](https://discord.gg/GbfgXGJ8Bk).

## Contributing

We welcome contributions. Read our [contributor guidelines](CONTRIBUTING.md) to get started.

## License

The code is released under the [Apache 2.0 license](LICENSE).
