### Initialize SORT Tracker with IoU

Source: https://github.com/roboflow/trackers/blob/develop/docs/learn/iou.md

Quickstart example showing how to initialize a SORT tracker with the default IoU metric and a minimum IoU threshold.

```python
from trackers import SORTTracker
from trackers.utils.iou import IoU

tracker = SORTTracker(
    iou=IoU(),
    minimum_iou_threshold=0.3,
)
```

--------------------------------

### Quickstart: Track Objects via CLI

Source: https://github.com/roboflow/trackers/blob/develop/docs/learn/track.md

Track objects in a video file using a single command. This example uses RF-DETR Nano and ByteTrack by default.

```bash
trackers track --source source.mp4 --output output.mp4
```

--------------------------------

### Quickstart: Track Objects via Python

Source: https://github.com/roboflow/trackers/blob/develop/docs/learn/track.md

Perform end-to-end object tracking in Python. This example integrates detection models from `inference` and formatting utilities from `supervision`.

```python
import cv2

import supervision as sv
from inference import get_model
from trackers import ByteTrackTracker

model = get_model("rfdetr-nano")
tracker = ByteTrackTracker()

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

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

--------------------------------

### Install Development Dependencies

Source: https://github.com/roboflow/trackers/blob/develop/docs/learn/about.md

Install development dependencies using `uv sync`. Ensure you have `uv` installed.

```bash
uv sync
```

--------------------------------

### Install Tuning Dependencies

Source: https://github.com/roboflow/trackers/blob/develop/docs/learn/tune.md

Install the tuning extra to enable Optuna-based hyperparameter search.

```text
pip install "trackers[tune]"
```

--------------------------------

### Install Trackers from Source

Source: https://github.com/roboflow/trackers/blob/develop/docs/learn/install.md

Install the latest development version directly from GitHub using pip.

```bash
pip install git+https://github.com/roboflow/trackers.git
```

--------------------------------

### Install Trackers with uv

Source: https://github.com/roboflow/trackers/blob/develop/docs/learn/install.md

Use this command to install the base trackers package with uv.

```bash
uv pip install trackers
```

--------------------------------

### Install Trackers Package

Source: https://github.com/roboflow/trackers/blob/develop/docs/learn/track.md

Install the base trackers package. Use the `[detection]` extra to include inference models for built-in detection.

```bash
pip install trackers
```

```bash
pip install trackers[detection]
```

--------------------------------

### Set Up Local Development Environment (virtualenv)

Source: https://github.com/roboflow/trackers/blob/develop/docs/learn/install.md

Clone the repository, set up a virtual environment with Python 3.10+, and install the package in editable mode.

```bash
git clone --depth 1 -b develop https://github.com/roboflow/trackers.git
cd trackers

python3.10 -m venv venv
source venv/bin/activate

pip install --upgrade pip
pip install -e "."
```

--------------------------------

### Set Up Local Development Environment (uv)

Source: https://github.com/roboflow/trackers/blob/develop/docs/learn/install.md

Clone the repository, configure uv with Python 3.10+, sync dependencies, and install the package in editable mode with all extras.

```bash
git clone --depth 1 -b develop https://github.com/roboflow/trackers.git
cd trackers

uv python pin 3.10
uv sync
uv pip install -e . --all-extras
```

--------------------------------

### Full Example: Compare ByteTrack with XYXY and XCYCSR Estimators

Source: https://github.com/roboflow/trackers/blob/develop/docs/learn/state-estimators.md

This example runs ByteTrack with both `XYXYStateEstimator` and `XCYCSRStateEstimator` on the same video to compare results side-by-side. It prints the tracker IDs assigned by each estimator.

```python
import cv2

import supervision as sv
from inference import get_model
from trackers import ByteTrackTracker
from trackers.utils.state_representations import (
    XCYCSRStateEstimator,
    XYXYStateEstimator,
)

model = get_model("rfdetr-nano")

tracker_xyxy = ByteTrackTracker(
    state_estimator_class=XYXYStateEstimator,
)
tracker_xcycsr = ByteTrackTracker(
    state_estimator_class=XCYCSRStateEstimator,
)

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

    result = model.infer(frame)[0]
    detections = sv.Detections.from_inference(result)

    tracked_xyxy = tracker_xyxy.update(detections)
    tracked_xcycsr = tracker_xcycsr.update(detections)

    # Compare tracker_id assignments, box smoothness, etc.
    print(f"XYXY IDs:   {tracked_xyxy.tracker_id}")
    print(f"XCYCSR IDs: {tracked_xcycsr.tracker_id}")
```

--------------------------------

### Install Trackers with Detection Extra (uv)

Source: https://github.com/roboflow/trackers/blob/develop/docs/learn/install.md

Install the trackers package with the 'detection' extra using uv to include built-in detection functionality.

```bash
uv pip install "trackers[detection]"
```

--------------------------------

### Install Trackers with Detection Extra

Source: https://github.com/roboflow/trackers/blob/develop/docs/learn/detection-quality.md

Install the 'trackers' library with the 'detection' extra to enable built-in model support. This is required for using various detection models with the tracker.

```bash
pip install trackers[detection]
```

--------------------------------

### Install Trackers with pip

Source: https://github.com/roboflow/trackers/blob/develop/docs/learn/install.md

Use this command to install the base trackers package with pip.

```bash
pip install trackers
```

--------------------------------

### Install Trackers with Detection Extra (pip)

Source: https://github.com/roboflow/trackers/blob/develop/docs/learn/install.md

Install the trackers package with the 'detection' extra using pip to include built-in detection functionality.

```bash
pip install "trackers[detection]"
```

--------------------------------

### Initialize OCSORT Tracker with GIoU

Source: https://github.com/roboflow/trackers/blob/develop/docs/learn/iou.md

Example of initializing an OCSORT tracker using the GIoU metric. Note that negative thresholds are permissible with GIoU.

```python
from trackers import OCSORTTracker
from trackers.utils.iou import GIoU


