BoxMOT 为您提供统一的 CLI 和 Python API，用于运行、评估、调优和导出现代多目标跟踪（multi-object tracking）流水线。无需重写检测器（detector）堆栈即可切换跟踪器（tracker），在实验中重复使用缓存的检测结果和嵌入（embeddings），并在本地对 MOT 风格的数据集进行基准测试。

为何选择 BoxMOT

• 统一接口支持 track（跟踪）、generate（生成）、eval（评估）、tune（调优）和 export（导出）。
• 兼容检测、分割和姿态模型，只要它们输出边界框（boxes）。
• 支持仅运动（motion-only）跟踪器以及运动+外观（motion + appearance）跟踪器。
• 重复使用保存的检测结果和嵌入（embeddings）以加速重复评估和调优。
• 原生支持 AABB（轴对齐边界框）和 OBB（定向边界框）检测布局。
• 包含针对 MOT17、MOT20 和 DanceTrack 消融（ablation）分割的本地基准测试工作流。

安装

BoxMOT 支持 Python 3.9 至 3.12。

pip install boxmot
boxmot --help

基准测试结果（MOT17 消融分割）

命令行界面

BoxMOT 提供统一的命令行界面（CLI），语法简洁：

boxmot MODE [OPTIONS] [DETECTOR] [REID] [TRACKER]

模式：

track      在摄像头、图像、视频、目录或流上运行检测器 + 跟踪器
generate   预计算检测结果和嵌入（embeddings）以供后续重复使用
eval       在 MOT 风格的数据集上进行基准测试并应用可选的后处理（postprocessing）
tune       通过多目标搜索优化跟踪器超参数（hyperparameters）
export     将 ReID 模型导出为部署格式

使用 boxmot MODE --help 查看特定模式的标志。

使用 --detector、--reid 和 --tracker 进行显式的组件选择。不支持旧版别名，如 --yolo-model、--reid-model 和 --tracking-method。

快速示例：

# 跟踪摄像头输入
boxmot track --detector yolov8n --reid osnet_x0_25_msmt17 --tracker deepocsort --source 0 --show

# 跟踪视频，绘制轨迹并保存结果
boxmot track --detector yolov8n --reid osnet_x0_25_msmt17 --tracker botsort --source video.mp4 --show-trajectories --save

# 在 MOT17 消融（ablation）分割上评估，使用 GBRC 后处理
boxmot eval --benchmark mot17-ablation --tracker boosttrack --postprocessing gbrc --verbose

# 为基准测试生成可复用的检测结果和嵌入（embeddings）
boxmot generate --benchmark mot17-ablation

# 在基准测试上调优跟踪器超参数（hyperparameters）
boxmot tune --benchmark mot17-ablation --tracker ocsort --n-trials 10

# 将 ReID 模型导出为 ONNX 和 TensorRT 格式，支持动态输入
boxmot export --weights osnet_x0_25_msmt17.pt --include onnx --include engine --dynamic

