简介一份基于YOLOv5的双目摄像头测距完整工程面向需要同时做目标检测与距离估计的Python开发者也适合毕业设计或课程设计阶段参考。整个项目在原始YOLOv5框架上新增camera_config.py、dis_count.py、video_remain.py三个核心文件分别完成双目参数配置、深度图与距离矩阵计算、主流程控制从摄像头标定到单/双设备号设置都给出了对应说明方便直接改参数运行。压缩包共131个文件、约46.75MB以Python源码和说明文档为主另有yaml模型配置、pt权重文件、Jupyter notebook以及演示mp4视频其中源码、配置和模型分工清晰整体结构完整可用于复现双目测距效果。资源已有189人学习下载。相比从零搭建这份工程节省了双目校正、YOLO集成和视频流读取适配的调试时间尤其适合作为高分课设或项目起步框架结合文档、模型与演示视频能快速产出可运行结果。1. “基于YOLOv5对双目摄像头进行测距”到底解决什么问题先说结论这个项目的核心价值不是“识别出画面里有什么”而是“识别出的那个东西离我多远”。YOLOv5负责给出目标的类别和检测框双目摄像头通过左右两路画面的视差算出深度再把检测框和深度对齐最终输出“前方5米处有一辆车”这类结果。它适合做车载预警、机器人避障、安防监控、无人机定高等需要检测与测距同时完成的场景也适合做自动驾驶课程的课设或毕业设计。直接跑通项目的人先用预训练权重验证检测再按标定、立体匹配、目标测距这三步把代码接起来只想搞懂原理的人从视差公式开始读再回头看源码就不会被一堆参数劝退。2. 先搞懂测距原理再动手视差、基线选型和单目测距差在哪2.1 测距的核心是视差不是检测框大小双目测距的数学基础非常朴素同一个空间点在左右两张图里的成像位置不同这个位置差叫视差。视差越大目标越近视差越小目标越远。深度计算公式是depth (focal_length_px * baseline) / disparityfocal_length_px是相机内参里的fx单位是像素baseline是左右相机光心之间的距离单位用毫米算出来的depth单位也是毫米。disparity是左右图上同一个特征点的横坐标之差单位是像素。这套公式告诉你一个反直觉的结论检测框的大小对测距没有任何直接贡献。同一辆车在画面里占据300像素高度可能是3米外的卡车也可能是6米外的轿车。单目测距之所以不准就是因为它必须依赖“目标实际尺寸已知”这个先验假设一旦目标类别没见过的外形尺寸误差直接失控。双目测距相当于用三角测量直接还原了物理尺度和目标的类别无关所以比单目视觉测距的泛化能力强得多。2.2 双目系统里YOLOv5的角色是“目标定位器”完整的测距管线不是让YOLOv5去算距离而是各管一段。左右两路图像先做立体匹配得到视差图视差图再换算成深度图YOLOv5在左图或右图上跑目标检测输出检测框最后把检测框映射到深度图上取框内深度值的中位数作为该目标的距离。这也是很多人在源码里找“测距在哪一行”时容易懵的原因。YOLOv5的detect.py只负责输出检测框坐标和类别测距代码通常是在检测结果的后处理阶段接进去的。你会在项目里看到类似estimate_distance、compute_depth这样的函数输入是检测框和视差图输出是目标距离。这里有一个关键问题YOLOv5默认会对输入图像做letterbox缩放检测框坐标是在缩放后画出来的必须还原回原图坐标系再对齐到深度图上。这个步骤如果漏掉检测框和测距点就会错位后面第5章会专门讲这个坑。2.3 基线、焦距和量程的关系选摄像头前先算一遍双目系统的硬件参数直接决定了“能测多远、测得有多准”。depth f*b/d这个公式里视差d是整数像素最小分辨率就是1个像素所以测距误差和距离的平方成正比。想测远要么加大基线b要么加大焦距f。工程上常见的做法是按工作距离倒推参数。假设你想测3到8米范围内的目标用一个焦距6毫米、传感器像元尺寸约等于0.003毫米的摄像头像素焦距大约等于6/0.003 2000像素基线选120毫米。那么8米处目标的视差大约是2000*120/8000 30像素1个像素的视差误差对应大约267毫米的距离抖动这已经是比较极限的状态了。如果把基线缩到60毫米8米处的视差只有15像素误差会翻倍到500毫米以上。所以选型不能只看分辨率要把工作距离、基线、焦距放在一起算一遍。下面是单目与双目测距的选型对比对比项单目视觉测距双目视觉测距硬件成本一个摄像头即可需要两个摄像头固定安装测距原理依赖先验尺寸或地面平面假设三角测量物理尺度直接恢复对目标类别的依赖强依赖类别先验与类别无关标定要求只需要单目标定需要单目加立体标定远距离精度误差随距离快速放大误差与距离平方成正比可控夜间/弱光环境受单目图像质量影响大同样受影响但不受尺寸先验欺骗这套对比也解释了为什么很多量产方案宁可增加一个摄像头也要上双目。单目方案在封闭场景如固定高度的无人机里够用一旦目标类别或场景变化测距结果会突然翻车而双目的底线是“算不准但不会瞎猜”。3. 搭环境和跑通demo用conda建Python环境、装依赖、跑检测一次过关3.1 环境清单Python版本、PyTorch和CUDA怎么对应这一步是新手最容易卡住的地方。YOLOv5对Python版本的要求不算苛刻3.8到3.10都可以但PyTorch和CUDA的版本必须配套。一个常见做法是先用conda创建一个独立的yolov5环境避免把系统Python搞乱。conda create -n yolov5 python3.8 -y conda activate yolov5 conda install pytorch2.0.0 torchvision0.15.0 cudatoolkit11.8 -c pytorch -c nvidia这里python3.8、pytorch2.0.0、cudatoolkit11.8是一组我自己验证过的组合。CUDA版本号要和显卡驱动匹配驱动版本新一点的可以直接装CUDA 11.8以上。实在没有NVIDIA显卡就把pytorch换成CPU版conda install pytorch2.0.0 torchvision0.15.0 cpuonly -c pytorchCPU版跑推理没问题训练就很痛苦了。YOLOv5的requirements.txt里还会要求opencv-python、numpy、matplotlib、pandas等依赖建议直接用pip一条命令装完。装完之后验证一下PyTorch能不能调用GPU这一步值得做省得后面训练到一半才发现在用CPU硬抗。python -c import torch; print(torch.cuda.is_available())输出True说明GPU可用输出False就检查CUDA版本和驱动是否匹配。3.2 克隆源码并安装依赖requirements.txt里的核心包项目源码拿到手之后第一步是把YOLOv5官方仓库克隆下来再把项目里的utils、models等目录覆盖进去因为后面的测距代码需要依赖YOLOv5的检测模型结构。git clone https://github.com/ultralytics/yolov5 cd yolov5 pip install -r requirements.txt很多自带测距源码的项目会直接要求你“把本项目文件放到YOLOv5目录下运行”原因就在这里。requirements.txt里的核心依赖包括torch、torchvision、opencv-python、PyYAML、matplotlib等。注意不要用pip install -U把NumPy升到2.xYOLOv5老版本对NumPy 2.x的兼容性很差经常报_ARRAY_API相关的错误把numpy固定到1.23.5以上、2.0以下最稳妥。装完依赖后从YOLOv5官方release页面下载yolov5s.pt权重文件放到项目根目录。这是检测部分的预训练模型测距部分不需要单独下载深度模型因为双目测距的“深度”是靠立体匹配算出来的不是靠深度学习回归出来的。3.3 用预训练权重跑通检测再确认摄像头双路可取流先用一张图片或视频验证检测链路通不通再切换到摄像头。摄像头模式下YOLOv5的detect.py默认只读取单路摄像头索引--source 0对应系统的/dev/video0。python detect.py --source 0 --weights yolov5s.pt --conf 0.5 --imgsz 640--conf 0.5表示置信度阈值低于0.5的检测框会被丢弃--imgsz 640是输入分辨率越大越准但越慢。这一步能跑通说明环境没问题。接下来验证双路摄像头是否能同时取流两个摄像头都接上后用OpenCV写个最小脚本import cv2 cap_left cv2.VideoCapture(0) # 左摄像头 cap_right cv2.VideoCapture(1) # 右摄像头 print(左摄像头打开:, cap_left.isOpened()) print(右摄像头打开:, cap_right.isOpened()) while True: ret_l, frame_l cap_left.read() ret_r, frame_r cap_right.read() if not ret_l or not ret_r: print(读取失败请检查摄像头索引) break cv2.imshow(left, frame_l) cv2.imshow(right, frame_r) if cv2.waitKey(1) 0xFF ord(q): break cap_left.release() cap_right.release() cv2.destroyAllWindows()如果两个摄像头都是免驱UVC相机索引顺序不一定是物理位置顺序。左摄像头被识别成1、右摄像头被识别成0是常有的事这一步发现错位及时交换索引别等到标定完才发现。4. 把测距写进YOLOv5相机标定、SGBM视差图、目标框取深度三步走4.1 相机标定棋盘格照片要多少张、内参和立体标定怎么做双目测距的所有误差都始于标定。标定要解决两件事一是每个相机的内参焦距、主点、畸变二是两个相机之间的外参旋转矩阵R和平移向量T。先打印一块棋盘格标定板内角点个数取(9,6)比较常见方格边长25毫米左右。左右相机对着标定板同时拍20到30对照片覆盖画面的九个方位中间、四个角、四条边的中点每张照片里棋盘格最好占画面三分之一以上。拍摄时相机和标定板都不能动按下快门时保证画面清晰不模糊。标定脚本的常见结构如下import cv2 import numpy as np pattern (9, 6) # 内角点数 criteria (cv2.TERM_CRITERIA_EPS cv2.TERM_CRITERIA_MAX_ITER, 30, 0.001) # 世界坐标系下的棋盘格角点坐标z轴为0 objp np.zeros((pattern[0] * pattern[1], 3), np.float32) objp[:, :2] np.mgrid[0:pattern[0], 0:pattern[1]].T.reshape(-1, 2) obj_points [] # 世界坐标 img_points_l [] # 左图角点像素坐标 img_points_r [] # 右图角点像素坐标 for idx in range(20): left cv2.imread(fstereo/left_{idx}.jpg) right cv2.imread(fstereo/right_{idx}.jpg) gray_l cv2.cvtColor(left, cv2.COLOR_BGR2GRAY) gray_r cv2.cvtColor(right, cv2.COLOR_BGR2GRAY) ret_l, corners_l cv2.findChessboardCorners(gray_l, pattern, None) ret_r, corners_r cv2.findChessboardCorners(gray_r, pattern, None) if ret_l and ret_r: # 亚像素级角点定位精度更高 corners_l cv2.cornerSubPix(gray_l, corners_l, (11, 11), (-1, -1), criteria) corners_r cv2.cornerSubPix(gray_r, corners_r, (11, 11), (-1, -1), criteria) obj_points.append(objp) img_points_l.append(corners_l) img_points_r.append(corners_r) # 先分别标定单目内参再标定双目外参 ret_l, mtx_l, dist_l, _, _ cv2.calibrateCamera( obj_points, img_points_l, gray_l.shape[::-1], None, None) ret_r, mtx_r, dist_r, _, _ cv2.calibrateCamera( obj_points, img_points_r, gray_r.shape[::-1], None, None) ret_s, mtx_l, dist_l, mtx_r, dist_r, R, T, E, F cv2.stereoCalibrate( obj_points, img_points_l, img_points_r, mtx_l, dist_l, mtx_r, dist_r, gray_l.shape[::-1], criteria(cv2.TERM_CRITERIA_EPS cv2.TERM_CRITERIA_MAX_ITER, 100, 1e-5), flagscv2.CALIB_FIX_INTRINSIC) print(立体标重投影误差(像素):, ret_s)cv2.stereoCalibrate返回的第一个值就是重投影误差以像素为单位。这个值小于0.5说明标定质量合格大于1就要检查是否有照片模糊、角点提取失败或标定板未覆盖整个画面。CALIB_FIX_INTRINSIC表示只优化外参内参沿用单目标定的结果这样收敛更快更稳。标定时还有两个容易忽略的细节。一是把镜头对焦到实际工作距离后锁死不要让相机自动对焦否则焦距一直在变标定结果就废了二是手动把光圈固定自动曝光会导致不同亮度下标定结果不一致。4.2 立体匹配SGBM参数和视差图质量的关系标定完拿到内参和畸变系数后先对左右图做畸变校正再做立体校正让两路图像的极线对齐。校正之后同一目标在左右图里只存在水平方向的位移这就是视差。OpenCV里最常用的立体匹配算法是StereoSGBM参数调起来一度让人觉得是玄学但核心就那么几个import cv2 # 假设已经用mtx_l, dist_l, mtx_r, dist_r, R, T做完极线校正 sgbm cv2.StereoSGBM_create( minDisparity0, numDisparities64, # 必须是16的倍数决定可测的最近距离 blockSize11, # 必须是奇数块越大对纹理要求越低但越模糊 P18 * 3 * 11 ** 2, # 平滑惩罚的小值 P232 * 3 * 11 ** 2, # 平滑惩罚的大值P2建议为P1的4倍 disp12MaxDiff1, uniquenessRatio10, # 匹配唯一性越大越容易拒绝歧义匹配 speckleWindowSize100, # 去噪点窗口 speckleRange4, ) disparity sgbm.compute(gray_l, gray_r).astype(np.float32) / 16.0numDisparities决定视差搜索范围。范围越大能测的最近距离越小但计算量成倍增加。如果目标就在一两米内而你的基线又短视差可能高达几十像素64的范围会截断这时候要设成128或更大。blockSize决定匹配窗口大小窗口小对细节敏感但噪声大窗口大更平滑但会抹掉边缘。disp12MaxDiff1用来检查左右一致性不一致的像素视为遮挡区域置为无效值。uniquenessRatio如果太低纹理重复区域的匹配结果会非常毛糙太高则会让有效视差点变稀疏。调参顺序建议是先固定numDisparities和blockSize调P1/P2让视差图变平滑再用speckleWindowSize和speckleRange清掉孤立噪点。判断视差图好坏不要凭感觉直接打印几个已知距离的点位看视差是否符合预期。比如你站在3米远处摆一个物体找到物体中心点的视差用depth fx * baseline / disparity反算距离偏差在5%以内就是合格的。4.3 目标级别测距把YOLOv5检测框映射到深度图并取中位数检测和深度两条链路都通了最后一步是合流。这里最容易出问题的是坐标系对齐。深度图的分辨率和校正后的原始图像一致但YOLOv5的检测框是在letterbox缩放后的图上算出来的直接拿来框深度图必然错位。坐标还原是固定套路def letterbox_to_original(x1, y1, x2, y2, ratio, dw, dh): 把letterbox后的检测框还原到原图坐标 return (int((x1 - dw) / ratio), int((y1 - dh) / ratio), int((x2 - dw) / ratio), int((y2 - dh) / ratio))ratio、dw、dh是YOLOv5预处理时记录下来的缩放比例和padding偏移在inference阶段的输出里能拿到。还原后的框直接映射到深度图上然后取框内中心区域的深度中位数import numpy as np def estimate_distance(depth_map, box, margin0.3): depth_map: 深度图, 单位mm box: (x1, y1, x2, y2) 原图坐标系下的检测框 返回目标的估计距离(米) x1, y1, x2, y2 box w x2 - x1 h y2 - y1 # 只取检测框中心区域避开边框处的背景混合 cx1 int(x1 w * margin) cy1 int(y1 h * margin) cx2 int(x2 - w * margin) cy2 int(y2 - h * margin) region depth_map[cy1:cy2, cx1:cx2] valid region[region 0] # 无效点深度为0直接剔除 if len(valid) 0: return -1.0 # 表示没有有效深度 return float(np.median(valid) / 1000.0)为什么要取中心区域而不是整个框因为检测框边缘通常混合了背景和目标的过渡像素这些像素的深度值不是目标的真实距离拉低或拉高统计值。取30%到50%的中心区域能有效规避这个问题。为什么用中位数而不是均值SGBM算出来的深度图有离群噪点个别像素的视差会突然跳变导致深度值异常。均值对这类离群点非常敏感一个几百毫米的错误值就能把均值拉跑中位数把排序后正中间的那个值取出来稳定性好得多。如果你的目标一边在反光一边在阴影里视差图左侧可能大面积无效取均值会出现负值中位数不会。这套“检测框 中心区域 中位数”的组合是我在调试时反复对比后的结论也是源码里最值得借鉴的部分。5. 避坑手册双目测距最容易翻车的5个细节5.1 现象左右画面错位测出来的距离全是负值左相机的图像被当成右路输入右相机的图像被当成左路输入或者物理上两个摄像头的左右朝向装反了。立体匹配算法假设左图是参考帧右图是匹配帧如果输入反了算出来的视差为负深度公式直接给出负值看起来像是“目标在相机后面”。原因是摄像头索引顺序和物理位置不对应或者安装时左右放反。解决方法是先跑一个取流脚本把左右两路图像并排显示确认左图里目标在画面右侧、右图里同一目标在更靠右的位置。更严谨的做法是看一眼标定结果里的平移向量T的x分量正常安装下它应该接近正数或负数与左右相机的实际距离一致。发现反了就交换摄像头索引而不是在代码里硬改符号。5.2 现象近距离测得很准远距离误差成倍放大3米内误差±5厘米8米外误差直接到±1米以上看着像玄学其实是数学决定的。深度公式的误差和距离平方成正比视差多一个像素或少一个像素在远距离上就是几十厘米的偏差。这不是代码bug是系统的物理极限。解决思路有两个方向。硬件上加大基线视差变大单位视差的深度分辨率变高软件上则不要对远距离的视差做平滑滤波中值滤波和均值滤波会把边缘视差抹掉反而增加系统性偏差。还要注意远距离目标的检测框本身有抖动帧与帧之间的距离输出建议做时间滤波比如滑动窗口取中值能压掉相当一部分随机误差。如果目标在8米外而你的基线只有60毫米先别急着调参去算一下理论分辨率大概率会发现这个量程本来就是不合理的。5.3 现象检测框看着没问题测出来的距离和目标位置对不上YOLOv5画出的框稳稳框住目标但深度图上取到的区域根本不是目标所在的位置。这个现象在项目集成后最容易碰到原因也最隐蔽检测框坐标没有从letterbox坐标系还原回原图坐标系。解决方法是回看预处理代码YOLOv5在推断时把原图等比缩放到640分辨率再填充边缘检测框是在填充后的图像上生成的。取深度值之前一定要把ratio和pad偏移还原。有一个更省事的思路先确认深度图和原图分辨率一致然后直接把检测输出里的(x1, y1, x2, y2)经过还原公式再送入estimate_distance函数。如果懒得还原就不要用原图作为深度图参考而是把深度图也跟着letterbox到一起但这会让视差图的尺寸失真不推荐。5.4 现象标定重投影误差小于0.5像素但测距结果系统性地偏大或偏小重投影误差达标不代表标定没问题很可能是标定板的物理尺寸填错了或者棋盘格角点个数填错。常见做法是买现成的印刷标定板但自己用纸打印时打印缩放比例不对毫米单位的参考长度就错了整个空间尺度被均匀拉伸或压缩。这类系统性偏差在视差图上往往看不出来因为视差本身是对的错在把视差换算成深度时的基线或焦距标称值。解决方法是校准“标称基线”而不是盲目相信机械安装的尺寸。用卷尺量出目标到相机平面的真实距离和系统输出对比算出真实基线是多少把这个值回填到测距代码里。比如安装尺寸写的120毫米实测3米和5米两个距离反推出来的基线可能是118毫米直接替换即可。5.5 现象视差图上目标区域一片黑洞测距返回-1SGBM算不出视差的区域会标记为无效值在可视化里就是黑色。目标表面是纯色、低纹理区域或者严重反光时左右图的匹配窗口找不到可靠的对应点深度图自然就空了。这在高光车漆、白色墙面、深色衣服上非常常见。解决的思路是让深度信息更“鲁棒”。先把blockSize调大大窗口能抓住更大范围的纹理代价是边缘精度下降再把uniquenessRatio调低一点让匹配算法更容忍歧义。如果目标区域仍然大面积无效退而求其次只输出“最近有效深度”而不是拒绝整个目标。更彻底的做法是在硬件层改善补光或者用主动纹理投射但这对很多项目来说改动太大不划算。6. 验证你的测距精度拿尺子实测画误差曲线再调参6.1 最小验证流程固定相机选定5个距离点把相机固定在三脚架上用卷尺量出1米、2米、3米、5米、8米五个位置每个位置放一个目标物跑检测加测距连续记录50帧输出计算平均值和标准差。标准差超过这个距离的10%就说明视差图在时间维度上不稳定优先检查SGBM参数而不是检测端。例如3米处平均输出3.12米标准差0.1米说明系统精度约±10厘米符合大多数预警场景的要求。再把五个距离点的误差画成曲线如果误差随距离线性增长说明基线或焦距标称值有系统偏差如果误差不规则跳动先看检测框是否在目标边缘抖动再看SGBM的numDisparities是否把视差截断了。6.2 调参顺序和部署建议调参不要东一锤西一棒按顺序来先确认标定文件没丢重投影误差合格再调SGBM参数直到视差图在目标区域连续、无明显空洞最后调目标框的取深度区域比例。这个顺序反过来会非常痛苦框里取出来深度不对你会不知道该改检测还是改匹配。如果你想把模型训练成自己的目标类别训练前的准备工作也不复杂给目标标注几百张图把图像和标签按YOLO格式放好写一个data.yaml把类别和路径列清楚然后把/yolov5/train.py的--data指向它--weights用yolov5s.pt做迁移学习训练完再跑一遍上述的实测验证。需要特别提醒的是换了自己训练的数据集后置信度阈值可能要重新调预训练模型在COCO上0.5的阈值表现良好你自己的类别可能要降到0.3。在树莓派5这类边缘设备上部署时记得把模型换成yolov5s.torchscript或者yolov5s.engine纯CPU推理的帧率很低检测框会跳测距结果也会跟着抖这时候时间中值滤波的作用就很明显。我自己的一个习惯是每次改标定参数前把旧的标定结果和误差记录留一个副本。测距这类系统参数互相牵连改完没效果是常态有后悔药可吃才能放心试。这个方案是值得投入的只要你按第4章的流程把标定做扎实、按第5章的避坑清单排查一遍得到一个稳定输出距离的检测系统并不难。希望帮到你。本文还有配套的精品资源点击获取