```

--------------------------------

### CLI: Configure Tracker Parameters

Source: https://github.com/roboflow/trackers/blob/develop/docs/learn/track.md

Select a specific tracker using the `--tracker` flag and fine-tune its behavior with `--tracker.*` arguments. This example configures ByteTrack with custom buffer and frame count settings.

```bash
trackers track \
    --source source.mp4 \
    --tracker bytetrack \
    --tracker.lost_track_buffer 60 \
    --tracker.minimum_consecutive_frames 5
```

--------------------------------

### Track Objects from Python

Source: https://github.com/roboflow/trackers/blob/develop/docs/index.md

Integrate trackers into a Python detection pipeline. This example uses ByteTrack with a specified detection model and processes a video file.

```python
import cv2
import supervision as sv
from inference import get_model
from trackers 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)
```

--------------------------------

### Run OC-SORT on Webcam Feed

Source: https://github.com/roboflow/trackers/blob/develop/docs/trackers/ocsort.md

This example shows how to apply the OC-SORT tracker to a live webcam feed. Replace `<WEBCAM_INDEX>` with your camera's index, typically 0. The code processes frames in real-time and displays the annotated output.

```python
import cv2
import supervision as sv
from rfdetr import RFDETRMedium
from trackers import OCSORTTracker

tracker = OCSORTTracker()
model = RFDETRMedium()

box_annotator = sv.BoxAnnotator()
label_annotator = sv.LabelAnnotator()

video_capture = cv2.VideoCapture("<WEBCAM_INDEX>")
if not video_capture.isOpened():
    raise RuntimeError("Failed to open webcam")

while True:
    success, frame_bgr = video_capture.read()
    if not success:
        break

    frame_rgb = cv2.cvtColor(frame_bgr, cv2.COLOR_BGR2RGB)
    detections = model.predict(frame_rgb)
    detections = tracker.update(detections)

    annotated_frame = box_annotator.annotate(frame_bgr, detections)
    annotated_frame = label_annotator.annotate(annotated_frame, detections, labels=detections.tracker_id)

    cv2.imshow("RF-DETR + OC-SORT", annotated_frame)
    if cv2.waitKey(1) & 0xFF == ord("q"):
        break

video_capture.release()
cv2.destroyAllWindows()
```

--------------------------------

### Run OC-SORT on Video File

Source: https://github.com/roboflow/trackers/blob/develop/docs/trackers/ocsort.md

This snippet demonstrates how to initialize and use the OC-SORT tracker with a local video file. Ensure OpenCV is installed and replace `<SOURCE_VIDEO_PATH>` with the actual path to your video.

```python
import cv2
import supervision as sv
from rfdetr import RFDETRMedium
from trackers import OCSORTTracker

tracker = OCSORTTracker()
model = RFDETRMedium()

box_annotator = sv.BoxAnnotator()
label_annotator = sv.LabelAnnotator()

video_capture = cv2.VideoCapture("<SOURCE_VIDEO_PATH>")
if not video_capture.isOpened():
    raise RuntimeError("Failed to open video source")

while True:
    success, frame_bgr = video_capture.read()
    if not success:
        break

    frame_rgb = cv2.cvtColor(frame_bgr, cv2.COLOR_BGR2RGB)
    detections = model.predict(frame_rgb)
    detections = tracker.update(detections)

    annotated_frame = box_annotator.annotate(frame_bgr, detections)
    annotated_frame = label_annotator.annotate(annotated_frame, detections, labels=detections.tracker_id)

    cv2.imshow("RF-DETR + OC-SORT", annotated_frame)
    if cv2.waitKey(1) & 0xFF == ord("q"):
        break

video_capture.release()
cv2.destroyAllWindows()
```

--------------------------------

### Download MOT17 Dataset

Source: https://github.com/roboflow/trackers/blob/develop/docs/learn/download.md

Example of downloading the MOT17 dataset with specified splits, assets, and output directory using both CLI and Python.

```APIDOC
## Download MOT17 Dataset

### Description
Download specific splits and assets of the MOT17 dataset to a custom output directory.

### CLI Example
```text
trackers download mot17 \
    --split train,val \
    --asset annotations,frames \
    --output ./datasets
```

### Python Example
```python
from trackers import Dataset, DatasetAsset, DatasetSplit, download_dataset

download_dataset(
    dataset=Dataset.MOT17,
    split=[DatasetSplit.TRAIN, DatasetSplit.VAL],
    asset=[DatasetAsset.ANNOTATIONS, DatasetAsset.FRAMES],
    output="./datasets",
)
```
```

--------------------------------

### MOT Challenge Data Format Example

Source: https://github.com/roboflow/trackers/blob/develop/docs/learn/evaluate.md

Example lines demonstrating the MOT Challenge text format for ground-truth and tracker output files. Each line includes frame, ID, bounding box, confidence, and position.

```text
1,1,100,200,50,80,1,-1,-1,-1
1,2,300,150,60,90,1,-1,-1,-1
2,1,105,198,50,80,1,-1,-1,-1
```

--------------------------------

### Python: Integrate Detection Model

Source: https://github.com/roboflow/trackers/blob/develop/docs/learn/track.md

Combine any detection library with any tracker. This Python example uses the `inference` library with RF-DETR for object detection, then passes the results to the tracker.

```python
import cv2

