单应：平面场景的快捷通道

1. 高 inlier 的 H，AR 虚拟物仍飘

地面 AR overlay，findHomography RANSAC inlier 90%+——但家具、行人 depth 差大，虚拟框「贴地」却随视角漂。inlier 定义在 重投影误差 上，不是物理平面正确性。非平面点被 H 强行解释 为 outlier 或被 warp 拉歪，不能只看 inlier 数。产品 demo 在空厂房好看，一进真实库房就穿帮，多半是场景非平面却信仰了 RANSAC 分数。

单应 H 是降维打击，前提是问题真是平的或 纯旋转（绕光心）。

2. 模型

x^{'} \sim H x, H \in R^{3 \times 3},; rank (H) = 2

8 DOF（scale 自由）。平面 $π$ 上 3D 点精确满足 homography；一般 3D 只有 dominant plane 或纯旋转时 H 合理。cv2.decomposeHomographyMat(H, K) 返回最多 4 组 $(R, t, n)$ ，需 cheirality 选解。平面诱导公式把平面法向与距离编码进 H，分解后可检查法向是否与「地面」先验一致。

3. OpenCV 用法

python

H, mask = cv2.findHomography(
    src, dst, cv2.RANSAC, ransacReprojThreshold=3.0)
warped = cv2.warpPerspective(img, H, (w, h))

ransacReprojThreshold 单位像素，在 undistort 后图像上设，常见 2–5 px。OpenCV 4 可用 cv2.USAC_MAGSAC。inlier 上再 findHomography(inliers, method=0) 做 DLT refine，可降 0.2–0.5 px RMS。匹配点 spread 要够；共线四点 homography 退化，SVD 检查条件数。

4. 何时用 H 而非 E/F

标定板、文档扫描、假设 flat ground 的 BEV；panorama stitching（旋转 + 远平面近似）；平面 AR 初始化。别用：有明显 baseline 和 parallax 的 VO 初始化——应 findEssentialMat。文档扫描与 AR 地面虽都用 H，但前者点几乎共面，后者常有近处非平面遮挡——后者必须 ROI 或 F/H 竞争。

5. F vs H 竞争

对同一匹配集分别 RANSAC 估 F 和 H，比较 inlier count 和 mean Sampson error。平面 dominant 时 H score 常碾压 F，但要看 outlier 比例和 depth 先验。moving object 污染——ROI 到平面 patch 或 motion mask 后再估 H。小 motion 可 H_curr = H_prev @ delta_H 减 jitter，大 motion 或遮挡变多时应全量重估。

6. warpPerspective 与有效像素

dsize 取 dst 尺寸；H 把 src 四角映到 dst，黑边来自 out-of-bound。warp + mask 统计有效像素比例；比例掉太多说明 H 极端或 FOV 不匹配。AR「飘」常先于 seam 暴露——看非平面点 residual 是否被 H 系统性压低。stitch 的 photometric gain 另论，但平面 AR 应先过几何验收再过调色。

7. 退化与 rolling shutter

四点共线时 homography 仍可能有解但无意义。平面 AR 每帧全图 RANSAC 会被行人污染；静态背景 mask + 特征匹配是常见组合。rolling shutter 快速平移时「平面」warp 出现 seam，此时 H 模型本身受限，需 RS 校正或降速。坡道地面局部 H OK 全局弯，BEV 应用应分段平面或改用 DEM/SLAM。

8. 失败模式

深度倾斜平面：局部 OK 全局弯。移动物体：静态假设被违反。未 undistort：像素域直线变曲线，H bias。

9. 验收

warp 后 photometric error / seam；非平面点 residual 是否被 H 系统性压低。AR 虚拟物是否「飘」是下游最直观指标。F/H 竞争结果写进 debug overlay；参数 yaml：h_ransac_px、usac_on、roi_mask_path。hold-out 场景 clip 虚拟物 anchor 误差超 SOP 则回滚，而不是继续降 threshold 换 inlier。

10. 案例：F/H 竞争揭穿假平面

库房 AR 地面贴标，H inlier 92%、F inlier 61%——看似该用 H。但非平面点（货架腿）被 H 标为 outlier 的比例仅 15%，说明大量 furniture 点仍被 H 低误差「吃掉」，虚拟框在腿边飘。加 depth ROI mask 只估地面 patch 后，H inlier 降到 78% 但 anchor 误差减半。教训：inlier 高 + 物理错 并存时，看 outlier 空间分布与下游 anchor，不是单一 RANSAC 分。

11. 与 BEV / 文档扫描的差异

文档扫描四点共面、纹理丰富，H 几乎总是对的。地面 BEV 假设 flat ground，但坡道与路缘石引入非平面——H warp 后直线变弯，应用分段 H 或改用 DEM/点云。选型时在 PR 里写清 场景平面假设，避免把文档扫描代码直接拷到 AR 地面而不做 F/H 竞争。stitch 与 AR 共用 H 时，photometric 补偿与 seam 切分是下一层问题——几何 H 不对时调 gain 无济于事。平面假设写进需求文档，测试用例包含「非平面 dominant」clip 必 fail。homography PR 应附 F/H 竞争表格截图，inlier 高但 anchor 差时不得 merge。记录每帧 H 条件数便于离线筛退化帧。

怀疑时做 F/H 竞争，比信仰 RANSAC 分数更老实。