简介：这份资源面向计算机视觉初学者与机器人、自动驾驶方向的开发者，聚焦ZED立体相机与YOLO目标检测结合实现双目测距的完整工程。包内共42个文件，以20个Python脚本为核心，配合YOLOv4与YOLOv4-tiny的cfg配置及weights权重、若干xml工程配置、CUDA加速所需的cu与h源文件、Makefile及说明文档，压缩包约78.97MB，覆盖从相机标定、TensorRT推理到距离计算与可视化展示的多个模块。已有3015人学习下载，说明该方案在同类实践中具备一定参考价值。读者可据此获得可直接运行的测距脚本、YOLO与ZED深度信息融合的处理逻辑，以及numpy版本兼容、环境配置等常见问题的排错思路，适合作为立体视觉目标测距项目的起步模板。
1. 从 zedceju.py 说起：一套能跑通的双目测距最小闭环
手里有一台 ZED 双目相机，想量出画面里某个物体的真实距离，最省事的路径不是从零推公式，而是先跑通一份现成的脚本。zedceju.py就是这样一个入口文件：它把 ZED SDK 取图、YOLO 检测、双目视差换算这三件事串成一条线，输出的是检测框中心点对应的物理距离。很多人卡在“相机能出图、YOLO 能框人，但两个东西拼不到一起”，这份代码解决的正是拼接问题。它适合已经装好 ZED SDK、手里有.pt权重、想快速验证测距精度的从业者，也适合拿它当骨架改成自己的业务逻辑。下面按“先立原理、再拆脚本、最后踩坑”的顺序走，参数和边界都会落到具体数值上。
2. 双目测距的几何底子：为什么 Z 只跟视差和焦距有关
2.1 从相似三角形推到 Z = f·B/d
双目测距的核心公式只有一行：Z = f * B / d。f是焦距（像素单位），B是基线（两个镜头光心的物理距离，ZED 系列常见 120mm 左右，以你手上型号的标定值为准），d是视差，也就是同一个物点在左右图像上的横坐标差。推导不复杂：左右相机光心相距 B，物点在左图成像位置 xl、右图 xr，由相似三角形可得Z / f = B / (xl - xr)，整理就是上面的式子。
这里有个容易被忽略的点：f必须是像素焦距，不是毫米焦距。ZED SDK 给的相机内参里fx就是像素焦距，直接拿来用；如果你自己拿毫米焦距去算，结果会差一个像素尺寸的倍数，量程直接崩掉。另一个点是d的单位是像素，B的单位是米或毫米，算出来的Z单位跟着B走，脚本里统一用米最省心。
2.2 视差从哪来：ZED 的深度图 vs 自己算
ZED 相机本身就能输出深度图，zedceju.py走的是“取 SDK 深度 + YOLO 框中心采样”这条路，而不是自己拿左右原图做立体匹配。原因很实际：自己写 SGBM 或 BM 匹配，参数调起来是玄学，纹理弱的墙面、反光的桌面基本出不来可用视差；ZED SDK 内部已经做了校正、匹配和滤波，直接读MEASURE::DEPTH模式的深度图，稳定性和开发速度都占优。
代价是你要接受 SDK 的深度图分辨率限制和有效距离范围。常见做法是把深度图缩放到和 RGB 同尺寸再采样，或者反过来把 YOLO 框坐标按比例映射到深度图坐标系。脚本里用的是后者，映射比例写在初始化那段，改分辨率时这里必须同步改，否则框和深度对不上，测出来的距离会整体偏移。
2.3 坐标系对齐：像素坐标、深度图坐标、相机坐标
三个坐标系必须理清：YOLO 输出的是 RGB 图像像素坐标(u, v)；深度图有自己的分辨率(W_d, H_d)；相机坐标系是(X, Y, Z)，单位米。采样深度时做的是u_d = u * W_d / W_rgb、v_d = v * H_d / H_rgb，取整后读深度值。这一步错了，后面全错，而且错得很隐蔽——框看着在物体上，距离却差出半米。
提示：映射比例建议在初始化时算一次存成变量，不要在每个检测框里重复做浮点除法，既慢又容易写错取整方向。
3. 拆 zedceju.py：取图、检测、采样三段怎么接
3.1 初始化段：打开相机与加载权重
脚本开头做两件事：初始化 ZED 并设成深度模式，加载 YOLO 权重。ZED 的初始化参数里，resolution和depth_mode是关键，前者决定 RGB 和深度图的分辨率档位，后者决定深度质量。YOLO 这边用 ultralytics 的接口最省事，权重路径、置信度阈值、IOU 阈值都在这里定。
import pyzed.sl as sl from ultralytics import YOLO import numpy as np # ZED 初始化：深度模式 + 分辨率档位 zed = sl.Camera() init_params = sl.InitParameters() init_params.camera_resolution = sl.RESOLUTION.HD720 # 1280x720 init_params.depth_mode = sl.DEPTH_MODE.NEURAL # 深度质量档，按 SDK 版本选 init_params.coordinate_units = sl.UNIT.METER # 深度单位统一为米 status = zed.open(init_params) if status != sl.ERROR_CODE.SUCCESS: raise RuntimeError(f"ZED open failed: {status}") # YOLO 权重与阈值 model = YOLO("weights/best.pt") CONF = 0.45 # 置信度阈值，漏检多就降到 0.3 左右 IOU = 0.5 # NMS 的 IOU 阈值，重叠目标多时调高 runtime = sl.RuntimeParameters() image = sl.Mat() depth = sl.Mat()coordinate_units设成METER之后，深度图里读出来的值直接是米，省掉后面换算。depth_mode选NEURAL是较新 SDK 的档位，老版本可能只有PERFORMANCE/QUALITY/ULTRA，按你装的 SDK 版本改，选错会直接报枚举不存在。CONF和IOU这两个值不是拍脑袋定的：室内近距离目标CONF0.4～0.5 够用，远距离小目标要降到 0.3 才不漏，但误检会变多，得自己权衡。
3.2 主循环段：抓帧、推理、框中心采样
主循环的逻辑是：抓一帧 → YOLO 推理 → 遍历每个框 → 框中心映射到深度图 → 读深度 → 打印或画图。采样点选框中心是最简单的做法，但对遮挡敏感——框中心正好落在背景上时，距离就是背景的距离。更稳的做法是取框内深度值的中位数，脚本里如果只取中心点，改起来也就几行。
while True: if zed.grab(runtime) == sl.ERROR_CODE.SUCCESS: zed.retrieve_image(image, sl.VIEW.LEFT) # 左目 RGB zed.retrieve_measure(depth, sl.MEASURE.DEPTH) # 深度图，单位米 frame = image.get_data()[:, :, :3] # BGRA -> BGR results = model.predict(frame, conf=CONF, iou=IOU, verbose=False) h_rgb, w_rgb = frame.shape[:2] h_d, w_d = depth.get_height(), depth.get_width() for box in results[0].boxes: x1, y1, x2, y2 = box.xyxy[0].cpu().numpy() u = int((x1 + x2) / 2) v = int((y1 + y2) / 2) # RGB 像素坐标映射到深度图坐标 u_d = int(u * w_d / w_rgb) v_d = int(v * h_d / h_rgb) err, dist = depth.get_value(u_d, v_d) # dist 单位米 if err == sl.ERROR_CODE.SUCCESS and np.isfinite(dist): print(f"cls={int(box.cls)} dist={dist:.2f} m")retrieve_image拿到的数据是 BGRA 四通道，切片[:, :, :3]转成 BGR 再喂给 YOLO，少了这一步 OpenCV 和 ultralytics 都会报通道数不匹配。depth.get_value返回的是(error_code, value)元组，必须判err，无效深度（比如天空、纯色墙面）会返回nan或极大值，不判就会打印出一堆inf。np.isfinite是第二道保险，两个都判才干净。
3.3 输出段：距离怎么用、怎么画
打印只是调试用，真正落地一般要把距离画回画面或者发给下游。画图时注意retrieve_image出来的图是 BGRA，cv2.putText之前要么转 BGR 要么直接按四通道处理，颜色顺序写错会得到蓝色的人脸。距离值建议保留两位小数，米制下厘米级精度对大多数场景够用，写太多位反而暴露深度噪声。
如果下游要的是相机坐标系下的(X, Y, Z)而不只是Z，可以用 SDK 的MEASURE.XYZ直接取三维点，比拿Z反推X、Y少一步内参运算。脚本目前只输出Z，需要扩展时在retrieve_measure那里换枚举即可，采样逻辑不变。
4. 参数与精度：哪些旋钮真的影响测距结果
4.1 基线、分辨率、深度模式的取舍
| 参数 | 常见取值 | 对测距的影响 | 调整建议 |
|---|---|---|---|
| 基线 B | 120mm 左右（按型号） | B 越大远距离越准，近距离盲区越大 | 不改硬件，按标定值填 |
| 分辨率 | HD720 / HD1080 | 分辨率高，远距离视差更细 | 算力够就上 HD1080 |
| 深度模式 | NEURAL / ULTRA / QUALITY | 档位越高噪声越小、帧率越低 | 静态场景用高檔，动态降檔 |
| 置信度 CONF | 0.3～0.5 | 只影响检测，不直接影响深度 | 漏检降、误检升 |
| 采样方式 | 中心点 / 中位数 | 中位数抗遮挡 | 目标有遮挡时改中位数 |
基线是硬件决定的，软件改不了，但要知道它的含义：Z的误差和B成反比，基线小的型号在 5 米外误差会明显放大。分辨率影响的是视差的最小可分辨单位，分辨率翻倍，同样距离下视差像素数翻倍，相对误差减半，代价是算力。深度模式是质量和帧率的权衡，NEURAL在纹理弱的地方比传统块匹配稳，但首次加载模型会慢一两秒，别以为是卡死。
4.2 有效量程与盲区：0.3m 到 20m 不是随便写的
ZED 的标称量程通常从 0.3m 左右起步，近距离盲区来自基线几何——太近的物点在左右图上的视差超过搜索范围，匹配不上。远距离的上限则受分辨率和基线限制，20m 外视差只剩几个像素，噪声占比飙升。实际用的时候，1m 以内和 15m 以外都要打问号，中间段最可信。
判断某个距离是否可信，有个土办法：看深度图对应位置的邻域方差。方差大说明这块深度不稳，读出来的单点值不可信。脚本里没做这个判断，需要的话在采样点周围取 5×5 窗口算标准差，超过阈值就标记为“不可信”而不是硬报一个数。
4.3 采样策略：中心点、中位数、分位数
中心点采样快但脆，中位数稳但要遍历框内像素，分位数（比如 30% 分位）适合目标前方有遮挡的场景——取偏近的分位值能避开背景。三种策略的代码差别就在采样那几行：
# 框内深度中位数采样，抗单点噪声 x1, y1, x2, y2 = map(int, [x1, y1, x2, y2]) u1, v1 = int(x1 * w_d / w_rgb), int(y1 * h_d / h_rgb) u2, v2 = int(x2 * w_d / w_rgb), int(y2 * h_d / h_rgb) roi = depth.get_data()[v1:v2, u1:u2] # 取框内深度子图 valid = roi[np.isfinite(roi) & (roi > 0.1) & (roi < 30)] dist = float(np.median(valid)) if valid.size > 10 else float("nan")roi直接切片拿子图比逐点get_value快一个量级，但要注意get_data()返回的是 numpy 数组，切片顺序是[行, 列]即[v, u]，写反了取到的是转置区域。valid.size > 10是防止框太小、有效像素太少时中位数没意义，直接返回nan让上层处理。距离上下限 0.1～30 米是过滤明显异常值，按你的场景改。
5. 避坑与排查：跑不通时先看这五条
5.1 现象：深度全是 nan 或 0 → 原因：深度模式没开或单位没设 → 解决：查初始化参数
最常见的是retrieve_measure读出来一片nan。先查depth_mode是不是设成了NONE，再查coordinate_units有没有设METER。还有一种情况是相机刚打开头几帧深度还没收敛，前 10 帧丢掉不用。如果一直全nan，用 SDK 自带的查看器确认相机本身能出深度，排除硬件和驱动问题。
5.2 现象：框和距离对不上，整体偏移 → 原因：RGB 与深度图分辨率映射写错 → 解决：打印两边尺寸核对
映射比例写错时，框画在物体上，采样的却是旁边背景的深度，表现为距离系统性偏大或偏小。排查方法很直接：在循环里打印w_rgb, h_rgb, w_d, h_d，确认比例是不是 1:1 或者 2:1。有些分辨率档位下 RGB 和深度图尺寸不同，硬编码比例换档就崩，必须用运行时读到的尺寸算。
5.3 现象：近距离目标测不出 → 原因：落在盲区或视差超搜索范围 → 解决：拉开距离或换深度模式
0.3m 以内的目标基本测不准，这是几何决定的，不是代码 bug。如果业务必须测很近，考虑换基线更小的型号或者改用单目加已知尺寸的估算方案。另一个隐蔽原因是深度模式的搜索范围有限，极近距离视差太大匹配不上，换ULTRA档有时能救回来一点，但别指望根治。
5.4 现象：帧率掉到个位数 → 原因：高分辨率 + 高深度档 + YOLO 大模型三重叠加 → 解决：逐项降档定位
先单独跑 ZED 取图看帧率，再单独跑 YOLO 看帧率，最后合起来看，哪一步掉得狠就降哪一步。常见组合是 HD1080 + ULTRA + 大权重，三个都吃算力。实用配置是 HD720 + NEURAL + 轻量权重，帧率能回到 15 以上。别一上来就怀疑代码写得烂，先做这个分段测量，血泪经验。
5.5 现象：同一物体距离跳动大 → 原因：深度噪声 + 单点采样 → 解决：换中位数采样并加时间滤波
单帧单点采样天然抖，尤其纹理弱的目标。改框内中位数能压掉大部分空间噪声，再加一个简单的指数滑动平均压时间噪声：z_smooth = 0.7 * z_prev + 0.3 * z_now，系数按帧率调，帧率高可以取更小的新值权重。注意滤波会引入滞后，快速移动的目标别滤太狠。
6. 把测距做成可验证的模块：标定核对与误差量化
脚本能跑通只是起点，要敢用在业务里，得知道它错多少。我一般会做两件事：一是拿卷尺量几个已知距离做核对，二是把误差量化成表格，心里有数才敢上线。
标定核对的做法：把相机固定，在 1m、2m、3m、5m 处各放一个纹理清晰的标定板或纸箱，跑脚本读距离，和卷尺值对比。误差在 2% 以内算正常，超过 5% 就要查基线值是不是填错、深度模式是不是太低档。注意核对时目标要正对相机，斜放会让采样点落到侧面，读数偏大。
误差量化可以写成一个小循环，把多帧读数统计出来：
import statistics def measure_stability(depth, u_d, v_d, n=30): vals = [] for _ in range(n): err, d = depth.get_value(u_d, v_d) if err == sl.ERROR_CODE.SUCCESS and np.isfinite(d): vals.append(d) if len(vals) < n // 2: return None return { "mean": statistics.mean(vals), "std": statistics.pstdev(vals), "p10": sorted(vals)[len(vals) // 10], "p90": sorted(vals)[len(vals) * 9 // 10], }std反映抖动，p10到p90的区间反映可信范围。如果std超过均值的 5%，说明这个位置的深度不稳，业务逻辑里应该降级处理而不是硬用。这个函数不依赖 YOLO，单独对某个像素坐标就能测，调试深度质量时很好用。
还有一个容易忽略的点：相机温度漂移。ZED 连续跑十几分钟后，深度可能会有轻微系统性偏移，长时间运行的场景建议每隔一段时间对固定参照物做一次零点核对。这不是玄学，是实测能看到的。
从那以后我每次接新的双目测距需求，都强制先跑一遍已知距离核对表，再谈业务逻辑——跳过这步，后面调参全是黑匣子。希望帮到你。
本文还有配套的精品资源，点击获取