import supervision as sv
from inference import get_model
from trackers import ByteTrackTracker

model = get_model("rfdetr-nano")
tracker = ByteTrackTracker()

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

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

--------------------------------

### CLI: Configure Detection Model

Source: https://github.com/roboflow/trackers/blob/develop/docs/learn/track.md

Specify the detection model using `--model.*` arguments and filter detections by confidence and class before tracking. This example uses RF-DETR medium with a confidence threshold and selects specific classes.

```bash
trackers track \
    --source source.mp4 \
    --model rfdetr-medium \
    --model.confidence 0.3 \
    --model.device cuda \
    --classes person,car
```

--------------------------------

### Run ByteTrack with RF-DETR Nano (Single Sequence)

Source: https://github.com/roboflow/trackers/blob/develop/docs/learn/detection-quality.md

Execute ByteTrack on a single sequence of the MOT17 dataset using the RF-DETR Nano detection model. This command is similar to the YOLO26 Nano example but uses a different detector.

```bash
trackers track \
        --source ./data/mot17/val/MOT17-13-FRCNN/img1 \
        --model rfdetr-nano \
        --tracker bytetrack \
        --classes person \
        --mot-output results/rfdetr-nano/MOT17-13-FRCNN.txt
```

--------------------------------

### Run BoT-SORT Tracker on Video

Source: https://github.com/roboflow/trackers/blob/develop/docs/trackers/botsort.md

Integrates BoT-SORT with RFDETR to track objects in a video file. Replace `<SOURCE_VIDEO_PATH>` with the actual path to your video. This example uses `opencv-python` for video decoding and display.

```python
import cv2
import supervision as sv
from rfdetr import RFDETRMedium
from trackers import BoTSORTTracker

tracker = BoTSORTTracker()
model = RFDETRMedium()

box_annotator = sv.BoxAnnotator()
label_annotator = sv.LabelAnnotator()

video_capture = cv2.VideoCapture("<SOURCE_VIDEO_PATH>")
if not video_capture.isOpened():
    raise RuntimeError("Failed to open video source")

while True:
    success, frame_bgr = video_capture.read()
    if not success:
        break

    frame_rgb = cv2.cvtColor(frame_bgr, cv2.COLOR_BGR2RGB)
    detections = model.predict(frame_rgb)
    detections = tracker.update(detections, frame=frame_bgr)

    annotated_frame = box_annotator.annotate(frame_bgr, detections)
    annotated_frame = label_annotator.annotate(
        annotated_frame,
        detections,
        labels=detections.tracker_id,
    )

    cv2.imshow("RF-DETR + BoT-SORT", annotated_frame)
    if cv2.waitKey(1) & 0xFF == ord("q"):
        break

video_capture.release()
cv2.destroyAllWindows()
```

--------------------------------

### Track Objects in Video with SORT

Source: https://github.com/roboflow/trackers/blob/develop/docs/trackers/sort.md

Use this snippet to track objects in a video file using the SORT tracker. Ensure you have OpenCV and supervision installed, and replace `<SOURCE_VIDEO_PATH>` with your video file path.

```python
import cv2
import supervision as sv
from rfdetr import RFDETRMedium
from trackers import SORTTracker

tracker = SORTTracker()
model = RFDETRMedium()

box_annotator = sv.BoxAnnotator()
label_annotator = sv.LabelAnnotator()

video_capture = cv2.VideoCapture("<SOURCE_VIDEO_PATH>")
if not video_capture.isOpened():
    raise RuntimeError("Failed to open video source")

while True:
    success, frame_bgr = video_capture.read()
    if not success:
        break

    frame_rgb = cv2.cvtColor(frame_bgr, cv2.COLOR_BGR2RGB)
    detections = model.predict(frame_rgb)
    detections = tracker.update(detections)

    annotated_frame = box_annotator.annotate(frame_bgr, detections)
    annotated_frame = label_annotator.annotate(
        annotated_frame,
        detections,
        labels=detections.tracker_id,
    )

    cv2.imshow("RF-DETR + SORT", annotated_frame)
    if cv2.waitKey(1) & 0xFF == ord("q"):
        break

video_capture.release()
cv2.destroyAllWindows()
```

--------------------------------

### Run BoT-SORT Tracker on Webcam

Source: https://github.com/roboflow/trackers/blob/develop/docs/trackers/botsort.md

Integrates BoT-SORT with RFDETR to track objects from a webcam feed. Replace `<WEBCAM_INDEX>` with your camera's index (usually 0). This example uses `opencv-python` for video decoding and display.

```python
import cv2
import supervision as sv
from trackers.core.botsort import BoTSORTTracker
from rfdetr import RFDETRMedium

tracker = BoTSORTTracker()
model = RFDETRMedium()

box_annotator = sv.BoxAnnotator()
label_annotator = sv.LabelAnnotator()

video_capture = cv2.VideoCapture("<WEBCAM_INDEX>")
if not video_capture.isOpened():
    raise RuntimeError("Failed to open webcam")

while True:
    success, frame_bgr = video_capture.read()
    if not success:
        break

    frame_rgb = cv2.cvtColor(frame_bgr, cv2.COLOR_BGR2RGB)
    detections = model.predict(frame_rgb)
    detections = tracker.update(detections, frame=frame_bgr)

    annotated_frame = box_annotator.annotate(frame_bgr, detections)
    annotated_frame = label_annotator.annotate(
        annotated_frame,
        detections,
        labels=detections.tracker_id,
    )

    cv2.imshow("RF-DETR + BoT-SORT", annotated_frame)
    if cv2.waitKey(1) & 0xFF == ord("q"):
        break

video_capture.release()
cv2.destroyAllWindows()
```

