Tune

Use tune to search tracker hyperparameters against one or more objective metrics.

Examples

Example

CLIPython

boxmot tune --benchmark mot17 --split ablation --tracker ocsort --n-trials 10

from boxmot import Boxmot

boxmot = Boxmot(detector="yolov8n", reid="lmbn_n_duke", tracker="ocsort")
tuned = boxmot.tune(benchmark="mot17", split="ablation", n_trials=10)
print(tuned)
print(tuned.best_yaml)

How it works

Tracker search spaces come from the selected tracker YAML in boxmot/configs/trackers. Runtime defaults use each parameter's default value, while tuning uses its type, range, and options.

Public detections

Use --detection-source to tune against public MOTChallenge detections instead of the configured detector:

boxmot tune --benchmark mot17 --split ablation --tracker ocsort --detection-source frcnn --n-trials 10

See Evaluate — Public detections for the full list of sources.

Kalman filter noise tuning

Use --tune-kf to estimate Kalman filter noise matrices (Q/R) once before the tuning loop. The estimated noise is then reused for all trials:

boxmot tune --benchmark mot17 --split ablation --tracker botsort --tune-kf --n-trials 20

This is especially useful for KF-based trackers where the default noise parameters may not suit the dataset.

Postprocessing

Use --postprocessing to apply postprocessing after each trial's tracking run before scoring:

boxmot tune --benchmark mot17 --split ablation --tracker ocsort --postprocessing gsi --n-trials 10

See Evaluate — Postprocessing for available steps and chaining behavior.

Native C++ trials

Use --tracker-backend cpp when you want each trial to score the native C++ tracker backend instead of the Python backend:

boxmot tune --benchmark mot17 --split ablation --tracker sfsort --tracker-backend cpp --n-trials 10

Native tuning uses the same search space YAML as the Python tracker and swaps only the tracker implementation used during cached replay. Native replay is currently available for botsort, bytetrack, ocsort, occluboost, and sfsort.

Objective configuration

Example

CLIPython

Single-objective tuning:

boxmot tune --benchmark mot17 --split ablation --tracker bytetrack --objectives HOTA

Multi-objective tuning:

boxmot tune --benchmark mot17 --split ablation --tracker bytetrack \
  --objectives HOTA IDF1_rate \
  --maximize HOTA \
  --minimize IDSW_rate

from boxmot import Boxmot

boxmot = Boxmot(detector="yolov8n", reid="lmbn_n_duke", tracker="bytetrack")
tuned = boxmot.tune(
    benchmark="mot17",
    split="ablation",
    n_trials=10,
    maximize=("HOTA",),
    minimize=("IDSW_rate",),
)
print(tuned)
print(tuned.best_config)

Outputs

Tuning writes trial artifacts and a best.yaml tracker config that can be reused in later runs.

CLI Arguments

boxmot tune

Tune models via evolutionary algorithms

Usage:

boxmot tune [OPTIONS]

Options:

Name	Type	Description	Default
--benchmark	text	benchmark config name or YAML file, e.g. mot17 or boxmot/configs/datasets/mot17.yaml	None
--split	text	Dataset split to use (e.g. train, val, test, ablation). Overrides auto-detection from source path.	None
--detection-source	choice (public | private)	Detection source: "public" reads det/det.txt from sequences, "private" (default) runs the configured detector model.	None
--tracking-backend	choice (process | thread | cpp)	Cached replay executor for eval/tune/research. Use 'cpp' as a compatibility alias for '--tracker-backend cpp'.	process
--tracker-backend	choice (python | cpp)	Tracker implementation backend. Native 'cpp' is available for botsort, bytetrack, ocsort, and sfsort.	python
--imgsz	text	Image size for model input as H,W (e.g. 800,1440) or single int for square. Default: read from the selected detector config, otherwise use detector-specific defaults.	None
--fps	integer	video frame-rate	None
--conf	float	Min confidence threshold. Default: read from the selected detector config, fallback 0.01.	None
--iou	float	IoU threshold for NMS	0.7
--device	text	cuda device(s), e.g. 0 or 0,1,2,3 or cpu	cpu
--batch-size	integer	micro-batch size for batched detection/embedding	16
--auto-batch / --no-auto-batch	boolean	probe GPU memory with a dummy pass to pick a safe batch size	True
--resume / --no-resume	boolean	resume detection/embedding generation from progress checkpoints	True
--n-threads	integer	CPU threads for image decoding; defaults to min(8, cpu_count)	4
--project	Path	save results to project/name	runs
--name	text	save results to project/name	exp
--exist-ok	boolean	existing project/name ok, do not increment	False
--half	boolean	use FP16 half-precision inference	False
--vid-stride	integer	video frame-rate stride	1
--ci	boolean	reuse existing runs in CI (no UI)	False
--tracker	text	deepocsort, botsort, strongsort, ...	bytetrack
--verbose	boolean	print detailed logs	False
--show-timing / --hide-timing	boolean	print runtime timing summary after evaluation	False
--agnostic-nms	boolean	class-agnostic NMS	False
--postprocessing	text	Postprocess tracker output (comma-separated, applied in order): none	gsi
--show	boolean	display tracking in a window	False
--show-labels / --hide-labels	boolean	show or hide detection labels	True
--show-conf / --hide-conf	boolean	show or hide detection confidences	True
--show-trajectories	boolean	overlay past trajectories	False
--show-kf-preds	boolean	show Kalman-filter predictions	False
--save-txt	boolean	save results to a .txt file	False
--save-crop	boolean	save cropped detections	False
--save	boolean	save annotated video	False
--line-width	integer	bounding box line width	None
--per-class	boolean	track each class separately	False
--target-id	integer	ID to highlight in green	None
--masks-dir	text	Override directory for cached segmentation masks (.npz files)	None
--masks-model	choice (maskrcnn)	Mask model to use for generation (stored under cache tree automatically)	None
--n-trials	integer	number of trials for evolutionary tuning	10
--max-concurrent-trials	integer	max concurrent trials (0 = auto, defaults to min(4, cpu_count)); controls parallelism and improves Bayesian search effectiveness	0
--time-budget-s	float	optional time budget in seconds for the entire tuning run; Tune stops launching new trials after this time	None
--resume-tune	text	resume a Ray Tune experiment; pass a folder name (e.g. deepocsort_tune_3) or full path under runs/ray/. Retries errored trials and continues remaining ones.	None
--objectives	text	metrics to track and return from each trial; accepts repeated, comma-separated, or space-separated values	('HOTA',)
--maximize	text	metrics to maximize; accepts repeated, comma-separated, or space-separated values; defaults to first --objectives value (e.g. HOTA)	('HOTA',)
--minimize	text	metrics to minimize for Pareto search; accepts repeated, comma-separated, or space-separated values (e.g. IDSW_rate); triggers multi-objective mode when set	()
--detector	Path	one or more YOLO weights for detection	[PosixPath('/home/runner/work/boxmot/boxmot/models/yolov8n.pt')]
--reid	Path	one or more ReID model weights	[PosixPath('/home/runner/work/boxmot/boxmot/models/osnet_x0_25_msmt17.pt')]
--classes	text	filter by class indices, e.g. 0 or "0,1"	None
--tune-kf / --no-tune-kf	boolean	Run KF noise tuning (Q/R estimation) before tracker hyperparameter tuning. Applied once, then reused for all trials.	False
--help	boolean	Show this message and exit.	False