★ FEATURED ARTICLE 简介本资源是一套已成功跑通的YOLOv5双目测距完整实现方案面向计算机视觉初学者、深度学习实践者及智能感知系统开发者解决单目检测缺乏空间深度信息的痛点助力快速掌握目标检测与三维测距融合技术。压缩包共106个文件含25个核心Python脚本如detect.py、datasets.py、18个配置yaml文件模型结构与训练参数、1个预训练权重pt文件yolov5s.pt、1个实操演示mp4、1个Dockerfile及README.md等工程化支持文件兼顾算法复现、环境部署与结果验证总大小20.88MB。已有2844人学习下载适合希望跳过环境踩坑、直接运行调试的进阶学习者。用户可获得端到端双目测距流水线从左右图像输入、YOLOv5目标定位、SGBM视差计算到基于基线与焦距的实时距离估计配套bus.jpg样例图与清晰目录结构显著降低立体视觉落地门槛。1. YOLOv5双目测距源码已跑通不是调参玄学是能直接测出厘米级距离的完整闭环系统你手头有一对普通USB双目摄像头比如罗技C270拆出来的左右模组想让YOLOv5不仅框出人、车、瓶子还能实时告诉你“那个快递箱离镜头还有83.6cm”——不是靠单目估计的相对大小而是基于真实物理基线、像素匹配和视差计算出的绝对深度。这个项目就是干这个的它把YOLOv5的目标检测结果无缝喂进双目立体匹配流水线输出带深度值的检测框x, y, w, h, depth所有代码在Ubuntu 20.04 CUDA 11.3 PyTorch 1.10环境下实测跑通无需额外标定工具、不依赖OpenCV contrib的SGBM黑匣子连相机内参都用自带的棋盘格标定脚本一键生成。适合做智能小车避障、机械臂抓取定位、工业分拣demo的开发者也适合刚学完《计算机视觉中的多视图几何》但卡在“理论会了代码不会连”的同学。它不是论文复现玩具而是一个从图像采集→标定→检测→匹配→深度解算→可视化全链路可调试、可打断、可替换模块的工程包。2. 项目结构与技术栈看清这6个核心目录你就掌握了90%的改造入口这个YOLOv5双目测距项目不是简单把detect.py改两行就完事。它重构了YOLOv5原生结构把单目推理流程扩展为双流输入深度后处理的协同架构。整个工程共23个文件核心逻辑集中在以下6个目录每个目录都对应一个可独立验证、可替换的技术环节2.1calibration/棋盘格标定不是玄学是必须走通的第一步标定质量直接决定后续深度误差。项目提供calibrate_stereo.py支持同时标定左右相机内参fx, fy, cx, cy和畸变系数k1, k2, p1, p2并计算旋转矩阵R和平移向量T即外参。关键点在于它不依赖OpenCV默认的stereoCalibrate()全流程而是先用cv2.calibrateCamera()分别标定左右再用cv2.stereoRectify()做极线校正——这样能避免因左右图像同步抖动导致的标定失败。标定结果保存为stereo_params.npz含8个关键参数left_mtx,left_dist,right_mtx,right_dist,R,T,E,F。你只需准备一张A4打印的10×7棋盘格格子边长2.5cm放在不同角度拍20张左右图像运行命令即可python calibration/calibrate_stereo.py \ --left_dir ./data/calib/left \ --right_dir ./data/calib/right \ --pattern_size 10,7 \ --square_size 2.5 \ --output ./calibration/stereo_params.npz提示--square_size单位是厘米必须和你实际打印的格子边长严格一致否则后续深度值会整体偏大或偏小。我第一次用2.0cm参数标定测得1m处物体显示为1.25m调回2.5cm后误差压到±1.2cm以内。2.2models/YOLOv5s轻量模型已剪枝检测头输出增加置信度通道项目未使用原始YOLOv5官方仓库而是基于ultralytics/yolov5:v6.1分支做了针对性修改在models/yolo.py中Detect类的forward()方法被重写除原有[x, y, w, h, obj_conf, cls_conf]外新增depth_pred通道第6维用于后续与视差图对齐models/common.py里加入DepthHead模块接在P3/P4/P5特征图后用1×1卷积预测每个anchor中心点的初步深度归一化到0~1模型权重weights/yolov5s_dual.pt已预训练好支持直接加载无需从头训。加载时注意model torch.load(weights/yolov5s_dual.pt, map_locationcpu)[model].float() model.eval()注意torch.load()返回的是字典必须取[model]键否则会报AttributeError: dict object has no attribute eval——这是新手最常翻车的点之一。2.3stereo/视差计算不靠SGBM硬扛用半全局匹配YOLO引导ROI双目深度的核心是视差图disparity map但直接对整图跑SGBM耗时且噪声大。本项目采用“YOLO粗定位 → ROI裁剪 → 半全局匹配 → 视差优化”四级流水先用YOLOv5跑一次单帧得到目标框坐标对左右图按框裁剪出ROI区域比原图小80%在ROI上用cv2.StereoSGBM_create()计算视差minDisparity0,numDisparities128,blockSize11经实测此组合在1280×480双目图上兼顾精度与速度最后用cv2.filterSpeckles()滤除孤立噪点。关键函数stereo/disparity.py中compute_disparity_roi()封装了全部逻辑输入是左右图检测框列表输出是每个框对应的视差均值。2.4geometry/深度解算公式不是抄来的是推导自三角测量原理拿到视差d后深度Z计算公式为Z (f * B) / d其中f是焦距像素单位B是基线距离厘米d是视差像素。项目中f取左右相机fx平均值因双目水平排列fx≈fyB来自标定结果中的T[0]平移向量X分量单位厘米。geometry/depth_calc.py里calculate_depth()函数严格按此实现并做三重保护视差d 1.0时返回None无效匹配深度Z 300cm时截断超出双目有效测距范围对同一目标多个像素深度值取中位数而非均值抗异常点。2.5utils/可视化不是画框了事要带深度标签坐标系箭头utils/plots.py重写了plot_one_box()新增depth参数在框右上角绘制绿色标签D:83.6cm更关键的是draw_coordinate_system()函数能在图像左下角叠加三维坐标系箭头X红/Y绿/Z蓝直观展示当前相机坐标系朝向——这对调试机械臂手眼标定至关重要。调用方式简单img draw_coordinate_system(img, R, T, mtxleft_mtx, scale50)scale50表示坐标轴长度为50像素太小看不清太大会遮挡画面。2.6inference/主推理脚本run_dual.py是胶水也是调试入口整个流程的调度中心。它按顺序执行加载标定参数初始化YOLO模型启动双目视频流支持USB摄像头或视频文件对每帧左右图同步读取 → YOLO检测 → ROI视差计算 → 深度解算 → 可视化叠加输出带深度信息的JSON日志含时间戳、目标类别、中心坐标、深度值。运行命令python inference/run_dual.py \ --weights weights/yolov5s_dual.pt \ --source 0,2 \ # 左摄像头ID0右摄像头ID2 --calib_path calibration/stereo_params.npz \ --view-img \ --save-txt--source 0,2是关键告诉程序用两个独立VideoCapture实例拉流避免单线程读取导致左右帧不同步。3. 核心模块拆解从YOLO检测框到厘米级深度值的完整链路这一章我们盯住一个具体目标——比如检测到画面中央的一个矿泉水瓶看它的深度值是怎么一步步算出来的。整个链路分四步检测定位 → ROI裁剪 → 视差提取 → 深度解算。每一步都有可调试的中间变量绝不是黑匣子。3.1 YOLO检测输出不只是xywh还有置信度与类别索引当YOLOv5模型前向传播完成pred是一个长度为3的list对应P3/P4/P5层每个元素shape为(1, n, 85)其中n是该层检测到的anchor数。项目在inference/run_dual.py中用non_max_suppression()后得到detshape(N, 6)6列含义依次为x1, y1, x2, y2归一化后的边界框坐标0~1conf目标置信度obj_conf × cls_confcls类别索引0person, 1car, 2bottle...。关键改造在models/yolo.py的Detect.forward()末尾# 原始YOLOv5输出[x, y, w, h, obj_conf, cls_conf] # 本项目追加depth_pred归一化深度0~1 if self.depth_head is not None: depth_pred self.depth_head(x[i]) # x[i]是第i层特征图 pred[..., 5] depth_pred.squeeze(-1) # 写入第6列 return torch.cat([pred, depth_pred], dim-1) if self.depth_head else pred注意depth_pred.squeeze(-1)因为self.depth_head输出shape是(B, C, H, W, 1)必须squeeze掉最后一维才能拼接。漏掉这句会导致cat维度不匹配报错。3.2 ROI裁剪用检测框坐标反算像素坐标再做安全paddingYOLO输出是归一化坐标需转为像素坐标才能裁图。假设原图宽W1280高H480x1_pix int((x1 - w/2) * W) # 左上角x y1_pix int((y1 - h/2) * H) # 左上角y x2_pix int((x1 w/2) * W) # 右下角x y2_pix int((y1 h/2) * H) # 右下角y # 加padding防越界 pad 20 x1_pad max(0, x1_pix - pad) y1_pad max(0, y1_pix - pad) x2_pad min(W, x2_pix pad) y2_pad min(H, y2_pix pad) roi_left left_img[y1_pad:y2_pad, x1_pad:x2_pad] roi_right right_img[y1_pad:y2_pad, x1_pad:x2_pad]这里pad20是经验值太小则视差匹配易受边缘影响太大则ROI内噪声增多。我在测试中发现对480p图像pad在15~25之间效果最佳。3.3 视差计算SGBM参数不是随便填的要匹配你的基线与分辨率stereo/disparity.py中compute_disparity_roi()调用OpenCV SGBMstereo cv2.StereoSGBM_create( minDisparity0, numDisparities128, # 必须是16的倍数否则报错 blockSize11, # 奇数3~11间选越大越平滑但细节丢失 P18 * 3 * 11**2, # 一般设为8*ch*bs^2ch通道数灰度图为1 P232 * 3 * 11**2, # 一般为P1的4倍 disp12MaxDiff1, uniquenessRatio15, speckleWindowSize0, speckleRange2 ) disparity stereo.compute(roi_left_gray, roi_right_gray).astype(np.float32)重点参数说明numDisparities128最大视差值决定了最大可测距离。公式Z_max f*B / 1若f800px,B12cm则Z_max≈960cm覆盖绝大多数室内场景blockSize11匹配窗口大小实测11比默认的3在保持速度的同时显著降低误匹配率P1/P2控制视差连续性惩罚项P1小则允许局部突变P2大则强制全局平滑。本项目取值经网格搜索验证在双目USB摄像头上鲁棒性最佳。3.4 深度解算从视差到厘米三步校准缺一不可geometry/depth_calc.py中calculate_depth()函数def calculate_depth(disparity_map, fx, baseline_cm, valid_maskNone): disparity_map: 视差图float32单位像素 fx: 焦距像素取左右相机fx平均值 baseline_cm: 基线距离厘米 valid_mask: 可选布尔掩膜指定哪些像素参与计算 # 1. 过滤无效视差 mask (disparity_map 1.0) (disparity_map 128.0) if valid_mask is not None: mask valid_mask # 2. 计算深度厘米 depth_cm (fx * baseline_cm) / (disparity_map 1e-6) # 防零除 # 3. 取中位数并截断 valid_depths depth_cm[mask] if len(valid_depths) 0: return None median_depth np.median(valid_depths) return np.clip(median_depth, 20.0, 300.0) # 20cm~300cm有效范围为什么用中位数因为视差图边缘常有飞点spike均值会被拉偏。我曾用一瓶水做标定均值给出78.2cm中位数是83.6cm而游标卡尺实测为83.4cm——误差仅0.2cm。3.5 完整链路验证用一张静态图走通全流程为快速验证项目提供test/test_static.py加载左右两张静态图test/left.jpg,test/right.jpg和预标定参数手动设置一个检测框# 模拟YOLO检测结果瓶子在图像中心宽高各200px x1, y1, x2, y2 540, 190, 740, 390 # 像素坐标 det np.array([[x1, y1, x2, y2, 0.95, 2]]) # conf0.95, cls2(bottle) # 手动执行四步 roi_left left_img[y1:y2, x1:x2] roi_right right_img[y1:y2, x1:x2] disp compute_disparity_roi(roi_left, roi_right) depth calculate_depth(disp, fx798.5, baseline_cm12.0) print(fDetected bottle at depth: {depth:.1f} cm) # 输出83.6 cm跑通这5行你就确认了从图像到深度的数学链路完全正确。这是所有后续开发的基石。4. 避坑指南那些让我重启三次、重标定五遍才搞懂的致命细节双目测距是典型的“理论简单、落地极难”领域。下面5条全是血泪经验每一条都对应一个真实翻车现场按发生频率排序4.1 现象深度值整体偏大20%且随距离增大偏差加剧原因标定时--square_size单位用错了。你打印的是2.5cm格子但命令里写了--square_size 25以为单位是毫米导致标定出的fx被放大10倍代入ZfB/d后深度整体放大。解决重新标定严格按厘米输入。检查stereo_params.npz里的left_mtx[0,0]即fx正常USB双目在1280×480下应在700~900之间若2000必错。4.2 现象视差图大片黑色值为0深度计算返回None原因SGBM的minDisparity设太高或numDisparities太小。例如目标实际视差为45但minDisparity64则所有匹配都被过滤。解决先用cv2.StereoBM_create()快速试跑速度慢但鲁棒观察视差范围或临时把minDisparity0,numDisparities256确认有输出后再逐步收紧。4.3 现象左右图同步严重滞后YOLO框和深度标签错位原因--source 0,2用了两个独立cv2.VideoCapture但没做帧对齐。USB摄像头驱动本身有缓存左图读到第100帧时右图可能还在第95帧。解决在inference/run_dual.py中加入帧对齐逻辑# 读左图 ret_l, frame_l cap_l.read() # 循环读右图直到时间戳接近 while True: ret_r, frame_r cap_r.read() if not ret_r: break # 用frame_l.timestamp和frame_r.timestamp比较需启用CAP_PROP_POS_MSEC if abs(cap_l.get(cv2.CAP_PROP_POS_MSEC) - cap_r.get(cv2.CAP_PROP_POS_MSEC)) 50: break注意OpenCV的CAP_PROP_POS_MSEC在USB摄像头上不一定可靠更稳的方式是用time.time()打时间戳然后丢弃时间差100ms的帧。4.4 现象检测框很准但深度值跳变剧烈83cm→150cm→42cm原因ROI裁剪时没加padding导致目标靠近图像边缘时裁剪区域包含大量背景SGBM在无纹理区域匹配失败产生随机视差。解决强制加padding。在stereo/disparity.py中compute_disparity_roi()开头插入h, w roi_left.shape[:2] pad_h, pad_w min(30, h//4), min(30, w//4) # 动态padding roi_left cv2.copyMakeBorder(roi_left, pad_h, pad_h, pad_w, pad_w, cv2.BORDER_CONSTANT) roi_right cv2.copyMakeBorder(roi_right, pad_h, pad_h, pad_w, pad_w, cv2.BORDER_CONSTANT)4.5 现象cv2.StereoSGBM_create()报错numDisparities must be divisible by 16原因numDisparities不是16的倍数。OpenCV硬性要求哪怕你设127也会崩。解决写死为128、256、512。别试图用120这种“看起来合理”的数。项目里所有SGBM调用都加了断言assert numDisparities % 16 0, fnumDisparities{numDisparities} must be multiple of 165. 二次开发实战如何把YOLOv5双目测距接入ROS2输出标准sensor_msgs/PointCloud2如果你要做机器人导航或机械臂抓取光有单点深度不够需要稠密点云。本节教你把本项目改造成ROS2节点发布符合ROS2标准的点云消息。这不是概念演示是已在某高校移动机器人平台实测的方案。5.1 ROS2环境准备只装必要组件避免版本冲突不要用rosdep install全装只装三个核心ros-foxy-rclpyPython客户端库ros-foxy-sensor-msgs点云消息定义ros-foxy-image-transport图像传输安装命令sudo apt update sudo apt install ros-foxy-rclpy ros-foxy-sensor-msgs ros-foxy-image-transport提示本项目用Python3.8ROS2 Foxy官方支持Python3.8但如果你用3.9rclpy会编译失败。宁可降级Python也不要强行打patch。5.2 构建ROS2节点继承Node类重写timer_callback新建ros2_node/dual_depth_node.pyimport rclpy from rclpy.node import Node from sensor_msgs.msg import PointCloud2, PointField, Image from cv_bridge import CvBridge import numpy as np import struct class DualDepthNode(Node): def __init__(self): super().__init__(dual_depth_node) # 加载本项目模块 from inference.run_dual import load_model, load_calib self.model load_model(weights/yolov5s_dual.pt) self.calib load_calib(calibration/stereo_params.npz) self.bridge CvBridge() self.pc_pub self.create_publisher(PointCloud2, /dual_depth/points, 10) self.timer self.create_timer(0.1, self.timer_callback) # 10Hz def timer_callback(self): # 1. 读双目图此处简化为读静态图实际用cv2.VideoCapture left_img cv2.imread(test/left.jpg) right_img cv2.imread(test/right.jpg) # 2. 走本项目全流程得到深度图H,W depth_map self.compute_depth_map(left_img, right_img) # 自定义函数 # 3. 转点云 pc_msg self.depth_to_pointcloud(depth_map, self.calib) self.pc_pub.publish(pc_msg) def depth_to_pointcloud(self, depth_map, calib): # 关键用标定参数构建点云 fx calib[left_mtx][0,0] fy calib[left_mtx][1,1] cx calib[left_mtx][0,2] cy calib[left_mtx][1,2] baseline_m calib[T][0] / 100.0 # cm转米 h, w depth_map.shape x np.linspace(0, w-1, w) y np.linspace(0, h-1, h) xx, yy np.meshgrid(x, y) # Z fB/d d fB/Z # 但depth_map是Z米所以视差d fB/Z disparity (fx * baseline_m) / (depth_map 1e-6) # 三角测量X (u-cx)*Z/fx, Y (v-cy)*Z/fy, Z Z X (xx - cx) * depth_map / fx Y (yy - cy) * depth_map / fy Z depth_map # 拼成(N,3)点云 points np.stack([X, Y, Z], axis-1).reshape(-1, 3) # 过滤无效点Z0或inf mask np.isfinite(points[:, 2]) (points[:, 2] 0.02) (points[:, 2] 3.0) points points[mask] # 构建PointCloud2消息 msg PointCloud2() msg.header.stamp self.get_clock().now().to_msg() msg.header.frame_id camera_link msg.height 1 msg.width len(points) msg.fields [ PointField(namex, offset0, datatypePointField.FLOAT32, count1), PointField(namey, offset4, datatypePointField.FLOAT32, count1), PointField(namez, offset8, datatypePointField.FLOAT32, count1) ] msg.is_bigendian False msg.point_step 12 msg.row_step msg.point_step * len(points) msg.is_dense True msg.data points.astype(np.float32).tobytes() return msg5.3 编译与运行用ament_python不碰CMakeLists.txtROS2 Foxy对Python节点支持极好无需写CMakeLists.txt。只需在setup.py里声明入口点entry_points{ console_scripts: [ dual_depth_node ros2_node.dual_depth_node:main, ], },然后编译colcon build --packages-select dual_depth_pkg source install/setup.bash ros2 run dual_depth_pkg dual_depth_node用RViz2订阅/dual_depth/points你会看到一个稀疏但准确的点云——每个点的Z值就是本项目计算出的深度。5.4 性能优化从3FPS到15FPS的关键三招实测在Jetson Xavier NX上原始流程只有3FPS。通过以下三步优化提升至15FPS图像缩放在run_dual.py中读取后立即缩放至640×240原1280×480YOLO检测和SGBM都快3倍深度误差5%SGBM复用cv2.StereoSGBM_create()创建开销大提至__init__中只建一次每次compute()复用异步推理用threading.Thread把YOLO检测和SGBM计算放到不同线程YOLO跑P3层时SGBM已在算上一帧的视差。最终在Xavier NX上端到端延迟稳定在65ms满足机器人实时性要求。从那以后我每次接到双目项目都强制走一遍棋盘格标定静态图四步验证ROS2点云发布三步缺一不可。标定不牢地动山摇静态不通动态白搞点云不发集成白搭。希望帮到你。本文还有配套的精品资源点击获取
阅读完成 · 觉得有帮助？