--------------------------------

### Specify Input Source with CLI

Source: https://github.com/roboflow/trackers/blob/develop/docs/learn/track.md

Pass videos, webcams, streams, or image directories as input sources using the CLI.

```text
trackers track --source source.mp4
```

--------------------------------

### Evaluation Results Table

Source: https://github.com/roboflow/trackers/blob/develop/docs/index.md

Example output table showing MOTA, HOTA, and IDF1 scores for different sequences and a combined score.

```text
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
```

--------------------------------

### List Available Datasets (CLI)

Source: https://github.com/roboflow/trackers/blob/develop/docs/learn/download.md

Use the `--list` flag with the trackers download command to see all available datasets, their splits, and asset types.

```text
trackers download --list
```

--------------------------------

### Run Tuner from CLI (Detection-Only)

Source: https://github.com/roboflow/trackers/blob/develop/docs/learn/tune.md

Run the tracker tuning process from the command line interface, configuring it for detection-only mode with specific fixed parameters.

```text
trackers tune \
    --tracker botsort \
    --gt-dir ./data/gt \
    --detections-dir ./data/detections \
    --fixed-params '{"enable_cmc": false}'
```

--------------------------------

### Visualize Tracking Results with CLI Options

Source: https://github.com/roboflow/trackers/blob/develop/docs/learn/track.md

Enable display and annotation options to see results in real time or in saved video using the CLI.

```text
trackers track \
    --source source.mp4 \
    --display \
    --show-labels \
    --show-confidence \
    --show-trajectories
```

--------------------------------

### Multi-Sequence Evaluation

Source: https://github.com/roboflow/trackers/blob/develop/docs/learn/evaluate.md

Evaluate all sequences in a directory and get per-sequence and aggregate results. Specify directories for ground truth and tracker outputs, metrics, columns, and an output JSON file.

```text
trackers eval \
    --gt-dir ./data/mot17/val \
    --tracker-dir results \
    --metrics CLEAR HOTA Identity \
    --columns MOTA HOTA IDF1 \
    --output results.json
```

--------------------------------

### Track Objects from CLI

Source: https://github.com/roboflow/trackers/blob/develop/docs/index.md

Run a tracking pipeline from the command line. Specify source video, output file, detection model, tracker, and visualization options.

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

--------------------------------

### Download Benchmark Datasets

Source: https://github.com/roboflow/trackers/blob/develop/docs/index.md

Use this command to pull benchmark datasets for evaluation. Specify the dataset name and the assets you need.

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

--------------------------------

### Apply Tuned Parameters to Tracker

Source: https://github.com/roboflow/trackers/blob/develop/docs/learn/tune.md

Load the best parameters from a JSON file and use them to initialize a tracker instance, applying the optimized configuration.

```python
import json

from trackers import ByteTrackTracker

with open("./results/bytetrack-best.json", "r", encoding="utf-8") as f:
    best_params = json.load(f)

tracker = ByteTrackTracker(**best_params)
```

--------------------------------

### Run BoT-SORT Tracker on RTSP Stream

Source: https://github.com/roboflow/trackers/blob/develop/docs/trackers/botsort.md

Integrates BoT-SORT with RFDETR to track objects from an RTSP stream. Replace `<RTSP_STREAM_URL>` with your stream's URL. This example uses `opencv-python` for video decoding and display.

```python
import cv2
import supervision as sv
from trackers.core.botsort import BoTSORTTracker
from rfdetr import RFDETRMedium

tracker = BoTSORTTracker()
model = RFDETRMedium()

box_annotator = sv.BoxAnnotator()
label_annotator = sv.LabelAnnotator()

video_capture = cv2.VideoCapture("<RTSP_STREAM_URL>")
if not video_capture.isOpened():
    raise RuntimeError("Failed to open RTSP stream")

while True:
    success, frame_bgr = video_capture.read()
    if not success:
        break

    frame_rgb = cv2.cvtColor(frame_bgr, cv2.COLOR_BGR2RGB)
    detections = model.predict(frame_rgb)
    detections = tracker.update(detections, frame=frame_bgr)

    annotated_frame = box_annotator.annotate(frame_bgr, detections)
    annotated_frame = label_annotator.annotate(
        annotated_frame,
        detections,
        labels=detections.tracker_id,
    )

    cv2.imshow("RF-DETR + BoT-SORT", annotated_frame)
    if cv2.waitKey(1) & 0xFF == ord("q"):
        break

video_capture.release()
cv2.destroyAllWindows()
```

--------------------------------

### Download Multiple Splits and Assets (CLI)

Source: https://github.com/roboflow/trackers/blob/develop/docs/learn/download.md

Download specific combinations of splits and assets by providing comma-separated lists to the `--split` and `--asset` flags.

```text
trackers download mot17 --split train,val --asset annotations,frames
```

--------------------------------

### Python: Configure Tracker Parameters

Source: https://github.com/roboflow/trackers/blob/develop/docs/learn/track.md

