trackers

即插即用的多目标跟踪，适用于任何检测模型。

在视频帧之间跟踪对象是那种听起来简单但尝试起来却困难重重的问题——遮挡、快速运动、外观相似的目标以及移动相机都会与你作对。trackers 提供了 SORT、ByteTrack、OC-SORT、BoT-SORT 和 C-BIoU 的清晰且经过基准测试的实现，让你可以跳过底层管道搭建，专注于你的应用。它原生支持 supervision.Detections，这意味着它可以无缝集成到你已经使用的任何检测器中——YOLO、DETR、RT-DETR 或其他任何检测器——无需胶水代码。无论你是比较算法的研究人员、部署生产流水线的工程师，还是构建有趣项目的爱好者，trackers 都为所有这些算法提供了单一且一致的接口。需要 Python ≥ 3.10。

为什么需要跟踪器？

• Clean-room implementations. 每个算法均基于原始论文重新实现——而非对他人代码的简单封装。您可以阅读、理解并修改它。
• Detector-agnostic. 兼容 YOLO、DETR、RT-DETR 或任何能生成边界框的模型。无需依赖或假设任何推理库。
• supervision.Detections native. 直接集成到 supervision 生态系统中。输入检测框，返回跟踪后的检测框——零胶水代码。
• Benchmarked across four datasets. 在 MOT17、SportsMOT、SoccerNet 和 DanceTrack 四个数据集上进行了基准测试——包括默认参数和超参数调优后的结果，以便您在部署前了解预期表现。
• Tunable out of the box. 内置基于 Optuna 的超参数搜索功能，通过 trackers tune 实现，以便针对您的特定场景和检测器进行优化。
• Camera motion compensation. BoT-SORT 原生支持移动相机，即使整个画面发生位移，也能保持跟踪 ID 稳定。

Install

pip install trackers

pip install git+https://github.com/roboflow/trackers.git

有关更多选项，请参阅安装指南。

快速入门

只需几行代码即可将跟踪功能添加到现有的检测流水线中。所有跟踪器共享相同的 update(detections, frame=None) 接口，因此日后切换算法只需一行代码。以下示例使用 inference 作为检测器——可将其替换为任何返回 supervision.Detections 的检测器。

import cv2
import supervision as sv
from inference import get_model
from trackers import ByteTrackTracker

model = get_model(model_id="rfdetr-medium")
tracker = ByteTrackTracker()

cap = cv2.VideoCapture("video.mp4")
while cap.isOpened():
    ret, frame = cap.read()
    if not ret:
        break

    result = model.infer(frame)[0]
    detections = sv.Detections.from_inference(result)
    tracked = tracker.update(detections)

有关更多示例，请参阅 跟踪指南。

从 CLI 进行跟踪

更喜欢使用终端？将 trackers track 指向视频、网络摄像头流、RTSP 流或图像目录，它会在一条命令中处理检测、跟踪和带注释的输出——无需 Python 脚本。

trackers track \
    --source video.mp4 \
    --output.video output.mp4 \
    --detection.model rfdetr-medium \
    --tracker bytetrack \
    --show.labels \
    --show.trajectories

有关所有 CLI 选项，请参阅 跟踪指南。

算法

以下每个跟踪器都是其原始论文的忠实实现。选择适合您场景的跟踪器，或运行基准测试以了解哪个在您的数据上表现最佳。

所有分数均使用标准划分上的默认参数。请参阅 tracker comparison 以获取调优后的数值和方法论。

trackers 还附带了 McByte，这是一种掩码条件跟踪器，它扩展了 BoT-SORT 风格的关联，将时间传播的 SAM/Cutie 分割掩码作为额外的匹配线索。它需要可选的重型依赖项（torch、SAM、Cutie），默认情况下未安装——请参阅 McByte docs 以了解设置和基准测试数值。

Evaluate

一旦你获得了跟踪结果，你就想知道它们的质量如何。trackers eval 针对真值标注计算 CLEAR、HOTA 和 Identity 指标，并打印出每个序列的细分结果以及综合分数。

trackers eval \
    --gt_dir ./data/mot17/val \
    --tracker_dir results \
    --metrics '[CLEAR,HOTA,Identity]' \
    --columns '[MOTA,HOTA,IDF1]'

Sequence                        MOTA    HOTA    IDF1
----------------------------------------------------
MOT17-02-FRCNN                30.192  35.475  38.515
MOT17-04-FRCNN                48.912  55.096  61.854
MOT17-05-FRCNN                52.755  45.515  55.705
MOT17-09-FRCNN                51.441  50.108  57.038
MOT17-10-FRCNN                51.832  49.648  55.797
MOT17-11-FRCNN                55.501  49.401  55.061
MOT17-13-FRCNN                60.488  58.651  69.884
----------------------------------------------------
COMBINED                      47.406  50.355  56.600

完整的评估工作流，请参阅评估指南。

下载数据集

需要基准数据用于评估？trackers download 可通过单条命令拉取 MOT17、SportsMOT 及其他受支持的数据集，并可选择性地处理数据划分和资源，以便您仅下载所需内容。

trackers download --dataset mot17 \
    --split val \
    --asset annotations,detections

有关更多下载选项，请参阅下载指南。

试一试

想在编写任何代码之前看到实际效果吗？在我们的 Hugging Face Playground 中在浏览器里试用跟踪器——无需安装。

下一步去哪里

• 跟踪新手？ 从跟踪指南开始——它从头到尾介绍了 Python API 和 CLI。
• 想要基准测试？ 跟踪器对比涵盖了所有四种算法在所有四个数据集上的表现，包括默认和调优参数，并提供了针对您的场景选择哪种算法的指导。
• 正在构建研究流水线？ 评估指南和下载指南涵盖了完整的离线基准测试工作流程。
• 完整 API 参考 → trackers.roboflow.com
• 无需安装试用 → Hugging Face Playground
• 有问题？ 在 Discord 上找到我们。

贡献

我们欢迎贡献。请阅读我们的贡献者指南以开始。

许可证

代码以Apache 2.0 许可证发布。