BoxMOT 多目标追踪快速入门：从安装到跑通你的第一个视频

BoxMOT 多目标追踪快速入门：从安装到跑通你的第一个视频

【免费下载链接】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 教程带你完成四件事：装好包、命令行跑通第一段追踪、把追踪器接进自己的 Python 代码，再根据基准数据挑一个合适的追踪算法。全部示例都基于仓库真实存在的命令与文件路径。

1. 先把 BoxMOT 的定位说清楚

做追踪的人最熟悉的老问题是：检测模型每一帧只告诉你"这里有个人"，却不保证这一帧的 1 号目标下一帧还是 1 号。多目标追踪（MOT，Multi-Object Tracking）要解决的就是这个身份保持问题——把逐帧检测结果串成带稳定 ID 的轨迹。

BoxMOT 的做法是把"追踪"从检测模型里拆出来：它不做检测，只接收任何能输出边界框的模型的预测，然后在其上完成关联、ID 分配与轨迹维护。五个能力值得你留意：

• 追踪器可插拔：bytetrack、ocsort、botsort、strongsort、deepocsort、hybridsort、boosttrack 等实现统一放在 boxmot/trackers/，接口一致，换算法等于换一个参数；
• 不挑上游模型：任何输出框的分割、检测、姿态模型都能喂给它，包括 Torchvision、YOLOX、RF-DETR 等；
• 自带基准管道：MOT17、MOT20、DanceTrack 等数据集的配置文件就在 boxmot/configs/datasets/，检测、追踪器、ReID 的组合可以量化对比；
• 纯运动 / 运动+外观两档：轻量档只靠运动模型，适合 CPU 实时场景；加上外观嵌入（ReID，外观再识别，如 LightMBN、OSNet）后 ID 一致性更高，代价是计算量上升；
• 检测与嵌入一次生成、多次复用：跑一次检测并缓存，之后换任意追踪器评估都不用重跑感知部分。

2. 安装与验证

环境要求 Python 3.10–3.13（仓库pyproject.toml声明>=3.10,<3.14）。一条命令装好：

pip install boxmot

验证方法：

boxmot --help

能列出track、eval、tune、export等子命令，就说明安装成功。

3. 用 track 子命令跑通第一次追踪

boxmot track是最常用的入口。一次调用只需想清楚五个维度，下面每个维度给你 1–3 条代表命令。

3.1 指定追踪源 --source

--source接受摄像头编号、图像、视频或目录，路径支持通配符：

boxmot track --source 0 # 本机摄像头，编号 0 boxmot track --source vid.mp4 # 视频文件 boxmot track --source ./assets/MOT17-mini/train # 目录作为输入

3.2 选择检测模型 --detector

boxmot track --source 0 --detector rf-detr-base.pt # 仅输出边界框 boxmot track --source 0 --detector yolox_s.pt # 仅输出边界框

--detector既可以是权重文件路径，也可以是内置 profile 名（如yolo26n）。

3.3 选择追踪算法 --tracker

boxmot track --source 0 --tracker deepocsort boxmot track --source 0 --tracker strongsort boxmot track --source 0 --tracker ocsort

完整可选列表跑boxmot track --help即可看到。

3.4 搭配外观模型 --reid

用到外观信息的追踪器才需要它。仓库当前内置的 profile 可参考 boxmot/configs/reid/：

boxmot track --source 0 --reid lmbn-n-duke # 轻量级 boxmot track --source 0 --reid osnet-x0-25-msmt17

3.5 过滤类别 --classes

默认追踪模型预测到的所有类别。只追踪部分类别时，传 MS COCO 类别索引：

boxmot track --source 0 --detector yolov8s.pt --classes 16,17 # 仅猫和狗

五个维度拼起来，例如：boxmot track --source 0 --detector yolov8s.pt --tracker botsort --reid osnet-x0-25-msmt17 --show --save。

4. 把追踪器接进自己的 Python 代码

如果你已经有检测流程（比如 Torchvision 的 FasterRCNN），只需把检测输出拼成追踪器期望的格式再逐帧update。下面示例：FasterRCNN 出检测，BoostTrack 出轨迹，代码中每步都标注了意图：

