前阵子帮朋友调一个桌面小零件抓取的项目机械臂要抓的东西离镜头只有二三十厘米手上那台常规双目深度相机在这个距离上基本是瞎子深度图大片空洞偶尔冒出来的点还飘。后来换了这颗主打近距离测距的 OAK-D-SR同样的工位、同样的光照深度图第一次完整地盖住了整个料盒。社区里管它叫大白深度相机名字听着挺可爱但它真正值钱的地方不在体积而在于它是少数把近距离当成主战场来设计的深度相机。这篇就把我这两周踩过的东西摊开讲它为什么能在近处工作、拿到手怎么把自己的机器参数读出来、DepthAI 流水线该怎么配、近距离场景里那六个坑分别怎么排、以及什么时候你其实不该选它。内容偏实战参数给了推导过程代码能直接跑刚上手的人和有几年经验的都能拿走点东西。1. 近距离测距才是真正的地狱难度OAK-D-SR解决了什么问题1.1 看得远是常规操作看得近是硬骨头绝大多数人对深度相机的直觉是测距范围越大越牛所以选型时第一眼看的是最大量程。真正做过项目的人都知道远距离只是精度衰减的问题近距离是根本测不出来的问题。原因有两个而且都是物理层面的。第一个是视差搜索范围。双目深度靠的是左右两幅图的像素偏移量视差反推距离而芯片能搜索的视差是有上限的一般几十到一百九十像素。距离越近同一个物理点在左右图上的像素偏移越大一旦超过搜索上限这个点就直接被判为无效。所以每一台双目相机都有一个最小可测距离不是镜头限制是算法限制。这也解释了为什么 OAK-D-SR 的近距离测距能力本质上来自更短的基线 更宽的有效视场而不是什么神秘算法。第二个是遮挡。两台相机分开了距离 B看同一个物体时各自能看到的部分是不一样的。基线除以距离这个比值越大两侧视角差异越大被一侧看到、另一侧看不到的区域就越多。30cm 距离配常规基线时这个比值相当可观左右一致性检查会毫不留情地把这些点全部剔掉深度图上就出现一圈描边式空洞。近距离测距的难点一大半都在这里。1.2 从 Z f·B / d 这条公式看清近的代价立体视觉的核心公式就一行Z (f_px × B) / dZ 是深度米f_px 是焦距换算成像素后的值B 是基线米d 是视差像素。最小可测距离就是视差取到搜索上限时的 ZZ_min (f_px × B) / d_max我按几种常见的小基线量级和不同匹配分辨率把 Z_min 算了一遍你可以直接对照自己手里的设备基线 Bf_px 640 宽d_max95d_max190扩展视差3.5 cm440 px16.2 cm8.1 cm5.0 cm440 px23.2 cm11.6 cm7.5 cm440 px34.7 cm17.4 cm7.5 cm880 px 1280 宽69.5 cm34.7 cm这张表里最有信息量的是最后两行。同一个物理基线匹配分辨率从 640 宽提到 1280 宽f_px 翻倍最小可测距离也直接翻倍。反过来说想让相机贴得更近把参与匹配的分辨率降一档是个有效手段代价是每个像素代表的角度变大深度分辨率变粗。这就是工程上的取舍没有免费午餐。注意表里第二、三行的 f_px 是我按水平视场约 72 度估的f_px (W/2) / tan(HFOV/2)你手上的实际值要用标定文件读别照抄。我在第 2 节会给出读取脚本读出来的才是真数。1.3 体积做小之后被换掉的是什么全网最小这个说法当然有营销成分但体积小这件事在近距离任务里确实是实打实的加分项前提是你清楚它换掉了什么。换掉的第一样是散热面积。算力芯片满载跑深度推理时外壳会明显温热这是正常的但温度变化会让结构件产生微米到几十微米级的形变而近距离对角度误差极其敏感。第二样是镜头口径和通光量进光少意味着暗光下噪声大、匹配质量下降。第三样是接口和固定点小体积模组往往只有几个安装孔刚性安装比大机器更难做。但它加回来的东西同样明显能塞进机械臂末端执行器旁边、能卡进狭窄的设备腔体、能装在移动平台的前裙板里补近场盲区。这些位置大机器根本进不去。我这次的项目就是把它直接固定在夹爪基座上跟着机械臂一起动线缆直接从拖链里走整机没有任何额外支架。这种安装自由度是省下来的体积换来的。2. 先把自己的机器测明白从标定文件里挖出真实基线与fx2.1 读EEPROM标定二十行代码拿到内参与基线我不建议你照抄任何网上的参数来配流水线。不同批次、不同镜头版本的模组基线和内参都会有差异自己读出来的才作数。DepthAI 把出厂标定烧在 EEPROM 里读起来非常方便import depthai as dai with dai.Device() as device: calib device.readCalibration() # 1) 内参分辨率要和你后面参与匹配的分辨率一致 W, H 640, 400 K calib.getCameraIntrinsics(dai.CameraBoardSocket.LEFT, W, H) fx, fy K[0][0], K[1][1] cx, cy K[0][2], K[1][2] print(ffx{fx:.2f} fy{fy:.2f} cx{cx:.1f} cy{cy:.1f}) # 2) 基线默认单位厘米 B_cm calib.getBaselineDistance(dai.CameraBoardSocket.LEFT, dai.CameraBoardSocket.RIGHT) print(fbaseline {B_cm:.3f} cm) # 3) 出厂标定先备份改坏了还能刷回去 calib.eepromToJsonFile(factory_calib.json) # 4) 顺手把传感器型号打出来确认批次 for socket, name in device.getCameraSensorNames().items(): print(socket, name)两个提醒。第一getCameraIntrinsics的第二个参数是你想要的输出分辨率DepthAI 会按比例缩放内参所以这里传的分辨率必须和后面实际参与深度计算的分辨率一致否则算出来的 fx 是错的。第二不同 SDK 版本的方法名偶尔会调整getBaselineDistance如果报错用dir(calib)看一眼当前版本叫什么别硬套。拿到 fx 和 B 之后把你机器的最短可测距离算出来fx_px, B_m, d_max 440.0, 0.075, 190 print(Z_min %.3f m % (fx_px * B_m / d_max))这一步花不了一分钟但它决定了你后面所有的参数取舍。如果你算出来的 Z_min 是 35cm而你的工位最近要测 20cm那你必须开扩展视差、或者降匹配分辨率、或者用视差偏移否则怎么调都是在跟物理规律较劲。2.2 三个近距离增强开关的真实收益与代价DepthAI 的 StereoDepth 节点上有几个开关网上教程大多只告诉你打开更好但没说代价。我在实际项目里逐个试过结论是这样的开关作用收益代价setExtendedDisparity(True)搜索上限翻倍最近距离大约缩短一半计算量上升边缘噪点变多对分辨率有约束setLeftRightCheck(True)左右一致性校验剔除绝大部分错误匹配遮挡区和物体边缘空洞明显变多setSubpixel(True)亚像素插值深度值更平滑量化台阶消失极小视差处的可信度下降需要过滤setConfidenceThreshold(n)匹配置信度门限低置信度区域被清空阈值调太高会把有效点也吃掉setDisparityShift(n)视差范围整体前移能看更近最远距离被硬截断关于setDisparityShift用法很简单但要想清楚再开# 已知我只看 0.15m - 1.2m远距离对我没用就把搜索窗口整体往前推 stereo.setDisparityShift(24)它的逻辑是牺牲远场换近场。如果你的场景里确实有远距离目标比如移动平台既要看脚下又要看前方三米那这个开关不能开得换方案或者加一台相机。我吃过一次亏为了看得更近把视差偏移调大了结果机械臂抬起来之后完全看不到料架高度排查了半天才发现是被自己截断的。还有一个坑藏在setOutputSize里。这个参数设成比输入小的尺寸时参与匹配的等效焦距会变小最近距离反而能拉近但深度精度会下降。不同 SDK 版本对这个参数的处理细节不完全一致所以别信文档结论自己验证同一个物体固定不动改一下输出尺寸看深度图的空洞分布和数值有没有变化。这是最快搞清楚你手上这套 SDK 行为的方法。2.3 用标定文件验证精度误差是随距离平方增长的这一点特别值得单独说因为它经常被误读。双目的深度误差大致和 Z² 成正比ΔZ ≈ Z² × Δθ / B其中 Δθ 是标定和匹配引入的角度误差弧度。我拿 0.1 度约 0.00175 弧度的角误差和 5cm 基线估算目标距离深度误差估算20 cm约 1.4 mm50 cm约 8.8 mm1 m约 35 mm3 m约 315 mm结论很反直觉近距离不但更容易测而且精度天然更好。这正好是 OAK-D-SR 这类小基线近距离机器存在的意义——它把双目方案最擅长的那段距离做成了主场。反过来你如果想用它去测三米外的东西物理上就注定不准硬调参数也没用。3. 跑通第一条近距离流水线DepthAI节点逐个拆解3.1 相机节点为什么近距离场景要锁死曝光先看相机节点。近距离场景我最常做的一件事是手动锁定曝光而不是让它自动调import depthai as dai pipeline dai.Pipeline() monoL pipeline.create(dai.node.MonoCamera) monoR pipeline.create(dai.node.MonoCamera) for cam, socket in ((monoL, dai.CameraBoardSocket.LEFT), (monoR, dai.CameraBoardSocket.RIGHT)): cam.setBoardSocket(socket) cam.setResolution(dai.MonoCameraProperties.SensorResolution.THE_800_P) cam.setFps(30) # 关键左右目必须用完全相同的曝光否则两幅图亮度不一致匹配质量断崖式下跌 cam.initialControl.setManualExposure(8000, 800)为什么一定要手动因为立体匹配本质上是在两幅图里找长得一样的区域。自动曝光是每颗传感器独立决策的两边的积分时间稍微差一点同一块表面在左右图里的灰度就对不上纹理相似度下降匹配直接就崩了。近距离场景里这类问题尤其致命因为物体离得近、反光强自动曝光容易来回振荡深度图会跟着一帧好一帧烂。setManualExposure(曝光微秒数, ISO)这两个数要按你的实际光照试。室内常规照明下 5000 到 10000 微秒是个合理起点太长了会拖帧率太短了噪声大。全局快门传感器在这里帮了大忙——它是整帧同时曝光的机械臂快速运动时不会出现果冻式的行间错位这一点对跟随运动的场景是刚需。3.2 深度节点的参数组合以及每一行为什么这么写深度节点的配置是整个流水线的核心我按注释逐行解释stereo pipeline.create(dai.node.StereoDepth) monoL.out.link(stereo.left) monoR.out.link(stereo.right) # 预设近距离小物体建议 HIGH_DENSITY人脸类场景可试 FACE stereo.setDefaultProfilePreset(dai.node.StereoDepth.PresetMode.HIGH_DENSITY) # 近场视差大必须开扩展视差否则 20-40cm 直接没数据 stereo.setExtendedDisparity(True) # 左右一致性检查宁可留下空洞也不要一堆假点 stereo.setLeftRightCheck(True) # 亚像素让深度值平滑抓取场景里很重要否则点会一跳一跳 stereo.setSubpixel(True) # 置信度门限先给 200 左右太低会有飞点太高近处有效点也保不住 stereo.setConfidenceThreshold(200) # 中值滤波压掉散点代价是物体边缘会被磨掉一两个像素 stereo.setMedianFilter(dai.MedianFilter.KERNEL_7x7) # 输出尺寸决定后续可视化和点云的密度 stereo.setOutputSize(640, 400)这几行里最容易被忽略的是setConfidenceThreshold。它不是一个越高越好的参数而是一个你更怕假点还是更怕空洞的选择。做抓取的时候我通常偏保守因为一个假的深度点会让机械臂直接抓空甚至撞上去做三维重建的时候我会调低因为点云配准能容忍少量离群点。如果你需要把深度对齐到彩色图比如要把颜色贴到点云上加一行stereo.setDepthAlign(dai.CameraBoardSocket.CAM_A)。但注意对齐之后深度图的有效边缘会变窄因为对齐是一个重采样过程近场视差大、遮挡多边缘本来就不牢靠。我的习惯是先在原始左目坐标系里把深度算准需要上色的时候再对齐。3.3 从深度图到彩色点云输出节点的完整写法# 深度图通道 xout_depth pipeline.create(dai.node.XLinkOut) xout_depth.setStreamName(depth) stereo.depth.link(xout_depth.input) # 点云通道可选近距离重建时很有用 pointcloud pipeline.create(dai.node.PointCloud) stereo.depth.link(pointcloud.inputDepth) xout_pcl pipeline.create(dai.node.XLinkOut) xout_pcl.setStreamName(pcl) pointcloud.outputPointCloud.link(xout_pcl.input)跑起来之后读深度图并转成真实的米with dai.Device(pipeline) as device: q_depth device.getOutputQueue(depth, maxSize4, blockingFalse) while True: in_depth q_depth.tryGet() if in_depth is None: continue frame in_depth.getFrame() # uint16单位毫米 z_m frame.astype(float32) / 1000.0 # 0 表示无效点画图前先屏蔽掉 cv2.imshow(depth, cv2.applyColorMap( cv2.convertScaleAbs(frame, alpha0.03), cv2.COLORMAP_JET)) if cv2.waitKey(1) ord(q): break深度帧是 uint16单位毫米值 0 代表没有有效视差。做任何统计之前先把 0 屏蔽掉否则算出来的平均深度会被拉偏。3.4 上手第一件事拿尺子量别信看起来不错可视化出来的彩虹图特别有欺骗性看着挺完整和数值准不准是两件事。我的验证流程很简单拿一块贴了报纸或者打印了随机纹理的硬纸板正对相机放在刻度尺上从 20cm 开始每 5cm 挪一次到 100cm 为止每次记录中心区域的深度中位数、标准差和空洞率。参考值大概长这样我的环境和参数你的会有差异实际距离深度中位数标准差空洞率20 cm20.4 cm2.1 mm12%30 cm30.1 cm1.2 mm6%50 cm50.1 cm1.5 mm4%100 cm100.3 cm4.0 mm9%空洞率这一列特别有诊断价值。如果 20cm 处空洞率超过一半说明你的最近距离还没压够该开扩展视差或者调视差偏移如果 30cm 处反而比 50cm 空洞更多那就是纹理或者曝光的问题跟距离无关。用同一套流程量一遍你对这台机器的边界就有数了后面调参不会再靠感觉。4. 近距离深度图的六个典型坑附排查链路4.1 白墙、桌面、纯色零件深度图成片空洞的根因这是新手遇到的第一个也是最常见的坑。现象是深度图中间一条一条的横向条纹或者大面积全黑。根因不是相机坏而是立体匹配需要纹理——左右两幅图里得有能唯一对应的图案。一块纯白、纯灰的平面上每个像素周围长得都一样匹配算法根本不知道哪个对哪个置信度自然上不去。排查顺序很简单把相机对着有纹理的报纸、木纹桌面、带印花的地毯如果深度图瞬间变完整那就是纹理问题不是设备问题。补救手段按成本从低到高排一是更换表面或临时贴标记工业场景里最常见的做法贴几块随机纹理贴纸几块钱解决问题二是调整打光角度让表面产生自然的明暗渐变斜射光比正射光强得多三是加主动纹理投射散斑投影器这是最彻底的方案但要额外加硬件而且户外强光下效果会打折四是调整setConfidenceThreshold和setLeftRightCheck用放宽标准硬挤出一些点来代价是假点变多。我一般只在静态测量场景用最后一种动态抓取绝对不用。4.2 曝光与红外干扰户外白天为什么表现掉档双目深度是纯被动视觉方案靠的是环境光。到了户外阳光里含大量红外成分会把近处的暗部细节全部淹没对比度被压扁匹配质量直线下降。这不是设备缺陷是所有被动双目在强光下的共性问题。排查办法看深度图的空洞是不是呈现越亮的地方越差的规律如果是基本就是过曝。处理方式是手动降低曝光时间、必要时加窄带滤光片或者把工作时段挪开正午。近距离室内场景里另一个相关坑是对着窗户或灯管拍高光区域直接饱和成一片白那片区域的深度也是废的。调整相机俯仰角避开直射光源往往比调参数有效得多。4.3 玻璃、透明与镜面物理上就无解的那类目标如果你的项目里要测玻璃板、亚克力、抛光金属先接受一个事实被动双目对这类表面基本无能为力。透明物体不反射红外到相机镜面则把附近的场景反射进去算法看到的是假目标。我见过有人把置信度调到最低试图抢救最后拿到的是一堆噪声点比没有更危险。工程上的解法只有绕过换个角度让表面产生可测的漫反射斜 30 到 45 度打光在玻璃上贴一小块哑光胶带做基准点或者干脆换成接触式测量。这一条我建议写进项目文档的需求评审里别等调试阶段才发现。4.4 热漂移与标定为什么长时间跑之前要先热机这是最少被提及、但影响最直接的一条。算力芯片工作一段时间后温度上升结构件产生微米级形变等效于基线长度和左右目的相对姿态发生了极小变化。对远距离相机这几乎无感但对近距离相机这个变化会体现在深度值的系统性偏移上。我的做法是设备开机后先空跑 8 到 10 分钟让温度稳定再做任何精度相关的采集或标定。如果项目要求长时间连续运行就记录温度与深度偏移的对应关系必要时做温度补偿查表。顺带说标定的注意事项。旋转镜头调焦之后一定要重新标定因为光学状态变了。写 EEPROM 之前先执行calib.eepromToJsonFile()存一份出厂备份这个习惯救过我一次——改错参数之后是靠备份文件刷回去的。标定板建议用打印精度高的棋盘格贴在刚性平板上平板不平是标定误差的常见来源比算法本身影响还大。4.5 带宽与供电USB线材导致的帧率崩塌现象是帧率莫名其妙掉到个位数或者干脆设备识别不到。近距离高密度深度图的数据量不小双路高分辨率图像加深度输出走 USB2 或者劣质延长线、带供电不足的 Hub带宽立刻不够。排查链路先看设备是不是枚举在高速口上再换一根短的、质量好的数据线直连主板后置接口最后去掉所有 Hub。我在一个项目里被一根三米长的廉价延长线坑了整整一个下午换线之后帧率恢复满值。这条经验值很低但很实用调试阶段一旦出现性能莫名下降先怀疑线再怀疑代码。4.6 对齐到彩色图后边缘歪了是怎么回事开了深度到彩色的对齐之后你会发现物体边缘出现一圈彩色的晕深度值在边缘处也不准。这不是 bug是两个原因叠加一是两个相机在物理上位置不同近场视差大遮挡区域大对齐是重采样遮挡区没有真实数据二是彩色和单目分辨率不同缩放插值会模糊边界。处理办法尽量在原始左目坐标系里做几何计算只在需要展示或者上色时才对齐如果必须要对齐后的彩色点云把对齐后的边缘区域裁掉再使用别拿边缘的深度值做测量。5. 能直接抄的四个近距离用法含ROI取三维坐标代码5.1 桌面抓取用ROI拿一个稳定的三维点抓取场景不需要整张深度图只需要目标物体中心那一小块的三维坐标而且用 ROI 取平均能有效压掉噪声spatial pipeline.create(dai.node.SpatialLocationCalculator) stereo.depth.link(spatial.inputDepth) spatial.inputConfig.setWaitForMessage(False) cfg dai.SpatialLocationCalculatorConfigData() cfg.depthThresholds.lowerThreshold 150 # 只看 15cm 以上 cfg.depthThresholds.upperThreshold 800 # 忽略 80cm 以外的背景 cfg.roi dai.Rect(dai.Point2f(0.42, 0.42), dai.Point2f(0.58, 0.58)) config dai.SpatialLocationCalculatorConfig() config.addROI(cfg) spatial.initialConfig.addROI(cfg) xout_spatial pipeline.create(dai.node.XLinkOut) xout_spatial.setStreamName(spatial) spatial.out.link(xout_spatial.input)读取的时候q device.getOutputQueue(spatial, maxSize8, blockingFalse) data q.tryGet() if data is not None: for loc in data.getSpatialLocations(): c loc.spatialCoordinates print(X%.1fmm Y%.1fmm Z%.1fmm % (c.x, c.y, c.z))坐标单位是毫米原点在左目相机光心X 向右、Y 向下、Z 向前。这里的lowerThreshold和upperThreshold一定要设它们是过滤背景的关键——近距离场景里最常见的错误就是料盒边缘的深度混进来导致抓取点偏移。我一般让 ROI 比物体实际投影小一圈宁可取到物体内部的一个小区域也不要吃到边缘。5.2 微距三维重建转台加多视角配准的实际细节要把小零件扫成完整模型单视角不够得转。我用的方案是转台每转 30 度采一帧点云一共 12 帧。细节一先用标定好的内参把深度图转成点云不要靠 SDK 直接出的点云做配准因为你自己转换的时候可以控制是否屏蔽无效点、是否做下采样。转换公式就三行z depth_mm / 1000.0 x (u - cx) * z / fx y (v - cy) * z / fy细节二无效点深度 0必须在配准前剔除否则 ICP 会被拉到无穷远或者原点。细节三转台的旋转角度是已知的直接用这个先验做初始对齐比纯 ICP 快得多也稳得多。纯 ICP 对初始位姿很敏感两个视角差 30 度时容易收敛到错误解。细节四近距离点云稠密下采样到 2 到 3mm 的体素再做配准精度损失可以接受速度提升好几倍。5.3 近场补盲给移动平台补上脚下的死角移动机器人正前方的大基线相机在一米以内基本是盲区桌腿、台阶、地面上的线缆全都看不到这是很多碰撞事故的直接原因。用一颗小基线近距离相机朝前下方装专门管 10cm 到 80cm 这一段两个传感器分工明确成本也不高。这里有个实际经验两个深度源的坐标系统一问题比算法本身更花时间。我建议所有深度输出统一转到机器人基座坐标系用一套外参管理别在业务代码里到处做手动的偏移补偿后面改一个参数会牵动一片。5.4 手部与指尖跟踪小视差范围的意外好处近距离做手部交互的时候我发现一个反直觉的好处因为视差搜索范围有限远处背景根本不会产生有效深度这就相当于自带了一个距离滤波器背景干扰天然被排除。用人脸或手部预设跑深度图里只有手是实的后面的墙是空的。代价是要注意手的运动速度。手在近场移动时像素位移很快曝光时间必须压短我一般用 3000 到 5000 微秒。另外手的表面纹理弱皮肤在红外下比较均匀空洞率会比测纸板高不少做指尖定位时要加时序滤波补点。6. 选型账本什么时候SR是对的什么时候该换6.1 一张表看清几类方案的边界方案类型近场20-40cm中远场强光户外无纹理表面小基线被动双目SR这类好精度快速衰减差差常规/大基线双目基本不可用好差差主动纹理投射双目好好中等好结构光好差衰减快差好飞行时间类受最小距离限制中等中等好看这张表就很清楚了如果是近距离 有纹理 室内受控光照小基线被动双目是性价比最高的选择算力还自带在模组里不用额外主机。一旦你的场景里出现强光户外或者大面积白墙就必须考虑主动投射这时候小基线被动方案的短板暴露得最彻底。6.2 我自己的选型顺序距离、精度、体积吃过几次亏之后我现在的评估顺序固定成三步。第一步先问最近要测多近、最远要测多远把区间画出来然后对照 Z_min 公式判断哪些方案在区间内。这一步能砍掉大部分候选。第二步问深度误差容忍多少用 ΔZ ≈ Z²Δθ/B 估算如果算出来的误差大于公差方案直接否掉别指望后处理能把物理误差修回来。第三步才问体积、接口、算力、功耗这些工程约束。这个顺序的关键在于前两步是物理约束改不了第三步是工程约束能用钱和时间解决。很多人反过来先挑型号再看参数最后只能在参数上妥协。6.3 想往上走下一步可以试什么如果你发现被动方案在你的场景里实在撑不住两个方向可以试。一是加主动纹理投射把无纹理表面的问题解决掉同时扩展近距离的可用范围这是收益最直接的一步。二是做多相机分工近距离一颗、中距离一颗用统一的坐标变换把数据合起来软件上多写一点融合逻辑但每颗相机都在自己最擅长的区间工作整体精度比单颗硬撑高得多。如果你的目标是把近距离的精度再往上顶一档还有一条路是提高匹配分辨率再配更好的标定。前面那张表里f_px 翻倍会让最小距离变远但深度精度会明显变好所以要更近和要更准在同一个方案里是要权衡的想同时拿到就得双相机分工这是绕不过去的取舍。最后分享一个小习惯。我现在每拿到一颗新的深度相机第一件事不是跑官方示例而是读标定、算 Z_min、量一遍尺子。这三件事加起来不到半小时但它决定了后面两周我会不会在参数里瞎转。踩过几次坑之后我越来越确信深度相机的调试从来不是调参数的艺术而是先把物理边界摸清楚再在边界内做工程的过程。