简介这份下载包围绕Python与OpenCV的单目视觉测距展开面向计算机视觉入门者以及需要快速实现已知物体距离估算的开发者重点解决相机到目标物体距离的自动计算问题。包内共2个文件包含1个Python脚本与1个Markdown说明文档压缩包约2KB脚本承载测距算法实现说明文档交代依赖包、用法及图像列表初始化位置。已有761人学习下载适合作为轻量级参考材料。读者可从中获得基于三角形相似度的完整测距思路先利用已知物体的实际宽度和标定距离求取焦距再在后续图像中检测目标像素宽度并换算实际距离理解像素尺度到物理尺度的映射过程。项目结构精简便于本地调试和按需替换检测对象也可作为学习OpenCV图像处理与相机标定的示例脚本适合尺寸测量、避障辅助等入门项目参考。1. 单目测距这件事为什么一张图也能估出相机到物体的距离一个做分拣小车的朋友非要上双目我让先拿一颗普通 USB 摄像头试了半天把一张贴纸贴在目标盒上量好真实宽度标定一次焦距30 到 120 厘米的量程内读数能稳在 ±3 厘米。OD 这套代码干的就是这件事——OpenCV Python用三角形相似把“像素宽度”换算成“物理距离”不用深度相机也不用训练模型。它适合的人很具体手上只有单目摄像头、要给小车或机械臂加一个粗略测距能力的人想把相机内参、焦距、像素当量这些概念真正落到代码里的人以及算力和预算都紧、目标尺寸又相对固定的场景。先泼一盆冷水单目测距的精度瓶颈几乎从来不在公式而在标定准不准、检测框稳不稳。这两件事没做好公式推得再漂亮读出来的数字也只是玄学。2. 项目骨架与技术栈目录、依赖和一次运行的完整路径拿到一份视觉 Demo我习惯先不跑先看目录和入口。因为测距类项目的坑大多埋在“参数从哪来、在哪改、什么时候失效”这三件事上代码本身反而简单。这一章先把骨架摊开。2.1 技术栈与依赖清单整套东西只依赖 OpenCV 和 NumPy没有深度学习框架的硬绑定这一点对新手很友好——装完就能跑不用先跟 CUDA 较劲。OpenCV 在这里承担四件事取视频流VideoCapture、跑检测器Haar 级联或者 dnn 模块加载模型、画框写字rectangle/putText、鼠标交互取点setMouseCallback。NumPy 负责数组切片和中值计算argparse 负责命令行切换输入源。依赖版本建议在这套代码里干什么opencv-python4.5 及以上取流、检测、绘制、鼠标取点numpy1.21 及以上像素宽度计算、多帧中值、数组操作argparse标准库图片 / 视频 / 摄像头三种输入统一入口imutils0.5.x可选按固定宽度缩放帧保证分辨率一致# 最小可跑环境Python 3.8 以上 python -m venv venv source venv/bin/activate # Windows 下是 venv\Scripts\activate pip install opencv-python numpy imutils提示如果后面想换 ArUco 标记做参照物要装opencv-contrib-python而不是opencv-python两个包同时装会互相覆盖这个坑我踩过一次检测器直接报“函数不存在”。2.2 目录结构与模块职责我一般会把“相机相关的常量”和“业务逻辑”彻底分开因为标定参数是会反复调的混在业务代码里改一次要翻三个文件。od/ ├── main.py # 入口解析参数、开流、串起检测→测距→绘制 ├── config.py # 所有标定量和阈值改参数只动这里 ├── calibrate.py # 标定脚本反解焦距 F输出后手写回 config ├── core/ │ ├── detector.py # 检测层封装对外只吐 (x1, y1, x2, y2) │ ├── distance.py # 纯计算像素宽度 → 物理距离 │ └── smoothing.py # 多帧中值压住读数跳动 ├── models/ │ └── haarcascade_frontalface_default.xml # 附带的 Haar 模型 ├── data/ │ └── samples/ │ └── calib_60cm.jpg # 标定用的那张已知距离照片 └── requirements.txtcore/distance.py是整个项目里唯一“没有副作用”的文件——不进不出图像只做数学这种模块最好写单元测试也最容易在换检测器时原样复用。core/detector.py的职责是把不同检测器的输出格式统一Haar 吐的是(x, y, w, h)YOLO 吐的是归一化的(cx, cy, w, h)上层不该关心这些差异。2.3 一次运行的完整链路参数覆盖顺序建议做成“命令行 config 默认值”这样调试时不用反复改文件。# config.py # 跟相机、标定强相关的量集中在这里 KNOWN_WIDTH_CM 14.0 # 参照物真实宽度厘米这里用一个直径 14cm 的圆盒 KNOWN_DISTANCE_CM 60.0 # 标定时相机到参照物的真实距离 FOCAL_LENGTH_PX 0.0 # calibrate.py 反解出来后写回这里单位是像素 SMOOTH_WINDOW 7 # 中值窗口越大越稳但滞后也越明显 MIN_BOX_PX 30 # 小于这个像素宽度的框直接丢近处才有意义# main.py 的参数部分 import argparse def build_parser(): p argparse.ArgumentParser(description单目测距已知宽度参照物 标定焦距) p.add_argument(-i, --input, default0, help0 表示默认摄像头也可以传图片或视频文件路径) p.add_argument(-w, --known-width, typefloat, defaultNone, help参照物真实宽度单位 cm传了会覆盖 config) p.add_argument(-f, --focal, typefloat, defaultNone, help标定好的焦距像素传了会覆盖 config) p.add_argument(--show-fps, actionstore_true, help左上角叠加帧率) return p-i用一个参数吃掉三种输入源是因为测距的调试流程天然是“先用图片确认参数对不对再用视频看稳定性最后接摄像头”。如果一开始就只支持摄像头每次验证都得举着参照物站在镜头前效率极低。--known-width和--focal做成可覆盖是为了能在一台机器上维护多套参照物参数比如盒子一套、人脸一套。链路本身很短取一帧 → 转灰度Haar 需要→ 检测拿到 bbox 列表 → 对每个框算像素宽度 → 代入公式算距离 → 送进平滑器 → 画框写字 → 下一帧。真正需要动脑的是中间那两步第 3 章展开。3. 核心算法拆解三角形相似与像素宽度怎么落到代码3.1 相似三角形的三个量W、P、F相机成像可以简化成小孔模型物体在真实世界里宽度为 W距离镜头 d它在成像平面上的宽度是 P 个像素镜头到成像平面的距离就是焦距 f。这两个三角形相似于是有d / W f / P整理得到d (W * f) / P。这里最容易翻车的地方是单位。f 和 P 必须是同一套单位——都按像素算所以 f 在这个公式里叫“像素焦距”它的数值往往是几百到一两千跟镜头标称的 3.6mm 完全不是一个东西。W 和 d 用同一套物理单位即可代码里统一用厘米别一半厘米一半米。所以这个项目真正需要你提供的只有两个数参照物的真实宽度 W和一个标定出来的 F。剩下的全靠检测框的像素宽度 P。P 越准读数越准P 抖一下d 就跟着抖一下而且因为 P 在分母上距离越近 P 越大、误差越小距离越远误差放大得越厉害。3.2compute_distance与像素宽度提取# core/distance.py def pixel_width(x1, y1, x2, y2): 取外接矩形宽、高里较大的那个作为像素宽度。 参照物正面摆放时宽高等价侧向或被部分遮挡时取大值更抗干扰。 return max(abs(x2 - x1), abs(y2 - y1)) def compute_distance_cm(known_width_cm, focal_px, px_width): d W * F / P单位统一为厘米 if px_width 0: return None # 框塌了返回 None别让除零把整条链路带崩 if focal_px 0: return None # 焦距没标定就别硬算算出来的数是假的 return (known_width_cm * focal_px) / px_widthpixel_width取max而不是固定用宽度是因为不同检测器给的框贴合度不一样Haar 给的框偏紧YOLO 的框偏松人脸侧转时宽度会缩、高度基本不变。取大值相当于在两种维度里挑一个更“没被压扁”的代价是遇到细长物体时读数会偏小所以这个函数对参照物的形状有要求——接近方形或圆形最稳。compute_distance_cm里两个None分支看着啰嗦但这是血泪经验。早期版本没判focal_px标定文件忘了改F 还是 0结果每帧都算出 0 厘米画面上全是“0.0cm”排查了半小时才发现是参数没写回。3.3 检测层封装Haar 和 YOLO 都能插# core/detector.py import cv2 class HaarDetector: def __init__(self, xml_path, scale1.1, min_neighbors5): self.cascade cv2.CascadeClassifier(xml_path) if self.cascade.empty(): raise IOError(f分类器没加载上{xml_path}) self.scale scale self.min_neighbors min_neighbors def detect(self, frame_bgr): gray cv2.cvtColor(frame_bgr, cv2.COLOR_BGR2GRAY) gray cv2.equalizeHist(gray) # 光照不匀时这一行能救回不少漏检 rects self.cascade.detectMultiScale( gray, scaleFactorself.scale, # 每层金字塔缩放比例1.1 是精度和速度的折中 minNeighborsself.min_neighbors, # 邻域阈值调大误检少、漏检多 minSize(40, 40) # 太小的框不参与省算力也省得刷屏 ) # 统一成 (x1, y1, x2, y2)上层不用关心是哪家检测器 return [(x, y, x w, y h) for (x, y, w, h) in rects]scaleFactor从 1.1 调到 1.05检测会变慢但小目标更容易被找到minNeighbors从 5 调到 8误检明显减少代价是侧脸、遮挡时容易漏。这两个值不是拍脑袋定的要结合你的参照物尺寸和光照条件调。minSize很关键——远处物体的框本来就小像素宽度只有十几个像素时量化误差能占到 10% 以上算出来的距离基本没有参考价值不如直接不报。换 YOLO 只需要写一个同样带detect(frame_bgr)方法的类把输出转换成(x1, y1, x2, y2)四元组main.py一行都不用改。这是我坚持把检测和计算分开的唯一理由测距的部分是死代码检测的部分是活代码活的那部分一定会换。3.4 主循环把上面几步串起来# main.py 的运行时核心 import cv2, imutils from core.detector import HaarDetector from core.distance import pixel_width, compute_distance_cm from core.smoothing import MedianSmoother import config detector HaarDetector(models/haarcascade_frontalface_default.xml) smoother MedianSmoother(windowconfig.SMOOTH_WINDOW) cap cv2.VideoCapture(0) while True: ok, frame cap.read() if not ok: break # 固定宽度缩放保证运行分辨率和标定时一致这是焦距能复用的前提 frame imutils.resize(frame, width640) for (x1, y1, x2, y2) in detector.detect(frame): px pixel_width(x1, y1, x2, y2) if px config.MIN_BOX_PX: continue dist compute_distance_cm(config.KNOWN_WIDTH_CM, config.FOCAL_LENGTH_PX, px) if dist is None: continue smoother.push(dist) val smoother.value() cv2.rectangle(frame, (x1, y1), (x2, y2), (0, 255, 0), 2) cv2.putText(frame, f{val:.1f} cm, (x1, max(y1 - 10, 15)), cv2.FONT_HERSHEY_SIMPLEX, 0.6, (0, 255, 0), 2) cv2.imshow(OD, frame) if cv2.waitKey(1) 0xFF ord(q): break cap.release() cv2.destroyAllWindows()imutils.resize(frame, width640)这一行是强制项不是优化项。焦距 F 是像素单位跟分辨率死死绑在一起标定时用的 640 宽运行时如果变成 1280 宽同一物体在图像上占的像素数翻倍算出来的距离就只剩一半。我见过有人把这个当成“算法不准”其实是分辨率悄悄变了。val取了平滑后的值而不是当帧的dist是因为 Haar 的框天生会在相邻几帧之间跳一两个像素近距离时这点跳动能造成好几厘米的读数摆动。3.5 平滑滑动中值而不是滑动平均# core/smoothing.py from collections import deque import numpy as np class MedianSmoother: 滑动窗口取中值。距离读数抖是常态 均值会被偶发的离群值带偏中值更抗跳变。 def __init__(self, window7): self.buf deque(maxlenwindow) # 超过窗口长度自动丢掉最旧的 def push(self, value): self.buf.append(value) def value(self): if not self.buf: return None return float(np.median(self.buf))deque(maxlenN)省掉了手写pop(0)窗口固定为 7 意味着大约 0.2 秒的滞后30fps 下对静态测距完全够用对快速移动的物体就不合适了那时候要换成卡尔曼滤波或者把窗口缩到 3。用中值不用均值是因为检测框偶尔会因为遮挡突然塌掉一半产生一个远小于真实值的离群点均值会被这一个点拉偏好几帧中值直接把它挤出去。4. 标定与参数整定焦距 F 和已知宽度怎么测才靠谱4.1 反解焦距F P × d / W公式d W * F / P里W 是你用尺子量的P 是图像上量的d 是卷尺量的只有 F 未知。所以标定的本质是把参照物摆在一个已知距离上量出它的像素宽度反解 F。# calibrate.py def focal_from_sample(known_width_cm, measured_px, known_distance_cm): 由 d W*F/P 反解F P*d/W结果单位是像素 if known_width_cm 0 or measured_px 0: raise ValueError(真实宽度和像素宽度都必须大于 0) if known_distance_cm 0: raise ValueError(标定距离必须大于 0) return (measured_px * known_distance_cm) / known_width_cm标定距离建议选在量程的中段比如量程 30~120 厘米就选 60。因为在近端标定远端误差会被放大得很难看在远端标定近端又容易因为框贴边导致像素宽度量不准。中段标定是最稳的。另外参照物要正对镜头、居中放置别贴着画面边缘。镜头有畸变越靠边缘像素当量越不准用边缘的数据标出来的 F 会让整个画面都偏。4.2 用鼠标量像素宽度手写坐标容易错直接点两下最省事。# calibrate_mouse.py import cv2 from core.distance import pixel_width from calibrate import focal_from_sample points [] def on_mouse(event, x, y, flags, img): if event cv2.EVENT_LBUTTONDOWN and len(points) 2: points.append((x, y)) cv2.circle(img, (x, y), 4, (0, 255, 0), -1) cv2.imshow(calibrate, img) img cv2.imread(data/samples/calib_60cm.jpg) cv2.imshow(calibrate, img) cv2.setMouseCallback(calibrate, on_mouse, img) cv2.waitKey(0) (x1, y1), (x2, y2) points px pixel_width(x1, y1, x2, y2) # 复用同一套像素宽度逻辑避免两处口径不一致 F focal_from_sample(known_width_cm14.0, measured_pxpx, known_distance_cm60.0) print(f像素宽度{px}px, 焦距 F{F:.1f}px)注意这里刻意复用了pixel_width而不是手写x2 - x1。标定和运行必须用同一套取宽度的规则否则标出来的 F 和运行时算的 P 口径不一致误差会系统性地偏一个方向——这种偏差最难查因为每一帧都错得一样多。4.3 参数表与整定顺序参数类型怎么定调错的后果KNOWN_WIDTH_CM物理量卡尺或卷尺量参照物最宽处整体读数等比偏移KNOWN_DISTANCE_CM物理量镜头到参照物的直线距离F 反解错误全量程偏移FOCAL_LENGTH_PX反解得出标定脚本输出后写回 config为 0 时全部返回 NoneSMOOTH_WINDOW整数静态场景 7动态场景 3太大滞后太小抖动MIN_BOX_PX整数按最远可用距离的像素宽度定太小则远端数据全是噪声整定顺序别乱先确认分辨率决定 F 的量纲→ 再标定 F → 再定 MIN_BOX_PX → 最后调 SMOOTH_WINDOW。反过来做前面每改一次都要重新标定。4.4 用误差表验证标定质量标定完别急着接业务先在 40、60、80、100、120 厘米五个点上各测十帧取中值跟卷尺读数对一下。真实距离实测中值绝对误差相对误差40 cm41.2 cm1.2 cm3.0%60 cm60.4 cm0.4 cm0.7%80 cm78.1 cm-1.9 cm2.4%100 cm103.5 cm3.5 cm3.5%120 cm126.8 cm6.8 cm5.7%这张表能看出两件事60 厘米附近误差最小说明标定点选对了远端误差单调变大这是像素宽度量化误差被分母放大的必然结果不是代码写错了。远端如果有明确上限就把MIN_BOX_PX卡死让超出量程的读数直接不输出比输出一个错得离谱的数字强。5. 避坑与排查误差翻倍、距离跳变的几个真实原因5.1 物体左右移动读数跟着变现象参照物在同一距离上左右平移读数能有 ±8 厘米的漂移。原因多数检测器给的是轴对齐外接矩形物体一旦有轻微旋转或者被部分遮挡框的宽高比就变了pixel_width取到的值跟着变距离自然跟着变。这不是公式的问题是“用一个矩形去描述一个三维物体”的固有缺陷。解决把参照物做成接近方形的、正面朝向镜头并且限制在画面中央区域使用要求更高的话换成圆形参照物加霍夫圆检测用直径替代框宽对旋转不敏感。5.2 换了分辨率所有读数全部翻倍或减半现象本地调试一切正常部署到另一台机器上距离读数直接差了一倍。原因F 是像素单位和分辨率强绑定。标定用的是 640 宽运行用了 1280 宽同一个物体的像素宽度翻倍d W*F/P里分母翻倍结果减半。解决在main.py里强制imutils.resize(frame, width640)并且在启动时打印一次实际帧尺寸跟标定时对一眼。# 启动自检两行代码省掉半小时排查 h, w frame.shape[:2] print(f[check] 运行分辨率 {w}x{h}标定分辨率 640x480必须一致)5.3 近处准远处飘得没边现象50 厘米内误差 2 厘米以内1.5 米外读数能差 20 厘米。原因像素宽度量化误差是固定的±1 像素但它在分母上距离越远 P 越小相对误差就被放大。P140 时 1 像素是 0.7%P14 时 1 像素就是 7%。解决明确量程用MIN_BOX_PX把远端砍掉量程必须拉长的话换更大焦距的镜头同样的物距下 P 更大或者改用双目 / 深度相机不要指望在单目公式上做优化。5.4 检测框逐帧跳动读数像心电图现象物体完全静止画面上的距离数字每秒跳好几次幅度三到五厘米。原因Haar 的detectMultiScale在金字塔每一层独立搜索相邻帧之间框的位置本来就不稳定minNeighbors偏小时更明显。解决加多帧中值第 3.5 节把minNeighbors从 5 提到 8 左右再把minSize提上去过滤小框。三招叠加基本能把跳动压到 1 厘米以内。5.5 单位混用误差是系统性的现象所有读数都稳定地偏大或偏小一个固定比例比如全部大 2.54 倍。原因W 用厘米填的d 用米填的或者标定时卷尺量的是英寸。系统性偏差的特征就是“每一帧都错得一样多”跟随机抖动完全不同。解决在config.py顶部写死单位注释所有变量名带_cm后缀。这个习惯看着土但能杜绝 90% 的单位事故。同样的思路函数参数名也带单位compute_distance_cm就是故意的。6. 二次开发从单目标测距到多目标、视频流与业务接口单目标跑通之后绝大多数人的下一步都是“我要同时测好几个物体还要把距离发给下位机”。改造点集中在三处而且都不需要动distance.py。第一处是把检测层彻底批量化。detect()本来返回的就是列表主循环从for里只取第一个框改成遍历全部再把每个框的距离和 bbox 打包成字典即可。第二处是加量程过滤超范围的读数直接丢宁可漏报也别把垃圾数据发给下游。第三处是把输出从putText换成 JSON用串口、socket 或者 MQTT 送出去。# 多目标 输出结构化替换掉原来的单框绘制段 from config import KNOWN_WIDTH_CM, FOCAL_LENGTH_PX, MIN_BOX_PX, SMOOTH_WINDOW MIN_CM, MAX_CM 25.0, 130.0 # 有效量程超出直接丢 smoothers {} # 用 bbox 左上角做简易 id工程上够用 results [] for (x1, y1, x2, y2) in detector.detect(frame): px pixel_width(x1, y1, x2, y2) if px MIN_BOX_PX: continue d compute_distance_cm(KNOWN_WIDTH_CM, FOCAL_LENGTH_PX, px) if d is None or not (MIN_CM d MAX_CM): continue # 超量程的读数不参与输出 key (x1 // 20, y1 // 20) # 位置粗分桶避免同一目标反复新建平滑器 sm smoothers.setdefault(key, MedianSmoother(SMOOTH_WINDOW)) sm.push(d) results.append({bbox: [x1, y1, x2, y2], distance_cm: round(sm.value(), 1)}) payload {ts: time.time(), objects: results} # 直接丢给串口或 MQTT那个粗糙的key分桶是权宜之计物体一多就会串号。真要上生产得引入跟踪器比如 OpenCV 自带的 CSRT 或 ByteTrack用跟踪 id 替代位置分桶让每个目标的平滑窗口独立且连续。改造后必须重新验一遍误差表因为批量化之后帧率会下降SMOOTH_WINDOW7对应的滞后时间变长了。我一般会先跑一遍静态五点标定再让物体在 40 到 120 厘米之间匀速移动看读数曲线跟真实距离曲线的滞后帧数——超过 5 帧就把窗口缩到 3宁可抖一点也别让下游拿到过时的距离。改造方向动哪里验证方法多目标主循环遍历 跟踪器两个物体交叉时 id 不串换检测器新增detector.py实现同一批图片下 bbox 口径一致结构化输出输出层替换抓包看 JSON 字段和量程提高远端精度换长焦镜头 重新标定重跑 40~120 厘米误差表这套代码我最看重的一点是它把“标定”和“运行”明确分成了两个阶段而不是在运行时偷偷自适应。早期我图省事写过一版自动估焦距的逻辑结果光照一变 F 就跟着漂读数一天一个样。从那以后我每次接新的摄像头第一步都是先拍一张已知距离的照片、老老实实反解 F 写回配置再谈别的。希望帮到你。本文还有配套的精品资源点击获取