
Ultralytics YOLO26 目标间距离测量DistanceCalculation 解决方案的原理、参数与完整实现【免费下载链接】ultralyticsUltralytics YOLO26, YOLO11, YOLOv8 — object detection, instance segmentation, semantic segmentation, image classification, pose estimation, object tracking项目地址: https://gitcode.com/GitHub_Trending/ul/ultralytics本文围绕 Ultralytics YOLO26 的DistanceCalculation解决方案展开介绍如何用像素级欧氏距离实时测量画面中任意两个被跟踪对象之间的距离覆盖完整的可运行 Python 示例、全部初始化参数模型、跟踪、可视化三类、鼠标交互规则并结合仓库源码逐层剖析选框—取质心—算距离—绘制的完整调用链帮助你在监控、安防、运动分析等场景中快速落地对象间距监控能力。什么是距离计算距离计算Distance Calculation是测量图像或视频帧中两个被检测对象之间空间间隔的过程。在 Ultralytics YOLO26 中该功能采用检测框的**质心centroid**作为测量基准你用鼠标点选两个目标框后系统会计算这两个质心之间的欧氏距离单位为像素并以连线加文字标注的形式直接绘制在画面上。DistanceCalculation会跨帧跟踪目标并对用户鼠标选中的任意两个边界框质心之间的像素距离进行度量。运行示例后左键单击两个对象即可画出连接线并读出距离右键单击可清除选择。距离计算的价值距离测量能力为纯 2D 视觉系统补上了空间关系这一维度主要价值包括定位精度Localization Precision提升计算机视觉任务中对象的空间定位精度尺寸估算Size Estimation借助像素距离结合标尺关系可估算物体大小增强上下文理解场景理解Scene Understanding改善三维场景认知辅助自动驾驶、监控等系统做决策碰撞规避Collision Avoidance通过持续监控移动物体间的距离预警潜在碰撞空间分析Spatial Analysis分析监控环境中对象之间的关系与交互模式。交互提示来自官方文档的操作约定用鼠标左键依次点击两个边界框即可计算它们之间的距离使用鼠标右键可删除所有已绘制的点清空选择在帧内的任意位置左键点击可添加新点最多选择 2 个目标。注意距离是一个估计值基于 2D 数据计算而缺乏深度信息因此无法保证与真实世界的绝对距离一致。若需换算为米等真实单位可参考 Solutions 配置中的meter_per_pixel参数默认0.05见 SolutionConfig 中用于将像素距离换算为真实世界单位的比例因子的定义该参数被仓库中的速度估算等解决方案用于像素到实物的换算。使用 YOLO26 计算距离完整可运行示例官方文档给出的端到端示例如下打开视频文件初始化DistanceCalculation逐帧调用即可得到带标注的plot_im并写入输出视频import cv2 from ultralytics import solutions cap cv2.VideoCapture(path/to/video.mp4) assert cap.isOpened(), Error reading video file # Video writer 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 cv2.VideoWriter(distance_output.avi, cv2.VideoWriter_fourcc(*mp4v), fps, (w, h)) # Initialize distance calculation object distancecalculator solutions.DistanceCalculation( modelyolo26n.pt, # path to the YOLO26 model file. showTrue, # display the output ) # Process video while cap.isOpened(): success, im0 cap.read() if not success: print(Video frame is empty or processing is complete.) break results distancecalculator(im0) print(results) # access the output video_writer.write(results.plot_im) # write the processed frame. cap.release() video_writer.release() cv2.destroyAllWindows() # destroy all opened windows要点说明solutions.DistanceCalculation(...)的实例可像函数一样直接调用distancecalculator(im0)——BaseSolution.__call__会对process计时并在verboseTrue时逐帧打印输入分辨率、各类别计数与跟踪/解决方案耗时见 BaseSolution.call返回值是SolutionResults对象除plot_im带标注的帧外还携带pixels_distance当前帧两选中目标质心间的像素距离与total_tracks当前跟踪目标总数这些字段在 SolutionResults 中有明确定义showTrue时会在名为Ultralytics Solutions的 OpenCV 窗口中显示画面按q键关闭窗口退出显示见 display_output。DistanceCalculation()参数DistanceCalculation接受的解决方案通用参数摘自文档参数表参数类型默认值说明modelstrNoneUltralytics YOLO 模型文件路径。line_widthint2解决方案绘制框、关键点与计数时使用的线宽。verboseboolTrue启用解决方案逐帧日志输入形状、类别计数与处理速度跟踪调用本身始终静默。此外还可以使用各类track相关参数参数类型默认值说明trackerstrbotsort.yaml指定使用的跟踪算法。内置选项botsort.yaml、bytetrack.yaml、ocsort.yaml、deepocsort.yaml、fasttrack.yaml、tracktrack.yaml配置位于 ultralytics/cfg/trackers/。conffloat0.25检测置信度阈值值越低纳入跟踪的对象越多但可能引入误检。ioufloat0.7用于过滤重叠检测的 IoU 阈值。classeslistNone按类别索引过滤结果。例如classes[0, 2, 3]仅跟踪指定类别。devicestrNone指定推理设备如cpu、cuda:0或0可在 CPU、指定 GPU 或其他计算设备之间切换。以及以下可视化参数参数类型默认值说明showboolFalse为True时在窗口中显示标注后的图像或视频便于开发调试时的即时视觉反馈。show_confboolTrue在视觉输出中于标签旁显示每个检测的置信度分数。show_labelsboolTrue在视觉输出中为每个检测显示类别标签。从 SolutionConfig 源码看这些参数都是SolutionConfigdataclass 的字段conf默认0.25、iou默认0.7、tracker默认botsort.yaml等BaseSolution.__init__会用SolutionConfig().update(**kwargs)解析入参并对未在配置中定义的键直接抛出ValueErrorconfig.py 第 104-116 行。另外若model为None会回退使用默认模型yolo26n.ptsolutions.py 第 109-111 行且所有 Solutions 默认启用botsort.yaml跟踪器——这与 FAQ 中tracker 默认botsort.yaml的说明一致。BaseSolution还会把iou、conf、device、max_det、quantize、tracker、imgsz收集为track_add_args在每帧调用model.track(persistTrue, ...)时透传给跟踪器solutions.py 第 118-120 行因此DistanceCalculation天然支持imgsz...、max_det...等附加推理参数。实现细节剖析从鼠标点击到像素距离DistanceCalculation的工作流程是跨视频帧跟踪对象计算所选两个边界框质心之间的欧氏距离。当你点击两个对象时解决方案提取所选边界框的质心中心点以像素为单位计算这两个质心之间的欧氏距离用一条连接线把两个对象连起来并把距离值显示在帧上。下面结合 distance_calculation.py 源码逐环节说明。状态管理与鼠标交互mouse_event_for_distance类在__init__中初始化三个状态left_mouse_count左键计数、selected_boxes以 track ID 为键的选中框字典、centroids选中框质心列表第 40-42 行。鼠标回调mouse_event_for_distance的规则第 44-68 行左键按下cv2.EVENT_LBUTTONDOWNleft_mouse_count自增只有当前计数 ≤ 2 时才生效——遍历当前帧的self.boxes与self.track_ids若点击坐标落在某个框内且该track_id尚未被选中则把该框存入selected_boxes。因此一次交互最多选择 2 个目标右键按下cv2.EVENT_RBUTTONDOWN清空selected_boxes并重置left_mouse_count即删除所有已绘制的点。这个回调在showTrue且环境支持显示时每帧末尾都会通过cv2.setMouseCallback(Ultralytics Solutions, ...)重新挂到显示窗口上第 123-124 行。测试用例印证了该交互逻辑左键点选选中框test_left_click_selection、右键重置清空选择test_right_click_reset并且选框命中判定对 OBB 模型的(4, 2)旋转框角点同样有效test_left_click_selection_obb——因为命中判定用的是get_enclosing_box归一化出的轴对齐外框。逐帧处理processprocess(im0)是每帧的入口核心步骤第 70-127 行提取跟踪结果self.extract_tracks(im0)调用底层BaseSolution.extract_tracks内部执行model.track(sourceim0, persistTrue, classesself.classes, verboseFalse, **self.track_add_args)persistTrue保证跟踪器跨帧维持状态随后把boxes、clss、track_ids、confs更新为当前帧值solutions.py 第 157-183 行。绘制所有检测框用SolutionAnnotator对每个框调用box_label标签内容由adjust_box_label按show_labels/show_conf生成格式为track_id 类别名 置信度solutions.py 第 139-155 行。跟随目标更新选中框已选中的track_id若仍在当前帧中就用新框覆盖selected_boxes里的旧框——这样连线端点会跟随移动的目标实时更新而不是停留在点击瞬间的位置。计算质心与距离当选中框恰好为 2 个时对每个框用get_enclosing_box归一化后取中心[int((box[0] box[2]) // 2), int((box[1] box[3]) // 2)]再按欧氏距离公式sqrt(dx² dy²)得到pixels_distance第 106-117 行。绘制连线与数值调用SolutionAnnotator.plot_distance_and_line它在画面左上角绘制一个深色背景框并写上Pixels Distance: {distance:.2f}再用 3 像素宽连线连接两个质心、以紫色实心圆半径 6标记端点solutions.py 第 598-635 行。返回结果SolutionResults(plot_im..., pixels_distance..., total_tracks...)注意self.centroids每帧结束会被清空保证下一帧从干净状态重新计算。单元测试 test_distance_calculation_process_method 验证了完整链路给定两个选中框[100,100,200,200]与[300,300,400,400]process返回的SolutionResults中total_tracks 2且pixels_distance 0按几何关系该值约为 282.84 像素。一个值得注意的设计细节get_enclosing_box是静态方法可把 OBB 的(4, 2)角点框归一化为轴对齐[x1, y1, x2, y2]普通检测框则原样透传solutions.py 第 210-229 行——从源码结构看这使得距离计算同样兼容旋转框模型。参数与类导出DistanceCalculation通过 ultralytics/solutions/init.py 导出因此文档示例中的from ultralytics import solutions写法可用所有参数默认值集中定义在 SolutionConfig 中调整时只需以关键字参数覆盖即可例如solutions.DistanceCalculation(modelyolo26s.pt, trackerbytetrack.yaml, conf0.4, showTrue)。应用场景距离计算在以下领域有实际落地空间零售分析测量顾客与商品的接近程度评估门店布局效果工业安全监控人员与机械之间保持安全距离交通管理分析车距、识别尾随驾驶行为运动分析计算球员、球与场上关键位置之间的距离医疗健康候诊区保持间距、监控患者活动机器人让机器人与障碍物、人之间保持适当距离。FAQ如何用 Ultralytics YOLO26 计算对象间距离需要拿到检测框的质心作为测量基准初始化solutions模块中的DistanceCalculation类借助模型的跟踪输出跨帧维持目标身份然后计算质心间距离。完整流程见上文使用 YOLO26 计算距离章节。距离计算有哪些优势定位精度准确的空间定位、尺寸估算帮助估算物理尺寸、场景理解增强自动驾驶与监控等应用的三维场景理解、实时处理随帧在线计算适合直播流分析、集成能力可与目标跟踪、速度估算等 YOLO26 解决方案无缝组合。能否在实时视频流中做距离计算可以。流程为用 OpenCV 抓取视频帧文件、摄像头或 RTSP 流均可、运行 YOLO26 检测、用DistanceCalculation在连续帧间计算所选对象距离。上面的 Python 示例即实时逐帧处理实现。如何删除距离计算中已绘制的点直接使用鼠标右键单击即可清空所有已选点。源码层面这会触发selected_boxes {}并重置左键计数distance_calculation.py 第 66-68 行。初始化 DistanceCalculation 的关键参数有哪些modelYOLO26 模型文件路径不传时默认yolo26n.pttracker跟踪算法Solutions 默认botsort.yamlconf检测置信度阈值默认0.25show是否显示输出窗口默认False。其余如iou、classes、device、line_width、verbose、show_conf、show_labels的完整列表与默认值见上文参数表。参考文件文件说明docs/en/guides/distance-calculation.md本文主体对应的官方指南文档ultralytics/solutions/distance_calculation.pyDistanceCalculation核心实现鼠标事件 距离计算ultralytics/solutions/solutions.pyBaseSolution模型加载/跟踪、SolutionAnnotator连线绘制、SolutionResults结果封装ultralytics/solutions/config.pySolutionConfig全部参数默认值与非法参数校验tests/test_solutions.py选框、右键重置、process距离计算的单元测试ultralytics/cfg/trackers/botsort.yaml默认跟踪器配置【免费下载链接】ultralyticsUltralytics YOLO26, YOLO11, YOLOv8 — object detection, instance segmentation, semantic segmentation, image classification, pose estimation, object tracking项目地址: https://gitcode.com/GitHub_Trending/ul/ultralytics创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考