ARTICLE DETAIL

资讯详情

深耕网站视觉设计与运营推广的一线实战洞察。

Ultralytics SpeedEstimator 速度估计 API 全面解析:基于 YOLO 追踪的实时车速计算原理与实战

Ultralytics SpeedEstimator 速度估计 API 全面解析:基于 YOLO 追踪的实时车速计算原理与实战 Ultralytics SpeedEstimator 速度估计 API 全面解析基于 YOLO 追踪的实时车速计算原理与实战【免费下载链接】yolov10YOLOv10: Real-Time End-to-End Object Detection [NeurIPS 2024]项目地址: https://gitcode.com/GitHub_Trending/yo/yolov10导读本文围绕 YOLOv10 仓库中ultralytics/solutions/speed_estimation.py模块的SpeedEstimator类展开系统讲解其 API 参考构造函数、set_args配置、核心方法与参数语义、底层速度估算原理并结合docs/en/guides/speed-estimation.md中的完整示例给出可直接运行的视频车速估计方案。读完本文你将掌握如何用 YOLO 目标检测 多目标跟踪 速度估算三步流水线在交通监控、自动驾驶辅助、安防分析等场景中实时计算并可视化物体运动速度。一、模块定位从 API 参考到源码实现SpeedEstimator是 Ultralytics Solutions 系列中负责速度估计的类其 API 参考文档位于 docs/en/reference/solutions/speed_estimation.md对应的完整实现位于 ultralytics/solutions/speed_estimation.py。该类不直接执行检测或跟踪而是消费跟踪结果它读取model.track()输出的每帧检测框与轨迹 ID结合预设的速度测速区域Region和帧间时间差计算物体运动速度并叠加可视化。从源码结构看SpeedEstimator的整体工作流是model.track(im0, persistTrue) → tracks含 boxes / cls / track id ↓ estimate_speed(im0, tracks) → extract_tracks 提取数据 ↓ store_track_info → 记录每个 track_id 的 bbox 中心点历史最多 30 帧 ↓ plot_box_and_track → 绘制 bbox、速度标签与轨迹线 ↓ calculate_speed → 依据测速区域与时间差计算速度类的 docstring 将其定位为A class to estimation speed of objects in real-time video stream based on their tracks基于目标轨迹估计实时视频流中物体速度的类。二、构造函数与默认状态SpeedEstimator()构造函数无必传参数仅初始化各类内部状态包括状态组属性默认值说明可视化im0/annotatorNone当前帧图像与标注器可视化view_imgFalse是否弹窗显示结果帧测速区域reg_pts[(20, 400), (1260, 400)]定义测速区域的默认两点测速区域region_thickness3区域线条厚度跟踪数据boxes/clss/trk_idsNone检测框、类别、轨迹 ID跟踪数据trk_historydefaultdict(list)每个 track_id 的中心点轨迹历史速度估计dist_data{}track_id → 速度的映射表速度估计spdl_dist_thresh10测速线的欧氏距离阈值速度估计trk_previous_times/trk_previous_points{}记录每个 track 上次时间戳与位置环境检查env_checkcheck_imshow(warnTrue)检测环境是否支持窗口显示见 ultralytics/utils/checks.py值得注意的是测速区域默认值[(20, 400), (1260, 400)]是一条水平线实际使用时几乎总是通过set_args覆盖为视频画面中的真实测速线。三、set_args 配置方法与全部参数所有外部配置都通过set_args一次性注入。其签名与参数语义如下对应文档 docs/en/guides/speed-estimation.md 中的 Optional Arguments 表格并结合源码逐一核对参数名类型默认值作用reg_ptslist[(20, 400), (1260, 400)]定义速度计算区域的两个端点测速线namesdictNone目标检测类别名称映射用于未测速目标上显示类别名view_imgboolFalse是否实时显示标注后的帧画面line_thicknessint2边界框线宽region_thicknessint5测速区域线的绘制厚度spdl_dist_threshint10判断目标是否处于测速线附近的欧氏距离阈值像素从源码可见当reg_pts传入None时set_args仅打印提示 Region points not provided, using default values 并保留默认区域其余参数直接覆盖实例属性。names虽然标注默认None但在后续plot_box_and_track中会被用于显示类别名因此实际使用中必须传入模型类别字典通常取model.model.names。四、核心方法逐一拆解4.1 extract_tracks从跟踪结果提取数据def extract_tracks(self, tracks): self.boxes tracks[0].boxes.xyxy.cpu() self.clss tracks[0].boxes.cls.cpu().tolist() self.trk_ids tracks[0].boxes.id.int().cpu().tolist()接收model.track()返回的Results列表提取xyxy格式边界框、类别索引与整数轨迹 ID。这里强依赖tracks[0].boxes.id非空即必须启用跟踪模式。4.2 store_track_info维护轨迹中心点历史对每个 track 计算 bbox 中心点((x1x2)/2, (y1y2)/2)追加到trk_history[track_id]并裁剪至最近30 个点超出即pop(0)与多目标跟踪文档 docs/en/modes/track.md 中轨迹绘制的窗口思路一致。随后通过np.hstack(track)组装成(N, 1, 2)的形状供cv2.polylines绘制运动轨迹。4.3 plot_box_and_track速度标签与轨迹可视化若目标已被测速track_id in self.dist_data标签显示为f{int(self.dist_data[track_id])}km/ph否则显示类别名颜色上已测速目标使用colors(int(track_id))取色未测速目标固定为洋红色(255, 0, 255)使用绿色折线绘制轨迹并在当前中心点画实心圆点底层标注依赖Annotator的box_label与draw_region方法见 ultralytics/utils/plotting.py。4.4 calculate_speed速度估算的核心算法这是整个模块最关键的逻辑逐段解读if not self.reg_pts[0][0] track[-1][0] self.reg_pts[1][0]: return横向约束目标当前中心点的 x 坐标必须落在测速区域两端点 x 坐标之间确保目标确实处于测速线对应的画面区间内否则直接跳过本帧测速。if self.reg_pts[1][1] - self.spdl_dist_thresh track[-1][1] self.reg_pts[1][1] self.spdl_dist_thresh: direction known elif self.reg_pts[0][1] - self.spdl_dist_thresh track[-1][1] self.reg_pts[0][1] self.spdl_dist_thresh: direction known else: direction unknown纵向约束目标中心点的 y 坐标必须落在测速线任一端的spdl_dist_thresh默认 10 像素邻域内才被判定为known方向即正在穿越测速线否则为unknown。if self.trk_previous_times[trk_id] ! 0 and direction ! unknown and trk_id not in self.trk_idslist: self.trk_idslist.append(trk_id) time_difference time() - self.trk_previous_times[trk_id] if time_difference 0: dist_difference np.abs(track[-1][1] - self.trk_previous_points[trk_id][1]) speed dist_difference / time_difference self.dist_data[trk_id] speed测速公式目标首次被识别为穿越测速线且具备上一帧时间戳时用距离差 / 时间差得到速度。其中距离差取 y 方向位移绝对值时间差为两次time()的间隔。注意该速度为像素/秒量纲并非真实物理速度标签中展示的km/ph仅为示意且每个 track_id 只测速一次trk_idslist去重之后一直复用首次测得的速度。最后更新trk_previous_times[trk_id]与trk_previous_points[trk_id]供下一帧计算。4.5 estimate_speed每帧主入口def estimate_speed(self, im0, tracks, region_color(255, 0, 0)):每帧调用一次流程为保存当前帧 → 若tracks[0].boxes.id is None未启用跟踪则直接返回原帧 →extract_tracks→ 用Annotator和draw_region绘制测速线 → 遍历每个目标依次执行store_track_info、plot_box_and_track、calculate_speed→ 按需弹窗显示 → 返回标注后的帧。region_color默认为红色(255, 0, 0)可通过参数自定义测速线颜色。4.6 display_frames结果弹窗使用cv2.imshow(Ultralytics Speed Estimation, self.im0)展示画面waitKey(1)检测到q键退出。仅在view_imgTrue且env_check通过环境支持 imshow时被调用。五、端到端实战示例视频目标速度估计以下完整示例继承自官方指南 docs/en/guides/speed-estimation.md可直接复制运行需安装ultralytics与opencv-python模型文件会自动下载from ultralytics import YOLO from ultralytics.solutions import speed_estimation 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(speed_estimation.avi, cv2.VideoWriter_fourcc(*mp4v), fps, (w, h)) line_pts [(0, 360), (1280, 360)] # Init speed-estimation obj speed_obj speed_estimation.SpeedEstimator() speed_obj.set_args(reg_ptsline_pts, namesnames, view_imgTrue) 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, persistTrue, showFalse) im0 speed_obj.estimate_speed(im0, tracks) video_writer.write(im0) cap.release() video_writer.release() cv2.destroyAllWindows()关键点说明model.track(im0, persistTrue)必须开启persistTrue表示跨帧延续轨迹与 docs/en/modes/track.md 中 Persisting Tracks Loop 的要求一致否则boxes.id为Noneestimate_speed将直接返回原帧line_pts的(0, 360)与(1280, 360)通常取自画面中道路所在位置的横向水平线两个端点的 y 值一致时即构成一条测速横线若需倾斜测速线也可给出不同 y 坐标video_writer用mp4v编码将标注帧写回视频文件便于离线复核。六、model.track 跟踪参数参考由于速度估计强依赖跟踪质量这里列出model.track常用参数摘自 docs/en/guides/speed-estimation.md 的 Arguments 表格参数名类型默认值说明sourceim0None图像或视频源persistboolFalse帧间保持轨迹trackerstrbotsort.yaml跟踪算法可选bytetrack.yaml见 ultralytics/cfg/trackers 下的 botsort.yaml 与 bytetrack.yamlconffloat0.3置信度阈值ioufloat0.5IOU 阈值classeslistNone按类别过滤如classes0或classes[0,2,3]verboseboolTrue是否打印跟踪结果实践建议在交通场景中通常只关心车辆可用classes2COCO 中 car 的索引过滤行人等干扰目标若目标 ID 频繁跳变可尝试trackerbytetrack.yaml或调低conf。七、精度边界与适用前提官方指南在 docs/en/guides/speed-estimation.md 中明确给出了两点重要提示必须在应用时牢记速度为估计值Speed will be an estimate and may not be completely accurate。像素位移换算的速度受相机角度、透视畸变、画面分辨率影响不宜直接用于执法或计费类严肃场景结果受 GPU 性能波动影响estimation can vary depending on GPU speed即帧处理耗时波动会直接影响time()测得的时间差进而干扰速度计算。此外从源码实现可推断的局限还包括目标只在首次穿越测速线时被记录速度trk_idslist去重机制测速仅使用 y 方向位移水平测速线场景对垂直方向穿越的目标效果最佳dist_data中保存的是像素/秒的原始值km/ph仅是展示标签而非真实物理单位换算。八、与同系列解决方案的关系SpeedEstimator位于 ultralytics/solutions 解决方案包内与object_counter目标计数、heatmap热力图、ai_gym健身计数、distance_calculation目标间距离计算参考 docs/en/reference/solutions/distance_calculation.md共享同一套「检测 跟踪 后处理」架构。这些类均不参与模型推理只负责消费Results并叠加分析能力因此可以无缝嵌入任何基于YOLO(...)加载的检测模型流水线中从 YOLOv8 到本仓库主推的 YOLOv10 模型见 ultralytics/models/yolov10均可配合使用。九、速查模块内全部 API 一览API签名要点作用SpeedEstimator()无必选参数构造实例并初始化默认状态set_args(reg_pts, names, view_img, line_thickness, region_thickness, spdl_dist_thresh)全部带默认值配置测速区域与可视化参数extract_tracks(tracks)传入 track 结果提取 boxes / clss / trk_idsstore_track_info(track_id, box)传入 id 与框记录中心点历史并返回轨迹plot_box_and_track(track_id, box, cls, track)内部调用绘制速度标签、bbox 与轨迹calculate_speed(trk_id, track)内部调用判定穿越测速线并计算速度estimate_speed(im0, tracks, region_color)每帧调用主入口返回标注帧display_frames()内部调用弹窗显示按q退出如需阅读源码级注释与 docstring 原文可前往 ultralytics/solutions/speed_estimation.py 对照学习。【免费下载链接】yolov10YOLOv10: Real-Time End-to-End Object Detection [NeurIPS 2024]项目地址: https://gitcode.com/GitHub_Trending/yo/yolov10创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表