Kornia 相机标定修复深度解析:非零 sensor tilt 下 tilt_projection 与 distort_points 的 OpenCV 对齐实现
Kornia 相机标定修复深度解析:非零 sensor tilt 下 tilt_projection 与 distort_points 的 OpenCV 对齐实现
导读
本文围绕 Kornia 变更记录中一项关键修复展开:changelog.d/+migration-015.fixed.md 所记载的“修正非零 sensor tilt 下 tilt_projection 与 distort_points 以匹配 OpenCV,恢复 forward/inverse round trip,并修正 undistort_image 采样”(对应 PR #4384)。你将看到该修复在源码中的具体形态:tilt 投影矩阵的旋转约定(R = Ry(tauy) @ Rx(taux))、正向/逆向两条分支的构造方式、distort_points 与 undistort_points 的对称设计,以及测试层面对 OpenCV 参考值的严格对齐验证。读完你可以直接在 Kornia 中正确使用 14 系数畸变模型(含 τx、τy),并理解为什么这一修复能让“先畸变再去畸变”的往返操作闭环。
修复背景:sensor tilt 在畸变模型中的位置
OpenCV 的完整镜头畸变模型由 14 个系数描述,Kornia 在 distort_points 与 undistort_points 的文档字符串中明确列出了其顺序:
(k1, k2, p1, p2[, k3[, k4, k5, k6[, s1, s2, s3, s4[, τx, τy]]]])
即:6 个径向系数(k1...k6)、2 个切向系数(p1, p2)、4 个薄棱镜系数(s1...s4),以及最后两个 sensor tilt 角度 τx(绕 x 轴)与 τy(绕 y 轴)。Kornia 在 kornia/geometry/calibration/distort.py 与 kornia/geometry/calibration/undistort.py 中同时支持这四种畸变成分,而本次修复聚焦的就是前 12 个系数为零时并不生效、一旦非零即影响全局的 tilt 部分。
该修复并非孤立改动,它由更早的 issue #4276 牵引而来:当时非零 tilt 下 distort_points 与 undistort_points 无法形成正确的往返关系(round trip),修复后测试文件 tests/geometry/calibration/test_distort.py 与 tests/geometry/calibration/test_undistort.py 中以 _4276 后缀命名了一系列“约定钉子”(convention pin)测试,将修复后的行为固化下来。
tilt_projection:矩阵构造约定与两条分支
tilt_projection 是本次修复的核心函数,位于 kornia/geometry/calibration/distort.py#L27-L109,其代码注释明确标注“基于 OpenCV 的 distortion_model.hpp”实现。修复后确立了以下约定:
旋转约定:R = Ry(tauy) @ Rx(taux)
tilt 的物理含义是传感器平面相对理想成像平面的倾斜。Kornia 采用独立欧拉角构造旋转矩阵:
Rx:绕 x 轴旋转taux,形如[[1, 0, 0], [0, cos(τx), sin(τx)], [0, -sin(τx), cos(τx)]];Ry:绕 y 轴旋转tauy,形如[[cos(τy), 0, -sin(τy)], [0, 1, 0], [sin(τy), 0, cos(τy)]];- 最终旋转
R = Ry @ Rx。
测试 test_convention_tilt_projection_forward_is_pz_times_r_4276(tests/geometry/calibration/test_distort.py)用独立的 euler_angles_to_rotation_matrix(-taux, -tauy, zero) 构造参考 R,并断言 tilt_projection(taux, tauy) 严格等于 Pz @ R,从外部验证了旋转次序没有被内部实现悄悄“纠正”。
正向分支:Pz @ R
当 return_inverse=False(默认)时,函数返回 Pz @ R。其中 Pz 是一个由 R 第三列元素构造的透视投影矩阵:
Pz = [[R22, 0, -R02],
[ 0, R22, -R12],
[ 0, 0, 1 ]]
Pz @ R 将倾斜传感器的点投影到成像平面,这正是 OpenCV tilt projection 的定义。这一分支被 distort_points 使用,对应“归一化平面 → 畸变(含 tilt)点”的变换。
逆向分支:Rᵀ @ Pz⁻¹
当 return_inverse=True 时,函数先构造 Pz 的逆(借助 1/R22 缩放),再返回 R.transpose(-1, -2) @ invPz,即完整的 (Pz @ R)⁻¹。这一分支被 undistort_points 使用,是 undistortPoints 语义在 Kornia 上的复现。
测试 test_convention_tilt_projection_branches_are_inverses_4276 断言 tilt_projection(τx, τy) @ tilt_projection(τx, τy, True) 严格等于单位阵 eye(3);而 test_convention_tilt_projection_inverse_branch_inverts_pz_times_r 更进一步,验证“逆向分支必须精确逆掉 Pz @ R”,并故意用错误的 Rᵀ 变体对比,证明该测试能捕捉约定错误(错误的残差超过 0.1,远高于正确路径的浮点精度)。
零角度恒等:不破坏已有 12 系数用户
修复刻意保证:当 τx = τy = 0(即 dist 向量第 13、14 位为零)时,两条分支都精确返回 eye(3)。测试 test_convention_tilt_projection_zero_angles_are_the_identity 用 torch.equal 严格断言了这一点。这意味着只使用 4/5/8/12 系数(不带 tilt)的既有用户,行为完全不受影响——这是本次修复“不引入破坏性变更”的关键设计。
distort_points 的 tilt 应用与参数语义
修复后的 distort_points 完整流程为:
- 像素 → 归一化平面:用
new_K的(fx, fy, cx, cy)将输入像素坐标去归一化; - 径向/切向/薄棱镜畸变:计算
r2, r4, r6,按 OpenCV 的分式径向模型rad_poly施加k1...k6,再叠加p1, p2切向项与s1...s4薄棱镜项; - tilt 投影:若
τx或τy非零,用tilt_projection(τx, τy)(正向分支)对畸变点做透视投影,并做齐次除法xd/w, yd/w; - 归一化平面 → 像素:用
K的(fx, fy, cx, cy)重新映射回像素坐标。
几个值得注意的语义细节(均为函数文档与源码共同确认):
dist长度约束:只接受 4、5、8、12、14 五种长度,其他长度抛ValueError;短向量内部用F.pad补零到 14,因此 4 系数向量与它对应的 14 系数零填充版本结果完全一致。new_K与K的角色相反:new_K负责把输入像素映射到归一化平面,K负责把畸变后的归一化点映射回像素。new_K默认等于K;传入不同矩阵时,它缩放/平移的是输入而非结果。- 编译/导出路径无条件走 tilt 分支:由于图捕获(graph capture)无法在主机侧读取系数值,代码用
is_exporting()/is_compiling()判断,在 TorchScript 编译或 ONNX 导出时无条件应用 tilt 分支,此时零角度恰好给出恒等变换,行为与 eager 模式一致(见 distort.py#L214-L225)。
undistort_points 与 undistort_image:修复如何传导
undistort_points:逆向 tilt + 定点迭代
undistort_points 是 distort_points 的逆映射,采用 OpenCV undistort.dispatch.cpp 相同的思路:
- 先反向施加 tilt:调用
tilt_projection(τx, τy, return_inverse=True),用transform_points把归一化点按逆向分支变换(undistort.py#L130-L136); - 再用
num_iters(默认 5)次定点迭代逼近径向/切向/薄棱镜的逆。
文档明确说明:该逆是迭代近似而非闭式解,因此往返精度受迭代次数约束——float16 在默认迭代次数下已触及舍入下限,float32/float64 增大 num_iters 可继续收敛。同时文档也警告:迭代无收敛判定,在有效半径之外可能进入两点循环(issue #4285),答案会依赖 num_iters 的奇偶性。
undistort_image:采样链路的关键修复
undistort_image 的修复价值在于它完全建立在 distort_points 之上:
- 用
create_meshgrid生成整数像素中心的网格(左上角中心为(0,0),与 Kornia 的整数像素中心约定一致); - 把整张网格的
(rows*cols, 2)点批量交给distort_points,得到采样坐标mapx, mapy; - 用
remap(..., align_corners=True)完成双线性重采样。
因此,只要 distort_points 的 tilt 行为正确,undistort_image 的采样自然被修正——这正是变更记录中“修正 undistort_image 采样”的底层机制:它本身不实现畸变模型,而是转发给已修复的 distort_points。测试 test_convention_undistort_image_is_remap_of_distort_points(tests/geometry/calibration/test_undistort.py)专门断言 undistort_image(image, K, dist) 与“先 distort_points 建图再 remap”逐位一致。
测试证据:OpenCV 参考值与往返闭环
修复的有效性由两类测试锁定:
OpenCV 参考值测试(14 系数,含非零 tilt)
tests/geometry/calibration/test_undistort.py 中保留了用 cv2.undistortPoints 生成期望值的测试(如 test_opencv_undistort_points、test_opencv_stereo),使用包含 14 个系数的真实标定数据(含非零 τx = -0.17322, τy = 0.0023154 等),断言 undistort_points 输出与 OpenCV 输出在 rtol=1e-4, atol=1e-4 内一致;随后又增加一条关键断言(test_undistort.py#L234-L235):对 OpenCV 独立求出的去畸变点再做一次 distort_points,必须恢复原始输入——即 forward 方向也要与 OpenCV 互逆。
往返(round trip)测试
test_convention_distort_undistort_round_trip_with_tilt_4276 专门构造“非零径向/切向系数 + 不相等 tilt 角 (0.1, 0.2)”这一曾暴露 #4276 的组合,断言:
undistort_points(distort_points(points, K, tilted), K, tilted) ≈ points
其中 tilt 为 (0.1, 0.2)、含 12 个非零前置系数的用例与零 tilt 用例均须通过(float16 放宽到 2 ulp 容差)。test_convention_undistort_points_inverts_distort_points 则给出量化残差参考:float32 往返残差约 3.81e-05 像素,float64 约 4.62e-05,且增大 num_iters 到 50 仍通过——在默认 5 步迭代下即达到 dtype 容差。
迁移影响与使用建议
作为 changelog.d/+migration-015.fixed.md 记录的内容,该修复对使用 tilt 的开发者意味着结果数值会发生变化(向 OpenCV 靠拢),但 API 签名不变:
- 如果你的
dist向量第 13、14 位全为零,本次修复不影响任何输出; - 如果使用了非零
τx/τy,tilt_projection、distort_points、undistort_points、undistort_image的结果会与修复前不同,且现在与 OpenCV 对齐、往返闭环可成立; - 涉及
undistort_image的既有管线,因采样图由修复后的distort_points生成,去畸变结果会随之修正,无需改动调用代码。
建议在升级后,用 OpenCV 标定数据对 distort_points/undistort_points 做一次互逆性回归验证;若追求更高往返精度,可将 undistort_points 的 num_iters 从默认 5 提高至 20~50(float32/float64 下有效,float16 已触底)。需要理解 14 系数布局、批次与 new_K 语义的读者,可直接阅读 kornia/geometry/calibration/distort.py 与 kornia/geometry/calibration/undistort.py 的完整 docstring,并以 tests/geometry/calibration/test_distort.py、tests/geometry/calibration/test_undistort.py 与 tests/geometry/calibration/test_compile.py 作为行为契约。