Customize tracker behavior by passing parameters to the constructor. Use `update()` for frame-by-frame processing and `reset()` to clear state between videos.

```python
import cv2

import supervision as sv
from inference import get_model
from trackers import ByteTrackTracker

model = get_model("rfdetr-nano")
tracker = ByteTrackTracker(
    lost_track_buffer=60,
    minimum_consecutive_frames=5,
)

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

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

--------------------------------

### Initialize Tuner for BoTSORT with CMC

Source: https://github.com/roboflow/trackers/blob/develop/docs/learn/tune.md

Initialize the Tuner class for BoTSORT tracker with CMC enabled. This requires MOT-style images to be present.

```python
from trackers.tune import Tuner

# BoTSORT with CMC (MOT-style images required)
tuner = Tuner(
    tracker_id="botsort",
    gt_dir="./data/gt",
    detections_dir="./data/detections",
    images_dir="./data/images",
    fixed_params={"enable_cmc": True},
    n_trials=50,
)
```

--------------------------------

### Initialize Tuner for BoTSORT (Detection-Only)

Source: https://github.com/roboflow/trackers/blob/develop/docs/learn/tune.md

Initialize the Tuner class for BoTSORT tracker with detection-only mode. This configuration is suitable when image sequences are not required for tracking.

```python
from trackers.tune import Tuner

# Detection-only BoTSORT (no frames, CMC off)
tuner = Tuner(
    tracker_id="botsort",
    gt_dir="./data/gt",
    detections_dir="./data/detections",
    fixed_params={"enable_cmc": False},
    n_trials=50,
)
```

--------------------------------

### Configure IoU Variants in Trackers

Source: https://github.com/roboflow/trackers/blob/develop/docs/learn/iou.md

Demonstrates configuring different IoU variants (IoU, GIoU, CIoU, BIoU) with SORT and OCSORT trackers, including custom buffer ratios for BIoU and negative thresholds for GIoU.

```python
from trackers import OCSORTTracker, SORTTracker
from trackers.utils.iou import BIoU, CIoU, GIoU, IoU

# Standard IoU in SORT
sort_iou = SORTTracker(iou=IoU(), minimum_iou_threshold=0.3)

# GIoU in OC-SORT (negative thresholds are valid)
ocsort_giou = OCSORTTracker(iou=GIoU(), minimum_iou_threshold=-0.3)

# CIoU in OC-SORT
ocsort_ciou = OCSORTTracker(iou=CIoU(), minimum_iou_threshold=-0.3)

# Buffered IoU in SORT
sort_biou = SORTTracker(
    iou=BIoU(buffer_ratio=0.1),
    minimum_iou_threshold=0.3,
)
```

--------------------------------

### Run ByteTrack on Video

Source: https://github.com/roboflow/trackers/blob/develop/docs/trackers/bytetrack.md

Use this snippet to process a local video file. Replace `<SOURCE_VIDEO_PATH>` with the actual path to your video.

```python
import cv2
import supervision as sv
from rfdetr import RFDETRMedium
from trackers import ByteTrackTracker

tracker = ByteTrackTracker()
model = RFDETRMedium()

box_annotator = sv.BoxAnnotator()
label_annotator = sv.LabelAnnotator()

video_capture = cv2.VideoCapture("<SOURCE_VIDEO_PATH>")
if not video_capture.isOpened():
    raise RuntimeError("Failed to open video source")

while True:
    success, frame_bgr = video_capture.read()
    if not success:
        break

    frame_rgb = cv2.cvtColor(frame_bgr, cv2.COLOR_BGR2RGB)
    detections = model.predict(frame_rgb)
    detections = tracker.update(detections)

    annotated_frame = box_annotator.annotate(frame_bgr, detections)
    annotated_frame = label_annotator.annotate(
        annotated_frame,
        detections,
        labels=detections.tracker_id,
    )

    cv2.imshow("RF-DETR + ByteTrack", annotated_frame)
    if cv2.waitKey(1) & 0xFF == ord("q"):
        break

video_capture.release()
cv2.destroyAllWindows()
```

--------------------------------

### Tune ByteTrack with Python

Source: https://github.com/roboflow/trackers/blob/develop/docs/learn/tune.md

Run the tracker tuning process using the Tuner class in Python, optimizing for HOTA and other specified metrics, with a defined seed for reproducibility.

```python
from trackers.tune import Tuner

tuner = Tuner(
    tracker_id="bytetrack",
    gt_dir="./data/gt",
    detections_dir="./data/detections",
    objective="HOTA",
    metrics=["CLEAR", "HOTA", "Identity"],
    n_trials=50,
    seed=42,
)

best_params = tuner.run()
print(best_params)
```

--------------------------------

### Run ByteTrack on Webcam

Source: https://github.com/roboflow/trackers/blob/develop/docs/trackers/bytetrack.md

Use this snippet to process a live feed from a webcam. Replace `<WEBCAM_INDEX>` with your camera's index, typically 0.

```python
import cv2
import supervision as sv
from rfdetr import RFDETRMedium
from trackers import ByteTrackTracker

tracker = ByteTrackTracker()
model = RFDETRMedium()

box_annotator = sv.BoxAnnotator()
label_annotator = sv.LabelAnnotator()

video_capture = cv2.VideoCapture("<WEBCAM_INDEX>")
if not video_capture.isOpened():
    raise RuntimeError("Failed to open webcam")

