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:

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

Basic evaluation:

:::python
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:

:::python
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:

:::python
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:

:::text
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:

:::text
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:

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

Migration Notes

• Prefer the new BoxMOT facade for benchmark workflows:

  :::python model = BoxMOT(detector="...", reid="...", tracker="...") results = model.val(benchmark="mot17", split="ablation")

• Use tracker_kwargs to apply tuned tracker parameters:

  :::python tuned_model = BoxMOT( detector="...", reid="...", tracker="occluboost", tracker_kwargs=tuned.best_config, )

• Use ReIDModel for direct embedding generation:

  :::python 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.