Skip to content

Releases

Release v26.0.0

Choose a tag to compare

@mikel-brostrom mikel-brostrom released this 27 Oct 11:38

BoxMOT v26.0.0

BoxMOT v26.0.0 adds multimodal tracking, optional EdgeTAM mask guidance, typed tracker configuration, and joint motion-model selection. It also improves evaluation reproducibility, replay performance, and tuning diagnostics.

Based on committed changes since v25.0.0, through 9da023fd.

New features and improvements

  • EagerMOT sensor fusion: Track objects using calibrated 2D and 3D detections, with optional camera poses. New spatial structures represent 3D boxes, camera calibration, and multimodal outputs. Includes KITTI evaluation, class-specific tuning, and 3D Kalman calibration.
  • MAF-HDA mask tracking: Adds a Python tracker combining motion with mask-based correlation-filter appearance. Supports AABB detections with instance masks without requiring ReID weights.
  • EdgeTAM integration: Generate detection masks with the standalone segmentor or enable temporal mask-guided association using --edgetam. Guidance supports the nine Python box trackers with AABB geometry, IoU association, and per_class=False.
  • Typed configuration and simpler factories: All eleven trackers expose immutable, validated configuration classes with editor completion. Detector, ReID, and tracker factories support simpler construction, while shared KalmanConfig and ReIDConfig group component settings.
  • Joint motion selection: tune --select-kf compares compatible Kalman filters and noise profiles using held-out predictions. Add --select-cmc to jointly select camera-motion compensation. Selected profiles are saved for reuse.
  • More targeted tuning: Conditional search spaces account for geometry, association metric, and enabled features. New controls expose motion, detection-confidence, and ReID–IoU fusion, with improved trial comparisons and parameter diagnostics.
  • Expanded evaluation: Adds KITTI-MOTS mask evaluation, saved 2D detection workflows, 3D tracking metrics, and optional official KITTI AP40 reports. Materialized AABB evaluation supports ordered GTA, GSI, and GBRC postprocessing while preserving raw results.
  • Faster repeated workloads: Batched Kalman operations, optimized camera-motion compensation, indexed embedding reads, reusable workers, and optional --cache-inputs reduce repeated processing.
  • Reliability fixes: Restores per-sequence evaluation reporting, corrects DeepOC-SORT covariance handling during camera compensation, cleans up orphaned workers, and fixes Python 3.10 typing compatibility. OpenCV is pinned to 4.11.0.86, and its runtime version participates in perception-cache identity.

Breaking changes

This major release includes breaking changes. When upgrading from v25:

  • Update direct tracker construction. Pass algorithm settings through the matching config, such as BotSort(config=BotSortConfig(...)). The factory also accepts algorithm keywords: create_tracker("botsort", match_thresh=0.8).
  • Group component settings. Move flat Kalman options into kalman and kalman.noise; configure tracker-owned appearance through reid=ReIDConfig(...) or an injected appearance encoder.
  • Replace track_buffer. ByteTrack and BoT-SORT now use max_lost_frames, counted directly in tracker updates without FPS scaling.
  • Review removed tracker features. SAM2MOT has been removed; standalone SAM segmentation remains available. OccluBoost's online GTA controls are removed, and its AABB/OBB thresholds and lifetime settings are consolidated.
  • Review centroid thresholds. centroid_max_distance now determines geometric eligibility across matching and recovery; overlap thresholds no longer restrict centroid matching.
  • Update commands and imports. Replace boxmot time-variant with boxmot materialize --time-variant. Internal tracker and motion modules have moved; prefer public imports from boxmot.
  • Rebuild native libraries. ByteTrack, BoT-SORT, and OccluBoost use constructor ABI v3. Their shared update/result ABI remains v2.
  • Install optional dependencies explicitly. Use boxmot install --extra ...; first-use automatic installation has been removed. Published Docker images are now CPU-only, while GPU build targets remain available.

EdgeTAM currently requires its full PyTorch checkpoint. The registered export-edgetam command and TFLite bundle runtime remain unfinished.

Release v25.0.0

Choose a tag to compare

