YOLOv5单目测距：从检测框到距离计算的关键技术与避坑指南

简介YOLOv5结合单目测距的Python项目面向计算机视觉学习者和PyTorch开发者解决单个摄像头估计物体距离的实际问题。模型以实时性能与高精度见长适用于自动驾驶、智能监控、图像分析等场景整体原理相对简单适合具备一定深度学习基础、希望上手项目实践的读者。压缩包共132个文件主体为34个py源码与40个yaml配置另有pt权重文件、ipynb示例笔记、sh运行脚本及md说明文档覆盖模型结构、训练参数、推理逻辑与运行环境配置资源包约13.91MB已有2293人学习。项目系统梳理了YOLOv5的网络结构、锚框机制、数据增强、训练流程与NMS后处理等核心要点同时给出单目测距的完整思路包括物体高度估计、相机参数标定与三角测量距离计算。读者可对照代码理解目标检测与单目几何的融合方法将预训练模型加载、推理与结果可视化串成完整流程整体是一份兼顾算法原理与工程落地的实用项目。1. 单目测距为什么“近大远小”不能直接换算成米单目测距看起来有直觉支撑近大远小人眼能估距离摄像头为什么不行但真正把一个像素高度换算成米的不是“感觉”而是相似三角形——检测框在图像里的高度 h、目标真实高度 H、相机焦距 f像素单位三者凑出一个三角形距离 d H·f / h。这个公式简单到一行就能写完可它恰恰是整个单目测距里最容易翻车的地方h 来自目标检测的输出f 来自相机标定H 来自对目标的先验设定三个来源各带一套误差任何一个出错距离都会被反比例方式放大。搞懂这条链路的每一环比背下公式重要得多这也是为什么市面上的测距 demo 看起来“原理简单”落到真实场景却永远差一截。2. YOLOv5 的输出张量测距真正拿到的输入是什么很多人写测距代码时直接拿results.xyxy[0]里的(x1, y1, x2, y2)去算高度YOLOv5 内部是什么结构完全是个黑匣子。但距离误差的源头恰恰藏在这个黑匣子里。检测框是从特征图上的预测张量一步步解码来的框的坐标、高度、置信度最初都是一些分布在网格上的数值理解了张量结构才理解“框高 h”这个关键输入的脾气。2.1 从 640×640 到 (1, 25200, 85)三个检测头的输出结构以 YOLOv5 v6.1 为例输入 640×640 的图像Backbone 提取特征后NeckPANet会输出三个不同尺度的特征图分别对应 stride 8、16、32。stride 8 的特征图是 80×80负责小目标stride 16 是 40×40负责中目标stride 32 是 20×20负责大目标。每个网格点上预置 3 个锚框所以总的预测数这样算# 三个特征图的网格数之和再乘每格锚框数 num_anchors 3 grid_cells 80 * 80 40 * 40 20 * 20 # 6400 1600 400 8400 total_predictions grid_cells * num_anchors # 25200每个预测向量包含 85 个数值(x, y, w, h)四个坐标参数1 个目标置信度以及 COCO 数据集的 80 个类别分数。推理时 v6.1 会把三个检测头的结果拼成一个[1, 25200, 85]的张量这就是 YOLOv5 前向推理的直接产出。值得说明的是这个 25200 不是随便定的84 个格子每格预测 3 个框意味着同一目标会被很多邻近网格重复预测后续必须有 NMS 来去重。测距代码拿到的是经过 NMS 后的最终框但你要清楚这个框最初是从 25200 个候选里筛出来的它的“坐标精度”受限于特征图分辨率不是像素级的精确分割。2.2 解码、置信度与 NMS哪些框才有资格参与测距模型输出的 85 维向量是编码状态必须解码成真实坐标。v6.1 的 Detect 头解码逻辑大致是这样# 以 YOLOv5 v6.1 Detect 头为原型简化后的解码流程 import torch def decode_prediction(pred, anchors, stride, nc80): # pred 形状: [B, 3, ny, nx, 85]其中 3 是锚框数 # 把 85 维拆成 坐标(4) 目标置信度(1) 类别分数(80) xy, wh, conf torch.split(pred, (2, 2, nc 1), dim-1) # 中心点坐标sigmoid 后乘 2 再减 0.5让中心点能偏移到相邻网格 xy xy.sigmoid() * 2 - 0.5 # 宽高sigmoid 后平方再乘 2再乘以锚框尺寸做基准缩放 wh (wh.sigmoid() * 2) ** 2 * anchors # 加上网格偏移乘以 stride 换算回输入图像的像素坐标 xy (xy grid) * stride return xy, wh, conf这个解码有两个关键设计中心点用sigmoid() * 2 - 0.5是为了让预测中心不局限于当前网格内部可以覆盖网格边界附近的物体宽高用(sigmoid() * 2) ** 2 * anchors则是以锚框为基准让预测的宽高始终处于一个可控范围内避免训练初期梯度爆炸。这些细节决定了框的稳定性——而框的稳定性直接决定后面测距的稳定性。解码之后程序按置信度阈值过滤再做 NMS 去掉重叠框。测距场景一般只关心特定类别比如行人、车辆类别过滤这一步很重要因为 80 个类别共享一套锚框不同类别的高宽比差异极大如果不按类别筛容易把误检的框也拿去做距离计算。2.3 检测框质量如何传导到距离误差这里要建立一个认知YOLOv5 的边框回归目标是最优 IoU 框不是物理边缘的精确拟合。目标在图像里只有十几个像素高时框的高度天然有 ±1 像素的抖动。这 1 个像素在检测任务里无伤大雅但在距离计算里会被放大——因为距离公式的分母是 hh 越小同样的像素抖动造成的距离变化越大。距离 80 米处的行人检测框高度可能只有 20 像素左右框高跳 1 个像素对应距离就是好几米的变化。这就是为什么同一帧图像、同一个模型有人能算出稳定距离有人算出来像随机数——问题往往不在模型而在你对“框高 h 不可控”这一点有没有准备。3. 相似三角形与相机内参一个像素高度怎么变成物理距离上一章说了检测框的来源现在进入测距的核心几何。很多人以为“标定”就是填几个数其实焦距 f、主点 cx/cy、像素尺寸这些参数决定了同一张图里不同的目标位置会得到完全不同的距离结果。这一章把针孔相机模型、高度先验和标定流程串起来讲清楚。3.1 针孔相机模型与焦距的像素单位先看基础模型。一个高为 H 的物体距离相机光心 d经过针孔成像在像平面上占据的高度 h 满足h / f H / d整理得到测距公式d H * f / h这个公式里的 f 必须是以像素为单位的等效焦距不是镜头包装上的毫米焦距。实际相机中物理焦距 f_mm 除以每个像素的物理尺寸 sx才得到像素焦距fx f_mm / sx。竖直方向同理有 fy f_mm / sy。由于像素往往不是严格正方形fx 和 fy 会有细微差别。用检测框的像素高度测距时应该用 fy因为 h 是图像竖直方向的高度。用 fx 会引入像素宽高比的偏差这在畸形标定参数下尤其明显。# 测距核心公式height_px 来自检测框 def estimate_distance(height_px: float, real_height: float, fy: float) - float: # 相似三角形距离 真实高度 * 焦距 / 图像高度 return real_height * fy / height_px这个公式只有一行但使用条件极其苛刻假设目标垂直于相机光轴方向假设目标底部没有遮挡假设相机没有俯仰角。任何一个假设被破坏计算结果就偏离真实值。3.2 高度先验与距离求解公式只有一行前提有一箩筐H 从哪来典型做法是给每个类别一个固定先验行人按 1.7 米、小轿车按 1.5 米、公交车按 3 米。这个“按类别取平均身高”的做法是工程上最常见的但它天然带误差。行人实际身高从 1.5 到 2.0 米先验取 1.7 米时最大相对误差约 15%这个误差会线性传导到距离上——测 50 米处的人可能差 7 米。这里有一个常见的误区有人试图用目标的宽度替代高度认为宽度先验更稳定。实际恰恰相反同样的目标在不同视角下宽度变化剧烈车辆侧面和正面的宽度差异可以超过一倍。而目标高度在竖直方向受视角影响较小所以“高度优先”是更合理的选择。但高度先验的缺陷也很明显——它隐含了一个假设目标在地面上是直立的且相机光轴与地面平行。3.3 标定与内参重映射fx、fy、cx、cy 怎么进公式获取准确 fx、fy 的标准做法是张正友棋盘格标定OpenCV 里流程固定采集不同角度的棋盘格照片检测角点再传入calibrateCamera得到内参矩阵。import cv2 import numpy as np # 假设已经用 1920×1080 的图完成标定得到如下内参单位像素 K np.array([[fx, 0, cx], [0, fy, cy], [0, 0, 1]], dtypenp.float64) # 若推理时把图像 resize 到 640×640内参必须按比例重映射 scale 640 / 1920 fx_resized fx * scale fy_resized fy * scale很多人在这里踩坑标定用的是原分辨率推理时为了速度把图缩到 640×640却直接拿原始内参去算距离导致整体距离系统性偏小或偏大。内参是“以像素为单位的”图像尺寸变了内参必须跟着变。另一个容易忽略的是主点 cx/cy。测距公式只用到了 fy没有显式用到 cx/cy但这不代表主点无关——主点影响的是目标在图像中的位置进而影响镜头畸变程度和目标是否被完整捕捉。如果目标是画面正中央的物体直接用简单公式误差不大目标在画面边缘时畸变和透视误差都会显著上升。3.4 地面假设与“框底边”约束摆脱高度先验的另一条路固定高度先验的最大问题是 H 不准确。工程上有一条替代路线假设目标站在地面上利用目标检测框的底边在图像中的位置来推算距离完全不依赖 H。这个思路基于地平线约束如果知道了相机距离地面的高度 H_cam 和相机俯仰角那么图像中任意一个“贴近地面”的点都能通过地面平面与像平面的交线解出距离。常见的落地方案是离线拟合在几个已知距离处放置目标记录检测框底边的 y 坐标与真实距离的对应表再拟合出一条曲线或单应矩阵。这样“测距”就变成了“查表”模型不用知道目标的真实高度只要框底边贴近地面即可。这个方案在自动驾驶和安防场景里很常见但它要求相机安装位置固定一旦俯仰角被碰动整条对应关系作废需要重新拟合。4. 数据标签与回归路线距离要不要交给神经网络自己学几何法虽然优雅但它的精度上限受标定和先验限制。于是有人想到能不能让神经网络直接从图像中回归出距离这条路看起来更“智能”实际做起来要面对标签怎么来、回归目标怎么定义、模型会不会像黑匣子一样不可控这些问题。这一章把数据、标签和回归路线梳理出边界。4.1 标注距离从激光雷达、GPS 到人工测量监督学习需要“图像 距离”的配对数据。现实中距离标签的来源大致有三种第一种是激光雷达或毫米波雷达。点云投影到图像上取检测框中心对应的那个点云的距离作为标签。要注意时间同步问题图像帧和雷达帧的时间戳若不对齐高速运动目标会有一两米的系统性误差。第二种是 RTK 定位。这在车端场景常见车辆位置已知目标位置已知两者相减得到距离但只对静态目标有效。第三种是人工测量。在场地里划好距离线让目标站在已知位置拍摄这是最准的但标注成本随距离点数线性增长。标签的质量直接决定回归模型的精度上限。常见的做法是先用几何法粗算一个距离再人工修正但这会让模型学到几何法的系统性误差属于自己给自己喂噪声。4.2 回归目标的三种形态直接回归距离、归一化深度、3D中心点确认了标签来源后下一个问题是如何定义回归目标。三种常见形态各有优劣# 形态一直接回归距离最简单的全连接头 # 输入检测框的像素高度、类别先验、目标在图像中的位置 # 输出距离 d损失用 L1 或 Smooth L1 features torch.cat([log_height_px, class_prior_log, center_offset], dim-1) d_pred fc_head(features) # 标量距离 # 形态二回归几何公式的残差混合方案 # 先用几何公式算一个初始距离 d_geo让网络只学修正量 # 优点网络只需要学残差数据量需求大幅下降 residual fc_head(features) d_pred d_geo * torch.exp(residual) # 乘性残差保证输出恒为正直接回归距离的缺点很明显模型要同时学到“近大远小”的几何关系又要学到不同类别的先验数据量不够时远处样本表现很差。归一化深度是把距离除以一个最大值比如 100 米让输出落在 0 到 1 区间能稳定训练但实际部署时误差是绝对的还是相对的需要想清楚。第三种形态是回归 3D 中心点也就是把目标在相机坐标系下的 (x, y, z) 都预测出来再算欧氏距离。这本质上走向了 3D 目标检测需要额外预测目标的朝向角和物理尺寸模型复杂度直线上升。这类方案在工业界的 3D 检测任务里比较多见但受害者是标注成本——3D 标注框比 2D 框贵一个数量级。4.3 几何法与回归法的分工什么场景选哪条路把两条路线放在一起看边界很清楚维度几何法端到端回归法距离标注需求不需要需要大量配对数据换相机后的适配重新标定内参即可需要重新采集数据可解释性高公式透明低黑匣子对先验误差的鲁棒性差H 不准就不准较好能学统计规律远距离表现受像素高度限制受训练数据分布限制落地速度快慢实际做的时候我一般会这么理解“原理比较简单”这句话它说的不是测距简单而是几何部分简单。真正的复杂度全在工程环节——标定准不准、先验选得合不合理、输入预处理有没有破坏内参假设。上面表格里“换相机重新标定即可”这一条是几何法最大的优势因为很多测距需求场景本身就是固定机位标定一次能跑很久而回归法一旦换场景就要重新采数据调试周期按周算。5. 常见问题与避坑为什么你测出来的距离总是飘前面几章把原理讲完了这一章专门记录我在复现这类“检测 测距”项目时反复踩过的坑。每一条都是先看到现象再定位到原因最后给出解决方案。这些坑不会都发生在同一台机器上但只要你部署到真实场景大概率会撞上一两个。5.1 检测框抖一下距离跳 20%现象目标静止不动检测框在帧间只有一两个像素的抖动但计算出的距离在 40 米和 48 米之间来回跳看起来像随机噪声。原因距离公式 d H·f/h 对 h 的导数是非线性的h 越小同样的像素误差放得越大。20 米处的行人框高约 50 像素抖动 1 像素对应约 2% 的距离波动80 米处框高约 17 像素同样抖动 1 像素就是接近 6% 的波动。目标检测的边框回归本身就有亚像素级不稳定性这是模型特性不是 bug。解决不要在原始距离序列上做简单平均先把 h 做时间维度的平滑再代入公式计算。工程上常见的是对 h 做 EMA指数滑动平均或中值滤波抖动能压掉大半。更稳妥的做法是平滑距离输出本身但要注意平滑系数要随帧率调整30 帧和 15 帧的系数不能一样。5.2 目标没完整入画测距翻倍现象行人从画面边缘走入时检测框只有半个身体此时输出的距离突然比真实值大得多甚至超过一倍。原因框底边在画面之外时框高 h 被截断只有真实高度的一半公式分母减半距离直接翻倍。YOLOv5 的检测框在目标被截断时会尽量贴合可见部分但它不知道目标剩下半截在哪。解决加一个约束条件框的底边距离图像下边缘小于某个阈值时认为目标是“不完整入画”直接丢弃这一帧的测距结果或者用前一帧的距离值保持输出。判断条件不要只看底边坐标还要考虑目标类别——行人在画面下沿被截断很常见车辆只有底部很小区域被遮住时影响不大因为车的高度方向不一定从底边算。5.3 换了分辨率整条距离曲线平移现象同一段视频用 640×640 推理结果正常换成 1280×1280 推理后所有距离整体变大一截或缩小一截且远近目标的偏差比例不一致。原因内参没有随输入分辨率重映射。标定得到的内参是“像素单位”如果标定时的原图是 1920×1080推理时缩到 640×640fx 和 fy 需要乘以同一个缩放比例。更隐蔽的是如果预处理里先做了 Letterbox 填充图像是缩放到 640×640 再补灰边那内参缩放比例还要考虑灰边的影响。解决把内参重映射和数据预处理放在同一个函数里每次修改分辨率必须同步修改内参。我的调试习惯是写一个自检函数输入一张已知距离的实拍图打印出“当前分辨率、当前 fx/fy、计算距离、真实距离”四个值任何预处理改动后都跑一遍这个自检比查半天日志快得多。5.4 广角镜头边缘针孔模型失效现象目标位于画面中心附近时测距还算准移到画面边缘后距离偏差明显变大有的偏近有的偏远没有固定规律。原因针孔相机模型只对无畸变镜头成立。广角镜头或运动相机有显著的桶形畸变画面边缘的像素位置被扭曲检测框的高度 h 不再满足相似三角形关系。标定能修正这个问题但前提是推理时先对图像做去畸变处理。解决推理前调用cv2.undistort或等效的去畸变处理让送入 YOLOv5 的图像接近针孔模型。注意去畸变也会改变图像尺寸和内容内参要使用cv2.getOptimalNewCameraMatrix返回的调整后内参不能拿原始内参继续用。如果目标一直是画面中心区域可以直接忽略边缘误差但要清楚这个适用边界。5.5 相机俯仰角一变所有距离一起错现象设备安装时测距正常过了几天或换了个安装位置后同样的目标在同样的图像位置距离却整体偏差。原因直接测距公式隐含了相机光轴与地面平行的假设。一旦相机有俯仰角图像中的目标位置和实际距离的关系会偏离相似三角形的理想条件。俯仰角 3 度对 50 米外的目标就能造成数米的误差且这个误差随距离非线性变化。解决如果是固定安装场景离线标定一次俯仰角把地面平面约束加进公式如果是可动摄像头几何法基本不可用只能切换到 3D 目标检测或用双目方案。判断方法很简单在画面不同位置放两个距离已知的目标如果近处准、远处偏大概率是俯仰角问题而不是内参问题。6. 设计取舍几何先验、误差放大与工程上限6.1 误差放大倍率远处一个像素值多少米把测距公式对 h 求导能得到一个很直观的结论∂d/∂h -H·f/h² -d/h。像素高度 h 越小d 越大分母越小导数值越大——同样的 1 像素误差在远处被放大成好几米。这不是某个环节没做好而是单目测距的物理天花板远处的目标本身就只占几个像素信息量不够任何算法都救不回来。所以评估一个测距方案时先算一下目标在图像里占多少像素如果只有十几个像素盲目追求“更准”没有意义。6.2 怎么权衡我的选择与一条血泪教训几何法和回归法之间的取舍核心指标是数据成本和稳定性。我的选择标准是没有高质量距离标注数据时老老实实用几何法把精力花在标定和安装上有激光雷达或丰富标注数据时优先做“几何公式 残差回归”的混合方案让网络只学修正量而不是从零学物理。纯端到端回归测距看起来美好但数据偏差会让模型在不同场景之间彻底失效调起来极其折磨。最后说一条我自己的血泪经验。某次调试一个固定机位的测距 demoA同学在预处理里加了 Letterbox 逻辑图像从 1920×1080 压到 640×640但标定内参按老流程从原图直接取的没有乘缩放比例。结果所有距离系统性偏大 3 倍查了一个晚上最后把预处理前后的图像对应像素点一对比才发现是分辨率换算漏了。从那以后我每次做测距实验都强制打印“标定分辨率 / 当前分辨率 / fx / fy”四个日志并且固定用一张已知距离的实拍图做回归测试任何预处理改动都必须先过这一关。这个习惯帮我挡掉过很多次翻车也希望帮到你。本文还有配套的精品资源点击获取