企业官网建设流程全解析

YOLOv10 实时目标距离计算实战：基于边界框质心与像素-米换算的完整指南

【免费下载链接】yolov10YOLOv10: Real-Time End-to-End Object Detection [NeurIPS 2024]项目地址: https://gitcode.com/GitHub_Trending/yo/yolov10

距离计算是计算机视觉空间分析中的常见需求。本文基于当前 YOLOv10 仓库（NeurIPS 2024）中提供的解决方案模块，系统讲解如何利用检测与跟踪结果、以边界框质心为基准，在实时视频流中测量两个目标之间的物理距离，并完整覆盖交互方式、全部参数含义与底层实现原理。读完本文，你将能够直接复现一套可运行的目标间距测量方案，并根据场景标定像素与米的换算比例。

什么是目标距离计算？

在指定空间内测量两个对象之间的间距，即被称为距离计算。在 Ultralytics YOLO 系列项目中，这一功能通过用户选中两个边界框（bounding box），计算两者质心（centroid）之间的像素距离，再结合"每米像素数"标定值换算为物理距离（米与毫米）来实现。

当前仓库在 ultralytics/solutions/distance_calculation.py 中提供了DistanceCalculation类，它不关心检测模型的内部结构，只消费model.track()产出的跟踪结果，因此可以与仓库支持的 YOLOv10 等检测模型无缝配合。

距离计算的核心价值

根据原文档 distance-calculation.md 的总结，在目标检测流程中引入距离计算主要有三方面收益：

• 定位精度（Localization Precision）：提升计算机视觉任务中的空间定位准确度，为后续决策提供更可靠的坐标依据。
• 尺寸估计（Size Estimation）：结合已知比例可进一步估计目标的物理尺寸，增强对场景的上下文理解。
• 场景理解（Scene Understanding）：为环境建立三维化的空间感知，帮助系统做出更合理的判断。

典型落地场景包括：车辆跟车距离监测、安防系统中的人员间距告警、物流分拣中的物体间距校验等。

快速上手：视频流距离计算完整示例

以下示例来自原文档，并保留了全部关键步骤：读取视频 → 逐帧推理跟踪 → 交由DistanceCalculation计算并绘制距离 → 写出结果视频。

from ultralytics import YOLO from ultralytics.solutions import distance_calculation import cv2 model = YOLO("yolov8n.pt") names = model.model.names cap = cv2.VideoCapture("path/to/video/file.mp4") assert cap.isOpened(), "Error reading video file" w, h, fps = (int(cap.get(x)) for x in (cv2.CAP_PROP_FRAME_WIDTH, cv2.CAP_PROP_FRAME_HEIGHT, cv2.CAP_PROP_FPS)) # Video writer video_writer = cv2.VideoWriter("distance_calculation.avi", cv2.VideoWriter_fourcc(*'mp4v'), fps, (w, h)) # Init distance-calculation obj dist_obj = distance_calculation.DistanceCalculation() dist_obj.set_args(names=names, view_img=True) while cap.isOpened(): success, im0 = cap.read() if not success: print("Video frame is empty or video processing has been successfully completed.") break tracks = model.track(im0, persist=True, show=False) im0 = dist_obj.start_process(im0, tracks) video_writer.write(im0) cap.release() video_writer.release() cv2.destroyAllWindows()

代码中的关键环节说明：

1. model.track()是距离计算的输入源：在 model.py 中，track()方法会为模型注册跟踪器（默认botsort.yaml，见 ultralytics/cfg/trackers/botsort.yaml），并强制persist=True时跨帧保持跟踪 ID 连续。值得注意的是，引擎层会为基于 ByteTrack 的跟踪方法自动将置信度兜底为0.1（见 model.py），因为低置信度预测输入是此类跟踪器的必要前提。
2. start_process(im0, tracks)是计算入口：它接收原始帧与跟踪结果，内部完成质心提取、距离换算与可视化绘制，并返回标注后的帧。
3. 当前仓库也支持 YOLOv10 权重：仓库在 ultralytics/cfg/models/v10/ 下提供了yolov10n.yaml至yolov10x.yaml全套模型配置，将示例中的权重替换为对应 YOLOv10 权重即可复用同一套距离计算流程（无需改动其余代码）。

交互方式：鼠标左键选择、右键一键清空

DistanceCalculation会在运行时弹出名为Ultralytics Distance Estimation的窗口（前提是环境支持imshow），交互规则如下：

• 鼠标左键点击：选中一个边界框。累计选中两个框后，立即计算并绘制二者质心连线与距离。
• 鼠标右键点击：清空所有已选中的框与已绘制的点，方便重新选择。