while True:
    success, frame_bgr = video_capture.read()
    if not success:
        break

    frame_rgb = cv2.cvtColor(frame_bgr, cv2.COLOR_BGR2RGB)
    detections = model.predict(frame_rgb)
    detections = tracker.update(detections)

    annotated_frame = box_annotator.annotate(frame_bgr, detections)
    annotated_frame = label_annotator.annotate(
        annotated_frame,
        detections,
        labels=detections.tracker_id,
    )

    cv2.imshow("RF-DETR + ByteTrack", annotated_frame)
    if cv2.waitKey(1) & 0xFF == ord("q"):
        break

video_capture.release()
cv2.destroyAllWindows()
```

--------------------------------

### Download Specific SportsMOT Split and Asset (CLI)

Source: https://github.com/roboflow/trackers/blob/develop/docs/learn/download.md

Download a specific split and asset for the SportsMOT dataset using the CLI.

```text
trackers download sportsmot --split val --asset annotations
```

--------------------------------

### Run Tracker on Detections (CLI)

Source: https://github.com/roboflow/trackers/blob/develop/docs/learn/evaluate.md

Feed pre-computed detections into a tracker and save the output in MOT format. Specify the input detections file, tracker type, and output file path.

```text
trackers track \
    --detections ./data/mot17/val/MOT17-02-FRCNN/det/det.txt \
    --tracker bytetrack \
    --mot-output results/MOT17-02-FRCNN.txt
```

--------------------------------

### CLI Reference for `trackers download`

Source: https://github.com/roboflow/trackers/blob/develop/docs/learn/download.md

Detailed reference for all arguments accepted by the `trackers download` command.

```APIDOC
## CLI Reference

### `trackers download` Arguments

| Argument      | Description                                                                 | Default       |
|---------------|-----------------------------------------------------------------------------|---------------|
| `dataset`     | Dataset name to download. Options: `mot17`, `sportsmot`.                    | —             |
| `--list`      | List available datasets, splits, and asset types without downloading.       | `false`       |
| `--split`     | Comma-separated splits to download. Omit to download all available splits.  | all           |
| `--asset`     | Comma-separated asset types to download: `frames`, `annotations`, `detections`. Omit to download all available assets. | all           |
| `--output`    | Directory where dataset files are extracted.                                | `.`           |
| `--cache-dir` | Directory for caching downloaded ZIP files. Cached files are verified by MD5 and reused across runs. | `~/.cache/trackers` |
```

--------------------------------

### Tune ByteTrack with CLI

Source: https://github.com/roboflow/trackers/blob/develop/docs/learn/tune.md

Tune the ByteTrack tracker using the CLI, optimizing for HOTA metric and specifying output file for best parameters.

```text
trackers tune \
    --tracker bytetrack \
    --gt-dir ./data/gt \
    --detections-dir ./data/detections \
    --objective HOTA \
    --metrics CLEAR HOTA Identity \
    --n-trials 50 \
    --output ./results/bytetrack-best.json
```

--------------------------------

### Initialize ByteTrack with XCYCSRStateEstimator

Source: https://github.com/roboflow/trackers/blob/develop/docs/learn/state-estimators.md

Import and pass `XCYCSRStateEstimator` to the `ByteTrackTracker` constructor. This is useful when objects maintain a consistent shape.

```python
from trackers import ByteTrackTracker
from trackers.utils.state_representations import XCYCSRStateEstimator

tracker = ByteTrackTracker(
    state_estimator_class=XCYCSRStateEstimator,
)
```

--------------------------------

### Download Full MOT17 Dataset (CLI)

Source: https://github.com/roboflow/trackers/blob/develop/docs/learn/download.md

Download the entire MOT17 dataset, including all splits and assets, using the CLI.

```text
trackers download mot17
```

--------------------------------

### Initialize OCSORTTracker with GIoU

Source: https://github.com/roboflow/trackers/blob/develop/docs/learn/iou.md

Use GIoU for tracking when IoU might drop to zero due to camera movement or direction changes. Negative thresholds are valid and can be optimal.

```python
from trackers import OCSORTTracker
from trackers.utils.iou import GIoU

tracker = OCSORTTracker(iou=GIoU(), minimum_iou_threshold=-0.3)
```

--------------------------------

### Tune with Sequence Subset (CLI)

Source: https://github.com/roboflow/trackers/blob/develop/docs/learn/tune.md

Tune the ByteTrack tracker using a specified sequence map file to limit tuning to a subset of sequences, configured via CLI.

```text
trackers tune \
    --tracker bytetrack \
    --gt-dir ./data/gt \
    --detections-dir ./data/detections \
    --seqmap ./seqmap.txt
```

--------------------------------

### Run ByteTrack with YOLO26 Nano (Single Sequence)

Source: https://github.com/roboflow/trackers/blob/develop/docs/learn/detection-quality.md

Execute ByteTrack on a single sequence of the MOT17 dataset using the YOLO26 Nano detection model. Ensure the output path for the MOT results is specified.

```bash
trackers track \
        --source ./data/mot17/val/MOT17-13-FRCNN/img1 \
        --model yolo26n-640 \
        --tracker bytetrack \
        --classes person \
        --mot-output results/yolo26n/MOT17-13-FRCNN.txt
```

--------------------------------

### Download MOT17 Dataset Assets (CLI)

Source: https://github.com/roboflow/trackers/blob/develop/docs/learn/evaluate.md

Use the CLI command to download MOT17 validation annotations and detections. Specify the dataset, split, assets, and output directory.

```text
trackers download mot17 \
    --split val \
    --asset annotations,detections \
    --output ./data
