BoxMOT Low-level Python API 深度指南组合 Detector、ReID 与 Tracker 的底层编程范式【免费下载链接】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导读docs/python/low-level.md是 BoxMOT 的底层 Python API 参考文档它面向需要显式组合多目标跟踪流水线的开发者不使用高层门面facadeBoxMOT而是直接实例化检测器Detector、ReID 运行时ReID与跟踪器Tracker自主编排每一帧的数据流。读完本文你将掌握Detector/Detections/ReID/create_tracker/get_tracker_config/TrackResults六个核心构件的完整契约、AABB 与 OBB 两种几何模式的列结构以及如何用它们构建可复用的底层跟踪应用。1. Low-level API 在 BoxMOT 架构中的定位BoxMOT 的 Python 接口分为两层见 docs/python/index.mdHigh-level API通过boxmot.BoxMOT门面及Detector、ReIDModel运行时包装器以最小样板代码完成视频 → 结果的整条链路等价于 CLI 的 Python 版本。Low-level API将流水线拆分为 Detector、ReID runtime、Tracker 三个可独立实例化的构件由调用方显式编排。Low-level API 适合以下场景需要对每一帧进行自定义后处理例如按业务规则改写检测框、在跟踪前后插入自己的逻辑需要复用同一个 ReID 模型实例驱动多个跟踪器节省显存与初始化开销需要精细控制每个构件的初始化参数、批大小、视频抽帧步长等细节需要将 BoxMOT 的跟踪能力嵌入到自己的推理服务或研究框架中而不是套用 CLI 工作流。该文档列出的构件与高层门面构成一一对应的底层实现Detector包装检测后端Detections承载结构化检测输出ReID统一 ReID 推理运行时create_tracker/get_tracker_config负责跟踪器的工厂化构建与配置解析TrackResults定义结构化的跟踪输出数组。2. Detector检测器公共包装器boxmot.detectors.detector.Detector是检测阶段的公共入口源码见 boxmot/detectors/detector.py。它负责根据模型路径自动选择后端、管理来源流式读取并暴露一组可覆盖的分阶段钩子preprocess / process / postprocess。2.1 构造参数Detector.__init__的核心参数如下默认值与行为均以源码为准参数类型默认值说明pathstr \| Path必填检测模型权重路径或包含 YOLO 系列关键字的模型名devicestrcpu推理设备imgszint \| list由模型推断推理图像尺寸缺省时经default_imgsz解析YOLOX 默认[1080, 1920]其余默认[640, 640]见 boxmot/detectors/registry.pyconffloat \| None由模型推断置信度阈值缺省经default_conf解析无配置时回退0.01见 boxmot/detectors/registry.pyioufloat0.7NMS 的 IoU 阈值classesint \| Iterable[int] \| NoneNone允许的类别 ID 过滤agnostic_nmsboolFalse是否跨类别执行 NMSbatchint1流式推理的批大小vid_strideint1视频抽帧步长每隔 N 帧取一帧callbacksdict预置 4 类事件生命周期回调on_predict_start、on_predict_batch_start、on_predict_postprocess_end、on_predict_end2.2 后端自动路由机制构造时Detector._get_backend_class(self.path)调用 boxmot/detectors/registry.py 的get_detector_class根据模型文件名中的关键字路由到对应后端YOLOX 系列yolox_n/s/m/l/x→boxmot.detectors.yolox.YoloXDetector需yolox、tabulate、thop依赖Ultralytics 系列yolov8、yolov9、yolov10、yolo11、yolo12、yolo26、sam→boxmot.detectors.ultralytics.UltralyticsDetectorRTDETR 系列rtdetr_v2_r50vd、rtdetr_v2_r18vd、rtdetr_v2_r101vd→boxmot.detectors.rtdetr.RTDetrDetector需transformers[torch]、timm依赖。这意味着自定义模型文件名也必须包含上述关键字之一才能被正确路由到对应包与架构不存在匹配项时注册表会打印支持的模型关键字并抛出SystemExit(1)。这一设计在源码注释中明确说明For custom models, the filename must include one of these substrings to route it to the correct package and architecture.此外Detector.is_obb会读取后端上的is_obb属性用于判定当前检测是否为旋转框OBB模式is_seg_model则根据模型名是否包含-seg/_seg判断是否为分割模型见 boxmot/detectors/registry.py。2.3 三种推理入口Detector通过__call__统一分发见 boxmot/detectors/detector.pydetector Detector(yolov8n.pt, devicecpu) # 1) 单图推理输入 3 维 ndarray / 图片文件路径返回单个结果 result detector(image) # 2) 流式推理生成器逐批产出 for result in detector.stream_inference(sourcevideo.mp4, batch4): ... # 3) 显式 stream 参数 results list(detector(sourcevideo.mp4, streamTrue))_is_single_inference_source决定返回值契约3 维 ndarray 或图片文件路径扩展名在IMAGE_EXTS中走_predict_single返回单个结果视频、目录、URL 或含通配符的路径走stream_inference。stream_inference内部通过setup_source构造批化迭代器并完整触发on_predict_start→on_predict_batch_start→on_predict_postprocess_end→on_predict_end回调链见 boxmot/detectors/detector.py。2.4 可覆盖的分阶段钩子Detector.process区分两种调用语义见 boxmot/detectors/detector.py复合路径composite path调用方传入conf/iou/classes/agnostic_nms任一覆盖参数时走一次调用完成全部推理的旧语义分阶段路径stage path只传预处理后的输入时仅执行模型 forward便于把 preprocess / process / postprocess 分别计时与替换。warmup()会用一张与imgsz同尺寸的零矩阵做一次空跑预热后端失败仅记录警告而不中断流程见 boxmot/detectors/detector.py。3. Detections规范化的检测结果结构boxmot.detectors.base.Detections是一个 dataclass源码见 boxmot/detectors/base.py以规范列契约承载单张图像的检测结果同时支持轴向对齐框AABB与旋转框OBB两种几何模式。3.1 列结构与字段字段说明dets检测矩阵AABB 为(N, 6)OBB 为(N, 7)构造时经as_detection_array强制转换为float32orig_img原始图像 ndarrayBGRpath来源路径字符串names类别 ID → 名称的映射masks分割掩码形状(N, H, W)必须与检测行数一致否则抛ValueErrorAABB 行布局为[x1, y1, x2, y2, confidence, class]OBB 行布局为[cx, cy, width, height, angle, confidence, class]其中角度以弧度为单位见 boxmot/detectors/base.py 的类文档字符串。这一契约由 boxmot/core/box_schema.py 中的AABB_SCHEMA/OBB_SCHEMA统一定义并在检测、跟踪、缓存、MOT 输出各路径间保持一致。3.2 便捷属性detections detector.predict(image) # Detections 对象 detections.boxes # 原生几何AABB 返回 xyxyOBB 返回 xywha detections.xyxy # 轴向对齐框 (N, 4)OBB 模式下为旋转框的外接 AABB detections.xywha # OBB 模式返回 (N, 5)AABB 模式返回 (N, 0) detections.conf # (N,) 置信度 detections.classes # (N,) 类别 IDint detections.is_obb # 是否为旋转框模式注意 OBB 模式下的xyxy是外接 AABB源码通过旋转框的宽高与角度的余弦/正弦绝对值计算出外接矩形见 boxmot/detectors/base.py。因此当需要按朝向精确裁剪 ReID 输入时应使用boxes或xywha而不是xyxy——这一点在原文档的 Composable runtime 一节中也有明确提醒。3.3 工具函数同模块还导出了几个底层工具见 boxmot/detectors/base.pyas_detection_array校验并返回float32的 AABB/OBB 检测矩阵filter_detections按置信度与类别过滤检测行ensure_image_batch将单图或图像序列归一化为校验过的图像列表resolve_image将图片路径解析为 OpenCV BGR ndarrayload_weights从本地路径加载 PyTorch 检查点Detections.empty(orig_img, is_obb...)构造保留 AABB/OBB 模式的空结果。4. ReID统一的行人重识别运行时boxmot.reid.core.runtime.ReID源码见 boxmot/reid/core/runtime.py是 ReID 阶段的统一运行时支持按权重文件扩展名自动选择推理后端并同样暴露 preprocess / process / postprocess 三阶段钩子。4.1 构造参数from boxmot.reid.core import ReID reid ReID( pathosnet_x0_25_msmt17.pt, # 或使用 weights 关键字 devicecpu, halfFalse, preprocess_nameNone, # 默认走 DEFAULT_PREPROCESS )path/weights均可作为模型引用两者同时提供时path优先两者都为空时回退到WEIGHTS / osnet_x0_25_msmt17.pt支持传入权重路径列表/元组多模型场景self.path取首个元素device经select_device规范化half开启半精度推理self.format resolve_reid_format(self.path)根据权重扩展名解析 ReID 格式PyTorch / ONNX / OpenVINO / TensorRT 等见 boxmot/reid/core/formats.pyget_backend()通过boxmot.reid.backends.registry.get_backend_class(self.format)选择对应后端类并实例化。4.2 推理调用约定# 方式一整图 检测框框由 ReID 内部裁剪 embeddings reid(image, boxesdetections.boxes) # boxes 传 xyxyAABB或 xywhaOBB内部经 coerce_boxes 规范化 # 方式二直接传入裁剪好的图像块序列 embeddings reid(crop_list)ReID.__call__内部依次执行preprocess→process→postprocesspreprocess当提供boxes时对整图按框裁剪并标准化否则把输入视为裁剪块序列经prepare_crop_batch打包成模型输入批见 boxmot/reid/core/runtime.pyprocess在torch.no_grad()下执行模型 forward空输入返回Nonepostprocess将特征移到 numpy 并做L2 归一化features / norms零范数行置为 1 以避免除零见 boxmot/reid/core/runtime.py。因此返回的嵌入向量天然是单位向量可直接用于余弦相似度匹配。ReID.from_backend(backend)类方法还可以包裹一个已实例化的后端对象跳过格式解析直接复用。4.3 包级导出boxmot/reid/core/init.py 提供了懒加载导出ReID与export_formats()返回支持的导出格式 pandas 表格。在类型检查场景TYPE_CHECKING下boxmot.reid.core.runtime.ReID可直接引用。5. Tracker 工厂create_tracker 与 get_tracker_config跟踪器的注册表与工厂集中在 boxmot/trackers/registry.py其中TRACKER_DEFINITIONS注册表boxmot/trackers/registry.py记录了 10 个跟踪器的名称、类路径与是否依赖 ReIDString key类需要 ReIDstrongsortboxmot.trackers.bbox.strongsort.StrongSort是ocsortboxmot.trackers.bbox.ocsort.OcSort否bytetrackboxmot.trackers.bbox.bytetrack.ByteTrack否sfsortboxmot.trackers.bbox.sfsort.SFSORT否botsortboxmot.trackers.bbox.botsort.BotSort是deepocsortboxmot.trackers.bbox.deepocsort.DeepOcSort是hybridsortboxmot.trackers.bbox.hybridsort.HybridSort是boosttrackboxmot.trackers.bbox.boosttrack.BoostTrack是occluboostboxmot.trackers.bbox.occluboost.OccluBoost是sam2motboxmot.trackers.hybrid.sam2mot.sam2mot.Sam2Mot否5.1 create_tracker工厂构建create_tracker见 boxmot/trackers/registry.py根据字符串名构建跟踪器并自动加载其默认 YAML 配置from boxmot.trackers.registry import create_tracker # 纯运动跟踪器无需 ReID 模型 tracker create_tracker(bytetrack) # ReID 感知跟踪器——传入权重工厂自动构建 ReID 后端 tracker create_tracker( botsort, reid_weightsosnet_x0_25_msmt17.pt, devicecpu, halfFalse, )关键参数语义均以 docstring 与源码为准tracker_type注册表字符串名未知名称抛ValueError并列出可用项tracker_config自定义 YAML 配置路径或内置预设名reid_weights/reid_model构建 ReID 后端的权重路径或直接传入预构建后端reid_model优先便于多个跟踪器共享同一个 ReID 后端device/half/reid_preprocess仅在从reid_weights构建后端时生效per_class是否按类别维护独立跟踪状态注意native (C) 后端当前不支持per_classTrue会抛NotImplementedErrorevolve_param_dict以普通 dict 直接覆盖参数跳过 YAMLtracker_kwargs在默认 YAML 解析后追加的构造覆盖tracker_backendpython默认或cpp委托给注册的 C 后端按需编译见 boxmot/native/registry.pyprecomputed_reid由调用方提供外观嵌入时保持外观匹配激活而不从权重现场构建 ReID 后端。对于需要 ReID 的跟踪器若既没有reid_model也没有可用权重工厂会把with_reid置为False静默降级为纯运动模式见 boxmot/trackers/registry.py。5.2 get_tracker_config解析配置路径get_tracker_config(tracker_type)返回跟踪器配置文件的路径boxmot/trackers/registry.pyfrom boxmot.trackers.registry import get_tracker_config path get_tracker_config(occluboost) # - boxmot/configs/trackers/occluboost.yaml配置解析逻辑位于 boxmot/trackers/config.pyget_tracker_config_path指向boxmot/configs/trackers/{name}.yamlget_tracker_preset_path指向boxmot/configs/trackers/presets/{name}.yamlload_tracker_config按确定性覆盖优先级解析先加载内置默认值再叠加tracker_config可以是部分标量 YAML 或内置预设最后从左到右应用额外的 mapping 覆盖内置预设必须声明tracker: name元数据且与目标跟踪器匹配否则抛ValueError自定义配置若位于内置配置目录且文件名与目标跟踪器不符也会被拒绝。以内置的 boxmot/configs/trackers/bytetrack.yaml 为例其运行时默认值包括min_conf: 0.1、track_thresh: 0.6、track_buffer: 30、match_thresh: 0.9、frame_rate: 30。每个条目还携带调参元数据type、range、options运行时会话只提取default值搜索元数据的解释权归boxmot.engine.tuning。5.3 高级覆盖技巧原文档补充了两种非默认配置方式from boxmot.trackers.registry import create_tracker # 方式一指定自定义 YAML tracker create_tracker(ocsort, tracker_configmy_ocsort.yaml) # 方式二纯 dict 覆盖跳过 YAML 解析 tracker create_tracker( ocsort, evolve_param_dict{det_thresh: 0.3, iou_threshold: 0.2, max_age: 50}, )6. TrackResults结构化的跟踪输出数组boxmot.trackers.results.TrackResults源码见 boxmot/trackers/results.py是np.ndarray的零拷贝子类视图覆盖跟踪器输出的(N, 8)或(N, 9)数组提供命名属性访问与导出方法。6.1 列契约AABB 列 (8): x1, y1, x2, y2, id, conf, cls, det_ind OBB 列 (9): cx, cy, w, h, angle, id, conf, cls, det_ind其中det_ind是检测索引将跟踪行映射回输入检测未匹配的沿海/coasting 轨迹为-1。构造时会做严格校验AABB 必须满足x2 x1且y2 y1OBB 必须有正宽高ID、类别、检测索引列必须是整数所有值必须有限见 boxmot/trackers/results.py。6.2 命名属性访问tracks tracker.update(dets, imageimg, embeddingsembeddings) tracks.id # (M,) 整数轨迹 ID tracks.xyxy # (M, 4) AABBOBB 模式下为外接框经 xywha_to_xyxy 计算 tracks.xywh # (M, 4) 中心点格式 tracks.xywha # (M, 5) OBB 模式原生几何 tracks.boxes # 原生几何OBB 返回 xywhaAABB 返回 xyxy tracks.conf # (M,) 置信度 tracks.cls # (M,) 类别 ID tracks.det_ind # (M,) 检测索引-1 表示该帧无匹配检测coasting tracks.is_obb # 是否旋转框模式6.3 导出与序列化TrackResults内置完整的导出工具见 boxmot/trackers/results.pytracks.summary() # - [{id:..., conf:..., cls:..., box:{...}}, ...] tracks.to_json(indent2) # - JSON 字符串 tracks.to_csv(frame_id1) # - CSV 字符串可选前置帧号列 tracks.save_csv(tracks.csv, frame_id1) # 追加写 CSV自动写表头 tracks.save_mot(result.txt, frame_id1) # 追加写 MOT / 角点式 MMOT 格式save_mot针对 OBB 模式使用角点式 MMOT 格式xywha_to_corners转 8 个角点坐标AABB 模式输出标准的frame,id,ltwh,conf,cls1,det_ind行注意 AABB 模式下类别列写入的是cls 1MOT 格式惯例从 1 计数。此外TrackResults通过__array_ufunc__/__array_function__保证凡改变行契约的 NumPy 运算reshape、transpose、take 等返回普通 ndarray而完整行切片含__getitem__保留类型并同步对齐掩码masks。7. 端到端Composable runtime 实战原文档给出了低层组合的完整示例下面结合源码补充注释与两种几何模式的完整实现7.1 AABB 模式组合import cv2 from boxmot import Detector, ReIDModel from boxmot.trackers import OccluBoost image cv2.imread(image.jpg) # 1) 检测器模型名自动路由后端 detector Detector(yolov8n.pt, devicecpu) # 2) ReIDReIDModel 是高层包装底层即 ReID runtime reid ReIDModel(osnet_x0_25_msmt17.pt, devicecpu) # 3) 跟踪器直接实例化类注入 ReID tracker OccluBoost(reid_modelreid, with_reidTrue) # 4) 逐阶段编排 detections detector.predict(image) # Detections embeddings reid.embed(image, boxesdetections.boxes) # xyxy for AABB tracks tracker.update(detections, imageimage, embeddingsembeddings) # 5) 结构化读取 print(tracks.id) # (M,) 轨迹 ID print(tracks.xyxy) # (M, 4) 轴向对齐框 print(tracks.conf) # (M,) 置信度7.2 OBB 模式的关键差异# 当检测器为旋转框模型如 yolo11l-mmot-obb时 detections detector.predict(image) # dets 为 (N, 7) assert detections.is_obb # True # 裁剪 ReID 输入必须用朝向感知几何不能用外接框 embeddings reid.embed(image, boxesdetections.boxes) # xywha for OBB tracks tracker.update(detections, imageimage, embeddingsembeddings) print(tracks.xywha) # (M, 5) [cx, cy, w, h, angle] print(tracks.xyxy) # (M, 4) 外接 AABB要点detections.xyxy在 OBB 模式下恒为外接 AABB因此提取 ReID 裁剪块时应使用detections.boxes返回原生xywha避免外接框引入过多背景。7.3 直接实例化跟踪器类跳过工厂、直接构造类以获得完全控制原文档示例import numpy as np from boxmot.trackers.bbox.bytetrack import ByteTrack tracker ByteTrack( track_high_thresh0.6, track_low_thresh0.1, track_buffer30, ) # dets: (N, 6)列序 [x1, y1, x2, y2, conf, cls] # img: 当前帧 numpy 数组 (H, W, 3) tracks tracker.update(dets, img)ReID 感知跟踪器的直接构造方式from boxmot import ReIDModel from boxmot.trackers import OccluBoost reid ReIDModel(osnet_x0_25_msmt17.pt, devicecpu, halfFalse) tracker OccluBoost(reid_modelreid, with_reidTrue) embeddings reid.embed(img, boxesdets[:, :4]) tracks tracker.update(dets, imageimg, embeddingsembeddings)7.4 包级导出说明boxmot/trackers/init.py 通过懒加载导出OccluBoostfrom boxmot.trackers import OccluBoost其余具体跟踪器类从boxmot.trackers.bbox.name直接导入。注册表层面还提供get_tracker_class、get_tracker_definition、TRACKER_MAPPING等工具方便需要编程式遍历所有跟踪器的场景。8. 与高层 API 的对比与选择维度High-levelBoxMOTLow-level本文构件样板代码最少一行配置 一行调用需手动编排 3 个构件每帧控制通过frame_result流式访问完全自主可插入任意逻辑模型共享每次调用独立可跨跟踪器复用同一 ReID 后端结果格式TrackRunResult/FrameResultDetections/TrackResults原生数组适用场景快速跑通、CLI 等价研究、服务集成、自定义后处理原文档明确提醒当你需要在有限文件/目录源上进行惰性迭代时由于 facade 会在返回前消费完有限源应显式组合组件并使用boxmot.api.functional.track(...)见 docs/python/high-level.md 的 warning。这正是 low-level API 的重要价值场景之一。9. 总结BoxMOT 的 low-level Python API 将多目标跟踪流水线拆解为三个可独立实例化、可自由组合的构件DetectorDetections负责检测与规范化输出Detections用 6/7 列统一 AABB 与 OBB 契约OBB 模式下xyxy为外接框、boxes/xywha为原生旋转几何ReID统一重识别运行时按权重扩展名路由后端输出 L2 归一化嵌入支持整图框或裁剪块两种输入方式create_tracker/get_tracker_configTrackResults注册表驱动跟踪器构建配置经确定性优先级叠加输出为带命名属性的np.ndarray子类内置summary/to_json/to_csv/save_mot等导出方法。掌握这六个构件你就能在保持 BoxMOT 全部能力含 OBB、ReID、native C 后端、per-class 跟踪的前提下构建完全由自己编排的底层跟踪应用。相关源码入口见 boxmot/detectors/detector.py、boxmot/detectors/base.py、boxmot/reid/core/runtime.py、boxmot/trackers/registry.py、boxmot/trackers/config.py 与 boxmot/trackers/results.py。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考