使用 Ultralytics YOLO26 进行距离计算
什么是距离计算?#
距离计算是测量图像或视频帧中两个检测对象之间间距的过程。使用 Ultralytics YOLO26 时,该解决方案会测量用户选定的两个边界框质心之间的距离。
观看: 如何使用 Ultralytics YOLO 以像素为单位估算检测目标之间的距离 🚀
可视化效果#
| 使用 Ultralytics YOLO26 进行距离计算 |
|---|
![]() |
距离计算的优势#
- 定位精度:提升计算机视觉任务中的空间定位准确性。
- 尺寸估算: 估算目标尺寸,帮助更好地理解上下文。
- 场景理解: 提升对 3D 场景的理解能力,从而改善自动驾驶车辆和监控系统等应用中的决策效果。
- 碰撞规避: 通过监测运动目标之间的距离,帮助系统检测潜在碰撞。
- 空间分析: 便于分析受监控环境中目标之间的关系和交互。
距离计算
- 按住鼠标左键,点击任意两个边界框即可计算距离。
- 使用鼠标右键删除所有绘制的点。
距离为估算值
距离只是估算值,可能不完全准确,因为它是使用缺少深度信息的 2D 数据计算得出的。要获取逐像素深度,请使用深度估计模型。
使用 YOLO26 计算距离#
DistanceCalculation 解决方案会跨帧跟踪目标,并以像素为单位,测量你用鼠标选定的任意两个边界框质心之间的欧氏距离。运行下面的示例,然后用鼠标左键单击两个目标,绘制连接线并读取距离;用鼠标右键清除选择。
import cv2
from ultralytics import solutions
cap = cv2.VideoCapture("path/to/video.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 = cv2.VideoWriter("distance_output.avi", cv2.VideoWriter_fourcc(*"mp4v"), fps, (w, h))
# 初始化距离计算对象
distancecalculator = solutions.DistanceCalculation(
model="yolo26n.pt", # YOLO26 模型文件的路径。
show=True, # 显示输出
)
# 处理视频
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) # 访问输出
video_writer.write(results.plot_im) # 写入处理后的帧。
cap.release()
video_writer.release()
cv2.destroyAllWindows() # 关闭所有已打开的窗口DistanceCalculation() 参数#
下面是 DistanceCalculation 参数表:
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
model | str | None | Ultralytics YOLO 模型文件的路径。 |
line_width | int | 2 | 解决方案绘制的框、关键点和计数的线条粗细。 |
verbose | bool | True | 启用逐帧日志,记录输入形状、类别计数和处理速度。跟踪调用本身始终不会输出日志。 |
你也可以在 DistanceCalculation 解决方案中使用 track 参数。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
tracker | str | 'tracktrack.yaml' | 指定要使用的跟踪算法。内置选项:botsort.yaml、bytetrack.yaml、ocsort.yaml、deepocsort.yaml、fasttrack.yaml、tracktrack.yaml。 |
conf | float | 0.25 | 设置检测的置信度阈值;较低的值允许跟踪更多物体,但可能会包含误检。 |
iou | float | 0.5 | 设置用于筛除重叠检测结果的交并比 (IoU) 阈值。 |
classes | list | None | 按类别索引筛选结果。例如,classes=[0, 2, 3] 只跟踪指定类别。 |
device | str | None | 指定推理设备(例如 cpu、cuda:0 或 0)。用户可以选择 CPU、特定 GPU 或其他计算设备来运行模型。 |
imgsz | int or tuple | 640 | 目标推理图像尺寸:正方形图像使用整数,或使用 (height, width) 对。图像尺寸会调整为模型步幅的整数倍。 |
max_det | int | 300 | 跟踪前每帧保留的最大检测数量,用于限制解决方案在密集场景中处理的物体数量。 |
quantize | int or str | None | 推理精度:对于非 CPU 上运行的 PyTorch 和 TorchScript 模型,使用 16 (FP16) 或 32/unset (FP32) 进行选择;其他格式使用其模型文件和运行时所选的精度。此参数替代已弃用的 half 参数。 |
此外,还可以使用以下可视化参数:
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
show | bool | False | 如果 True,则在窗口中显示带标注的图像或视频。适用于在开发或测试期间即时查看结果。 |
show_conf | bool | True | 在每个检测结果的标签旁显示置信度分数,帮助了解模型对该检测结果的确信程度。 |
show_labels | bool | True | 在可视化输出中显示每个检测结果的标签,便于立即了解检测到的对象。 |
实现细节#
DistanceCalculation 类通过跨视频帧跟踪目标,并计算所选边界框质心之间的欧氏距离来实现功能。当你点击两个目标时,该解决方案会:
- 提取所选边界框的质心(中心点)
- 计算这些质心之间以像素为单位的欧氏距离
- 在帧中显示距离,并用连接线标出两个目标
该实现使用 mouse_event_for_distance 方法处理鼠标交互,让用户可以根据需要选择目标和清除选择。process 方法负责逐帧处理、跟踪目标并计算距离。
应用场景#
使用 YOLO26 计算距离有许多实际应用:
- 零售分析: 测量顾客与商品之间的距离,并分析店铺布局效果
- 工业安全: 监控工人与机器之间的安全距离
- 交通管理: 分析车辆间距并检测跟车过近的情况
- 体育分析: 计算球员、球和场地关键位置之间的距离
- 医疗保健: 确保候诊区内保持适当距离,并监测患者的移动
- 机器人: 让机器人与障碍物和人员保持适当距离
常见问题#
要使用 Ultralytics YOLO26 计算目标之间的距离,你需要确定检测目标的边界框质心。此过程包括从 Ultralytics 的
solutions模块初始化DistanceCalculation类,并使用模型的跟踪输出计算距离。要删除使用 Ultralytics YOLO26 进行距离计算时绘制的点,可以单击鼠标右键。此操作会清除你绘制的所有点。有关详情,请参阅距离计算示例下方的备注部分。
在 Ultralytics YOLO26 中初始化
DistanceCalculation类时,关键参数包括:model:YOLO26 模型文件的路径。tracker:要使用的跟踪算法(解决方案默认使用tracktrack.yaml)。conf:检测置信度阈值。show:用于显示输出的标志。
完整列表和默认值请参阅 DistanceCalculation 的参数。
评论195
提出问题、分享结果,或帮助其他人。
muhammadwildangoni
hallo, I am processing a men's 100 meter sprint video using YOLO and SpeedEstimator (Ultralytics) to detect runners, estimate their speed, and track their progress. However, the output statistics are incorrect. My code detects 16 runners, while there should only be 8 (those on the track), and the maximum speed reported is 0.00 m/s, which is clearly not correct for a sprint race. The furthest distance covered is about 96.7 meters, which seems off.
import cv2 import math import numpy as np from ultralytics import YOLO from ultralytics.solutions import speed_estimation
--- SETTINGS ---
video_path = "WHAT A RACE! _ Men s 100m Final! _ #Paris2024 highlights (online-video-cutter.com).mp4" # Change to your video path model_path = "yolo11n.pt" # Path to your YOLO model (could be yolov11n.pt if available) output_path = "output_sprint.avi" # Output video file name
meter_per_pixel = 0.05 # Calibration result for track (e.g., 0.05 for a 100m lane) center_point = (0, 720) # Track start point (adjust to your video height)
--- INITIALIZATION ---
cap = cv2.VideoCapture(video_path) 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)) out = cv2.VideoWriter(output_path, cv2.VideoWriter_fourcc(*"MJPG"), fps, (w, h))
model = YOLO(model_path) names = model.model.names if hasattr(model.model, "names") else ["person"]
speed_obj = speed_estimation.SpeedEstimator( names=names, reg_pts=[(0, int(h/2)), (w, int(h/2))], # Speed estimation line (across track, adjust as needed) view_img=False, meter_per_pixel=meter_per_pixel # Convert pixel to meters )
frame_count = 0 speed_over_time, distance_over_time = {}, {}
while cap.isOpened(): success, frame = cap.read() if not success: break frame_count += 1
# Detect and track runners on each frame tracks = model.track(frame, persist=True, show=False) # Estimate runners' speed and update visualization on frame frame = speed_obj.estimate_speed(frame) # Extract runner IDs, position, speed, and distance # Make sure .boxes.id/cls property exists: if tracks and hasattr(tracks[0], "boxes") and tracks[0].boxes.id is not None: boxes = tracks[0].boxes.xyxy.cpu() track_ids = tracks[0].boxes.id.int().cpu().tolist() clss = tracks[0].boxes.cls.cpu().tolist() for box, track_id, cls in zip(boxes, track_ids, clss): if cls == 0: # 'person' class (runners) # Calculate runner's distance from start x1, y1 = int((box[0] + box[2]) // 2), int((box[1] + box[3]) // 2) distance = (math.sqrt((x1 - center_point[0]) ** 2 + (y1 - center_point[1]) ** 2)) * meter_per_pixel # Store statistics in dictionary if track_id not in distance_over_time: distance_over_time[track_id] = [0] * (frame_count - 1) distance_over_time[track_id].append(distance) speed = speed_obj.speeds.get(track_id, 0) if hasattr(speed_obj, "speeds") else 0 if track_id not in speed_over_time: speed_over_time[track_id] = [0] * (frame_count - 1) speed_over_time[track_id].append(speed) # Overlay runner's speed and distance information directly on video frame text_speed = f"Speed: {speed:.2f} m/s" text_dist = f"Distance: {distance:.2f} m" cv2.putText(frame, f"ID:{track_id} {text_speed}, {text_dist}", (x1, y1 - 10), cv2.FONT_HERSHEY_SIMPLEX, 0.8, (0,255,0), 2) # Save frame to output video out.write(frame) # Display real-time video preview cv2.imshow("Sprint Runner Detection Preview", frame) if cv2.waitKey(1) & 0xFF == ord("q"): breakcap.release() out.release() cv2.destroyAllWindows()
--- Final statistics: print results to terminal ---
best_speed = max((max(speeds) for speeds in speed_over_time.values()), default=0) best_distance = max((max(distances) for distances in distance_over_time.values()), default=0) total_runners = len(distance_over_time)
print(f"Total runners detected: {total_runners}") print(f"Highest speed: {best_speed:.2f} m/s") print(f"Furthest distance covered: {best_distance:.2f} meters")
maribalke(已编辑)
Hi! I have tried to do a test on the distance calculation on a single image, but I keep getting the attribute error: 'DistanceCalculation' object has no attribute 'start_process'. I have basis in the YOLO11n-model, further trained on images from a different dataset.
model_path = "../runs/detect/train2/weights/best.pt" model = YOLO(model_path) dist_obj = distance_calculation.DistanceCalculation() frame = cv2.imread("../images/s73/raw_images/10.jpg") # Detect objects results = model(frame) # Run object tracking tracks = model.track(frame, persist=True, show = False) # process the image image_with_distances = dist_obj.start_process(frame, tracks) # Display the frame cv2.imshow('Distance Calculation', image_with_distances) cv2.waitKey(0) cv2.destroyAllWindows()
Glenn JocherUltralytics(已编辑)@maribalke thanks for reaching out!
start_process()has been removed.DistanceCalculationis now called directly on the frame and returns a results object with the annotated image inplot_im. It also runs tracking itself, so no separatemodel.track()call is needed. Here's the minimal fix for your single-image case:dist_obj = solutions.DistanceCalculation(model=model_path, show=False) results = dist_obj(frame) cv2.imshow("Distance Calculation", results.plot_im)Note that the distance is measured between two objects you select by clicking them in a display window, so a single static image only shows a distance once two boxes have been selected. For full implementation details, see our Distance Calculation Guide. Let us know if you encounter any other issues!
dgnovo
Is it possible to know the distance from an object and another object without using mouse?
Glenn JocherUltralytics@dgnovo yes, it's possible. You can calculate distances programmatically by using bounding box centroids from YOLO11 detections and computing the Euclidean distance between them without relying on mouse clicks. Refer to the
DistanceCalculationimplementation to customize the process for your needs: https://docs.ultralytics.com/guides/distance-calculation/.1
Muhammad-237
How can we find the distance of in the bounding box like from one point to another point in the bounding box to measure the size of object
Glenn JocherUltralytics@Muhammad-237 to measure the size of an object within a bounding box using Ultralytics YOLO11, you can calculate the distance between two points (e.g., edges or centroid) within that bounding box. This can be achieved using the
DistanceCalculationclass, which allows you to click on specific points to measure distances. Keep in mind, these calculations are approximations as they rely on 2D data without depth information. For more details, refer to the Distance Calculation Docs.
gg120wolf
Hi, I am using the example code of Distance Calculation using YOLO11 Example, but there is a problem of File "f:\fyp yolo\ultralytics-main\distance test1.py", line 13, in distance = solutions.DistanceCalculation() ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ TypeError: DistanceCalculation.init() missing 1 required positional argument: 'names' So what is this names should i set?
RizwanMunawar
@gg120wolf Hi, the correct way to use the Ultralytics distance calculation module is mentioned below.
import cv2 from ultralytics import solutions 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 distance = solutions.DistanceCalculation(model="yolo11n.pt", show=True) # Process video while cap.isOpened(): success, im0 = cap.read() if not success: print("Video frame is empty or video processing has been successfully completed.") break im0 = distance.calculate(im0) video_writer.write(im0) cap.release() video_writer.release() cv2.destroyAllWindows()Thanks :) The Ultralytics Team!
tylerfrisinger01
Hey there, I have a model that is trained for object detection not tracking. We are detecting two animals that are inside a cage. What we want to do is import a mp4 video then calculate the distance between the two objects while also showing the bounding boxes. However when i use the VideoStream code snippet from above, the popup window is larger then my screen. How could i adjust that code to make it a different window size so that I am able to track them in real time.
Also after this is done and the distances are calculated is there anyway to save the whole video with the bounding boxes and the distance calculations that were done in real time? Or would I have to save the video by doing the results = model.predict(save=true) and also do the VideoStream code snippet from above at the same time? and not have the distances shown in the saved video?
Get back to me as soon as possible as this is for a project for school! Thank You!!
tylerfrisinger01
I am also using YOLOv11, i'm not sure if that will change anything or not. And i have tried creating my own window using cv2 but that didnt work when i attempted it.
Glenn JocherUltralytics@tylerfrisinger01 to adjust the window size in OpenCV, you can use
cv2.namedWindow()andcv2.resizeWindow()to set a custom size. For saving the video with bounding boxes and distances, you can modify the code to include distance annotations and usecv2.VideoWriterto save the processed frames. Here's a quick example on resizing the window:cv2.namedWindow('Video', cv2.WINDOW_NORMAL) cv2.resizeWindow('Video', 800, 600) # Adjust the dimensions as neededRegarding saving the video with distances, you can overlay the distance on the frames before writing them out with
cv2.VideoWriter. If you need further assistance, feel free to ask!tylerfrisinger01
@glenn-jocher when I do this, it still pops open its own window that I am assuming is built into the solutions.DistanceCalculator function (since that is the name of the window) So then it does not work. Any workaround for this?
Glenn JocherUltralytics(已编辑)@tylerfrisinger01 to prevent the
DistanceCalculationfunction from opening its own window, you can set theshowparameter toFalsewhen initializing it, like so:distance = solutions.DistanceCalculation(model="yolo26n.pt", show=False). This should stop the automatic display window. For saving the video, continue usingcv2.VideoWriter. Let me know if you need further assistance!
Abtinz
Hello everyone, I want to deploy an yolov8-application on the edge device and estimate the distance through the user's camera without having to click on the detected object, how can I find the distance of the objects to the camera without need to click?
Glenn JocherUltralytics@Abtinz to estimate object distances without clicking, you'll need to use depth estimation techniques, as YOLOv8 primarily provides 2D bounding boxes. Consider integrating depth sensors or stereo cameras to obtain depth information. For more details, you can refer to the distance calculation guide.
gaodaren47297
Hi,Is there a method to calculate the distance between the camera and the objects?
Glenn JocherUltralytics(已编辑)@gaodaren47297 the
DistanceCalculationsolution measures the pixel distance between the centroids of two objects you select in the frame; it does not estimate the distance between the camera and an object. A 2D bounding box has no depth information, so camera-to-object distance needs extra information such as a depth sensor or stereo camera, or a calibration using an object of known size. For measuring between objects, see the distance calculation documentation on our website. If you have further questions, feel free to ask here.
Dmitrii-Smirnov
Hi Guys, Guys, I have a video with multiple objects(people) on the video. I need to calculate distance between each detected person on the each frame and to save results to csv file. Can you help me with that task? It will be really cool if you will share documentation=) As I understood relevant method for my task is DistanceCalculation(names=names[0], view_img=True).calculate_distance(obj1, obj2), am I correct?
Glenn JocherUltralytics(已编辑)@Dmitrii-Smirnov there is no
calculate_distance(obj1, obj2)method onDistanceCalculationin current versions. The solution is called on each frame (results = dist_obj(im0)), you left-click two tracked objects, and it reports the pixel distance inresults.pixels_distance. For distances between every pair of people on each frame and a CSV export, compute the centroid distances from the tracking boxes yourself. For details, see our documentation: https://docs.ultralytics.com/guides/distance-calculation/.Dmitrii-Smirnov
Thank you!
Glenn JocherUltralytics(已编辑)@Dmitrii-Smirnov to calculate distances between all detected people in each frame and save the results to a CSV file, compute the centroid distances from the tracking results. The
DistanceCalculationsolution only measures between two objects you click, so for all pairs here's a basic implementation:import csv import math from itertools import combinations import cv2 from ultralytics import YOLO model = YOLO("yolo26n.pt") cap = cv2.VideoCapture("path/to/video/file.mp4") assert cap.isOpened(), "Error reading video file" with open("distances.csv", mode="w", newline="") as file: writer = csv.writer(file) writer.writerow(["Frame", "Object1", "Object2", "Distance"]) frame_count = 0 while cap.isOpened(): success, im0 = cap.read() if not success: break results = model.track(im0, persist=True, show=False, classes=[0]) # class 0 = person boxes = results[0].boxes if boxes.id is not None: centroids = dict(zip(boxes.id.int().tolist(), boxes.xywh[:, :2].tolist())) for (id1, c1), (id2, c2) in combinations(centroids.items(), 2): writer.writerow([frame_count, id1, id2, math.dist(c1, c2)]) frame_count += 1 cap.release()This script captures video frames, calculates pixel distances between detected people, and writes the results to a CSV file. For more details, refer to our documentation: https://docs.ultralytics.com/guides/distance-calculation/.
zgr1446741194
Hello author, I would like to propose a scenario similar to this: using monocular distance measurement to calculate the distance from the distant water level line (similar to the shoreline) in the video stream obtained by the camera to my camera (a kind of early warning of the water level), how can I use the solution? At present, the difficulty can be determined that we need to complete distance conversion similar to 3D to 2D, because of perspective space, instead of using fixed linear distance conversion similar to visionEye (from pixels to realistic distance). Another difficulty is that we do not know the true physical properties of the observed water line, which means that we cannot use the traditional method of monocular distance measurement to deduce the distance from the true length or height of the observed object. If you have any viable solutions, thank you very much for adding the code demo in your reply.
Glenn JocherUltralyticsFor calculating distances to a waterline using monocular vision, consider using depth estimation techniques or stereo vision for more accurate results. YOLO models can assist in object detection, but for precise distance measurement, integrating additional sensors or methods might be necessary. For more details, please refer to our distance calculation guide.