```

--------------------------------

### Run ByteTrack with RF-DETR Nano (All Sequences)

Source: https://github.com/roboflow/trackers/blob/develop/docs/learn/detection-quality.md

Iterate through all sequences in the MOT17 validation set and run ByteTrack with the RF-DETR Nano detection model for each. This facilitates comparison with other detectors across the entire dataset.

```bash
for seq in MOT17-02-FRCNN MOT17-04-FRCNN MOT17-05-FRCNN MOT17-09-FRCNN MOT17-10-FRCNN MOT17-11-FRCNN MOT17-13-FRCNN; do
    trackers track \
        --source ./data/mot17/val/$seq/img1 \
        --model rfdetr-nano \
        --tracker bytetrack \
        --classes person \
        --mot-output results/rfdetr-nano/$seq.txt
done
```

--------------------------------

### SoccerNet-tracking Tuned Tracker Configurations

Source: https://github.com/roboflow/trackers/blob/develop/docs/trackers/comparison.md

Provides the tuned YAML configurations for SORT, ByteTrack, OC-SORT, and BoT-SORT trackers on the SoccerNet-tracking dataset. These parameters were optimized via grid search.

```yaml
SORT:
  lost_track_buffer: 30
  track_activation_threshold: 0.25
  minimum_consecutive_frames: 2
  minimum_iou_threshold: 0.05

ByteTrack:
  lost_track_buffer: 30
  track_activation_threshold: 0.2
  minimum_consecutive_frames: 1
  minimum_iou_threshold: 0.05
  high_conf_det_threshold: 0.5

OC-SORT:
  lost_track_buffer: 60
  minimum_iou_threshold: 0.1
  minimum_consecutive_frames: 3
  direction_consistency_weight: 0.2
  high_conf_det_threshold: 0.4
  delta_t: 1

BoT-SORT:
  lost_track_buffer: 60
  minimum_consecutive_frames: 2
  minimum_iou_threshold_first_assoc: 0.1
  minimum_iou_threshold_second_assoc: 0.6
  minimum_iou_threshold_unconfirmed_assoc: 0.2
  high_conf_det_threshold: 0.6
  track_activation_threshold: 0.7
  enable_cmc: true
  cmc_method: sparseOptFlow
```

--------------------------------

### Add Trackers to uv Project

Source: https://github.com/roboflow/trackers/blob/develop/docs/learn/install.md

If your project uses uv for dependency management, add trackers directly to your project using this command.

```bash
uv add trackers
```

--------------------------------

### Format Code with Pre-commit

Source: https://github.com/roboflow/trackers/blob/develop/docs/learn/about.md

Run pre-commit to check formatting, linting, and type checks across all files. This ensures code style consistency.

```bash
pre-commit run --all-files
```

--------------------------------

### Download MOT17 Dataset to Custom Output Path

Source: https://github.com/roboflow/trackers/blob/develop/docs/learn/download.md

Specify a custom output directory for dataset extraction using the `--output` flag in the CLI or the `output` parameter in Python.

```text
trackers download mot17 \
    --split train,val \
    --asset annotations,frames \
    --output ./datasets
```

```python
from trackers import Dataset, DatasetAsset, DatasetSplit, download_dataset

download_dataset(
    dataset=Dataset.MOT17,
    split=[DatasetSplit.TRAIN, DatasetSplit.VAL],
    asset=[DatasetAsset.ANNOTATIONS, DatasetAsset.FRAMES],
    output="./datasets",
)
```

--------------------------------

### Download Specific Split and Asset (CLI)

Source: https://github.com/roboflow/trackers/blob/develop/docs/learn/download.md

Filter downloads by specifying a single split and asset type using the `--split` and `--asset` flags.

```text
trackers download mot17 --split train --asset annotations
```

--------------------------------

### Tune with Sequence Subset (Python)

Source: https://github.com/roboflow/trackers/blob/develop/docs/learn/tune.md

Tune the ByteTrack tracker using a specified sequence map file to limit tuning to a subset of sequences, configured via the Tuner class in Python.

```python
from trackers.tune import Tuner

tuner = Tuner(
    tracker_id="bytetrack",
    gt_dir="./data/gt",
    detections_dir="./data/detections",
    seqmap="./seqmap.txt",
    n_trials=25,
)

best_params = tuner.run()
print(best_params)
```

--------------------------------

### Track with RF-DETR Medium (Single Sequence)

Source: https://github.com/roboflow/trackers/blob/develop/docs/learn/detection-quality.md

Use this command to run object tracking on a single sequence using the RF-DETR medium model and ByteTrack.

```bash
trackers track \
    --source ./data/mot17/val/MOT17-13-FRCNN/img1 \
    --model rfdetr-medium \
    --tracker bytetrack \
    --classes person \
    --mot-output results/rfdetr-medium/MOT17-13-FRCNN.txt
```

--------------------------------

### Run ByteTrack with YOLO26 Nano (All Sequences)

Source: https://github.com/roboflow/trackers/blob/develop/docs/learn/detection-quality.md

Iterate through all sequences in the MOT17 validation set and run ByteTrack with the YOLO26 Nano detection model for each. This allows for comprehensive evaluation across the dataset.

```bash
for seq in MOT17-02-FRCNN MOT17-04-FRCNN MOT17-05-FRCNN MOT17-09-FRCNN MOT17-10-FRCNN MOT17-11-FRCNN MOT17-13-FRCNN; do
    trackers track \
        --source ./data/mot17/val/$seq/img1 \
        --model yolo26n-640 \
        --tracker bytetrack \
        --classes person \
        --mot-output results/yolo26n/$seq.txt