@mikel-brostrom mikel-brostrom released this 09 Sep 18:34

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 integrations as follows:

  • Replace the BoxMOT facade, root Detector / ReIDModel imports, and boxmot.api usage with component factories and pipelines.
  • Construct trackers with create_tracker(TrackerSpec(...)).
  • Replace update(..., img=..., embs=..., masks=...) with update(detections, frame). Attach precomputed embeddings and masks to Detections.
  • Replace previous detection and result wrappers with the new canonical structures.
  • Update boxmot.data imports to boxmot.datasets.
  • Replace boxmot generate with boxmot materialize.
  • Replace --n-threads with --sequence-workers.
  • Regenerate positional .npy / .npz caches as keyed Parquet builds.
  • Update ReID exporter imports to the reorganized backend modules.
  • Migrate native integrations to the typed v2 C ABI and rebuild native extensions.

Additional fixes align ReID center loss with training features, correct oriented association geometry, repair native Docker dependencies, and remove stale tests for deleted helper scripts. Documentation now includes theme-aware logos and updated installation, deployment, and migration guidance.

Release validation now checks distribution contents, synchronized package versions, and clean-wheel imports and CLI startup across Python 3.10–3.13.

Migration guide · Full changelog: v23.0.0 → v25.0.0

Release v23.0.0

Choose a tag to compare

@github-actions github-actions released this 26 Aug 20:38

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

v22 v23
--benchmark / benchmark= --experiment / experiment= for reproducible workflows
Model-free benchmark selection --dataset / dataset=
boxmot train boxmot train-reid
boxmot/configs/benchmarks/ configs/experiments/, datasets/, detectors/, reid/, and artifacts/
boxmot/configs/modes.yaml boxmot/configs/runtime.yaml
boxmot.pipeline boxmot.api.pipeline
boxmot.reid.core.reid boxmot.reid.core.runtime
boxmot.trackers.occluboost boxmot.trackers.bbox.occluboost
DeepOCSORT iou_thresh iou_threshold

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

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

Contributors

Release v22.0.0

Choose a tag to compare

@github-actions github-actions released this 10 Jul 13:32
8f8babc

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, evaluator, trainer, export, and reproducibility tests.

ONNX Export

  • High-level Python ReID export now defaults to dynamic batch.
  • Spatial dimensions remain static; only the batch dimension is dynamic.
  • Existing static-batch ONNX exports are refreshed when dynamic export is requested.
  • This better matches tracking workloads where each frame can produce a different number of ReID crops.

Expected ONNXRuntime log shape for dynamic exports:

input=['batch', 3, 384, 128] dtype=float32 buckets=dynamic

Tuning

  • Improved tune result handling and reporting.
  • Added metric alias normalization, for example id_switches maps to IDSW.
  • Suppressed Ray's accelerator environment warning with RAY_ACCEL_ENV_VAR_OVERRIDE_ON_ZERO=0.
  • Added tests for tuner metric aliasing and workflow behavior.

Downloads And Docs

  • Improved benchmark download behavior and progress output.
  • Updated docs across:
    • Python API
    • evaluation
    • tuning
    • ReID training/export
    • benchmark config
    • tracker docs
    • native backend docs
  • Fixed mkdocstrings collection for public result objects exported through boxmot.api.results.

Dependency Changes

  • Added timm.
  • Removed unused legacy dependencies:
    • ftfy
    • regex
    • yacs

Breaking Changes

This release includes internal import path changes.

Notable changes:

  • boxmot.engine.eval.trackeval has been removed.
  • Old nested tracker module paths were flattened or replaced.
  • boxmot/trackers/basetracker.py was replaced by boxmot/trackers/base.py.
  • boxmot/trackers/tracker_zoo.py was removed in favor of the tracker registry.
  • Several ReID backbone modules were reorganized under the new registry/family layout.

Recommended public imports:

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

Migration Notes

  • Prefer the new BoxMOT facade for benchmark workflows:
model = BoxMOT(detector="...", reid="...", tracker="...")
results = model.val(benchmark="mot17", split="ablation")
  • Use tracker_kwargs to apply tuned tracker parameters:
tuned_model = BoxMOT(
    detector="...",
    reid="...",
    tracker="occluboost",
    tracker_kwargs=tuned.best_config,
)
  • Use ReIDModel for direct embedding generation:
reid = ReIDModel("models/lmbn_n_duke.pt")
embeddings = reid.embed(image, boxes=detections.xyxy)
  • If you used internal TrackEval paths, migrate to the integrated BoxMOT evaluation APIs.
  • If you used old tracker internals directly, migrate to public tracker exports or the new registry/common modules.

Release v21.0.0

Choose a tag to compare

