Tune

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

Examples

Example

CLIPython

boxmot tune --experiment mot17-ablation-yolox-lmbn --tracker ocsort --n-trials 10

from boxmot import BoxMOT

boxmot = BoxMOT(detector="yolov8n", reid="lmbn_n_duke", tracker="ocsort")
tuned = boxmot.tune(experiment="mot17-ablation-yolox-lmbn", n_trials=10)
print(tuned)
print(tuned.best_yaml)

How it works

Runtime defaults and search metadata come from the same boxmot/configs/trackers/<tracker>.yaml. Runtime construction extracts each parameter's default, while the tuner reads its search policy and combines it with any selected runtime overrides to form the baseline.

Public detections

Select a public-detection experiment to tune against public MOTChallenge detections:

boxmot tune --experiment mot17-ablation-frcnn-lmbn --tracker ocsort --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 --experiment mot17-ablation-yolox-lmbn --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 --experiment mot17-ablation-yolox-lmbn --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 --experiment mot17-ablation-yolox-lmbn --tracker sfsort --tracker-backend cpp --n-trials 10

Native tuning uses the same tracker YAML search space 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 --experiment mot17-ablation-yolox-lmbn --tracker bytetrack --objectives HOTA

Multi-objective tuning:

boxmot tune --experiment mot17-ablation-yolox-lmbn --tracker bytetrack \
  --objectives HOTA IDF1 IDSW_rate \
  --maximize HOTA IDF1 \
  --minimize IDSW_rate

from boxmot import BoxMOT

boxmot = BoxMOT(detector="yolov8n", reid="lmbn_n_duke", tracker="bytetrack")
tuned = boxmot.tune(
    experiment="mot17-ablation-yolox-lmbn",
    split="ablation",
    n_trials=10,
    maximize=("HOTA",),
    minimize=("IDSW_rate",),
)
print(tuned)
print(tuned.best_config)

Outputs

Tuning writes trial artifacts and a fully resolved scalar best.yaml tracker config that can be reused by create_tracker.

CLI Arguments

boxmot tune

Tune models via evolutionary algorithms

Usage:

boxmot tune [OPTIONS]

Options:

Name	Type	Description	Default
--experiment	text	experiment id or YAML file, e.g. mot17-ablation-yolox-lmbn or boxmot/configs/experiments/mot17/ablation-yolox-lmbn.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, occluboost, 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 range (1 and above)	frame-rate override: saved track video FPS or evaluation target FPS	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 range (1 and above)	Maximum CPU worker budget for image decoding and cached tracking	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	one of: strongsort, ocsort, bytetrack, sfsort, botsort, deepocsort, hybridsort, boosttrack, occluboost, sam2mot	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	()
--search-alg	choice (optuna | hyperopt | random)	search algorithm backend for hyperparameter optimization; optuna (default) uses TPE with conditional search spaces, hyperopt uses Tree-structured Parzen Estimators via HyperOpt, random uses uniform random sampling	optuna
--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