mikel-brostrom/boxmot

BoxMOT – Pluggable Multi‑Object Tracking

What it is BoxMOT is a Python (and optional C++) library that lets you build, run, and evaluate multi‑object trackers (MOT) on top of any object detector. It provides a clean, modular API where the four main pieces – detector, segmentation mask, appearance encoder (Re‑ID), and tracker – can be swapped independently. The library ships with a command‑line interface (CLI) for common workflows (tracking, evaluation, tuning, dataset materialisation, etc.) and a Python API for embedding trackers in your own code.

Key features

Feature	Why it matters
Unified CLI	One entry point (boxmot) covers tracking, evaluation, hyper‑parameter tuning, Re‑ID training, dataset export, and more, reducing the need to stitch together separate tools.
Pluggable components	Detectors (e.g., YOLO variants), segmentors, Re‑ID encoders, and trackers can be mixed‑and‑matched via simple flags, enabling rapid experimentation.
AABB & OBB support	Handles both axis‑aligned (AABB) and oriented (OBB) bounding boxes, useful for aerial or sports footage where objects rotate.
Native C++ backend	An optional high‑performance C++ implementation of the trackers can be used (--tracker-backend cpp) and integrated into other C++ projects via CMake.
Immutable Parquet builds	Detections, masks, and embeddings are stored in keyed Parquet files, making datasets reproducible and reusable across experiments.
Extensive benchmark tables	The README lists HOTA, MOTA, and IDF1 scores on MOT17, SportsMOT, and MMOT OBB datasets for many built‑in trackers (e.g., occluboost, botsort, bytetrack).
Python API	Example shows creating a tracker (OccluBoost) and feeding NumPy detections + BGR frames to obtain track IDs, with optional OBB mode.
Installation	pip install boxmot works on Python 3.10‑3.13; extra profiles (yolo, service, onnx, etc.) are available for GPU or CPU builds.
Community & support	Discord, GitHub Discussions, and limited free consulting for non‑profit conservation projects.

Typical usage

# Track from a webcam using YOLO‑v2 detector, a Re‑ID model, and the OccluBoost tracker
boxmot track \
  --detector yolo26n \
  --reid lmbn_n_duke \
  --tracker occluboost \
  --source 0 --save --show

from boxmot import OccluBoost
import numpy as np

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

Who should use it

• Researchers prototyping new MOT algorithms who need a reproducible pipeline.
• Practitioners deploying real‑time tracking (e.g., wildlife monitoring, sports analytics) who want a fast C++ backend.
• Anyone needing a unified interface to evaluate multiple trackers on standard MOT benchmarks.

Where to learn more

• Full documentation: docs/ (installation, modes, API reference, tracker list).
• Benchmark results and experiment guides are in the README tables and docs/guides/.
• Community help via Discord or GitHub Discussions.