简介这份资源面向计算机视觉初学者与需要落地双目测距的开发者围绕ZED立体相机与YOLO目标检测的联合使用解决从环境搭建到实际测距的完整链路问题。压缩包共42个文件约78.97MB以20个Python脚本为核心辅以YOLOv4与YOLOv4-tiny的cfg配置、weights权重、xml工程配置及cu/h等编译文件覆盖检测、相机调用、可视化与标定等模块。已有3015人学习下载说明其在同类实践中具备一定参考价值。读者可获得可直接运行的zedceju.py主程序以及相机标定、TensorRT加速、多模型检测与显示工具等配套脚本便于对照理解ZED深度信息与YOLO识别结果的融合逻辑并借鉴numpy版本兼容、依赖配置等排错思路快速复现物体识别与距离计算流程。1. 从一台双目相机到真实距离这个项目到底在算什么很多人第一次拿到双目相机第一反应是“拍两张图不就行了”真跑起来才发现两张图之间的像素差怎么变成米才是整件事的核心。这个项目做的事情很具体用 ZED 双目相机采集左右目图像交给 YOLO 做目标检测再把检测框内的目标位置换算成相机坐标系下的三维坐标最终输出目标到相机的直线距离。入口脚本就是zedceju.py一个文件把采集、推理、测距串起来适合想快速验证双目测距链路、又不想从零搭工程的人。它适合两类读者一类是刚接触双目视觉想先跑通一条“检测 测距”闭环的新手另一类是手里已经有 ZED 和 YOLO 权重想把两者接起来做二次开发的老手。项目本身不追求工程化封装胜在链路短、依赖清晰改起来不绕弯。下面按“能干什么 → 怎么跑 → 怎么改”的顺序拆。2. 技术栈与目录结构一个脚本背后的四层依赖2.1 技术选型为什么是 ZED YOLO 的组合双目测距的经典路线有两条一条是纯几何靠双目视差和标定参数直接算深度另一条是学习路线用深度估计网络出稠密深度图。这个项目走的是第一条但把“哪里需要测”交给 YOLO 决定。这样做的原因是纯几何测距对纹理缺失区域很敏感整幅图算深度噪声大而目标检测框天然圈定了有意义的区域框内取视差中位数或均值距离就稳得多。ZED 在这里承担的是“高质量双目图像源 内参外参提供者”的角色。它的 SDK 能直接给出左右目校正后的图像和相机基线、焦距等参数省掉了自己标定和极线校正的一大摊事。YOLO 负责检测常见做法是用 Ultralytics 的接口加载权重输出框的类别、置信度和像素坐标。两者之间靠一段坐标换算代码粘合这也是整个项目最值得看的部分。依赖上除了pyzedZED SDK 的 Python 绑定和ultralytics还需要opencv-python、numpy。ZED SDK 本身要单独装版本要和相机固件匹配这是后面避坑章节要重点说的。2.2 目录结构短链路项目的典型布局这类项目通常不会有大目录树zedceju.py是主入口旁边配几个辅助文件。一个合理的布局大致如下zed_yolo_distance/ ├── zedceju.py # 主入口采集 检测 测距 ├── config.yaml # 相机参数、模型路径、测距阈值 ├── models/ │ └── best.pt # YOLO 权重 ├── utils/ │ ├── zed_capture.py # ZED 图像与参数读取封装 │ └── distance.py # 视差转深度、深度转距离 └── requirements.txt主脚本负责编排utils里放可复用的换算逻辑。这样拆的好处是换相机型号只动zed_capture.py换测距公式只动distance.py主流程不用碰。如果拿到手的版本是单文件也建议按这个思路先拆一刀后面调参时省很多来回。2.3 核心参数表测距准不准就看这几个数参数含义典型取值影响baseline左右目基线距离米0.12 左右越大测距越远但近处盲区变大fx校正后焦距像素由 SDK 给出直接进公式错一位距离全偏disparity目标框内视差像素中位数取均值易被边缘污染conf_thresYOLO 置信度阈值0.40.5太低框飘测距跟着飘roi_shrink框内缩比例0.2避开框边缘的背景像素这张表建议直接落到config.yaml里别硬编码在脚本中间。调参时改配置比翻代码快得多也方便记录哪组参数在什么场景下好用。3. 运行链路拆解从打开相机到打印距离3.1 环境准备与依赖安装先装 ZED SDK再装 Python 依赖。ZED SDK 的安装包要从相机厂商渠道拿装完用python -c import pyzed验证。Python 依赖用虚拟环境隔离python -m venv venv source venv/bin/activate # Windows 用 venv\Scripts\activate pip install pyzed ultralytics opencv-python numpy pyyaml注意pyzed这个包名在不同平台下略有差异有的环境里是随 SDK 一起装的 wheel直接pip install pyzed可能拉不到这时要去 SDK 安装目录下的pyzed文件夹手动装。装完跑一句导入测试能过再往下走。3.2 相机初始化拿到左右目图像和内参ZED 的初始化有一套固定流程创建Camera对象、配置分辨率与帧率、打开、然后每帧grab再retrieve。关键是要同时取到左目和右目校正后的图像以及相机内参。import pyzed.sl as sl def open_zed(): cam sl.Camera() init sl.InitParameters() init.camera_resolution sl.RESOLUTION.HD720 init.camera_fps 30 init.depth_mode sl.DEPTH_MODE.NONE # 我们自己做测距不用 SDK 深度 status cam.open(init) if status ! sl.ERROR_CODE.SUCCESS: raise RuntimeError(fZED 打开失败: {status}) # 读取校正后的相机内参 calib cam.get_camera_information().camera_configuration.calibration_parameters fx calib.left_cam.fx baseline calib.get_camera_baseline() return cam, fx, baseline这段代码里有两个点值得说。depth_mode设成NONE是因为项目自己算视差不需要 SDK 的深度图关掉能省算力。get_camera_baseline()返回的是左右目物理基线单位米直接进后面的公式。fx取左目焦距因为视差通常以左目为参考计算。3.3 视差计算在检测框内做块匹配拿到左右目图像后对 YOLO 检出的每个框在框内做局部块匹配求视差。整幅图做 SGBM 再取框内值也行但局部匹配更快也更聚焦。import cv2 import numpy as np def disparity_in_box(left, right, box, shrink0.2): x1, y1, x2, y2 box w, h x2 - x1, y2 - y1 # 框内缩避开边缘背景 x1 int(w * shrink); x2 - int(w * shrink) y1 int(h * shrink); y2 - int(h * shrink) roi_l left[y1:y2, x1:x2] roi_r right[y1:y2, x1:x2] stereo cv2.StereoSGBM_create( minDisparity0, numDisparities64, blockSize9, uniquenessRatio10, speckleWindowSize100, speckleRange2 ) disp stereo.compute(roi_l, roi_r).astype(np.float32) / 16.0 valid disp[disp 0] return float(np.median(valid)) if valid.size else 0.0numDisparities必须是 16 的倍数它决定了能测多近blockSize越大越平滑但边缘越糊。除以 16 是因为 SGBM 输出的是定点数放大 16 倍存的。取中位数而不是均值是为了让框内少量错误匹配不把结果带偏这是血泪经验均值在纹理复杂处经常翻车。3.4 视差转距离一个除法背后的坐标系拿到视差后距离公式就是Z fx * baseline / disparity。这一步看着简单但单位要对齐fx是像素baseline是米disparity是像素算出来Z就是米。def disparity_to_distance(disp, fx, baseline): if disp 0: return None return fx * baseline / disp如果还想给出目标在相机坐标系下的 X、Y就用框中心像素(u, v)反投影X (u - cx) * Z / fxY (v - cy) * Z / fy。cx、cy同样从 SDK 内参里取。很多新手只算 Z 就以为完事做抓取或避障时才发现还需要横向偏移这一步别省。3.5 主循环把上面几步串起来主循环的逻辑是抓帧 → 左目图送 YOLO → 遍历框 → 框内求视差 → 转距离 → 画框标注。伪代码结构如下cam, fx, baseline open_zed() model YOLO(models/best.pt) runtime sl.RuntimeParameters() while True: if cam.grab(runtime) ! sl.ERROR_CODE.SUCCESS: continue left sl.Mat(); right sl.Mat() cam.retrieve_image(left, sl.VIEW.LEFT) cam.retrieve_image(right, sl.VIEW.RIGHT) img_l left.get_data()[:, :, :3] # 去掉 alpha 通道 img_r right.get_data()[:, :, :3] results model(img_l, conf0.45, verboseFalse) for box in results[0].boxes.xyxy.cpu().numpy(): disp disparity_in_box(img_l, img_r, box) dist disparity_to_distance(disp, fx, baseline) if dist: cv2.putText(img_l, f{dist:.2f}m, (int(box[0]), int(box[1]) - 8), cv2.FONT_HERSHEY_SIMPLEX, 0.7, (0, 255, 0), 2) cv2.imshow(zed-yolo-distance, img_l) if cv2.waitKey(1) 0xFF 27: breakretrieve_image拿到的图带 alpha 通道送 YOLO 前要切掉否则通道数不对会报错。verboseFalse关掉每帧日志不然控制台刷得看不清测距输出。按 ESC 退出后记得cam.close()不然下次打开可能占用失败。4. 避坑与排查双目测距最容易翻车的五个地方4.1 距离整体偏大或偏小现象所有目标测出来都比实际远一截或近一截比例大致固定。原因多半是fx或baseline取错比如用了未校正图像的焦距或者基线单位是毫米却当米用。解决打印 SDK 返回的fx和baseline用卷尺量一个已知距离的目标做对照反推比例系数确认是哪个参数错了再改别直接乘个系数糊弄过去。4.2 框内视差为 0 或大量无效值现象某些目标距离显示为空或者视差算出来是 0。原因是框内纹理太弱白墙、纯色物体SGBM 匹配不上也可能是numDisparities太小近处目标视差超出范围。解决把numDisparities调到 128 试试框内缩比例调小一点保留更多纹理实在不行对该框跳过并标注“不可测”别硬给一个假距离。4.3 YOLO 框抖动导致距离跳变现象同一静止目标距离在 0.1 米范围内来回跳。原因是检测框每帧有微小位移框内像素组成变了视差中位数跟着变。解决对距离做滑动平均或者对框做跟踪如 ByteTrack稳定框位置置信度阈值适当提高低置信框本来就飘。这是玄学问题滤波比调参管用。4.4 相机打开失败或帧率骤降现象cam.open返回错误或者跑一会儿帧率掉到个位数。原因是 ZED SDK 版本与相机固件不匹配或者 USB 带宽不够接了 Hub、用了 USB 2.0 口。解决查 SDK 版本文档确认支持范围换直连 USB 3.0 口分辨率从 HD1080 降到 HD720。帧率骤降还可能是每帧都新建StereoSGBM对象把它提到循环外复用。4.5 左右目图像对不齐现象测距结果随目标在画面中的位置变化很大边缘处尤其离谱。原因是用了未校正的原始图像或者左右目取图时序不一致。解决确认VIEW.LEFT和VIEW.RIGHT取的是校正后图像同一帧grab后连续retrieve不要跨帧混用。ZED 的校正图是配准好的用对了这一步基本不会出问题。5. 二次开发把单脚本改成能落地的测距模块5.1 拆出可复用的测距类单脚本跑通后第一件事是把测距逻辑收成一个类方便在别的项目里调用。核心接口就三个初始化、单帧测距、释放。class ZEDYoloRanger: def __init__(self, model_path, conf0.45): self.cam, self.fx, self.baseline open_zed() self.model YOLO(model_path) self.conf conf self.stereo cv2.StereoSGBM_create( minDisparity0, numDisparities128, blockSize9 ) def measure(self): # 返回 [(类别, 距离米, 框), ...] ... def close(self): self.cam.close()把StereoSGBM放进__init__是关键改动避免每帧重建。measure返回结构化结果而不是直接画图上层想画框、想发消息、想存日志都行解耦从这里开始。5.2 加一层距离滤波与有效性判断原始距离直接对外用抖动会传到下游。常见做法是给每个跟踪 ID 维护一个固定长度的队列取中位数输出同时设一个有效视差下限低于它就标记不可测。改造点做法收益滑动中位数队列长度 57抑制单帧跳变有效视差下限disp 1.0才计算过滤远距离噪声距离上限超过量程标“超限”避免给出无意义大数跟踪 ID 绑定接 ByteTrack同一目标距离连续这套组合拳下来静止目标的距离波动能压到厘米级移动目标也不会出现突跳。参数不用一次调到位先上中位数滤波不够再加跟踪。5.3 验证方法用已知距离做回归改完代码怎么确认没改坏我一般会在地上贴几个标记点量好 1 米、2 米、3 米、5 米把相机固定好逐个对准读距离记录误差。误差在量程 10% 以内算合格近处应该更准。每次改测距相关代码都跑一遍这组对照比盯着屏幕感觉靠谱得多。有条件的话把每次的读数存成 CSV改完对比前后曲线回归问题一眼能看出来。5.4 一个容易忽略的改造点分辨率与量程的权衡numDisparities和分辨率共同决定量程。分辨率越高同样物理视差对应的像素视差越大远处目标才有的测但高分辨率下 SGBM 计算量涨得快。我的习惯是先用 HD720 跑通确认量程够用再考虑升分辨率不够就加大numDisparities而不是盲目上 1080。曾经为了“看得更远”直接把分辨率拉满结果帧率掉到 5 帧测距延迟大到没法用从那以后每次调分辨率都先跑一遍帧率测试确认实时性再谈精度。希望这些拆解能帮到你把zedceju.py跑起来只是起点按上面的思路拆一层、滤一层它才真正能进你的项目。本文还有配套的精品资源点击获取
