Skip to content

Tune Trackers

Use Optuna to tune tracker hyperparameters automatically and maximize your target metric on MOT-format evaluation data.

What you'll learn:

  • Install tuning dependencies
  • Prepare ground truth and detection files for tuning
  • Run tuning from CLI and Python
  • Save and apply the best parameter set

Install

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

pip install "trackers[tune]"

For more options, see the install guide.

Prepare Data

The tuner needs matching MOT files for ground truth and detections.

By default, the first trial evaluates a baseline parameter set before Optuna samples further combinations. That trial counts toward --n-trials / n_trials. Set enqueue_defaults=False on Tuner to disable this behavior.

For each search_space key, the baseline uses the tracker's default when it lies within the search space.

Options that are not tuned (or differ from __init__) are set with fixed_params on Tuner. They apply to every trial, including the baseline, override the same key in search_space if present, and are returned from run() merged into the best parameter dict.

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,
)

# 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,
)

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

Images are read from {images_dir}/{sequence}/img1/ using MOT-style stems: 6-digit (000001.jpg, MOT17/SportsMOT) or 8-digit (00000001.jpg, DanceTrack), plus common extensions (.jpg, .png, …).

data
├── gt
│   ├── MOT17-02-FRCNN.txt
│   ├── MOT17-04-FRCNN.txt
│   └── ...
└── detections
    ├── MOT17-02-FRCNN.txt
    ├── MOT17-04-FRCNN.txt
    └── ...

Each sequence must exist in both directories with the same filename ({sequence}.txt).

Use MOT format lines:

<frame>,<id>,<bb_left>,<bb_top>,<bb_width>,<bb_height>,<conf>,<x>,<y>,<z>

For detections, use id=-1. For more details on the format and evaluation workflow, see the evaluation guide.

Quickstart

Tune ByteTrack and optimize HOTA.

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

Run the same tuning flow with the Tuner class.

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)

Tune a Sequence Subset

Use a seqmap file when you want to tune on a specific subset of sequences.

# seqmap.txt
MOT17-02-FRCNN
MOT17-04-FRCNN
MOT17-09-FRCNN

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

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)

Use Best Parameters

Apply tuned values by unpacking the saved JSON dictionary into your tracker constructor.

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)

CLI Reference

All arguments accepted by trackers tune.

Argument Description Default
--tracker Tracker name to tune. Common values: bytetrack, sort, ocsort. —
--gt-dir Directory with ground-truth MOT files ({sequence}.txt). —
--detections-dir Directory with detection MOT files ({sequence}.txt), one file per sequence. —
--objective Metric to maximize: MOTA, HOTA, or IDF1. HOTA
--n-trials Number of Optuna trials to run. 100
--metrics Metric families to compute: CLEAR, HOTA, Identity. The family required by --objective is added automatically. CLEAR
--threshold IoU threshold used during evaluation matching for CLEAR and Identity. Higher values make scoring stricter, lower values make it more permissive. 0.5
--seqmap Optional path to a sequence map file. When set, only listed sequences are tuned. all files in --detections-dir
--seed Random seed for Optuna's TPE sampler (reproducible sampled trials). None
--output, -o Path to save best parameters as JSON. None