ZED双目相机+YOLO目标检测的米制距离测量实现

简介一套面向计算机视觉与机器人感知学习者的ZED相机结合YOLO双目测距工程实践包重点解决立体相机目标检测与目标距离估算的联调问题。压缩包共42个文件、约78.97MB以20个Python脚本为核心配合5个XML工程配置、2个cfg与2个weights模型文件以及CUDA层源码、Makefile、说明文档和演示GIF等覆盖检测推理、相机调用、可视化与工程构建等模块。目录中包含可直接运行的zedceju.py主程序以及zed.py、zed_trt.py、yolo_with_plugins.py、size.py等辅助脚本和YOLOv4、YOLOv4-tiny权重便于读者对照梳理ZED SDK接入、numpy版本兼容、TensorRT加速与距离计算之间的工程组织方式。已有3016人学习适合具备一定Python和OpenCV基础、希望动手理解双目测距完整链路的开发者参考。1. 一台相机两个镜头zedceju.py 到底在算什么把 ZED 往桌上一架运行zedceju.py屏幕上每个检测框右上角就会跳出一个以米为单位的数字。这件事说起来就一句话ZED 双目相机出深度图YOLO 出目标框脚本把框和深度对齐给每个目标贴上一个绝对距离。整套逻辑全压在一个 Python 文件里没有 Web 服务、没有数据库、没有训练流程是那种拿来就能改、改完立刻能看见效果的小工程。它适合两类人一类是刚拿到 ZED想先确认相机、SDK、深度链路都是通的另一类是在做机器人避障、客流统计、工位安全距离告警这类活需要「检测框 米制距离」这个最小可用单元然后往上叠业务。要注意它不是高精度测量仪它是把 ZED 的物理基线和 YOLO 的语义框拼在一起给你一个能直接用的、有量纲的目标距离。2. 选型对照为什么用 ZED 的双目深度配 YOLO而不是单目估距先把这个组合的合理性说清楚不然后面调参全是玄学。测距这件事有三条常见路线各自的坑完全不一样选错了后面怎么调都别扭。2.1 三条测距路线的现场对比最省事的是「单目 已知物体尺寸」。框的像素宽高对应真实宽高按相似三角形反推距离。听起来很美实际用起来一地鸡毛同一类目标尺寸方差极大人站直和半蹲能差出 40%框还会因为遮挡被截断一半算出来的距离直接翻倍。这种方案只在「目标尺寸高度固定 视角稳定」的产线场景勉强能用换个场地就得重新标定。第二条是「单目深度估计网络」输出一张稠密深度图。视觉上很惊艳但它是相对深度尺度是漂的同一个场景换一批数据整体乘个系数才勉强对得上。做演示可以做告警阈值不行因为你没法给「2 米」定一个稳定阈值。第三条就是 ZED 走的路双目立体匹配。两个镜头有固定的物理基线 B同一个物点在左右图上的横坐标差视差 d和距离成反比Z fx * B / d。这里 fx 是焦距像素单位B 是基线米d 是视差像素。整条链路里 fx 和 B 都来自出厂标定是硬参数所以输出天然带米制尺度不需要你再去猜一个系数。路线尺度来源绝对精度主要失效场景上手成本单目 已知尺寸假设的目标真实尺寸差强依赖先验遮挡、姿态变化、同类尺寸分散低单目深度估计网络学到的相对尺度中等需后处理对齐换场景尺度漂移、远距离塌陷中双目立体匹配ZED出厂标定的 fx 与基线 B近距离好随距离平方衰减弱纹理、反光、透明、超近距离中ZED 这一路的精度衰减规律要提前有预期视差误差是固定的亚像素级而Z对d是反比关系所以距离越远同样的视差误差放大出的距离误差越大。经验上 0.55 米区间非常好用510 米开始抖10 米开外基本只能看个大概。你要做的是把业务阈值放在它擅长的区间里而不是指望它变成激光测距仪。2.2 硬件与依赖跑之前先把版本对齐这套代码要跑起来硬件侧是三件事一台 ZED 相机双目型号都行、一个能稳定跑满 USB 3.0 带宽的口子、以及一块能跑 CUDA 的显卡。深度图是 SDK 在 GPU 上算的没有独显会掉到个位数帧率主循环里再塞一个 YOLO 就更撑不住。USB 线也是常见翻车点线材质量差会导致相机枚举成功但 grab 频繁超时。软件侧的核心是pyzed。它不走 pip是随 SDK 一起装进 Python 环境的所以先装 SDK再验证import pyzed.sl as sl能通。其余依赖就是常规三件套# pyzed 由 SDK 安装包提供不要试图 pip install pyzed python -c import pyzed.sl as sl; print(sl.__version__) # 先确认 SDK 能被 Python 找到 pip install ultralytics opencv-python numpy这里有个血泪经验SDK 版本、相机固件版本、pyzed版本三者要大致同级。SDK 太老读不到新固件的相机会卡在open()返回一个非 SUCCESS 的错误码上而错误码又不会打印得很直白很容易误判成「相机坏了」。装完先跑 SDK 自带的示例示例能出图再跑zedceju.py能省掉一半排查时间。YOLO 侧用 ultralytics 的现成权重就够yolov8n.pt这种小模型在 720p 下单帧推理通常在十毫秒量级和深度计算能并行跑。模型文件第一次运行会自动下载离线环境记得提前把权重放到脚本同级目录否则会卡在下载超时。2.3 单位与坐标系不先定死后面全要返工InitParameters里那个coordinate_units是最容易被忽略、又最容易导致「距离差了 1000 倍」的开关。默认是毫米而大多数人写业务逻辑时脑子里想的是米。统一成sl.UNIT.METER之后深度图里每个像素值就是米YOLO 框上标出来的数字也是米中间不需要任何换算。如果中途改单位记得所有阈值常量比如「小于 1.5 米告警」一起改否则就是黑匣子式的 bug。另一个是深度图和彩色图的对齐。ZED 的深度图默认是对齐到左目图像的也就是说 YOLO 吃左目图检测框坐标可以直接拿来索引深度图不需要做任何仿射变换。这一点非常重要——一旦你手动把右目图或者某个 resize 后的图喂给 YOLO框坐标就和深度图错位了症状是「框明明在人身上读出来的距离却是背景墙面」。所有坐标缩放都必须在同一条尺寸链上完成。3. 结构拆解zedceju.py 一条从 grab 到画框的数据流单文件脚本没有目录结构但它有隐含的分层。看懂这四层改起来就知道该动哪一块。3.1 单文件脚本的隐含分层按执行顺序一个典型的zedceju.py长这样区块职责改动频率配置区分辨率、帧率、深度模式、置信度阈值、目标类别高初始化区打开相机、读取标定参数、加载 YOLO 权重低主循环grab → 取左目图 → 推理 → 逐框测距 → 画框显示中收尾区释放相机、关窗口、打印统计低配置区单独提到最上面是个好习惯。分辨率、置信度、只保留哪些类别这些参数在不同场地要反复调散落在主循环里改起来很痛苦。我一般会把它们收成一个字典或者一组常量主循环里只引用不定义。3.2 初始化把相机和模型都拉起来初始化这段是整个脚本里最容易报错的地方值得逐行看清楚。import numpy as np import cv2 import pyzed.sl as sl from ultralytics import YOLO # ---------- 配置 ---------- RESOLUTION sl.RESOLUTION.HD720 # 720p帧率与精度比较平衡的一档 FPS 30 CONF 0.45 # YOLO 置信度阈值 CLASSES [0] # 只保留 person按需扩展 UNIT sl.UNIT.METER # 全文统一用米 # ---------- 相机初始化 ---------- zed sl.Camera() init sl.InitParameters() init.camera_resolution RESOLUTION init.camera_fps FPS init.depth_mode sl.DEPTH_MODE.ULTRA # 精度优先低配机器可换 PERFORMANCE init.coordinate_units UNIT init.depth_minimum_distance 0.3 # 低于 0.3 米直接判无效 init.depth_stabilization 1 # 深度时域稳定减少跳变 err zed.open(init) if err ! sl.ERROR_CODE.SUCCESS: # 这里必须停下来后面所有 grab 都会失败硬跑只会得到一屏黑图 raise RuntimeError(fZED open failed: {err!r}) runtime sl.RuntimeParameters() runtime.enable_depth True # ---------- 读标定参数后面手算校验要用 ---------- cam_info zed.get_camera_information() calib cam_info.camera_configuration.calibration_parameters fx calib.left_cam.fx # 左目焦距像素单位 baseline calib.get_camera_baseline() # 基线与 coordinate_units 同单位 # ---------- 模型 ---------- model YOLO(yolov8n.pt) names model.namesdepth_mode是性能与精度的那根旋钮。精度档在弱纹理和边缘处补得更满代价是 GPU 占用高性能档帧率好看但边缘容易糊近距离测距会跳。工位上跑不动就先降到PERFORMANCE等确认链路通了再往上调。depth_stabilization打开后SDK 会对深度做时域滤波静止目标的读数会明显更稳。代价是目标快速移动时会有轻微拖影做高速抓取类应用时反而要关掉它。fx和baseline读出来只做一件事校验。后面会用它们手算一次视差跟 SDK 给的深度对一对确认单位没搞错、坐标没对齐错。3.3 主循环骨架五步不能乱序主循环的顺序是死的换一下结果就不对。image sl.Mat() # 左目彩色图BGRA depth sl.Mat() # 深度图float32单位由 coordinate_units 决定 while True: # 1) 抓一帧失败就重试不要直接 break if zed.grab(runtime) ! sl.ERROR_CODE.SUCCESS: continue # 2) 取左目图和深度图深度已对齐左目 zed.retrieve_image(image, sl.VIEW.LEFT) zed.retrieve_measure(depth, sl.MEASURE.DEPTH) frame_bgra image.get_data() # H x W x 4, BGRA frame cv2.cvtColor(frame_bgra, cv2.COLOR_BGRA2BGR) depth_np depth.get_data() # H x W, float32 # 3) 推理注意 imgsz 要和输入同尺度避免内部再缩放导致框坐标偏移 results model(frame, confCONF, classesCLASSES, verboseFalse)[0] # 4) 逐框测距 for box, cls, conf in zip(results.boxes.xyxy.cpu().numpy(), results.boxes.cls.cpu().numpy(), results.boxes.conf.cpu().numpy()): dist box_distance(depth_np, box) # ... 画框、写距离 # 5) 显示与退出 cv2.imshow(zedyolo, frame) if cv2.waitKey(1) 0xFF 27: break zed.close() cv2.destroyAllWindows()第 3 步有个细节model(frame)内部会做 letterbox 缩放ultralytics 返回的boxes.xyxy已经自动映射回原始frame尺寸了所以框坐标可以直接索引depth_np。但如果你自己手动 resize 过frame再喂进去就必须自己把框乘回缩放比否则测距全错。这是新手最常踩的一个坑症状是「框位置对距离偏大」。第 2 步取的是sl.VIEW.LEFT而不是sl.VIEW.IMAGE因为深度图对齐的是左目。用VIEW.IMAGE在某些型号上拿到的是校正后的合成视图和深度图存在微小偏移近距离测距会差几厘米。4. 核心实现把 YOLO 的框换算成米制距离这一节是整个项目的肉。box_distance写得好不好直接决定读数能不能用。4.1 框内取哪块像素才不会被背景带偏最直觉的做法是取框中心一个点。问题是 YOLO 的框是矩形人抬起手臂、目标旁边有桌角伸进来中心点很容易落在背景或者别的物体上。更稳的做法是取框中心的一个内缩矩形区域然后对这个区域做统计。内缩比例是个经验值。太小比如 0.1等于没内缩容易被边缘污染太大比如 0.6在远距离小目标上会退化成几个像素样本量不够中位数不稳。我用下来 0.30.4 比较通用小目标可以用固定像素下限兜底。def roi_of_box(box, ratio0.35, min_px6): 把检测框内缩成一块中心区域返回 (x1, y1, x2, y2) 整数像素坐标 x1, y1, x2, y2 box w, h x2 - x1, y2 - y1 # 按比例内缩但至少保留 min_px 像素防止小目标缩没了 rw max(w * ratio, min_px) rh max(h * ratio, min_px) cx, cy (x1 x2) / 2.0, (y1 y2) / 2.0 return (int(cx - rw), int(cy - rh), int(cx rw), int(cy rh))min_px存在的理由是远距离目标。一个 30 米外的人框可能只有 20×60 像素乘 0.35 之后宽只剩 7 像素再被int()一截就变成 0 宽的空区域patch.size直接为 0。加了这个下限后再小的框也能取到一块可用区域。4.2 深度值清洗与中位数聚合拿到 ROI 之后不能直接np.mean。深度图里有两类脏数据必须过滤一是无效值ZED 在弱纹理、反光、透明、超出量程的地方会输出NaN或inf二是异常值人物边缘会混进后面的墙把均值往上拉。def box_distance(depth_np, box, ratio0.35, min_m0.3, max_m20.0, min_valid25): depth_np : H x W 的 float32 深度图单位米 box : (x1, y1, x2, y2)像素坐标与 depth_np 同尺寸 返回 : 目标距离米样本不足时返回 None h, w depth_np.shape[:2] x1, y1, x2, y2 roi_of_box(box, ratio) # 裁到图内越界会让切片静默返回空数组 x1, y1 max(0, x1), max(0, y1) x2, y2 min(w, x2), min(h, y2) if x2 - x1 2 or y2 - y1 2: return None patch depth_np[y1:y2, x1:x2].astype(np.float32).ravel() # 1) 去掉 NaN / inf patch patch[np.isfinite(patch)] # 2) 去掉量程外与相机最小距离内的值 patch patch[(patch min_m) (patch max_m)] # 3) 样本太少不可信宁可不报 if patch.size min_valid: return None # 4) 中位数抗边缘污染比均值稳得多 return float(np.median(patch))几个参数的实际含义要说清楚。min_m除了挡掉噪声还挡掉了「贴脸」场景——ZED 在小于depth_minimum_distance的范围内基本算不出有效深度输出的是无效值直接过滤反而干净。max_m是业务上限超过 20 米的双目深度已经不可信留着只会让读数乱跳。min_valid25是样本量门槛。这个数是拍脑袋来的但方向是对的一个检测框内有效深度点少于二十几个说明这块区域大概率是弱纹理或者被遮挡此时报一个数不如不报。业务上可以让「无读数」显示成--比显示一个错误的0.4m好得多。用中位数而不是均值是因为中位数的崩溃点是 50%。框里只要一半以上像素还在目标身上读数就是目标本身的距离用均值的话哪怕 20% 的像素落在远处背景上结果就被拉偏了。4.3 用 fx 和 baseline 手算一次确认 SDK 没骗你链路刚搭起来的时候我很建议做一次交叉校验。ZED 的深度是从视差算出来的那我们就反过来拿 SDK 给的深度反推视差看是不是一个合理的亚像素量级。def sanity_check(depth_np, fx, baseline, box): z box_distance(depth_np, box) if z is None: print(该框无有效深度) return disparity fx * baseline / z # 反推视差单位像素 print(fZ{z:.3f} m | fx{fx:.2f} px | B{baseline:.4f} | d{disparity:.2f} px)判断标准很简单视差应该在零点几到一百多像素之间。如果算出来是几千像素八成是单位错了深度是毫米当成米用如果是 0.00x 像素八成是baseline和fx取错了相机比如拿了右目的 fx。这个方法还有个用处当你在怀疑「测距不准」到底是算法问题还是硬件问题时它能快速把范围缩到单位、标定、对齐这三件事上。顺带提一句基线 B 的取值单位跟着coordinate_units走。设成米B 就是 0.12 左右这个量级设成毫米B 就是 120。这个数量级对不上公式立刻给你难看的结果。4.4 点云接口除了 Z 还能拿到横向偏移只报一个距离做避障是不够的——你还得知道目标偏左还是偏右。ZED 提供了点云测量接口一次拿到 XYZ 三个分量。xyz sl.Mat() zed.retrieve_measure(xyz, sl.MEASURE.XYZ) # 每个像素是 (X, Y, Z)单位同 coordinate_units def box_xyz(xyz_np, box, ratio0.35): x1, y1, x2, y2 roi_of_box(box, ratio) patch xyz_np[y1:y2, x1:x2].reshape(-1, 3) patch patch[np.isfinite(patch).all(axis1)] if patch.size 0: return None # 分轴取中位数Z 用中位数抗噪X/Y 同理 return tuple(np.median(patch, axis0))拿到(X, Y, Z)之后横向偏角就是atan2(X, Z)做「只对正前方 ±30 度内的目标告警」这类逻辑时非常顺手。要注意点云的 X/Y 精度比 Z 差因为 X Z * (u - cx) / fxZ 的误差会按比例传到 X 上所以横向角度别用来做精确定位用来做粗分区足够了。5. 排查记录深度图全是 NaN、距离乱跳的五个现场这一节是从几个实际项目里攒下来的。现象都很有迷惑性但原因基本落在五个地方。5.1 现象所有框都显示--深度图肉眼可见全黑原因通常是coordinate_units和过滤区间不匹配。设成毫米时深度值是几百上千而min_m0.3 / max_m20这两刀下去全部被砍光patch.size归零函数一路返回None。解决办法是先打印一次原始统计再定阈值valid depth_np[np.isfinite(depth_np)] print(min/max/median , valid.min(), valid.max(), np.median(valid))看中位数的量级就知道当前单位是米还是毫米了。统一改成sl.UNIT.METER之后这个坑基本只会踩一次。5.2 现象人站着不动距离读数在 1.2 和 3.8 之间反复横跳原因是 ROI 里混进了背景。人站在墙前框的左右两侧包含大量墙面像素中位数的稳定性取决于目标占框内有效像素的比例。如果人只占三成中位数就会在人和墙之间跳。解决办法有两步把ratio从 0.2 提到 0.350.45缩小取样区域同时打开depth_stabilization让 SDK 在时域上先滤一遍。如果还跳就在业务层加一层指数平滑z_smooth 0.7 * z_prev 0.3 * z_now视觉上立刻老实。平滑系数别设太小否则目标真的走近了你反应不过来。5.3 现象框位置明显偏移距离读到的是旁边物体的这个基本可以确定是坐标链断了。三种典型情况喂给 YOLO 的是 resize 后的图但框没乘回缩放比用了sl.VIEW.IMAGE而不是sl.VIEW.LEFT或者自己做了裁剪、翻转、旋转却没同步变换框。解决办法是死守一条规则YOLO 的输入必须是VIEW.LEFT的原始尺寸除色彩空间转换BGRA→BGR之外不做任何几何变换。所有几何处理放在测距之后作用于「框 距离」这个结构体而不是原始图像。5.4 现象zed.open()返回非 SUCCESS或者 grab 频繁超时前者多半是版本或权限问题SDK 与相机固件不同级、USB 口供电不足、Linux 下 udev 规则没装。后者更常见于线材——相机枚举成功但带宽跑不满跑几秒就超时一次。排查顺序是换一个主板直连的 USB 3.0 口别用前面板、别用 Hub→ 换一根短一点的优质线 → 跑 SDK 自带示例看是否同样超时 → 降分辨率到 720p 或 VGA 再试。降到 VGA 就稳定说明是带宽问题不是相机坏了。5.5 现象5 米以内挺准10 米外数字乱飞这不是 bug是双目的物理特性。视差随距离衰减远距离下亚像素误差被放大深度置信度骤降。SDK 其实给了置信度图做远距离业务时应该一起取出来做门限。conf_map sl.Mat() zed.retrieve_measure(conf_map, sl.MEASURE.CONFIDENCE) # 0~100 conf_np conf_map.get_data() # 在 box_distance 里同时要求 patch 对应位置的置信度中位数 60工程上的处理是给业务分层3 米内用精确值做告警38 米只用来看趋势8 米外直接不显示数值只画框。硬要在 15 米上报两位小数那个数字除了好看没有任何意义。6. 二次开发把测距封装成可复用模块的三步改法zedceju.py是脚本形态所有东西都在主循环里一旦要做多路输出、要接业务回调就得先拆。我一般按三步改。第一步把「相机 模型 测距」收成一个类对外只暴露read()方法返回一个目标列表每项是{track_id, cls, conf, box, dist, angle}。这样主循环里只剩画图和业务判断换成别的显示方式推 RTSP、发 MQTT、存 CSV都不用动测距部分。第二步接上跟踪器让距离和 ID 绑定。检测框每帧都在变没有 ID 的话平滑状态没法维护告警也没法做「持续 N 秒」的判断。results model.track(frame, confCONF, classesCLASSES, persistTrue, trackerbytetrack.yaml, verboseFalse)[0] ids results.boxes.id # 可能为 None首帧或丢失 targets [] for i, box in enumerate(results.boxes.xyxy.cpu().numpy()): z box_distance(depth_np, box) tid int(ids[i]) if ids is not None else -1 targets.append({id: tid, box: box, dist: z})第三步给每个 track_id 维护一份状态做平滑和滞回。平滑用指数滤波滞回解决「距离在阈值附近抖动导致告警反复触发」——进入阈值用 1.5 米退出用 1.8 米中间留 0.3 米死区。改造点改动位置验证方法封装成类新增ZedRanger主循环只调read()换个输出方式不报错接跟踪器model.trackboxes.id绑定ID 在连续帧中保持稳定平滑与滞回按 track_id 维护状态字典人静止时读数波动 5 厘米验证方法里我最看重最后一条找个人站在 2 米处别动盯十秒读数波动超过 5 厘米就说明 ROI 或者平滑参数还得调。这个测试比任何指标都直观。踩过一次坑我一开始把平滑状态存在了检测索引上而不是 track_id 上。结果 YOLO 的输出顺序一变两个目标的距离就串了画面上的数字像在互相跳。查了半天以为是深度不稳最后发现是状态绑错了键。从那以后我每次接跟踪都强制先跑一遍「目标交叉走过」的场景确认 ID 不串、距离不跳再往下写业务。希望帮到你。本文还有配套的精品资源点击获取