repository·develop·Indexed 25 days ago
https://github.com/roboflow/trackersA detector-agnostic Python library providing clean-room implementations of multi-object tracking (MOT) algorithms, including SORT, ByteTrack, OC-SORT, BoT-SORT, C-BIoU, and McByte. It integrates natively with the supervision ecosystem and includes a CLI for tracking, tools for downloading benchmark datasets like MOT17 and SportsMOT, and utilities for evaluating performance using HOTA, IDF1, and MOTA metrics.
Roboflow Trackers is an open-source Python library providing clean-room implementations of multi-object tracking (MOT) algorithms, including SORT, ByteTrack, OC-SORT, and BoT-SORT.
Key features include:
supervision library using a single tracker.update(detections) call.SORT (Simple Online and Realtime Tracking) is a fast, lightweight tracking-by-detection method. It uses a Kalman filter for motion prediction and the Hungarian algorithm for data association based on Intersection over Union (IoU).
Key Characteristics:
McByte is a mask-conditioned multi-object tracking (MOT) algorithm that extends the BoT-SORT tracking-by-detection pipeline. It uses temporally propagated segmentation masks (via SAM and Cutie) as an additional matching cue to resolve ambiguous or isolated IoU-based matches.
Key characteristics:
State estimators wrap a Kalman filter to define how bounding boxes are encoded into the filter's state vector. This controls how the filter predicts the next position of a tracked object.
Both available estimators accept [x1, y1, x2, y2] bounding boxes on input and produce [x1, y1, x2, y2] bounding boxes on output. The difference lies in the internal motion modeling:
| Estimator | State Dimensions | Representation | Aspect Ratio |
|---|---|---|---|
XYXYStateEstimator | 8 | Top-left and bottom-right corners + velocities | Can change |
XCYCSRStateEstimator | 7 | Center point, area, velocities, and aspect ratio | Held constant |
trackers provides clean-room implementations of several multi-object tracking algorithms. Each is a faithful implementation of its original paper.
| Algorithm | Description |
|---|---|
| SORT | Kalman filter + Hungarian matching baseline. |
| ByteTrack | Two-stage association using high and low confidence detections. |
| OC-SORT | Observation-centric recovery for lost tracks. |
| BoT-SORT | Camera motion compensation (handles moving cameras natively). |
| C-BIoU | Cascaded buffered IoU matching for fast or irregular motion. |
Additionally, trackers includes McByte, a mask-conditioned tracker that extends BoT-SORT-style association with temporally propagated SAM/Cutie segmentation masks. McByte requires additional dependencies (torch, SAM, Cutie).
Run multi-object tracking from the command line using default settings (RF-DETR Nano and ByteTrack).
trackers track --source source.mp4 --output output.mp4trackers package on PyPI. It requires Python 3.10+.McByte's performance is heavily influenced by the mask pipeline. You can optimize speed by adjusting the following parameters:
max_internal_size within the eval_config to a specific value (e.g., 540 for a 1920x1080 input). This forces Cutie to propagate masks at a lower resolution (e.g., 960x540) before resizing them back, reducing computational cost at the expense of precision.McByteMaskConfig(sam_model_type=...) to select a smaller SAM variant. This reduces the cost of initial mask creation when new tracklets appear.enable_mask_manager=False removes the mask pipeline overhead entirely, creating a mask-free configuration.To enable hyperparameter optimization using Optuna, install the tune extra for the trackers package.
pip install "trackers[tune]"Install the trackers package using pip. Requires Python $\ge$ 3.10.
pip install trackersTo handle irregular frame timing (e.g., dropped frames, sparse sampling, or variable FPS), pass an optional timestamp (in seconds) to the update() method of your tracker. This allows the tracker to scale Kalman predictions and track pruning based on the actual elapsed time between captured frames rather than assuming a constant frame rate.
Supported trackers:
SORTTrackerByteTrackTrackerOCSORTTrackerBoTSORTTrackerCBIoUTrackerImportant Requirements:
timestamp is less than the previous call, the tracker will warn and skip the step (outputting IDs as -1).update() in non-decreasing capture time order. If processing frames out-of-order, sort them by capture time or frame index before updating.tracker.reset() when switching to a new video to prevent the last timestamp from the previous video from affecting the new one.# Example: Using ByteTrackTracker with timestamps from OpenCV
import cv2
import supervision as sv
from inference import get_model
from trackers import ByteTrackTracker
model = get_model("rfdetr-medium")
tracker = ByteTrackTracker(frame_rate=30.0, lost_track_buffer=30)
cap = cv2.VideoCapture("source.mp4")
while True:
ret, frame = cap.read()
if not ret:
break
# Get timestamp in seconds
timestamp = cap.get(cv2.CAP_PROP_POS_MSEC) / 1000.0
result = model.infer(frame)[0]
detections = sv.Detections.from_inference(result)
# Pass timestamp to enable dynamic rate mode
detections = tracker.update(detections, timestamp=timestamp)