boxmot

BoxMOT v25.0.0 rebuilds the engine around modular commands, composable tracking pipelines, and resumable perception builds. It also introduces an HTTP tracking service, faster cached evaluation, timestamp-aware tracking, and Kalman calibration. This is a breaking release for Python integrations, dataset caches, and native extensions. These notes cover changes since v23.0.0, the previous published release.

The engine rebuild establishes a new foundation for tracking, evaluation, and tuning:

• Modular CLI: Replaced the monolithic CLI implementation with lazily loaded command modules and shared option groups.
• Composable tracking execution: Separated frame sources, perception and tracking pipelines, execution runners, and output sinks. The runner manages sequence resets, interruption handling, resource cleanup, and timing.
• Typed component interfaces: Introduced Frame, Boxes, OrientedBoxes, MaskBatch, Detections, Tracks, and PipelineResult, alongside immutable component specifications and factories.
• Resumable materialization: Added separate detection, segmentation, embedding, and finalization stages. Stage fingerprints, completed-work tracking, retries, and shared detection caching allow interrupted builds to resume and compatible work to be reused.
• Immutable perception datasets: Replaced positional caches with keyed Parquet builds joined by sample and instance IDs. Changing ReID models can reuse compatible detector results.
• Reworked evaluation and tuning: Both workflows consume materialized builds through the live tracker API. When --build is omitted, they prepare or reuse a compatible build before replay or optimization. Individual tuning trials reuse prepared perception results.
• Clearer package responsibilities: The engine owns command and workflow orchestration; domain packages contain reusable detector, tracker, ReID, training, evaluation, and export components. Additional capabilities improve deployment and experimentation:
• HTTP tracker service: Added boxmot-service for session-based tracking, with CPU and GPU service images alongside full CLI Docker profiles. Requests containing images can infer frame dimensions.
• Faster cached replay: Reduced startup and loading overhead through prefetching, streamed Parquet reads, metadata reuse, and image decoding only when required.
• Experiment selection: Evaluation and tuning can resolve authored experiments through dataset, detector, and ReID profiles.
• Flexible tracker inputs: Added NumPy BGR image support for Python and native adapters. Packed NumPy detections return packed NumPy tracks; structured Detections return Tracks.
• Shared live ReID extraction: Supported trackers generate missing embeddings lazily from supplied frames. Attached embeddings bypass encoder inference.
• Selectable association metrics: Added configurable IoU, GIoU, DIoU, CIoU, HMIoU, and centroid association with AABB and OBB geometry. OBB CIoU and HMIoU remain experimental.
• Timestamp-aware tracking: Added experimental --variable-dt support for supported Python Kalman trackers. Prediction uses capture timestamps; fixed-step behavior remains the default. Native backends retain fixed-step prediction.
• Kalman calibration: Added --calibrate-kf to estimate noise settings from cached detections and ground truth before evaluation or tuning. Kalman settings remain fixed during tracker optimization.
• Reusable tracker configurations: Added --tracker-config for loading presets, parameter overrides, and saved calibration profiles.
• Frame-rate experiments: Added dataset sampling through --fps and reproducible dropped-frame experiments through time-variant, preserving capture timestamps and reusing cached perception results.
• Evaluation visualization: Added --show and --save for annotated sequence previews and videos.
• Detailed diagnostics: Expanded startup and runtime reporting for acquisition, component execution, rendering, and output handling.

When upgrading, update int

This major release completes oriented-box support across the Python tracker set, introduces reproducible experiment catalogs, improves native/Python parity, and substantially expands ReID training and deployment.

Highlights

• All registered Python trackers now support canonical AABB and OBB inputs and outputs.
• Added oriented association, angle-continuous motion updates, OBB-aware CMC and ReID crops, and row-aligned masks.
• Replaced monolithic benchmark configs with validated datasets, detectors, ReID profiles, artifacts, presets, and composable experiments.
• Experiment runs now preserve both authored and fully resolved configurations.
• MOT evaluation now parallelizes sequences and adds IDt, IDa, and IDm diagnostics.
• Added optional TrackEval comparison through --compare-trackeval and the trackeval extra.
• Hardened native AABB/OBB replay, CMC, fixed-batch ReID, cache identity, and Python/C++ metric parity.
• Expanded CSL-TinyViT, MobileNetV4, and Hi-AFA training, including privileged anatomical supervision, advanced augmentation, provenance checks, and reliable resume support.
• Added compare-reid for cross-domain checkpoint evaluation.
• Added native Core ML FP16 export and inference with configurable static batch buckets.
• Reduced tracker startup and CMC overhead, exposed setup timings, and added saved-video FPS control.
• Versioned embedding caches by producer, runtime, model fingerprint, preprocessing policy, and crop schema.

Breaking Changes and Migration

Recommended evaluation commands:

boxmot eval --experiment mot17-ablation-yolox-lmbn --tracker boosttrack
boxmot eval --dataset mot17 --split ablation --tracker boosttrack

The stable public imports remain:

from boxmot import BoxMOT, Detector, ReIDModel

Additional migration notes:

• Custom trackers must implement _track_detections() instead of _update_impl().
• Detection and result validation is stricter; empty arrays must retain their canonical column shape.
• TrackResults.xyxy returns the enclosing AABB in OBB mode. Use .boxes or .xywha for oriented geometry.
• Legacy embedding caches may be regenerated when their producer, model, runtime, or crop semantics cannot be verified.
• Finite file and directory sources are consumed before BoxMOT.track() returns. Use boxmot.api.functional.track() when lazy finite-source iteration is required.

What’s Changed

• Complete OBB support for the remaining trackers
• ReID, tracker, configuration, native backend, and metrics refactor
• Benchmark documentation cleanup

