SGBM：我先动哪些参数

1. 白墙不是加平滑能救

算力紧时传统 stereo 仍能干活，SGBM 在纹理丰富场景深度可用。近处物体 depth 卡在一堵「墙」上，边缘 fat、中心空洞——调 P2 没用，根因是 numDisparities 不够。最近距离、基线、焦距，最大视差约 $d_{\max }\approx f\cdot B/Z_{\min }$。搜索范围不够则 depth 截断，这是最常见的静默失败，表现为物体边缘深度墙、中心无效视差。白墙、纯色的问题是纹理弱，不是平滑参数能救——那是物理限制，别在白墙上猛加 P2。

2. 创建与核心参数

sgbm = cv2.StereoSGBM_create(
    minDisparity=0,
    numDisparities=128,   # 必须被 16 整除
    blockSize=5,
    P1=8 * 3 * 5**2,
    P2=32 * 3 * 5**2,
    disp12MaxDiff=1,
    uniquenessRatio=10,
    speckleWindowSize=100,
    speckleRange=2,
    mode=cv2.STEREO_SGBM_MODE_SGBM_3WAY)
disp = sgbm.compute(left_rect, right_rect).astype(np.float32) / 16.0

numDisparities 设搜索范围；blockSize 三到十一奇数，纹理强用小 block 保细节，弱纹理略大可减噪但边缘 fat。P1 惩罚小视差不连续，P2 惩罚大视差不连续；OpenCV 默认 P1 等于八乘三乘 blockSize 平方，P2 等于三十二乘三乘 blockSize 平方。mode=SGBM_3WAY 更快略损精度。

3. 视差转深度与调参顺序

焦距用 rectified 后像素单位，基线与 T 同单位，d 是视差像素。例：基线零点一二米，焦距七百像素，最近距离零点五米 → 最大视差约一百六十八 → numDisparities 设一百七十六（向上取十六倍数）。我调参顺序：numDisparities → blockSize → P1/P2 → uniquenessRatio（十到十五，太高空洞多）→ speckle。minDisparity 非零时对应更近物体被 clip；户外远场景可设 minDisparity 大于零收窄搜索省算力。

4. 后处理

disp12MaxDiff 做左右一致性；speckle 去小连通域。contrib 模块 WLS 滤波加 right matcher 可减 fat edge（lambda 八千、sigma 一点五常见起点）。无 contrib 时自写 left-right consistency：左视差减右视差在对应位置差小于阈值。StereoBM 比 SGBM 快、纹理弱处更噪——实时 preview 用 BM，离线 depth 用 SGBM 加 WLS。

5. 失败模式

6. 验收

已知距离板 RMSE；无效视差比例；近距离 object 是否 hit disparity max。对比 numDisparities 加倍后 depth 截断是否消失——最快的根因测试。SGBM 不是 SOTA，但参数有物理意义；先保证搜索范围覆盖工作距离，再谈网络替换。

7. 案例：深度墙是 numDisparities 不够

某双目抓取最近工作距离零点四米，numDisparities 设六十四，近处物体 depth 全卡在同一值——不是匹配算法坏，是搜索范围不够。按公式算 d_max 约二百一十，改 numDisparities 为二百二十四后深度墙消失。这是最快的根因测试，比调 P2 有效得多。

8. 与 rectification 联动

SGBM 假设极线水平、只需一维搜索。rectification 残余 vertical disparity 大于零点五像素时，SGBM 参数再调也是枉然——先在 rectified pair 上验 dy 分布，再动 SGBM。深度链路是标定 → 校正 → 匹配 → 重投影，不能跳步。

9. 配置与验收清单

numDisparities、blockSize、uniquenessRatio、speckle 写进 yaml；启动时按 f、B、Z_min 打印推荐 numDisparities 下界。验收：已知距离板 RMSE；无效视差比例；近距是否 hit disparity max；numDisparities 加倍后 depth 墙是否消失。SGBM 参数有物理意义，先覆盖工作距离再谈替换。

10. StereoBM 与实时 preview

StereoBM 比 SGBM 快、弱纹理更噪——实时 preview 用 BM，离线 depth 用 SGBM 加 WLS。mode、P1/P2 默认值与 blockSize 联动关系应写进文档，避免手调 P2 时忘记 blockSize 已变。白墙问题是纹理，不是平滑能救。深度截断先查 numDisparities 是否覆盖 $Z_{\min }$；rectification 残余 $dy$ 大于半像素时，SGBM 再调也枉然。WLS 要 contrib ximgproc 与 right matcher；无 contrib 时用 left-right consistency。disp 除以 16 转 float 后再 reprojectImageTo3D，格式错则深度全偏。

11. 工作距离公式钉死参数下界

工作距离下界 $Z_{\min }$ 决定视差上界 $d_{\max }\approx fB/Z_{\min }$。numDisparities 必须 $\ge d_{\max }$ 且为 16 的倍数。启动日志打印 $f$、$B$、$Z_{\min }$ 与推荐 numDisparities，比「经验开 128」可靠。近距抓取改焦后重算一次，否则深度墙会换个距离再现。