mikel-brostrom/boxmot

BoxMOT provides independent detector, segmentor, appearance-encoder, and tracker components built around validated Torch structures. Pipelines compose those components; the CLI owns sources, outputs, materialized datasets, evaluation, tuning, research, and ReID workflows.

Why BoxMOT

• One interface for track, materialize, materialize --time-variant, eval, tune, research, train-reid, eval-reid, compare-reid, export, export-edgetam, install, and native build workflows.
• Swappable components with explicit capabilities and requirements.
• Immutable, keyed Parquet builds with reusable detections, masks, and embeddings.
• Support for both AABB and OBB tracking paths.
• Optional production-ready native C++ tracker implementations with the same metrics as the Python path, opted into via --tracker-backend cpp and embeddable in standalone C++ projects via CMake (see Native C++ Integration and platform dependency installation).
• A structured Python API for embedding components and pipelines in applications.

Installation

BoxMOT supports Python 3.10 through 3.13.

pip install boxmot
boxmot --help

The default package uses the standard PyPI PyTorch build. Source checkouts and CI can explicitly select the lockfile-backed cpu or cu130 profile. For those profiles and mode-specific extras such as yolo, service, evolve, research, onnx, openvino, and tflite, see the installation guide.

Benchmark Results

Related guides:

• Evaluation and Postprocessing
• Experiment Workflows
• Native C++ Integration

Minimal Usage

CLI:

boxmot track --detector yolo26n --reid lmbn_n_duke --tracker occluboost \
  --source 0 --save --show

Evaluate a tracker:

boxmot eval \
  --dataset mot17 \
  --split ablation \
  --detector yolox-x-mot17 \
  --reid lmbn-n-duke \
  --tracker botsort

Python with axis-aligned boxes (AABB):

import numpy as np

from boxmot import OccluBoost

tracker = OccluBoost()
dets = np.array([[100, 200, 300, 400, 0.9, 0]])
frame = np.zeros((480, 640, 3), dtype=np.uint8)  # BGR image
tracks = tracker.update(dets, frame)
print(tracks[:, 4].astype(int))  # track IDs

Python with oriented boxes (OBB):

import numpy as np

from boxmot import OccluBoost

tracker = OccluBoost(is_obb=True)
# cx, cy, width, height, angle in radians, confidence, class_id
dets = np.array([[200, 300, 200, 100, np.pi / 6, 0.9, 0]])
frame = np.zeros((480, 640, 3), dtype=np.uint8)  # BGR image
tracks = tracker.update(dets, frame)
print(tracks[:, 5].astype(int))  # track IDs

2D/3D sensor fusion with ego-motion compensation using EagerMot:

import numpy as np

from boxmot import EagerMot

tracker = EagerMot()
camera = np.array([  # synthetic camera projection
    [100, 0, 100, 0],
    [0, 100, 50, 0],
    [0, 0, 1, 0],
])
camera_to_world = np.eye(4)
camera_to_world[0, 3] = 1.0  # synthetic pose: camera at world x = 1 meter
dets = np.array([[78, 39, 122, 62, 0.95, 0]])
# 3D in camera coordinates: x, y, z, yaw, length, width, height, confidence, class_id
dets_3d = np.array([[0, 1, 10, 0, 4, 2, 2, 0.9, 0]])

tracks_2d, tracks_3d = tracker.update(
    dets,
    detections_3d=dets_3d,
    camera=camera,
    image_size=(100, 200),  # height, width
    camera_to_world=camera_to_world,
)
print(tracks_2d[:, 4].astype(int))  # image track IDs
print(tracks_3d[:, 7].astype(int))  # 3D track IDs

Replace the synthetic pose with the current frame's absolute 4×4 camera-to-world transform on every update. KITTI evaluation loads these from poses.npy when the dataset declares a poses modality. If poses are unavailable, omit camera_to_world throughout the sequence to track in camera coordinates.

Contributing

Start with CONTRIBUTING.md and the contributor docs.

Contributors

Support and Citation

• Bugs and feature requests: GitHub Issues
• Questions and discussion: GitHub Discussions or Discord
• Limited free consulting is available for nonprofit nature conservation projects using BoxMOT. Contact [email protected] to discuss your project.
• Citation metadata: CITATION.cff
• Commercial support: [email protected]