@github-actions github-actions released this 03 Jun 17:18
de459eb

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

Area Change
Segmentation Show masks overlay during tracking when using a seg model
Downloads Use huggingface_hub CLI (hf download) for weights and datasets
Track UI More discrete Rich panels — removed verbose parameter dumps
Logo Updated project logo (higher resolution)

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.

Release v20.0.0

Choose a tag to compare

@github-actions github-actions released this 30 May 21:49
5e5cc79

Major Changes

  • Python 3.10+ minimum (previously 3.9)
  • NumPy ≥ 2.2.0 required
  • LiTERT-Torch exporter replaces the old ONNX2TF export path
  • LITERT backend fixes: XNNPACK dynamic reshape fallback, dimension mismatch fixes, flatten(1) in backbones for dynamic shape compatibility

New Features

  • GTA (Global Track Association) postprocessing — pure-appearance recovery pass for re-identifying dead tracks by embedding similarity, with GP-smoothed gap interpolation
  • ReID training pipeline improvements (feat/reid-training PR #2300)
  • SAM2MOT and OccluBoost tracker configs added
  • tune_analysis module for hyperparameter tuning results
  • Dataset configs, cache improvements, and CLI enhancements — optional pipeline steps, new modes, SportsMOT support
  • Part-3 ViT model and resume validation metrics

Refactors

  • Tracker directory reorganization into bbox/, hybrid/, mask/ subcategories
  • Config directory flattening — removed benchmarks/ dir, flattened detectors/ subdirs, merged mot17-ablation into mot17 with a splits: mechanism
  • Engine rework — cache, replay, tracker, tuner, CLI updates
  • Native C++ replay backend updates with C++/Python parity

Performance

  • OBB IoU vectorization — batch rect pre-computation (~3.5× faster)
  • Frame-indexed detection lookup — O(1) instead of O(N) per frame
  • Image I/O skipping after first frame during tracking replay
  • Parallel TrackEval using NUM_THREADS

Fixes

  • KF per-class class-ID alignment
  • OBB KF tuning injection
  • KF velocity noise derived from GT accelerations instead of fixed 0.01 ratio
  • CI fixes (Python 3.9 → 3.10 matrices, test datasets switched to mot17-mini)
  • TUI blank-space cleanup, GTA warning fix
  • iou_batch_obb crash on empty inputs

Release v19.0.0

Choose a tag to compare

@github-actions github-actions released this 11 May 11:55
603f928

Features

  • OccluBoost SOTA tracker (ours) — new Python tracker (#2280) + C++ native backend (#2283)
  • C++ native tracker backends — dual Python/C++ build system (#2277, #2282)
  • Per-phase ReID timing exposed through C++ backends (#2284)
  • Rich terminal UI for CLI output (#2285, #2286)
  • Structured TrackResults with named accessors (.id, .conf, .xyxy) and export API (save_csv, save_vid) (#2296)
  • Ordered embeddings & detections on frame results (#2297)
  • Custom tracker support — users can plug in their own tracker class (#2279)
  • Custom ReID preprocessing (#2275)
  • Auto ONNX export for ReID models
  • Expose common functionality as public API (#2281)

Fixes

  • ByteTrack val_half split limits & det/seqinfo alignment
  • Native build: serialize CMake across worker subprocesses with file lock
  • Native build: stream CMake output for live feedback during pip install
  • Windows CI: OpenCV/Eigen install ordering, PATH quoting
  • Version mismatch fix

CI / Build

  • cibuildwheel pipeline for manylinux, macOS, and Windows wheels
  • macOS deployment target aligned with Homebrew bottles
  • LD_LIBRARY_PATH fix for auditwheel + OpenCV

Docs

  • C++ integration guide
  • Light/dark theme toggle + header logo
  • Citation formatting fix

Release v18.0.0

Choose a tag to compare

@github-actions github-actions released this 14 Apr 20:00
634cca4

What's Changed

Full Changelog: v17.0.0...v18.0.0

Release v17.0.0 - OBB tracking and evaluation

Choose a tag to compare

@github-actions github-actions released this 30 Mar 19:27
6f23517

What's Changed

New Contributors

Full Changelog: v16.0.11...v17.0.0

Release v16.0.11 - SFSORT

Choose a tag to compare

@github-actions github-actions released this 01 Feb 22:52
4682d1d
  • Integrated SFSORT
  • Added SFSORT to CI and Benchmark for automatic metric generation