这套交互逻辑实现在 distance_calculation.py 的mouse_event_for_distance中：左键事件会遍历当前帧所有xyxy格式的边界框，仅当点击坐标落在框内（box[0] < x < box[2] and box[1] < y < box[3]）且该跟踪 ID 尚未被选中时才记录该框；右键事件则重置selected_boxes与点击计数。

参数详解

set_args配置参数

set_args负责配置距离计算与画面显示参数。基于 distance_calculation.py 的源码实现，完整参数如下：

提示：pixels_per_meter直接决定换算结果的准确性，建议在部署场景中先放置已知物理尺寸的参照物进行标定（详见下文"调优建议"）。

model.track跟踪参数

跟踪结果的质量直接决定距离计算的稳定性。原文档给出了track()的核心参数表：

需要补充的底层细节：即使在文档层面conf的默认展示为0.3，一旦走track()入口，model.py 会将其兜底为0.1以适配 ByteTrack 类跟踪器，因此距离计算示例中无需显式传入conf。跟踪器配置文件可在 ultralytics/cfg/trackers/ 目录下查看与修改。

源码级原理剖析

1. 质心（Centroid）计算

在 distance_calculation.py 中，质心取边界框对角坐标的中点：

return int((box[0] + box[2]) // 2), int((box[1] + box[3]) // 2)

即((x_min + x_max) / 2, (y_min + y_max) / 2)。质心代表目标的几何中心，相比框角点，它对目标尺度变化更稳健，因此被选作距离测量的基准点。

2. 像素距离 → 物理距离换算

calculate_distance 先用欧氏距离公式计算两个质心间的像素距离：

pixel_distance = math.sqrt((centroid1[0] - centroid2[0]) ** 2 + (centroid1[1] - centroid2[1]) ** 2) return pixel_distance / self.pixel_per_meter, (pixel_distance / self.pixel_per_meter) * 1000

返回值分别为米和毫米两种单位的距离。换算核心即"像素距离 ÷ 每米像素数"，可见pixels_per_meter是唯一决定量纲正确性的标定参数。

3. 可视化绘制

距离线与距离文本的绘制由 plotting.py 中的plot_distance_and_line完成，具体行为包括：

• 在画面左上角绘制白色信息底板，标注Distance M: x.xxm与Distance MM: x.xxmm两行文本；
• 用line_color以 3 像素线宽连接两个质心；
• 用centroid_color以半径为 6 的实心圆分别标记两个质心。

4. 关键边界条件

在 start_process 中有两处值得注意的防御性处理：

• 无跟踪 ID 时跳过：若tracks[0].boxes.id is None（例如首帧跟踪器尚未产出 ID），直接显示/返回画面而不计算距离，避免空引用崩溃；
• 选中框随帧更新：当已选中两个框后，每一帧都会用该跟踪 ID 的最新边界框更新选中数据，确保质心位置随时间移动而实时刷新，距离数值也随之动态变化。

调优建议与使用限制

1. 标定pixels_per_meter是精度的关键：该值本质是"图像平面上每米占多少个像素"，会随相机高度、焦距、视角变化。建议在部署场景中放置已知长度的参照物，实测其在画面中的像素跨度后换算得到准确标定值。
2. 保持persist=True：距离计算依赖稳定的跟踪 ID 才能在帧间持续更新同一个目标的框位置，关闭持久化会导致选中目标 ID 变化、距离无法连续计算。
3. 单目图像的固有局限：该方案基于图像平面上的欧氏距离，未考虑透视畸变与深度信息，属于近似测量。若目标在画面中的深度差异大，测量误差会随之增大；对精度要求苛刻的场景，应结合深度相机或透视矫正。
4. 显示环境依赖：view_img=True时程序会弹出窗口并注册鼠标回调，需要运行环境支持 GUI（源码中通过check_imshow预检）；纯服务器环境下建议关闭该选项。

延伸阅读

• 解决方案模块源码：ultralytics/solutions/distance_calculation.py
• 绘制方法实现：ultralytics/utils/plotting.py
• 跟踪入口方法：ultralytics/engine/model.py
• 跟踪器配置：ultralytics/cfg/trackers/botsort.yaml、ultralytics/cfg/trackers/bytetrack.yaml
• YOLOv10 模型配置：ultralytics/cfg/models/v10/yolov10n.yaml
• API 参考文档：docs/en/reference/solutions/distance_calculation.md

【免费下载链接】yolov10YOLOv10: Real-Time End-to-End Object Detection [NeurIPS 2024]项目地址: https://gitcode.com/GitHub_Trending/yo/yolov10