BoxMOT：给任意目标检测模型接上多目标追踪，11 种算法 1 条命令切换

BoxMOT：给任意目标检测模型接上多目标追踪，11 种算法 1 条命令切换

【免费下载链接】boxmotBoxMOT: Pluggable Python and C++ SOTA multi-object tracking modules with support for axis-aligned and oriented bounding boxes项目地址: https://gitcode.com/GitHub_Trending/bo/boxmot

BoxMOT 把目标检测、ReID 外观编码和追踪拆成可独立替换的组件，任何输出边界框的检测、分割或姿态模型都能接上多目标追踪。它内置 ByteTrack、BoT-SORT 等 11 种追踪算法，MOT17 消融集最高 HOTA 达 71.1，且检测与嵌入一次生成、跨算法复用，省去重复推理。

你的场景属于哪一类？按需求挑追踪器

先想清楚你要解决什么，比纠结参数更有效。BoxMOT 的每个追踪器都声明了自己需要哪些输入（运动框、外观嵌入、图像像素、掩膜、3D 框），选错档位会在运行边界直接报错。

只有检测框、想给目标贴稳定 ID：纯运动档

画面里目标清晰、不重叠太多，追求 CPU 上的高帧率。选bytetrack或ocsort，它们只靠运动模型关联，从不读取图像像素，是成本最低的基线。文档里明确 ByteTrack 是"最快且强的运动基线"。

遮挡多、外观相似会串 ID：运动+外观档

行人互相遮挡、衣服颜色相近，纯运动会频繁断号。选botsort、strongsort、deepocsort、hybridsort、boosttrack或occluboost，它们额外用 ReID 外观嵌入辅助关联，IDF1 通常更高，代价是每帧多一次外观推理。strongsort还需图像像素做 ECC。

目标带旋转角，正框框不住：OBB 定向框档

航拍、斜视角里目标是斜的，正交框（AABB）框不准。用--geometry obb切到定向框路径，输入改为(cx, cy, w, h, angle, conf, class)。注意 MAF-HDA、EagerMOT 只接受 AABB 图像几何。

要反复评估/调参、不想重跑检测：可复用感知档

调追踪器参数时若每次都重跑检测，时间都浪费在预处理上。用materialize把感知结果发布成带 key 的不可变 Parquet build，之后eval、tune都用--build BUILD_ID直接回放。

跑起来：3 步装好并出第一个结果

环境要求 Python 3.10–3.13，默认装 PyPI 上的 PyTorch。下面三步从安装到出结果一气呵成。

第一步，装包并校验 CLI 是否可用：

pip install boxmot # 基础包：CLI、Python API、追踪器、ReID 栈 boxmot --help # 能列出 track/materialize/eval/tune 等子命令即成功

看到--help打印子命令列表，说明命令入口已就绪。

第二步，用 YOLO 检测器时补装对应后端（yoloextra 会拉 Ultralytics 与 YOLOX）：

boxmot install --extra yolo

第三步，跑一条最简追踪命令，--source 0是摄像头，换成视频路径或 RTSP 地址即可：

boxmot track --source 0 --detector yolov8n --tracker bytetrack --save --show

--show实时画带 track ID 的框，--save把结果视频写到runs/下。预期会看到摄像头画面里每个行人挂着稳定编号，按q或 Ctrl-C 退出时会打印一份含检测、ReID、追踪各阶段耗时的 Rich 报告。

需要原生 C++ 构建或materialize实验时，源码检出比 pip 更完整：

git clone https://gitcode.com/GitHub_Trending/bo/boxmot

实测数据：MOT17 上哪档够用

下表是 MOT17 消融分割（Python 后端）的官方基准，括号口径为 Python 分数：

读法：追求实时、目标清晰选bytetrack/ocsort（纯运动、最轻）；遮挡重、怕断号选外观系，botsort的 MOTA 最高；综合 HOTA 与 ID 一致性看，occluboost三项都靠前，是默认首选。

换种方式调用：CLI、Python API 与原生后端

CLI 只是入口之一。把追踪器当组件嵌入自己的程序，用 Python API 更直接。下面这段直接喂 NumPy 检测与 BGR 图，拿到带 ID 的结果：

import numpy as np from boxmot import OccluBoost # 也可 create_tracker("occluboost", ...) tracker = OccluBoost() # 默认几何 aabb dets = np.array([[100, 200, 300, 400, 0.9, 0]]) # x1,y1,x2,y2,conf,class frame = np.zeros((480, 640, 3), dtype=np.uint8) # BGR 图像 tracks = tracker.update(dets, frame) print(tracks[:, 4].astype(int)) # 第 5 列是 track ID

预期打印出与每条检测对应的整数 ID；OBB 场景把构造改成OccluBoost(is_obb=True)并传 7 列即可。

想复用调好的参数，把--tracker-config指向一个 YAML 就能覆盖内置默认值：

boxmot track --source 0 --tracker botsort --tracker-config path/to/calibrated.yaml

同一追踪器还有原生 C++ 后端，botsort、bytetrack、ocsort、occluboost、sfsort加--tracker-backend cpp即可，指标与 Python 路径对齐；底层 C++ 库在 boxmot/native/，配置与调参范围在 boxmot/configs/trackers/。

别踩这几个坑：新手最容易配错的 4 个点

⚠️几何类型要和检测器一致。OBB 检测器必须配--geometry obb，AABB 追踪器收到 OBB 框（或反之）会在追踪前被工厂校验直接拒绝，不会默默转。

⚠️分清谁要像素、谁要嵌入。bytetrack/ocsort从不读图像像素；带 ReID 的追踪器需要frame或现成嵌入，strongsort还额外要 ECC 像素。eval时缺这些输入会抛出可操作的 materialization 错误，先补--reid或嵌入再回放。

⚠️变步长时间是实验功能，不是默认。默认 fixed-step 预测；variable_dt只对 8 个 Python 卡尔曼追踪器生效，native C++、SFSORT、MafHda、EagerMot 直接拒绝，且要求每帧时间戳严格递增，用采集时间而非处理耗时。

⚠️一条 pipeline 只服务一条序列。换视频、换分辨率或换序列前必须reset()（CLI 引擎自动处理，嵌入式 Python 调用要自己调pipeline.reset()），否则状态会跨序列串号。

BoxMOT 的价值在于把"检测 → 外观 → 追踪"拆成可插拔组件，让同一份感知结果在 11 种追踪算法间自由切换、可复现评估。深入用法看 docs/index.md，追踪器逐项参数见 docs/trackers/index.md。

【免费下载链接】boxmotBoxMOT: Pluggable Python and C++ SOTA multi-object tracking modules with support for axis-aligned and oriented bounding boxes项目地址: https://gitcode.com/GitHub_Trending/bo/boxmot