Full Changelog: v22.0.0...v23.0.0

Contributors

• @mikel-brostrom

BoxMOT v22.0.0

This release is a large architecture update centered on the tracker stack, the public Python API, ReID workflows, and evaluation metrics.

Highlights

• Added a cleaner high-level Python API with BoxMOT, Detector, and ReIDModel.
• Standardized tracker internals around shared base classes, registries, detection layouts, association helpers, motion utilities, and common track models.
• Replaced the bundled TrackEval runtime path with BoxMOT's integrated MOT metrics implementation.
• Preserved MOT metric behavior as closely as possible, including HOTA, MOTA, IDF1, AssA, AssRe, ID switches, and OBB evaluation support.
• Moved benchmark dataset roots to BoxMOT-owned locations under boxmot/datasets/mot and boxmot/datasets/reid.
• Reorganized ReID backbones, training recipes, pretrained loading, and export paths.
• Added dynamic-batch ONNX export by default for the high-level Python ReID workflow.
• Improved benchmark download handling and cleaner progress output.

New Python API

The recommended Python entry points are now:

from boxmot import BoxMOT, Detector, ReIDModel
from boxmot.trackers import OccluBoost

Basic evaluation:

from boxmot import BoxMOT

model = BoxMOT(
    detector="yolox_x_MOT17_ablation",
    reid="models/lmbn_n_duke.pt",
    tracker="occluboost",
)

results = model.val(
    benchmark="mot17",
    split="ablation",
)

print(results)

ReID export and embedding:

from boxmot import ReIDModel

reid = ReIDModel("models/lmbn_n_duke.pt")
reid = reid.export(format="onnx", half=True)

embeddings = reid.embed(
    image,
    boxes=detections.xyxy,
)

Default vs tuned tracker evaluation:

from boxmot import BoxMOT

model_args = {
    "detector": "yolox_x_MOT17_ablation",
    "reid": "models/lmbn_n_duke.pt",
    "tracker": "occluboost",
}

eval_args = {
    "benchmark": "mot17",
    "split": "ablation",
}

model = BoxMOT(**model_args)
default_results = model.val(**eval_args)

tuned = model.tune(
    **eval_args,
    n_trials=10,
    objectives=["hota", "id_switches"],
)

tuned_model = BoxMOT(
    **model_args,
    tracker_kwargs=tuned.best_config,
)
tuned_results = tuned_model.val(**eval_args)

Tracker Refactor

• Added boxmot/trackers/base.py as the shared tracker base.
• Added boxmot/trackers/registry.py and boxmot/trackers/specs.py.
• Flattened many tracker modules so public imports are simpler and more stable.
• Added shared packages under boxmot/trackers/common/ for:
  • appearance plumbing
  • association logic
  • detection layout handling
  • OBB geometry helpers
  • motion and CMC utilities
  • track lifecycle and output formatting
  • reusable track model implementations
• Added extensive tracker contract tests, including bbox/OBB behavior and common association/motion utilities.

Evaluation And Metrics

• Removed the old boxmot.engine.eval.trackeval runtime package.
• Added boxmot.engine.eval.motmetrics.
• Added in-repo tests for MOT metrics adapter and runner behavior.
• Kept AABB and OBB evaluation support.
• Updated evaluator, replay, tuning, and reporting paths to use the integrated metrics implementation.

Dataset Layout

Benchmark data is now owned by BoxMOT instead of living under the removed TrackEval tree:

boxmot/datasets/mot
boxmot/datasets/reid

This avoids keeping dataset assets under boxmot/engine/eval/trackeval/data now that TrackEval has been removed.

ReID Updates

• Reorganized ReID backbones into family/common modules.
• Added a backbone registry.
• Added shared pretrained-loading helpers.
• Added MobileNetV4 training configs:
  • mobilenetv4
  • mobilenetv4_conv_small
  • mobilenetv4_conv_medium
  • mobilenetv4_conv_large
• Added ReID training recipe modules.
• Added ReID comparison/data workflow modules.
• Expanded ReID core,

Highlights

• Mask visualization — tracking results now render segmentation masks when available
• HuggingFace CLI downloads — model and dataset downloads switched to the hf CLI for faster, more reliable fetches
• Cleaner tracking UI — streamlined Rich terminal output with more discrete, focused panels
• Memory leak fix — BotSort's removed_stracks list could grow without bound; now capped via deque(maxlen=100)

New Features

Bug Fixes

• BotSort memory growth — removed_stracks converted to a bounded deque(maxlen=100) to prevent unbounded RAM usage on long sequences
• Benchmark CI — fixed flaky workflow; added dedicated HF dataset download job with caching

Internal Improvements

• Tuner hardening — config parsing validates YAML structure and prints available trackers on FileNotFoundError; malformed param entries are warned and skipped instead of crashing
• Rich UI consolidation — shared formatters moved to boxmot/utils/rich/__init__.py; eval/tune/track reporters simplified
• Evaluator simplification — ~100 lines of dead code removed
• Timing module — removed legacy accumulation branches; cleaner cached-detection display ("loaded from cache (0 ms)")
• Dataset loader — simplified _collect_seq_info with direct fallback to seqinfo.ini
• CI benchmark — single ubuntu-latest runner with HF cache layer instead of full os×python matrix

Dependencies

• uv.lock refreshed
• pyproject.toml minor version bumps

Upgrade Notes

If you rely on raw timing dictionaries with keys preprocess / inference / postprocess, switch to detector_preprocess / detector_process / detector_postprocess. Dictionary access via the old names still works for reads (via _AliasedTotals) but will be removed in a future release.