Skip to content

Generate

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

Examples

Example

Benchmark-driven cache generation:

boxmot generate --benchmark mot17 --split ablation

Direct-source cache generation:

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

from boxmot import Boxmot

benchmark_cache = Boxmot().generate(benchmark="mot17", split="ablation")
print(benchmark_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 under the configured project/name directory so later runs can reuse them.

When to use it

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

Public detections

Use --detection-source to cache public MOTChallenge detections instead of running a detector:

boxmot generate --benchmark mot17 --split ablation --detection-source frcnn

This downloads the public detection files from the benchmark config and generates ReID embeddings for them. Later eval and tune runs with the same --detection-source reuse this cache.

Available sources for MOT17: frcnn, sdp, dpm, or public (uses the default defined in the benchmark YAML).

See Benchmark Workflows for cache reuse, MMOT benchmark ids, and replay image-loading behavior.

CLI Arguments

boxmot generate

Generate detections and embeddings

Usage:

boxmot generate [OPTIONS]

Options:

Name Type Description Default
--benchmark text benchmark config name or YAML file, e.g. mot17 or boxmot/configs/datasets/mot17.yaml None
--source text direct dataset root to generate dets/embs for without a benchmark 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 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
--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