import cv2 import numpy as np import torch from pathlib import Path from torchvision.models.detection import ( fasterrcnn_resnet50_fpn_v2, FasterRCNN_ResNet50_FPN_V2_Weights as Weights, ) from boxmot import BoostTrack device = torch.device("cuda" if torch.cuda.is_available() else "cpu") # 1) 加载预训练检测器与配套预处理 weights = Weights.DEFAULT detector = fasterrcnn_resnet50_fpn_v2(weights=weights, box_score_thresh=0.5) detector.to(device).eval() transform = weights.transforms() # 2) 初始化追踪器：ReID 权重路径 + 设备 + 是否半精度 tracker = BoostTrack( reid_weights=Path("osnet_x0_25_msmt17.pt"), device=device, half=False, ) cap = cv2.VideoCapture(0) # 3) 打开视频源 with torch.inference_mode(): while True: success, frame = cap.read() if not success: break # 4) BGR -> RGB -> 张量，过检测器的预处理 rgb = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB) tensor = torch.from_numpy(rgb).permute(2, 0, 1).to(torch.uint8) input_tensor = transform(tensor).to(device) # 5) 推理并做置信度过滤 output = detector([input_tensor])[0] scores = output["scores"].cpu().numpy() keep = scores >= 0.5 boxes = output["boxes"][keep].cpu().numpy() labels = output["labels"][keep].cpu().numpy() # 6) 组装 [x1, y1, x2, y2, conf, class] 的 N 行数组 detections = np.concatenate( [boxes, scores[keep][:, None], labels[:, None]], axis=1 ) # 7) 追踪器消费检测帧，返回当前帧的轨迹 res = tracker.update(detections, frame) tracker.plot_results(frame, show_trajectories=True) # 8) 在原图上画框与轨迹 cv2.imshow("BoxMOT demo", frame) if cv2.waitKey(1) & 0xFF == ord("q"): break cap.release() cv2.destroyAllWindows()

想换算法时，只需把BoostTrack换成BotSort、ByteTrack等——顶层包名与构造函数风格保持一致，update接口相同。

5. 看基准数据，按瓶颈挑算法

下表是 MOT17 消融分割上的官方基准结果（固定同一套"消融"检测，只变追踪器）：

选型建议很直接：帧率是瓶颈（比如摄像头实时流）就选 bytetrack / ocsort，两者 FPS 上千且指标不塌方；精度优先就选 boosttrack / botsort，HOTA 领先明显，代价是 17–46 FPS。中间档 hybridsort、strongsort 适合对精度和延迟都有要求的折中场景。注意 FPS 受硬件影响，只作相对量级参考。

6. 进阶：eval 评估、tune 调参、export 导出

6.1 eval：量化一次追踪组合

boxmot eval在标准数据集或自定义数据集上跑完整评估：

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

BoxMOT 的关键设计：感知产物（检测结果与外观嵌入）只物化一次、按构建缓存，之后换任何追踪器评估都直接复用，不用重跑检测。--postprocessing还支持评分前对轨迹做后处理，其中 GSI 即高斯平滑插值，用于抹平轨迹毛刺。

6.2 tune：让算法替你搜超参

boxmot tune --dataset mot17 --split ablation --tracker botsort --n-trials 9

它用多目标进化搜索（默认优化 HOTA、MOTA、IDF1 三项），找到的最优超参会回写到追踪器的 YAML 配置（见 boxmot/configs/trackers/），下次运行直接生效。

6.3 export：把 ReID 模型搬到部署端

boxmot export --weights osnet_x0_25_msmt17.pt --include onnx --device cpu boxmot export --weights osnet_x0_25_msmt17.pt --include engine --device 0 --dynamic

--include可指定导出目标，支持 ONNX、OpenVINO、TorchScript、TensorRT 等格式；--dynamic打开动态输入形状，适合推理时裁剪尺寸不固定的场景。

7. 学习资源

• Torchvision 检测框追踪示例：examples/det/torchvision_boxmot.ipynb
• Torchvision 姿态追踪示例：examples/pose/torchvision_boxmot.ipynb
• Torchvision 分割追踪示例：examples/seg/torchvision_boxmot.ipynb
• 官方文档入口：docs/index.md
• 追踪器配置与预设：boxmot/configs/trackers/
• 数据集配置：boxmot/configs/datasets/
• 完整 CLI 参考：终端执行boxmot --help

【免费下载链接】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