Skip to content

Generate

Use generate to precompute detections and embeddings that can be reused by later eval, tune, or research runs.

Examples

Example

Experiment-driven cache generation:

boxmot generate --experiment mot17-ablation-yolox-lmbn

Direct-source cache generation:

boxmot generate \
  --source path/to/dataset \
  --detector yolov8n \
  --reid osnet_x0_25_msmt17

from boxmot import BoxMOT

experiment_cache = BoxMOT().generate(experiment="mot17-ablation-yolox-lmbn")
print(experiment_cache.cache_dir)

direct_cache = BoxMOT(
    detector="yolov8n",
    reid="osnet_x0_25_msmt17",
).generate(source="path/to/dataset")
print(direct_cache.timings["frames"])

Why generate first

Cache generation removes repeated detector and ReID work from later benchmark runs. That makes evaluation and tuning faster and more reproducible.

What gets written

generate writes cached detector outputs and ReID embeddings below <project>/dets_n_embs/<dataset>/<split>/. Detection producers and ReID model/runtime identities add further subdirectories so compatible later runs can reuse the artifacts without mixing incompatible caches. The run --name is not part of this cache root.

When to use it

  • before repeated eval runs on the same experiment
  • before tune, which evaluates many tracker parameter sets
  • before research, which may evaluate many candidate code variants

Public detections

Select a public-detection experiment instead of a model-backed experiment:

boxmot generate --experiment mot17-ablation-frcnn-lmbn

This resolves and downloads the public artifact declared in boxmot/configs/artifacts, then generates ReID embeddings for it. Later eval and tune runs with the same experiment and runtime overrides reuse the cache.

MOT17 has source-specific FRCNN, SDP, and DPM experiment IDs. The compatibility option --detection-source accepts only public or private; use an experiment ID to identify the exact public producer.

See Experiment Workflows for cache reuse, MMOT experiment IDs, and replay image-loading behavior.

CLI Arguments

boxmot generate

Generate detections and embeddings

Usage:

boxmot generate [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
--source text direct dataset root to generate dets/embs for without an experiment config 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
--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
--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
--help boolean Show this message and exit. False