Repository navigation
Releases
Release v26.0.0
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, andper_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
KalmanConfigandReIDConfiggroup component settings. - Joint motion selection:
tune --select-kfcompares compatible Kalman filters and noise profiles using held-out predictions. Add--select-cmcto 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-inputsreduce 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
kalmanandkalman.noise; configure tracker-owned appearance throughreid=ReIDConfig(...)or an injected appearance encoder. - Replace
track_buffer. ByteTrack and BoT-SORT now usemax_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_distancenow determines geometric eligibility across matching and recovery; overlap thresholds no longer restrict centroid matching. - Update commands and imports. Replace
boxmot time-variantwithboxmot materialize --time-variant. Internal tracker and motion modules have moved; prefer public imports fromboxmot. - 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
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.
Release v23.0.0
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, andIDmdiagnostics. - Added optional TrackEval comparison through
--compare-trackevaland thetrackevalextra. - 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-reidfor 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 boosttrackThe stable public imports remain:
from boxmot import BoxMOT, Detector, ReIDModelAdditional 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.xyxyreturns the enclosing AABB in OBB mode. Use.boxesor.xywhafor 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. Useboxmot.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
Release v22.0.0
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, andReIDModel. - 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/motandboxmot/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 OccluBoostBasic 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.pyas the shared tracker base. - Added
boxmot/trackers/registry.pyandboxmot/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.trackevalruntime 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:
mobilenetv4mobilenetv4_conv_smallmobilenetv4_conv_mediummobilenetv4_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_switchesmaps toIDSW. - 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:
ftfyregexyacs
Breaking Changes
This release includes internal import path changes.
Notable changes:
boxmot.engine.eval.trackevalhas been removed.- Old nested tracker module paths were flattened or replaced.
boxmot/trackers/basetracker.pywas replaced byboxmot/trackers/base.py.boxmot/trackers/tracker_zoo.pywas 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 OccluBoostMigration Notes
- Prefer the new
BoxMOTfacade for benchmark workflows:
model = BoxMOT(detector="...", reid="...", tracker="...")
results = model.val(benchmark="mot17", split="ablation")- Use
tracker_kwargsto apply tuned tracker parameters:
tuned_model = BoxMOT(
detector="...",
reid="...",
tracker="occluboost",
tracker_kwargs=tuned.best_config,
)- Use
ReIDModelfor 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
Highlights
- Mask visualization — tracking results now render segmentation masks when available
- HuggingFace CLI downloads — model and dataset downloads switched to the
hfCLI for faster, more reliable fetches - Cleaner tracking UI — streamlined Rich terminal output with more discrete, focused panels
- Memory leak fix — BotSort's
removed_strackslist could grow without bound; now capped viadeque(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_stracksconverted to a boundeddeque(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_infowith direct fallback toseqinfo.ini - CI benchmark — single
ubuntu-latestrunner with HF cache layer instead of full os×python matrix
Dependencies
uv.lockrefreshedpyproject.tomlminor 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
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
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
What's Changed
- enable python api by @mikel-brostrom in #2266
- make python api benchmark eval multiprocessing-safe and quieter by @mikel-brostrom in #2268
- add research and generate to python api by @mikel-brostrom in #2271
Full Changelog: v17.0.0...v18.0.0
Release v17.0.0 - OBB tracking and evaluation
What's Changed
- Fix engine export by @mikel-brostrom in #2235
- Enable evaluation on FastTracker dataset by @Fleyderer in #2236
- Fix xysr_kf bug @amaizr in #2241
- Extend all trackers in order to enable OBB tracking @mikel-brostrom in #2242
- Add toy OBB dataset @mikel-brostrom in #2249
- Easier cpu/gpu installation by @mikel-brostrom in #2250
- Fix tflite export @mikel-brostrom in #2253 #2252
- Oriented bounding box evaluation by @mikel-brostrom in #2256
- Move tracker responsibilities from visualization to base tracker by @mikel-brostrom in #2257
- Extended tuning functionality, default configs for ultralytics YOLO by @Fleyderer in #2259
New Contributors
Full Changelog: v16.0.11...v17.0.0
Release v16.0.11 - SFSORT
- Integrated SFSORT
- Added SFSORT to CI and Benchmark for automatic metric generation