done
```

--------------------------------

### Initialize OC-SORT with XYXYStateEstimator

Source: https://github.com/roboflow/trackers/blob/develop/docs/learn/state-estimators.md

Import and pass `XYXYStateEstimator` to the `OCSORTTracker` constructor. This is suitable when object shapes vary or fewer assumptions are desired.

```python
from trackers import OCSORTTracker
from trackers.utils.state_representations import XYXYStateEstimator

tracker = OCSORTTracker(
    state_estimator_class=XYXYStateEstimator,
)
```

--------------------------------

### Download MOT17 Dataset Assets (Python)

Source: https://github.com/roboflow/trackers/blob/develop/docs/learn/evaluate.md

Use the Python API to download MOT17 validation annotations and detections. Import necessary components and call the download function.

```python
from trackers import Dataset, DatasetAsset, DatasetSplit, download_dataset

download_dataset(
    dataset=Dataset.MOT17,
    split=DatasetSplit.VAL,
    asset=[DatasetAsset.ANNOTATIONS, DatasetAsset.DETECTIONS],
    output="./data",
)
```

--------------------------------

### Track with RF-DETR Medium (All Sequences)

Source: https://github.com/roboflow/trackers/blob/develop/docs/learn/detection-quality.md

This script iterates through multiple sequences, running object tracking with the RF-DETR medium model and ByteTrack for each.

```bash
for seq in MOT17-02-FRCNN MOT17-04-FRCNN MOT17-05-FRCNN MOT17-09-FRCNN MOT17-10-FRCNN MOT17-11-FRCNN MOT17-13-FRCNN; do
    trackers track \
        --source ./data/mot17/val/$seq/img1 \
        --model rfdetr-medium \
        --tracker bytetrack \
        --classes person \
        --mot-output results/rfdetr-medium/$seq.txt
done
```

--------------------------------

### Evaluate Tracker Performance

Source: https://github.com/roboflow/trackers/blob/develop/docs/index.md

Run this command to evaluate your tracker against ground-truth MOT-format text files. It computes HOTA, IDF1, and MOTA scores.

```bash
trackers eval
```

--------------------------------

### List Available Datasets (Python)

Source: https://github.com/roboflow/trackers/blob/develop/docs/learn/download.md

Iterate through the `Dataset` enum in Python to programmatically list all supported datasets.

```python
from trackers import Dataset

for dataset in Dataset:
    print(dataset.value)
```

--------------------------------

### Initialize OCSORTTracker with DIoU

Source: https://github.com/roboflow/trackers/blob/develop/docs/learn/iou.md

Employ DIoU to penalize center distance, encouraging center alignment independently of aspect ratio. This leads to smoother associations in fast-motion sequences.

```python
from trackers import OCSORTTracker
from trackers.utils.iou import DIoU

tracker = OCSORTTracker(iou=DIoU(), minimum_iou_threshold=-0.3)
```

--------------------------------

### Download Multiple Splits and Assets (Python)

Source: https://github.com/roboflow/trackers/blob/develop/docs/learn/download.md

Download multiple splits and assets for the MOT17 dataset using the Python API. Provide lists of enums or strings.

```python
from trackers import Dataset, DatasetAsset, DatasetSplit, download_dataset

download_dataset(
    dataset=Dataset.MOT17,
    split=[DatasetSplit.TRAIN, DatasetSplit.VAL],
    asset=[DatasetAsset.ANNOTATIONS, DatasetAsset.FRAMES],
)
```

--------------------------------

### Initialize OCSORTTracker with CIoU

Source: https://github.com/roboflow/trackers/blob/develop/docs/learn/iou.md

Utilize CIoU for tracking, which extends DIoU by adding a penalty for aspect-ratio mismatch. This is particularly effective for small, fast-moving objects like balls.

```python
from trackers import OCSORTTracker
from trackers.utils.iou import CIoU

tracker = OCSORTTracker(iou=CIoU(), minimum_iou_threshold=-0.3)
```

--------------------------------

### Initialize Giscus Theme

Source: https://github.com/roboflow/trackers/blob/develop/docs/overrides/partials/comments.html

Sets the Giscus theme based on the current site palette when the page loads. Ensure the Giscus script is present.

```javascript
var giscus = document.querySelector("script[src*=giscus]") /* Set palette on initial load */ var palette = __md_get("__palette") if (palette && typeof palette.color === "object") { var theme = palette.color.scheme === "slate" ? "dark" : "light" giscus.setAttribute("data-theme", theme) }
```

--------------------------------

### Caching Downloaded Files

Source: https://github.com/roboflow/trackers/blob/develop/docs/learn/download.md

Demonstrates how to specify a custom cache directory for downloaded dataset ZIP files, enabling reuse and verification.

```APIDOC
## Caching Downloaded Files

### Description
Customize the cache directory for downloaded dataset ZIP files. Files are verified with an MD5 checksum and reused in subsequent runs.

### CLI Example
```text
trackers download mot17 \
    --split train \
    --asset annotations \
    --cache-dir ./my-cache
```

### Python Example
```python
from trackers import Dataset, DatasetAsset, DatasetSplit, download_dataset

download_dataset(
    dataset=Dataset.MOT17,
    split=DatasetSplit.TRAIN,
    asset=DatasetAsset.ANNOTATIONS,
    cache_dir="./my-cache",
)
```
```