Skip to content

Commit 0f9673f

Browse files
SkalskiPpre-commit-ci[bot]
SkalskiP
and
pre-commit-ci[bot]
authored
Revamp README for release (#265)
* Restructure README to improve first impressions and lower barrier to entry * fix(pre_commit): 🎨 auto format pre-commit hooks * Restructure README to improve first impressions and lower barrier to entry --------- Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
1 parent 96a46e5 commit 0f9673f

2 files changed

Lines changed: 64 additions & 80 deletions

File tree

‎README.md‎

Lines changed: 63 additions & 79 deletions
Original file line numberDiff line numberDiff line change
@@ -1,137 +1,121 @@
1+
<div align="center">
2+
<img width="200" src="https://raw.githubusercontent.com/roboflow/trackers/refs/heads/main/docs/assets/logo-trackers-violet.svg" alt="trackers logo">
3+
<h1>trackers</h1>
4+
<p>Plug-and-play multi-object tracking for any detection model.</p>
5+
16
[![version](https://badge.fury.io/py/trackers.svg)](https://badge.fury.io/py/trackers)
27
[![downloads](https://img.shields.io/pypi/dm/trackers)](https://pypistats.org/packages/trackers)
38
[![license](https://img.shields.io/badge/license-Apache%202.0-blue)](https://github.com/roboflow/trackers/blob/main/LICENSE.md)
49
[![python-version](https://img.shields.io/pypi/pyversions/trackers)](https://badge.fury.io/py/trackers)
510
[![hf space](https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Spaces-blue)](https://huggingface.co/spaces/Roboflow/Trackers)
611
[![colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/roboflow-ai/notebooks/blob/main/notebooks/how-to-track-objects-with-bytetrack-tracker.ipynb)
12+
[![discord](https://img.shields.io/discord/1159501506232451173?logo=discord&label=discord&labelColor=fff&color=5865f2&link=https%3A%2F%2Fdiscord.gg%2FGbfgXGJ8Bk)](https://discord.gg/GbfgXGJ8Bk)
713

8-
<div align="center">
9-
<h1 align="center">trackers</h1>
10-
<img width="200" src="https://raw.githubusercontent.com/roboflow/trackers/refs/heads/main/docs/assets/logo-trackers-violet.svg" alt="trackers logo">
1114
</div>
1215

13-
`trackers` gives you clean, modular re-implementations of leading multi-object tracking algorithms released under the permissive Apache 2.0 license. You combine them with any detection model you already use.
16+
## Try It
1417

15-
https://github.com/user-attachments/assets/eef9b00a-cfe4-40f7-a495-954550e3ef1f
18+
No install needed. Try trackers in your browser with our [Hugging Face Playground](https://huggingface.co/spaces/roboflow/trackers).
1619

1720
## Install
1821

19-
You can install and use `trackers` in a [**Python>=3.10**](https://www.python.org/) environment. For detailed installation instructions, including installing from source and setting up a local development environment, check out our [install](https://trackers.roboflow.com/develop/learn/install/) page.
20-
2122
```bash
2223
pip install trackers
2324
```
2425

2526
<details>
2627
<summary>install from source</summary>
2728

28-
<br>
29-
30-
By installing `trackers` from source, you can explore the most recent features and enhancements that have not yet been officially released. Please note that these updates are still in development and may not be as stable as the latest published release.
31-
3229
```bash
33-
pip install https://github.com/roboflow/trackers/archive/refs/heads/develop.zip
30+
pip install git+https://github.com/roboflow/trackers.git
3431
```
3532

3633
</details>
3734

38-
## Quickstart
39-
40-
Use the `trackers` CLI to quickly test how our tracking algorithms perform on your videos and streams. This feature is experimental; see the [CLI documentation](https://trackers.roboflow.com/develop/learn/track) for details.
41-
42-
```bash
43-
trackers track --source source.mp4 --output output.mp4 --model rfdetr-nano --tracker bytetrack
44-
```
45-
46-
## Tracking Algorithms
47-
48-
`trackers` gives you clean, modular re-implementations of leading multi-object tracking algorithms. The package currently supports [SORT](https://arxiv.org/abs/1602.00763) and [ByteTrack](https://arxiv.org/abs/2110.06864). [OC-SORT](https://arxiv.org/abs/2203.14360), [BoT-SORT](https://arxiv.org/abs/2206.14651), and [McByte](https://arxiv.org/abs/2506.01373) support is coming soon. For comparisons, see the [tracker comparison](https://trackers.roboflow.com/develop/trackers/comparison/) page.
49-
50-
| Algorithm | MOT17 HOTA | MOT17 IDF1 | MOT17 MOTA | SportsMOT HOTA | SoccerNet HOTA |
51-
| :-------: | :--------: | :--------: | :--------: | :------------: | :------------: |
52-
| SORT | 58.4 | 69.9 | 67.2 | 70.9 | 81.6 |
53-
| ByteTrack | **60.1** | **73.2** | **74.1** | **73.0** | **84.0** |
54-
| OC-SORT | — | — | — | — | — |
55-
| BoT-SORT | — | — | — | — | — |
56-
| McByte | — | — | — | — | — |
35+
https://github.com/user-attachments/assets/eef9b00a-cfe4-40f7-a495-954550e3ef1f
5736

58-
## Integration
37+
## Track from CLI
5938

60-
With a modular design, `trackers` lets you combine object detectors from different libraries with the tracker of your choice.
39+
Point at a video, webcam, RTSP stream, or image directory. Get tracked output.
6140

62-
```python
63-
import cv2
64-
from rfdetr import RFDETRNano
65-
from trackers import ByteTrackTracker
66-
67-
model = RFDETRNano()
68-
tracker = ByteTrackTracker()
69-
70-
cap = cv2.VideoCapture("source.mp4")
71-
while True:
72-
ret, frame = cap.read()
73-
if not ret:
74-
break
41+
Use our [interactive command builder](https://trackers.roboflow.com/develop/learn/track) to configure your tracking pipeline.
7542

76-
frame_rgb = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB)
77-
detections = model.predict(frame_rgb)
78-
detections = tracker.update(detections)
43+
```bash
44+
trackers track \
45+
--source video.mp4 \
46+
--output output.mp4 \
47+
--model rfdetr-medium \
48+
--tracker bytetrack \
49+
--show-labels \
50+
--show-trajectories
7951
```
8052

81-
<details>
82-
<summary>run with Inference</summary>
53+
## Track from Python
54+
55+
Plug trackers into your existing detection pipeline. Works with any detector.
8356

8457
```python
8558
import cv2
8659
import supervision as sv
8760
from inference import get_model
8861
from trackers import ByteTrackTracker
8962

90-
model = get_model(model_id="rfdetr-nano")
63+
model = get_model(model_id="rfdetr-medium")
9164
tracker = ByteTrackTracker()
9265

93-
cap = cv2.VideoCapture("source.mp4")
94-
while True:
66+
label_annotator = sv.LabelAnnotator()
67+
trajectory_annotator = sv.TrajectoryAnnotator()
68+
69+
cap = cv2.VideoCapture("video.mp4")
70+
while cap.isOpened():
9571
ret, frame = cap.read()
9672
if not ret:
9773
break
9874

9975
result = model.infer(frame)[0]
10076
detections = sv.Detections.from_inference(result)
101-
detections = tracker.update(detections)
77+
tracked = tracker.update(detections)
78+
79+
frame = label_annotator.annotate(frame, tracked)
80+
frame = trajectory_annotator.annotate(frame, tracked)
10281
```
10382

104-
</details>
83+
## Evaluate
10584

106-
<details>
107-
<summary>run with Ultralytics</summary>
85+
Benchmark your tracker against ground truth with standard MOT metrics.
10886

109-
```python
110-
import cv2
111-
import supervision as sv
112-
from ultralytics import YOLO
113-
from trackers import ByteTrackTracker
87+
```bash
88+
trackers eval \
89+
--gt-dir data/gt \
90+
--tracker-dir data/trackers \
91+
--metrics CLEAR HOTA Identity
92+
```
11493

115-
model = YOLO("yolo11n.pt")
116-
tracker = ByteTrackTracker()
94+
```
95+
Sequence MOTA HOTA IDF1 IDSW
96+
----------------------------------------------------------
97+
MOT17-02-FRCNN 75.600 62.300 72.100 42
98+
MOT17-04-FRCNN 78.200 65.100 74.800 31
99+
----------------------------------------------------------
100+
COMBINED 75.033 62.400 72.033 73
101+
```
117102

118-
cap = cv2.VideoCapture("source.mp4")
119-
while True:
120-
ret, frame = cap.read()
121-
if not ret:
122-
break
103+
## Algorithms
123104

124-
result = model(frame)[0]
125-
detections = sv.Detections.from_ultralytics(result)
126-
detections = tracker.update(detections)
127-
```
105+
Clean, modular implementations of leading trackers. See the [tracker comparison](https://trackers.roboflow.com/develop/trackers/comparison/) for detailed benchmarks.
128106

129-
</details>
107+
| Algorithm | MOT17 | SportsMOT | SoccerNet |
108+
| :-------------------------------------------: | :------: | :-------: | :-------: |
109+
| [SORT](https://arxiv.org/abs/1602.00763) | 58.4 | 70.9 | 81.6 |
110+
| [ByteTrack](https://arxiv.org/abs/2110.06864) | **60.1** | **73.0** | **84.0** |
111+
| [OC-SORT](https://arxiv.org/abs/2203.14360) | — | — | — |
112+
| [BoT-SORT](https://arxiv.org/abs/2206.14651) | — | — | — |
113+
| [McByte](https://arxiv.org/abs/2506.01373) | — | — | — |
130114

131-
## License
115+
## Contributing
132116

133-
The code is released under the [Apache 2.0 license](https://github.com/roboflow/trackers/blob/main/LICENSE).
117+
We welcome contributions. Read our [contributor guidelines](https://github.com/roboflow/trackers/blob/main/CONTRIBUTING.md) to get started.
134118

135-
## Contribution
119+
## License
136120

137-
We welcome all contributions—whether it’s reporting issues, suggesting features, or submitting pull requests. Please read our [contributor guidelines](https://github.com/roboflow/trackers/blob/main/CONTRIBUTING.md) to learn about our processes and best practices.
121+
The code is released under the [Apache 2.0 license](https://github.com/roboflow/trackers/blob/main/LICENSE).

‎pyproject.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
[project]
22
name = "trackers"
3-
version = "2.2.0rc1"
3+
version = "2.2.0"
44
description = "A unified library for object tracking featuring clean room re-implementations of leading multi-object tracking algorithms"
55
readme = "README.md"
66
maintainers = [

0 commit comments

Comments
 (0)