简介这份资源面向计算机视觉初学者与需要落地双目测距的开发者围绕ZED立体相机与YOLO目标检测框架的结合展开解决从环境搭建到距离计算的完整链路问题可用于机器人导航、无人机避障等场景的入门实践。压缩包共42个文件、约78.97MB以20个Python脚本为核心辅以YOLOv4与YOLOv4-tiny的cfg配置和weights权重文件、xml工程配置、Makefile与CUDA插件源码以及说明文档和演示动图覆盖检测、标定、可视化与TensorRT加速等模块。目前已有3015人学习下载。资源提供了可直接运行的zedceju.py主程序并配套相机标定、尺寸测量、多模型推理等脚本读者可据此理解YOLO识别与ZED深度信息融合的测距逻辑同时参考numpy版本兼容与虚拟环境配置的排错思路快速复现并二次开发。1. 从 zedceju.py 说起双目测距为什么值得单独拆一遍手头有一份zedceju.py配套 ZED 双目相机和 YOLO 检测模型跑起来就能在画面里框出目标并给出距离。这类资源看着简单真到自己机器上跑十有八九卡在相机打不开、模型路径对不上、测距数值飘得离谱这三件事上。它解决的不是“怎么训练 YOLO”而是把双目视差转成真实距离这条链路打通ZED 出左右目图像和深度图YOLO 负责框目标脚本把框中心对应的深度值换算成米。适合已经能跑通 YOLO 推理、想把手里的双目相机用起来的从业者也适合做机器人避障、体积测量、抓取定位这类需要“目标在哪、离多远”的场景。下面按我实际拆这份代码的顺序讲参数怎么调、哪里容易翻车都落到具体行上。2. 环境与依赖把 ZED SDK 和 YOLO 推理栈装到能互相看见2.1 先确认 ZED SDK 版本与 Python 绑定ZED 的 Python 接口不是 pip 装个包就完事它依赖官方 SDK 本体加pyzed绑定。常见做法是先装 SDK再把 SDK 自带的 Python 示例目录加进PYTHONPATH或者用 SDK 提供的get_python_api.py把绑定拷到当前环境。版本对不上是最常见的翻车点SDK 大版本和pyzed不匹配时import pyzed.sl直接报符号找不到。# 查看已安装 SDK 版本Linux 下常见路径 ls /usr/local/zed/ 2/dev/null # 确认 Python 能导入绑定 python -c import pyzed.sl as sl; print(sl.__file__)第一行看 SDK 是否落在默认目录第二行验证绑定是否真的进了当前解释器。如果第二行报ModuleNotFoundError别急着重装先确认你用的是不是 SDK 对应的那个 Python 版本——很多机器上系统 Python 和 conda 环境是两套绑定只装进了其中一套。2.2 YOLO 侧依赖与模型文件摆放YOLO 这边相对常规ultralytics或你惯用的推理封装都行关键是模型权重路径要写死成绝对路径或相对脚本的路径别依赖当前工作目录。zedceju.py里通常有一个模型加载入口我一般把它改成从脚本所在目录推导import os from ultralytics import YOLO BASE_DIR os.path.dirname(os.path.abspath(__file__)) MODEL_PATH os.path.join(BASE_DIR, weights, best.pt) model YOLO(MODEL_PATH) # 权重放脚本同级 weights 目录避免 cwd 变化导致找不到os.path.abspath(__file__)拿到脚本绝对路径再拼weights/best.pt这样无论从哪个目录python zedceju.py都能定位权重。参数上唯一要留意的是模型输入尺寸和 ZED 图像分辨率是否匹配——YOLO 内部会做 letterbox但如果你手动裁了 ROI 再送进去坐标映射回原图时容易错位这点后面避坑章会展开。2.3 一次最小连通性验证装完别直接跑完整脚本先写个十行的探针确认相机能出图、模型能出框两件事分开验证出问题好定位。import pyzed.sl as sl cam sl.Camera() init sl.InitParameters() init.camera_resolution sl.RESOLUTION.HD720 init.depth_mode sl.DEPTH_MODE.NEURAL # 深度模式NEURAL 对纹理弱场景更稳 err cam.open(init) print(camera open:, err) # 成功返回 SUCCESS if err sl.ERROR_CODE.SUCCESS: mat sl.Mat() cam.grab() cam.retrieve_image(mat, sl.VIEW.LEFT) print(frame shape:, mat.get_width(), mat.get_height()) cam.close()init.depth_mode是这份脚本里最值得先定的参数NEURAL走神经网络深度弱纹理和反光表面比传统QUALITY稳但吃 GPUPERFORMANCE快但边缘噪点多。探针里先确认camera open返回SUCCESS再确认frame shape和你预期分辨率一致两步都过再进主脚本。3. 测距主链路从双目视差到框中心那一米的换算3.1 深度图取值与坐标系对齐ZED 的深度不是直接给你“米”而是通过MEASURE.XYZ取某个像素的三维坐标Z 分量就是相机坐标系下的距离。zedceju.py的核心逻辑通常是YOLO 框出目标 → 取框中心像素(u, v)→ 用cam.retrieve_measure(xyz_map, sl.MEASURE.XYZ)拿到该点三维坐标 → 取z作为距离。这里有个容易忽略的点YOLO 输入的图像和 ZED 取深度的图像必须是同一路、同一分辨率。如果脚本里 YOLO 吃的是VIEW.LEFT深度图也必须基于左目坐标系否则(u, v)对不上距离会系统性偏。import numpy as np import pyzed.sl as sl xyz_map sl.Mat() runtime sl.RuntimeParameters() cam.grab(runtime) cam.retrieve_measure(xyz_map, sl.MEASURE.XYZ) # 每个像素对应相机坐标系三维点 def center_distance(xyz_map, u, v): err, point xyz_map.get_value(u, v) # 取框中心像素的三维坐标 if err ! sl.ERROR_CODE.SUCCESS or not np.isfinite(point[2]): return None # 无效深度常见于天空、玻璃、过曝区域 return float(point[2]) # z 分量即距离单位米get_value返回的point是[x, y, z]单位米z就是沿光轴的距离。np.isfinite那层判断不能省——无效深度在 ZED 里常表现为nan或极大值直接拿去显示会得到“距离 1e9 米”这种玄学数字。我一般还会对框内做一次小范围中值滤波取框中心 5×5 邻域有效 z 的中位数比单点稳得多。3.2 框中心取点的三种策略与取舍单点取中心最省事但目标边缘、遮挡、反光会让中心点恰好落在无效深度上。实际项目里我见过三种做法各有适用面策略做法适用代价单点中心取(u, v)一个像素目标大、纹理足易被单点噪声带偏邻域中值中心 5×5 有效 z 中位数通用场景多几次取值几乎无开销框内分位数框内所有有效 z 取 20% 分位目标贴地、前景遮挡多需遍历框内像素稍慢我一般默认用邻域中值目标贴地或前面有栏杆时切到分位数。分位数取 20% 而不是最小值是为了避开零星飞点取太小会被噪声拉低取 50% 又容易被背景拉高。3.3 把检测循环和深度取值接起来主循环的结构基本固定grab → 取左目图 → YOLO 推理 → 遍历框 → 取距离 → 画框标注。下面这段是骨架zedceju.py里大概率是它的变体while True: if cam.grab(runtime) ! sl.ERROR_CODE.SUCCESS: continue cam.retrieve_image(left_mat, sl.VIEW.LEFT) frame left_mat.get_data()[:, :, :3] # BGRA 转 BGRYOLO 要三通道 results model(frame, conf0.4, verboseFalse)[0] for box in results.boxes: x1, y1, x2, y2 map(int, box.xyxy[0].tolist()) u, v (x1 x2) // 2, (y1 y2) // 2 dist center_distance(xyz_map, u, v) label f{model.names[int(box.cls)]} {dist:.2f}m if dist else invalid cv2.rectangle(frame, (x1, y1), (x2, y2), (0, 255, 0), 2) cv2.putText(frame, label, (x1, y1 - 8), cv2.FONT_HERSHEY_SIMPLEX, 0.6, (0, 255, 0), 2)conf0.4是检测阈值测距场景宁可漏检也别误检——误检框到背景距离直接是墙的距离比没框更误导。left_mat.get_data()出来是 BGRA 四通道切前三个通道给 YOLO这一步漏了会报通道数不匹配。verboseFalse关掉每帧日志不然控制台刷屏看不清真正的报错。4. 避坑与排查五个让测距数值失真的真实原因4.1 现象距离整体偏大或偏小一个固定比例原因多半是深度模式和分辨率不匹配或者脚本里 YOLO 吃的是缩放后的图、深度却按原图坐标取。ZED 的(u, v)是图像像素坐标一旦你把帧 resize 给 YOLO框坐标必须按比例映射回原分辨率再取深度。解决要么不 resize要么在取距离前把u, v乘回原宽/输入宽。我见过最隐蔽的一种是VIEW.LEFT和VIEW.LEFT_UNRECTIFIED混用后者没做校正视差和深度对不上距离会随目标在画面中的位置漂移。4.2 现象框中心距离频繁返回 None 或极大值原因是中心点落在无效深度区玻璃、纯色墙面、过曝天空、目标自身高光。解决按 3.2 的策略换邻域中值或分位数并在显示层把无效值标成invalid而不是硬转 float。另外DEPTH_MODE.NEURAL在极近小于 0.3 米和极远超过 20 米区间本身置信度低超出这个范围的距离值要打个问号别直接喂给下游控制逻辑。4.3 现象相机能开但 grab 一直失败原因通常是 USB 带宽不够或分辨率/帧率组合超出链路能力。HD1080 加 60fps 在部分 USB 3.0 口上就撑不住。解决先把camera_fps降到 30、分辨率降到 HD720 验证链路再逐步往上加。另一个常见原因是同一台机器上另一个进程还占着相机ZED 不支持多进程同时打开同一台设备跑之前确认没有残留的 Python 进程。4.4 现象YOLO 框和画面错位半帧原因是 grab 和 retrieve 的时序先grab再retrieve_image和retrieve_measure必须针对同一帧。如果脚本里在循环外初始化了xyz_map却在循环内忘了每帧重新retrieve_measure深度图会停在第一帧框在动、距离不动。解决把retrieve_measure放进循环紧跟grab之后和取图同一帧完成。4.5 现象换一台机器距离全乱原因是标定文件没跟着走。ZED 出厂标定存在相机内部但如果你用了自定义标定或换了分辨率档位InitParameters里的optional_settings_path没指对深度就会用错内参。解决确认cam.get_camera_information().camera_configuration里的内参和你的预期一致跨机器部署时把标定相关配置显式带上别依赖默认。5. 进阶把单帧测距做成可验证的稳定输出单帧能出数只是起点真正上线前我会做两件事一是给距离加时间维度的平滑二是搭一个能复现的验证台。平滑用简单的一维卡尔曼或滑动中值都行目标静止时抑制抖动运动时别引入太大滞后——我一般用窗口 5 的滑动中值延迟约两帧对避障够用。验证台则是固定几个已知距离的标靶比如 1 米、3 米、5 米各放一个高纹理板每次改完参数跑一遍记录误差分布而不是靠肉眼觉得“差不多”。from collections import deque class DistanceSmoother: def __init__(self, window5): self.buf deque(maxlenwindow) # 固定窗口自动丢弃最旧值 def update(self, d): if d is None: return self.last() # 无效帧沿用上次有效值避免显示跳变 self.buf.append(d) return self.last() def last(self): if not self.buf: return None s sorted(self.buf) return s[len(s) // 2] # 中值抗单帧飞点window5是折中再大平滑更好但滞后明显再小抗噪不够。update里对None的处理是关键细节——无效帧直接沿用上次值比显示invalid再跳回来体验好但下游如果依赖“无效”信号做安全动作这里要改成透传None并单独标记。验证时我会把原始值和平滑值同时打日志对比两者的偏差偏差持续超过 10% 就说明窗口或深度模式该调了。从那以后我每次接新的双目测距脚本都强制先跑一遍已知距离标靶、把原始值和平滑值并排打出来看再谈集成。这套习惯帮我省掉了好几次“现场才发现距离系统性偏”的返工。希望帮到你。本文还有配套的精品资源点击获取