track 和直接源 generate 运行中常见的 --source 值包括 0、img.jpg、video.mp4、path/、path/*.jpg、YouTube 链接以及 RTSP / RTMP / HTTP 流。

对于配置驱动的 generate、eval 和 tune 运行：

• --benchmark <benchmark> 从 boxmot/configs/benchmarks/ 中选择基准测试配置
• 基准测试配置会自动选择 boxmot/configs/datasets/ 中关联的数据集配置
• 基准测试配置会自动选择 boxmot/configs/detectors/ 中关联的检测器配置文件
• 基准测试配置会自动选择 boxmot/configs/reid/ 中关联的 ReID 配置文件
• --tracker <name> 选择跟踪器并加载 boxmot/configs/trackers/<name>.yaml

示例：

boxmot eval --benchmark mot17-ablation --tracker boosttrack

基准测试配置会自动使用其关联的数据集、检测器和 ReID 配置文件。

要显式覆盖基准测试的检测器和 ReID 默认设置：

boxmot eval --benchmark mot17-ablation --detector yolo11s_obb --reid lmbn_n_duke --tracker boosttrack

如需仅跟踪指定类别，请传入逗号分隔的列表：

boxmot track --detector yolov8s --source 0 --classes 16,17

Python API

如果您已经拥有自己的模型检测结果，请在视频循环中每帧调用一次 tracker.update(...) 方法：

from pathlib import Path

import cv2
import numpy as np
from boxmot import BotSort

tracker = BotSort(
    reid_weights=Path("osnet_x0_25_msmt17.pt"),
    device="cpu",
    half=False,
)

cap = cv2.VideoCapture("video.mp4")

while True:
    ok, frame = cap.read()
    if not ok:
        break

    # Replace this with your detector output for the current frame.
    # AABB input: (N, 6) = (x1, y1, x2, y2, conf, cls)
    # OBB input: (N, 7) = (cx, cy, w, h, angle, conf, cls)
    detections = np.empty((0, 6), dtype=np.float32)
    # detections = your_detector(frame)

    tracks = tracker.update(detections, frame)
    tracker.plot_results(frame, show_trajectories=True)

    print(tracks)
    # AABB output: (N, 8) = (x1, y1, x2, y2, id, conf, cls, det_ind)
    # OBB output: (N, 9) = (cx, cy, w, h, angle, id, conf, cls, det_ind)
    # Use det_ind to map a track back to the detector output

    cv2.imshow("BoxMOT", frame)
    if cv2.waitKey(1) & 0xFF == ord("q"):
        break

cap.release()
cv2.destroyAllWindows()

对于端到端的检测器集成，请查看 examples 中的 notebooks。

检测布局

BoxMOT 根据检测张量形状切换跟踪模式：

当提供 OBB (定向边界框) 检测结果时，OBB 专用跟踪路径会自动启用。当前支持 OBB 的跟踪器有：bytetrack、botsort、ocsort 和 sfsort。

示例

上面的简短命令足以开始使用。以下部分保留了更长的示例列表，而不会让 README 变成命令墙。

# 摄像头
boxmot track --detector yolov8n --reid osnet_x0_25_msmt17 --tracker deepocsort --source 0 --show

# 视频文件
boxmot track --detector yolov8n --reid osnet_x0_25_msmt17 --tracker botsort --source video.mp4 --save

# 图像目录
boxmot track --detector yolov8n --reid osnet_x0_25_msmt17 --tracker bytetrack --source path/to/images --save

# 视频流或 URL
boxmot track --detector yolov8n --reid osnet_x0_25_msmt17 --tracker ocsort --source 'rtsp://example.com/media.mp4'

# YouTube
boxmot track --detector yolov8n --reid osnet_x0_25_msmt17 --tracker boosttrack --source 'https://youtu.be/Zgi9g1ksQHc'

# Ultralytics 检测
boxmot track --detector yolov8n
boxmot track --detector yolo11n

# 分割和姿态变体
boxmot track --detector yolov8n-seg
boxmot track --detector yolov8n-pose

# YOLOX
boxmot track --detector yolox_s

# RF-DETR
boxmot track --detector rf-detr-base

boxmot track --detector yolov8n --reid osnet_x0_25_msmt17 --tracker deepocsort
boxmot track --detector yolov8n --reid osnet_x0_25_msmt17 --tracker strongsort
boxmot track --detector yolov8n --reid osnet_x0_25_msmt17 --tracker botsort
boxmot track --detector yolov8n --reid osnet_x0_25_msmt17 --tracker boosttrack
boxmot track --detector yolov8n --reid osnet_x0_25_msmt17 --tracker hybridsort

# 仅运动跟踪器
boxmot track --detector yolov8n --reid osnet_x0_25_msmt17 --tracker bytetrack
boxmot track --detector yolov8n --reid osnet_x0_25_msmt17 --tracker ocsort
boxmot track --detector yolov8n --reid osnet_x0_25_msmt17 --tracker sfsort

# 绘制轨迹并在跟踪丢失时显示卡尔曼滤波预测
boxmot track --detector yolov8n --reid osnet_x0_25_msmt17 --tracker botsort --source video.mp4 --show-trajectories --show-kf-preds --save

# 仅跟踪选定类别
boxmot track --detector yolov8s --source 0 --classes 16,17

# 独立跟踪每个类别
boxmot track --detector yolov8n --source video.mp4 --per-class --save

# 高亮显示特定目标 ID
boxmot track --detector yolov8n --reid osnet_x0_25_msmt17 --tracker deepocsort --source video.mp4 --target-id 7 --show

# 复现 README 风格的 MOT17 结果
boxmot eval --benchmark mot17-ablation --tracker boosttrack --verbose

# MOT20 消融分割
boxmot eval --benchmark mot20-ablation --tracker boosttrack --verbose

# DanceTrack 消融分割
boxmot eval --benchmark dancetrack-ablation --tracker boosttrack --verbose

# VisDrone 消融分割
boxmot eval --benchmark visdrone-ablation --tracker botsort --verbose

# 应用后处理
boxmot eval --benchmark mot17-ablation --tracker boosttrack --postprocessing gsi
boxmot eval --benchmark mot17-ablation --tracker boosttrack --postprocessing gbrc

# 为基准测试生成检测和嵌入
boxmot generate --benchmark mot17-ablation

# 为直接数据集路径生成检测和嵌入
boxmot generate --detector yolov8n --reid osnet_x0_25_msmt17 --source ./assets/MOT17-mini/train

# 在内置基准配置上调优
boxmot tune --benchmark mot17-ablation --tracker boosttrack --n-trials 9

# 使用显式的检测器/ReID 覆盖调优跟踪器
boxmot tune --benchmark mot17-ablation --detector yolo11s_obb --reid lmbn_n_duke --tracker botsort --n-trials 9

# 导出为 ONNX
boxmot export --weights osnet_x0_25_msmt17.pt --include onnx --device cpu

# 导出为 OpenVINO
boxmot export --weights osnet_x0_25_msmt17.pt --include openvino --device cpu

# 导出为支持动态输入的 TensorRT
boxmot export --weights osnet_x0_25_msmt17.pt --include engine --device 0 --dynamic

贡献

如果您想贡献代码，请从 CONTRIBUTING.md 开始。

贡献者

支持与引用

• 错误报告和功能请求：GitHub Issues（GitHub 问题追踪）
• 问题与讨论：GitHub Discussions（GitHub 讨论区）或 Discord（Discord 聊天平台）
• 引用元数据：CITATION.cff
• 商业支持：box-mot@outlook.com

BoxMOT 快速上手指南

环境准备

• Python 版本：3.9 - 3.12
• 操作系统：Linux、Windows、macOS 均支持
• 硬件要求：支持 CPU 和 GPU（推荐 NVIDIA GPU 加速）

安装步骤

pip install boxmot
boxmot --help

基本使用

方式一：命令行工具（CLI）

实时追踪摄像头画面：

boxmot track --detector yolov8n --reid osnet_x0_25_msmt17 --tracker deepocsort --source 0 --show

追踪视频文件并保存结果：

boxmot track --detector yolov8n --reid osnet_x0_25_msmt17 --tracker botsort --source video.mp4 --save

方式二：Python API

在代码中集成追踪功能：

from pathlib import Path
import cv2
import numpy as np
from boxmot import BotSort

# 初始化追踪器
tracker = BotSort(
    reid_weights=Path("osnet_x0_25_msmt17.pt"),
    device="cpu",
    half=False,
)

# 读取视频
cap = cv2.VideoCapture("video.mp4")

while True:
    ok, frame = cap.read()
    if not ok:
        break

    # 用你的检测器获取检测结果
    # 格式: (N, 6) = (x1, y1, x2, y2, conf, cls)
    detections = np.empty((0, 6), dtype=np.float32)
    # detections = your_detector(frame)

    # 更新追踪器
    tracks = tracker.update(detections, frame)
    
    # 可视化结果
    tracker.plot_results(frame, show_trajectories=True)
    
    cv2.imshow("BoxMOT", frame)
    if cv2.waitKey(1) & 0xFF == ord("q"):
        break

cap.release()
cv2.destroyAllWindows()

提示：更多使用示例和高级功能（如模型评估、参数调优）请参考官方文档。