Tune
tune optimizes tracker parameters on a selected dataset. For image trackers,
it prepares or reuses a canonical perception build once, optionally calibrates
the Kalman filter, and replays that same immutable build in every trial.
Prepare Ray tuning dependencies with boxmot install --extra evolve; see
Install dependencies.
Ray workers use the local installation and dataset/model paths. Running with
uv run --no-sync keeps the existing environment without uploading the project
directory to Ray.
boxmot tune \
--dataset mot17 \
--split ablation \
--detector yolox-x-mot17 \
--reid lmbn-n-duke \
--tracker botsort \
--device mps \
--fps 2 \
--calibrate-kf \
--n-trials 200
This command prepares 2 FPS data, calibrates the KF from cached detections and
ground truth, then runs 200 tracker trials with the KF settings fixed. Omit
--calibrate-kf to keep default or loaded KF settings without fitting them.
The dataset and component selectors resolve a matching authored experiment.
You can select it directly with --experiment mot17/ablation-yolox-lmbn.yaml
in place of --dataset, --detector, and --reid. Missing or ambiguous
catalog matches produce an error; use --experiment to select the intended
configuration. See experiment workflows.
Tracker search profiles use association lists to declare which metrics each
parameter applies to. With centroid association, centroid_max_distance
is searched over [0.005, 0.1] of the frame diagonal; other metrics keep this
setting fixed. Centroid uses this radius as its sole geometric cutoff, so
the overlap matching thresholds are excluded from search and ignored by centroid
association. Use --asso-func centroid to fix the metric while tuning its
radius and other tracker settings. See association settings.
An explicit asso_func in --tracker-config also fixes the metric unless
--asso-func overrides it. Other searchable preset values remain starting values.
Conditional parameters are sampled only in their active branch. Optuna uses
Ray Tune's define-by-run interface;
HyperOpt and random search use branch-specific choice dictionaries. For example,
motion_fusion_lambda is suggested only when motion_fusion is blend.
Other modes can still record its fixed runtime default in results.csv and
trial configs. A recorded value alone does not mean the optimizer sampled it;
the analysis excludes these inactive defaults using the recorded search schema.
Inspect image-tracker tuning results
Each image-tracker run saves results.csv, best.yaml, and summary.md under
its reported run directory. The analysis uses that run's search-space.json
and trial JSON metadata to explain which parameters were actually searched:
| Output | What to inspect |
|---|---|
analysis.png |
Scores in completion order, best-so-far progress, score distribution, and detection/association and identity tradeoffs. |
analysis_scatter.png |
Numeric search dimensions, active sample counts, and Spearman correlations with HOTA. |
analysis_categories.png |
Categorical and Boolean choices, their sample counts, and association-function × motion-fusion comparisons. |
analysis_candidates.png |
Top-ten trial metrics and per-sequence HOTA changes against the reference. |
When a sequence CMC policy overrides the base tracker settings, best.yaml
and each trial YAML start with the effective policy and the evaluated sequences
where compensation was enabled or disabled. The use_cmc line is labeled as
an overridden base value. summary.md includes the same effective CMC setup;
cmc-policy.yaml records the decisions as machine-readable data.
Near-best means within 0.2 absolute HOTA points of the winner. The summary compares top-ten and near-best parameter ranges, active counts, and proximity to the recorded search bounds. Inactive conditional defaults are excluded; conditional ranges are shown separately. Numeric correlations are calculated within each active branch, and conditional categorical choices get separate panels with that branch's options and sample counts. An active sample is kept even when its value equals an inactive branch's default. Parameters that stayed constant are omitted from the scatter plots. A default baseline is identified by matching recorded defaults; otherwise the reference is labeled as the first completed trial. Missing metadata is reported, and diagnostics that require it are omitted.
To regenerate the figures, parameter diagnostics, and saved CMC annotations, run this from the repository root, replacing the directory with your run:
uv run --no-sync python -m boxmot.engine.tuning.analysis \
runs/ray/mot17-ablation-yolox-lmbn/bytetrack_3
The summary's run provenance and other sections are preserved. Correlations, category comparisons, and concentrated ranges describe the sampled trials; unequal sampling and simultaneous parameter changes prevent causal conclusions. They guide the next experiment, but do not establish repeatability or statistically demonstrated superiority. Check sequence regressions and evaluate selected profiles on held-out data before drawing broader conclusions.
Tune mask guidance
The nine Python box trackers can search EdgeTAM guidance settings together with
their ordinary tracker parameters when --edgetam is enabled. Guidance is off
by default. Install the optional package and tuning dependencies from a source
checkout:
Use --extra cu130 instead of --extra cpu on CUDA. The CPU PyTorch profile
also supports MPS on macOS. Enable guidance when starting the search:
boxmot tune --experiment mot17/ablation-yolox-lmbn.yaml \
--tracker occluboost --tracker-backend python --asso-func iou \
--edgetam --mask-guidance-weights models/edgetam.pt --device mps \
--n-trials 20 --max-concurrent-trials 1 --sequence-workers 1
The example selects an existing checkpoint at models/edgetam.pt. With just
--edgetam, the default edgetam.pt resolver downloads or reuses the official
checkpoint in ./models. Weights alone do not enable guidance;
--no-edgetam disables it even with --mask-guidance-weights. To reuse a
specific cached build, add --build BUILD_ID and select the experiment that
created it. An existing mot17/ablation-yolox-edgetam-lmbn.yaml build can supply
its detections and embeddings; new builds for guided tuning do not need a
standalone segmentor or published masks. Source image pixels must remain
available: each trial propagates masks while replaying cached detections.
--device selects the propagation device even when --build is supplied.
The built-in tracker YAMLs group defaults and search metadata under edgetam,
with resolved option paths
edgetam.min_coverage (0.90, uniform [0.50, 1.0]),
edgetam.min_fill (0.05, uniform [0.01, 0.25]),
edgetam.prompt_overlap (0.10, uniform [0.01, 0.50]), and
edgetam.max_objects (96, choices [8, 16, 24, 32, 64, 96]). See
guidance settings for their meanings
and a scalar runtime profile. --tracker-config overrides the starting values;
searchable parameters can still change in later trials. An explicit
--mask-guidance-max-objects N instead holds the cap fixed for every trial.
OccluBoost uses a wider min_fill search range of [0.01, 0.30] and
max_objects choices of [32, 64, 96, 128], with the same runtime defaults.
Guidance requires AABB, IoU, and per_class: false; guided tuning fixes
asso_func to iou instead of searching other association functions. Without
--edgetam, all four mask parameters are excluded from search.
Use --max-concurrent-trials 1 --sequence-workers 1 to limit model and temporal
state duplication on an edge device. Each concurrent trial or sequence worker
owns its own model and propagation state.
Published detection masks do not replace temporal EdgeTAM inference. Each
guided trial recomputes masks from its own track history. With --edgetam,
box trackers skip published masks when loading replay inputs; --cache-inputs
reuses images, detections, and embeddings but does not cache temporal masks.
Start with one sequence worker on MPS: additional workers share the same GPU and duplicate
model state, so more workers do not guarantee higher throughput.
For CUDA tuning, Ray assigns a GPU to each trial. Select --device cuda or
--device cuda:0, the trial's logical GPU; use CUDA_VISIBLE_DEVICES to select
physical GPUs. Nonzero CUDA device indices are rejected for guided tuning.
The resulting best.yaml saves the chosen mask settings under edgetam with
the other tracker parameters. Enable guidance again when evaluating that
profile, using the same checkpoint:
boxmot eval --experiment mot17/ablation-yolox-lmbn.yaml --build BUILD_ID \
--tracker occluboost --tracker-backend python --asso-func iou \
--tracker-config path/to/best.yaml \
--edgetam --mask-guidance-weights models/edgetam.pt --device mps --sequence-workers 1
Use the actual build and profile paths reported by tuning. The saved edgetam
group has no enabled field: enablement, checkpoint, and device are workflow
inputs, separate from the saved algorithm parameters. This command replays the
fitting split for inspection; evaluate the profile on
separate held-out sequences before claiming a tracking improvement. Keep the
same guidance checkpoint when comparing settings.
Each guided trial reruns EdgeTAM image encoding and temporal propagation from the source frames. Propagated guidance masks are not currently materialized or reused between trials; standalone detection-aligned masks remain a separate materialization output.
On MPS, temporal guidance automatically loads FP16 weights, uses FP16 autocast, and stores mask-memory features in FP16. CPU uses FP32; CUDA uses BF16 autocast on supported devices and FP32 otherwise. Propagation batches up to four objects with compatible histories per inference call; this is separate from the default 96-identity capacity and does not add a tuning parameter. Initial prompts remain individual. Each sequence worker owns its model and temporal state, so additional workers increase memory use. Masks stay on the inference device for propagation and reseeding; matching transfers only small integer overlap counts to the CPU. Full CPU masks are created lazily for rendering, so tuning without rendering avoids those transfers.
KITTI with image trackers
The kitti-mots/2d and kitti-mots/2d-lmbn-n-duke presets support saved-box
eval only. For image-tracker tuning, author a detector-based experiment that
selects images and box annotations, defines a detector and class mapping, and
optionally selects ReID. See experiment configuration.
EagerMOT with saved sensor inputs
Pass a multimodal sequence dataset to
--dataset with --tracker eagermot:
The folder's dataset.yaml defines classes, splits, and modalities with
encodings and paths for images, ground truth, calibration, ego poses, and
saved 2D/3D detections. Split overrides can select different prediction sets.
You can also pass dataset.yaml itself; an absolute
--dataset path works from any working directory. Keep the ./ prefix when
selecting the local folder by name; bare kitti-mots selects the built-in
image dataset profile.
For your own synchronized camera and 3D observations, start from the sensor dataset template. It supports custom split, partition, and sequence names with the documented calibration, pose, image, and prediction formats. Supply car/pedestrian ground-truth masks and image prediction masks for the tuning objective:
boxmot tune --dataset ./my-sensor-dataset --tracker eagermot \
--split train --n-trials 50 --seed 0
boxmot eval --dataset ./my-sensor-dataset --tracker eagermot \
--split val --class-config runs/eagermot-tune/train/best.yaml
Use the actual best.yaml path printed by tuning. The template keeps fitting
and validation sequences separate; record each detector's model, checkpoint,
and training data in your dataset README or YAML comments.
With the mots and evolve extras installed, this runs serial Optuna trials
on CPU, replaying independent sequences in parallel within each trial, and
maximizes class-average mask HOTA across car and pedestrian profiles.
The automatic worker count uses the selected
sequences and logical CPU count; --sequence-workers 4 caps it at four workers
per trial. The first trial uses the starting class profiles, including any
loaded or calibrated settings. Add
--sequence 0002 to select one validation sequence, repeat --sequence for
several, or use --split train or --split fulltrain to select another
dataset split. --project defaults to runs/eagermot-tune; each run saves
best.yaml for boxmot eval --tracker eagermot --class-config.
The shared Rich tuning panel shows trial and sequence progress, the first,
best, and last results with baseline comparisons, and the saved profile paths.
Add --verbose to display tracker and Optuna logs.
This sensor workflow reads the dataset and selected predictions directly.
It supports --search-alg optuna; an explicit device must be cpu.
--max-concurrent-trials accepts 0 (default) or 1, keeping trials serial.
Objective selectors must use HOTA. Perception and build options and
--resume-tune are unavailable for fusion datasets.
Supply 3D annotations
and add --calibrate-kf to fit the 3D Kalman noise once before Optuna starts:
boxmot tune --dataset ./my-sensor-dataset --tracker eagermot \
--split train --calibrate-kf --n-trials 50 --seed 0
The five covariance scales and kalman.is_angular stay fixed for each class by
default. Add --tune-kf to refine selected scales around each class's fitted
values. Reuse calibration without fitting again with
--class-config path/to/kf-tuning/calibrated.yaml. Both that starting profile
and the final best.yaml contain separate car and pedestrian settings.
--class-config also holds the loaded kalman.is_angular choices fixed; tuning
without either flag can search those choices.
Ego poses remain fixed; EagerMOT advances one frame per image. See
3D Kalman calibration.
An incompatible selection reports a short reason and next step. The check uses
the selected split and registered tracker inputs:
declared tracking inputs marked Unused cause rejection. Ground truth is used
separately for the tuning objective.
Direct saved-sensor tuning currently requires
--tracker eagermot --tracker-backend python. To intentionally tune an image-only
experiment, select only images and ground_truth in a separate dataset config
or explicit split override, plus a perception build or detector. Split modality
overrides set to null remove those inputs from the experiment.
See the EagerMOT tuning example for inputs and outputs.
Python callers use boxmot.engine.tuning.tuner.run_tune(args) for both image
builds and sensor datasets. It returns a TuneResult with the completed trials,
best metrics, and best_yaml path. For EagerMOT, best_config contains separate
car and pedestrian profiles. Runtime dictionaries use dotted noise keys;
the exported YAML nests them under kalman.noise.
Build preparation and reuse
For image trackers, when --build is omitted, tuning resolves the canonical
build from the selected experiment, source data, perception settings, and
requested frame rate. A matching complete build is validated and reused;
otherwise, materialization runs once before calibration and Ray start. Reuse requires
matching source and semantic component fingerprints, geometry, class taxonomy,
and the payloads needed by the tracker. It never selects a latest build.
--device controls perception during automatic preparation, for example
mps, cuda:0, or cpu. With an explicit --build, --device is accepted
when temporal EdgeTAM guidance needs it for propagation; otherwise it is rejected because
no perception models run. Use either an experiment or a dataset to replay a
specific build:
boxmot tune \
--dataset mot17 \
--split ablation \
--build BUILD_ID \
--tracker botsort \
--n-trials 200
A build ID resolves below --build-root; an existing build path is used
directly. An explicitly selected build must already exist and be compatible.
Dataset-only selection requires --build; automatic preparation needs an
experiment or --dataset plus --detector and optional --reid.
With automatic preparation, --fps 2 selects a 2 FPS build. A compatible
full-rate cache can supply the selected detections and embeddings without
rerunning perception. With an explicit --build, omitting --fps uses its
recorded rate, and an explicit rate must match it. Replayed images,
detections, and ground truth share the selected frames and contiguous frame
numbers, while capture timestamps retain their original elapsed time. See
dataset FPS.
Tuning validates the build and the tracker's requirements before optimization. Trials run no detector, segmentor, or encoder and cannot select or create another build. Optional temporal mask guidance runs during replay using source images and the selected checkpoint. Worker count and retry policy are execution settings, not semantic fingerprints.
Automatic preparation caches embeddings when the baseline uses them or the
search can enable use_embeddings. A runtime --tracker-config sets the
baseline; searchable parameters can still change in trials. To omit embeddings
throughout tuning, both the baseline and search must keep appearance disabled.
Appearance-enabled trials require cached embeddings rather than live ReID inference.
Each trial uses the automatic sequence worker count
unless temporal EdgeTAM guidance selects one worker by default or --sequence-workers
supplies a positive integer cap. For example,
--sequence-workers 4 allows up to four sequence worker processes per trial,
bounded by the number of selected sequences. Use --max-concurrent-trials to
limit how many image-tracker trials run at once; sequence workers are allocated
separately to each trial.
Each spawned sequence worker limits BLAS, OpenMP, PyTorch, and OpenCV compute
pools to one thread. This overrides inherited thread counts such as Ray's
OMP_NUM_THREADS allocation, so sequence parallelism does not multiply the
native thread count. The limits persist across trials in reused workers and
apply when new workers start.
For limited RAM, use --max-concurrent-trials 1 --sequence-workers 1 together
to run one trial and one sequence at a time. --n-trials controls the total
number of trials, not how many run concurrently.
Each reusable image tuning actor and each sensor study keeps its sequence-worker pool across trials. Every trial still creates fresh trackers, pipelines, frame cursors, and output files. Worker pools are closed when tuning ends; failed worker operations discard the pool before reuse. This applies to image search backends and the sensor Optuna workflow without an additional flag.
Pool workers also monitor their owning process and exit if it dies, including when Ray terminates a trial for running out of memory. When BoxMOT starts Ray, it enables process-group cleanup by default on POSIX systems so actor descendants are terminated together. Existing Ray runtimes and explicit Ray cleanup settings remain caller-owned. Ray's memory threshold is unchanged.
Add --cache-inputs to also reuse mapped inputs on disk across tuning sessions
and evaluation commands:
boxmot tune \
--dataset mot17 \
--split ablation \
--build BUILD_ID \
--tracker botsort \
--n-trials 200 \
--cache-inputs
The same flag works with multimodal datasets and per-class KF calibration:
boxmot tune --dataset ./kitti-mots --tracker eagermot \
--split train --calibrate-kf --cache-inputs --n-trials 50
This requires the 3D ground-truth declaration
used by calibration. Omit --calibrate-kf when tuning without 3D annotations.
Sensor caches reuse parsed 2D/3D detections, packed masks, calibration, ego poses,
and ground truth. Image builds cache requested detections, embeddings, masks,
and image pixels. Filtering remains inside each trial, so differing detection
thresholds and association settings reuse the same unfiltered input cache.
See replay input caching for
storage, preparation, and cleanup details.
The progress panel keeps three rows visible: First, Best, and Last. The baseline is the first scheduled trial, even if another trial finishes sooner. Best updates when the configured objective improves; Last updates after each successful trial. Each row shows HOTA, MOTA, IDF1, and any additional objective metrics.
Best and Last include signed differences from the baseline in metric units
(percentage points for percentage metrics). Improvements are green and
regressions red, respecting --minimize metrics; unavailable baseline metrics
show --. The same comparison appears during saved-sensor tuning.
Each running image-tracker trial also lists its sequences with frame counts, progress bars, and pending, running, done, or failed status. Sequence progress resets for each trial, including when Ray reuses a worker.
An evaluation exception marks that trial as failed, retains its traceback in the Ray trial directory, and lets the remaining trials continue. Failed trials are excluded from best-result selection and are not retried automatically. A completed evaluation with no predicted tracks remains a valid zero-score result; it is distinct from a tracker or input-loading error.
Use a native tracker with --tracker-backend cpp when that geometry and feature
combination is supported. Unsupported masks, per-class mode, or geometry are
rejected before a native trial starts.
Calibrate the KF before tracker tuning
For saved sensor datasets, use the EagerMOT workflow above. The build preparation and resume behavior below apply to image trackers.
Add --calibrate-kf, as in the first example, to estimate Kalman noise once
from the prepared build's cached detections and ground truth, then tune the
remaining tracker parameters. The flag works with automatic preparation or
an explicitly selected build.
Calibration runs after build validation and before Ray and the search start.
The fitted covariance vectors, global scales, timing settings, and the filter's
reference process-noise priors stay fixed throughout all 200 tracker trials.
kalman.adaptive_kf also stays fixed for trackers that support it. No search-schema
edits are needed.
Add --variable-dt to calibrate and predict using capture timestamps in
seconds. Fixed-step mode remains the default; --fps does not change the
Kalman timing mode.
The tuning directory contains kf-tuning/calibrated.yaml and
kf-tuning/calibration.json. The first is the calibrated starting tracker
configuration; the second records the data and estimates used for calibration.
The tuning result's best.yaml contains the selected tracker parameters with
the fixed KF settings included. Evaluate that result on held-out sequences.
Resume with --resume-tune <tuning-directory>, using the same experiment or
dataset selection and build. The saved calibration is restored automatically.
Combining --calibrate-kf with --resume-tune is rejected
because a fresh calibration would change the existing search.
Resuming retains the original search space; start a new run to use updated
search definitions, including a different selection of KF search dimensions.
Image tuning records the effective schema and fixed values in
search-space.json. Resume requires a matching profile; runs created before
this metadata was recorded need a new search. A running process keeps the
search space it started with.
eval --calibrate-kf instead calibrates and evaluates the tracker once. See
Kalman calibration for the estimator, supported
trackers, and limitations.
Select the KF before tracker tuning
Use --select-kf to compare compatible filter types with original, partially
calibrated, and fully calibrated noise on held-out trajectories:
boxmot tune --experiment mot17/ablation-yolox-lmbn.yaml \
--tracker botsort --select-kf --n-trials 200
Selection fits its own training folds, so --calibrate-kf is unnecessary.
The winning filter and noise stay fixed during the tracker search, and CMC
stays off. Defaults can win. Explicit --tune-kf options refine only the
requested scales after selection. Native trackers, EagerMOT, and trackers
without Kalman filters do not support this workflow.
Joint CMC and KF selection
Add --select-cmc to compare CMC off and automatic SOF alongside filter types
and noise profiles:
boxmot tune --experiment mot17/ablation-yolox-lmbn.yaml \
--tracker botsort --select-kf --select-cmc --n-trials 200
Source images are required for camera analysis. Each candidate is calibrated
under its camera behavior before held-out scoring. The winning strategy is
saved in best.yaml; evaluation analyzes its own sequences when automatic
CMC was selected. --select-cmc requires --select-kf.
For example, use_cmc: false with calibration.cmc_policy: auto is a base
setting overridden by automatic decisions for each sequence. The export's
annotations show the tuning run's decisions; they do not freeze those sequence
IDs into the policy for new evaluation data.
Resume either selection workflow with --resume-tune TUNING_DIRECTORY and
omit both selection flags. See Kalman calibration
for scoring, noise recipes, output artifacts, and held-out evaluation.
Kalman noise and timing
Tracker tuning holds covariance scales fixed unless you select them with --tune-kf. The five covariance
multipliers retain their runtime defaults of 1.0 in the tracker YAML;
kalman.adaptive_kf and timing settings also retain their YAML runtime defaults where
supported. OC-SORT's base process-noise priors are fixed inside the filter.
These covariance and timing settings have no default search ranges.
OccluBoost's kalman.ams settings retain their conditional search ranges.
EagerMOT's kalman.is_angular remains searchable when no calibration or class
profile fixes its state model.
Use Kalman calibration to estimate coordinate-wise
covariance multipliers from detections and ground truth. The fitted vectors
stay fixed; scale refinement changes each selected group as a whole.
For image trackers, reuse an existing calibration by starting a new tuning run
with --tracker-config path/to/kf-tuning/calibrated.yaml and omit
--calibrate-kf. The loaded KF values stay fixed while the other tracker
parameters are optimized. Without a filter constraint, the eight Python 2D
Kalman trackers search kalman.type over xyah, xywh, xysr, xyhr, and
xyscr, starting from the named default in each tracker YAML.
These YAML defaults apply to both AABB and OBB. Covariance and
timing defaults stay fixed. An explicit runtime kalman.type (including
null), covariance vectors, or adaptive KF policy fixes the filter, as do
--calibrate-kf and --select-kf. C++ tuning keeps its native filter fixed.
The selector also accepts partial runtime YAMLs and built-in presets.
EagerMOT uses --class-config for its separate car and pedestrian profiles.
Its 3D filter supports covariance calibration in fixed-step mode only.
kalman.variable_dt, kalman.noise.time_unit, and kalman.noise.reference_dt_s are fixed runtime
settings. They are not tuning parameters, and elapsed dt is never sampled.
Use --variable-dt to select elapsed-seconds prediction explicitly, or keep
the default fixed-step mode. The reference interval defaults to 1/30 second
and describes the original noise priors, not the source timestamps.
Saved configurations record the timing mode, explicit units, and reference
interval. Reuse them with --tracker-config in track, eval, or another
tune run in the same mode. A conflicting time-unit override is rejected. Tune results
measure the fitting split; evaluate on separate held-out sequences before
judging whether the selected settings improve deployment accuracy.
Refine selected calibrated scales
Repeat --tune-kf to select process_position_scale, process_velocity_scale,
measurement_noise_scale, initial_position_scale, or initial_velocity_scale.
Each selected multiplier is searched on a logarithmic scale from 0.25× to 4×
its starting value. Unselected scales, timing units, and the reference interval
stay fixed. Starting values come from selection, calibration, a loaded
--tracker-config, or tracker defaults, according to the requested workflow.
boxmot tune --experiment mot17/ablation-yolox-lmbn.yaml --build <build> \
--tracker botsort --calibrate-kf --per-class \
--tune-kf process_velocity_scale --tune-kf measurement_noise_scale
When calibration or a saved profile supplies kalman.noise.by_class, tuning
refines each class's selected scales around its own prior. It searches the
global prior only when it can be used as a fallback for the selected classes.
Saved YAML groups filter settings under kalman, with covariance settings
under noise and OccluBoost's smoothing controls under ams. For example:
per_class: true
kalman:
variable_dt: false
adaptive_kf: false
noise:
process_velocity_scale: 2.0
by_class:
"1":
process_velocity_scale: 3.0
ams:
enabled: true
alpha0: 0.75
This partial OccluBoost configuration inherits unspecified tracker defaults. Other trackers expose only the Kalman controls they support.
For EagerMOT, the same flags refine each car/pedestrian 3D filter independently:
boxmot tune --dataset ./kitti-mots --tracker eagermot --split train \
--calibrate-kf --tune-kf process_velocity_scale --tune-kf measurement_noise_scale
The first trial evaluates the starting profiles. Image tuning records its
selection and baseline priors in kf-refinement.json. When using
--resume-tune, repeat the same --tune-kf fields and retain the same baseline
configuration; omit --calibrate-kf because the saved calibration is restored.
Changing a scale's starting value, a class prior, or timing requires a new run.
OC-SORT base process noise
OC-SORT and DeepOCSORT use fixed reference process covariances of 0.01 for
centre velocity and 0.0001 for bounding-box area velocity. OBB angular
velocity also uses 0.0001. Python Kalman calibration scales these priors
with the shared velocity multiplier:
centre-velocity noise = 0.01 × kalman.noise.process_velocity_scale
area-velocity noise = 0.0001 × kalman.noise.process_velocity_scale
angular-velocity noise = 0.0001 × kalman.noise.process_velocity_scale (OBB)
These products describe reference noise before time-unit conversion and
integration into Q(dt). The relative balance between centre, area, and
angular velocity noise is fixed by the filter; calibration scales them
together. The five shared kalman.noise.*_scale settings are the noise-calibration
interface.
Arguments
boxmot tune
Tune tracker parameters from a perception build or a saved-sensor dataset. EagerMOT jointly tunes car and pedestrian profiles for class-average KITTI mask HOTA.
Usage:
Options:
--experiment TEXT experiment YAML filename or path, e.g.
mot17/ablation-yolox-lmbn.yaml or
boxmot/configs/experiments/mot17/ablation-
yolox-lmbn.yaml
--dataset TEXT Dataset id, YAML file, or sensor dataset
folder containing dataset.yaml (eval and
tune).
--detector TEXT Detector profile ID or YAML config used to
resolve an authored experiment with
--dataset; append /CHECKPOINT to
disambiguate.
--reid TEXT ReID profile for an authored experiment or
for encoding saved 2D detections during
eval. Omit when appearance is disabled.
--build TEXT Materialized build ID or explicit build
directory. Omit with --experiment, or with
--dataset and --detector, to materialize and
reuse a compatible canonical build
automatically.
--build-root PATH Root for build IDs, automatic
materialization, and shared detector cache;
overrides BOXMOT_BUILDS_DIR and defaults to
./runs/materializations.
--device TEXT One device for uncached perception and
EdgeTAM mask guidance: cpu, mps, cuda:N, or
N (e.g. 0).
--data-root PATH Base folder for dataset storage.root;
defaults to ./datasets/mot for built-in
datasets or the local YAML folder.
--split TEXT Dataset split to use (e.g. train, val, test,
ablation). Overrides auto-detection from
source path.
--sequence NAME Limit the selected split to one sequence.
Repeat to select multiple sequences.
--fps FLOAT Target dataset FPS: sample frames before
perception and align ground truth. Default:
original frames, or the selected build's FPS
when replaying.
--eval-masks Evaluate KITTI-MOTS with mask IoU. Image
workflows default to boxes; sensor workflows
default to masks.
--mask-guidance-weights PATH Checkpoint or exported TFLite bundle
directory used with --edgetam. Selecting
weights alone does not enable guidance;
edgetam.pt downloads into ./models. TFLite
guidance runs on CPU. Python AABB box
trackers with IoU only.
--edgetam / --no-edgetam Enable EdgeTAM mask guidance with tracker
YAML settings; uses edgetam.pt unless
weights are supplied. [default: no-edgetam]
--mask-guidance-max-objects INTEGER RANGE
Override the tracker config's
edgetam.max_objects (default 96) when
--edgetam is enabled. Maximum identities
with temporal mask memory; fixed when
tuning. [x>=1]
--tracker-backend [python|cpp] Tracker implementation backend. Native 'cpp'
is available for botsort, bytetrack,
occluboost, ocsort, and sfsort. [default:
python]
--tracker-config TEXT Tracker runtime YAML path or built-in
preset; overrides must preserve calibrated
time units.
--asso-func [iou|giou|diou|ciou|hmiou|centroid]
Association geometry override for AABB and
OBB tracking. OBB ciou is a custom
experimental adaptation; OBB hmiou is an
experimental global-y height cue for scenes
where image vertical is meaningful.
--class-config FILE EagerMOT: baseline car/pedestrian profiles;
--tune-kf selects noise scales to refine.
The yaw model stays fixed.
--sequence-workers INTEGER RANGE
Maximum sequence worker processes. Default:
1 for EdgeTAM evaluation/tuning; otherwise
min(sequences, CPU cores - 2), at least 1.
During tuning, this limit applies per trial.
[x>=1]
--cache-inputs / --no-cache-inputs
Build and reuse mapped inputs for repeated
eval/tune runs, including images,
detections, embeddings, masks, sensors, and
annotations. Uses extra disk space.
[default: no-cache-inputs]
--project PATH save results to project/name
--name TEXT save results to project/name
--exist-ok existing project/name ok, do not increment
--ci reuse existing runs in CI (no UI)
--tracker [boosttrack|botsort|bytetrack|deepocsort|eagermot|hybridsort|maf_hda|occluboost|ocsort|sfsort|strongsort]
one of: boosttrack, botsort, bytetrack,
deepocsort, eagermot, hybridsort, maf_hda,
occluboost, ocsort, sfsort, strongsort
[default: bytetrack]
--variable-dt / --fixed-dt Use capture timestamps for Kalman
prediction; otherwise keep the tracker YAML
setting (default: fixed dt).
--verbose print detailed logs
--show-timing / --hide-timing print runtime timing summary after
evaluation [default: hide-timing]
--per-class track each class separately
--calibrate-kf Calibrate Kalman noise from detections and
ground truth, then tune tracker parameters
with calibrated KF settings fixed; Python
Kalman trackers only. EagerMOT requires
ground_truth_3d with track IDs.
--select-cmc Jointly select CMC off/automatic SOF, KF
type and noise profile with --select-kf.
Fits each candidate under its camera
behavior; Python 2D Kalman trackers only.
--select-kf Compare default, partial and full KF
calibration across compatible filter types
on held-out detection/GT predictions, then
tune with the winning type and noise fixed.
CMC stays off unless --select-cmc is used.
Requires a Python 2D Kalman tracker.
--tune-kf [process_position_scale|process_velocity_scale|measurement_noise_scale|initial_position_scale|initial_velocity_scale]
Refine a KF scale from 0.25x to 4x its
baseline; repeat to select more scales.
Other priors stay fixed.
--n-trials INTEGER RANGE number of hyperparameter optimization trials
[x>=1]
--seed INTEGER RANGE Random seed for parameter sampling. Sensor
datasets default to 0. [0<=x<=4294967295]
--max-concurrent-trials INTEGER
max concurrent trials (0 = auto: 1 with
temporal EdgeTAM, otherwise min(4,
cpu_count)); controls parallelism and
improves Bayesian search effectiveness
--time-budget-s FLOAT optional time budget in seconds for the
entire tuning run; Tune stops launching new
trials after this time
--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.
--objectives TEXT metrics to track and return from each trial;
accepts repeated, comma-separated, or space-
separated values
--maximize TEXT metrics to maximize; accepts repeated,
comma-separated, or space-separated values;
defaults to first --objectives value (e.g.
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 [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
--help Show this message and exit.