企业官网建设流程全解析

• 计算机视觉
• 深度学习
• 图像处理

本篇技术指南聚焦 Kornia 迁移日志条目 changelog.d/+migration-019.fixed.md 所记录的缺陷修复：kornia.geometry.depth.depth_to_normals现在会在输入深度图的H < 2或W < 2时抛出ShapeError，因为表面法线需要两个切向方向。读完本文，你将理解该修复的数学动机、ShapeError的异常契约与错误信息格式、如何用pytest.raises复现验证，以及 2×2 及以上尺寸输入的行为保持不变这一兼容性边界。

迁移背景：一处边界输入导致的数值病态

在 Kornia 的 RGB-D 几何算子家族中，depth_to_normals负责从深度图反投影出逐像素 3D 点云、再以空间梯度叉积求出表面法线，是点云法线估计、平面检测与法线贴图管线的常用算子。迁移日志条目 #4458 记录的修复直指一个此前未被显式约束的输入条件：

depth_to_normals现在在H < 2或W < 2时抛出ShapeError，因为表面法线需要两个切向方向。此前，单例轴可能产生零或非有限法线，而空的空间维度会在 padding 内部失败。两个维度都至少为 2 的输入行为不变。

也就是说，这不是一次纯粹的 API 收紧，而是对既有数值病态行为的显式化：修复之前，H == 1或W == 1这类退化输入并不会被入口守卫拦截，而是流入后续计算，产生难以排查的静默错误。

为什么需要两个切向方向：法线的数学定义

表面法线在微分几何上定义为两个线性无关切向量的叉积并归一化。对于离散深度图，实现取未投影点云在行、列两个方向上的空间梯度，并按d/dx叉乘d/dy的顺序计算：

a = gradients[:, :, 0] # d/dx 方向的切向量 b = gradients[:, :, 1] # d/dy 方向的切向量 normals = torch.linalg.cross(a, b, dim=-1) return F.normalize(normals, dim=-1, p=2)

对应源码见 kornia/geometry/depth.py。当任一空间维度为 1 时，对应方向不存在真正的差分（spatial_gradient退化到零向量或奇异差分），叉积结果要么是零向量（归一化后产生 NaN/零），要么是数值上不稳定的非有限值——这正是迁移日志所说的"零或非有限法线"。而空维度（H == 0或W == 0）则会在F.pad这类 padding 操作内部直接崩溃。

源码级修复：入口守卫的显式断言

修复在函数入口处、常规形状校验之后加入显式维度检查（kornia/geometry/depth.py）：

height, width = depth.shape[-2:] if height < 2 or width < 2: raise ShapeError( f"depth_to_normals requires H >= 2 and W >= 2. Got H={height}, W={width}.", actual_shape=list(depth.shape), expected_shape=["B", "1", "H >= 2", "W >= 2"], )

在守卫之前，函数仍会执行KORNIA_CHECK_IS_TENSOR、KORNIA_CHECK_SHAPE(depth, ["B", "1", "H", "W"])与KORNIA_CHECK_SHAPE(camera_matrix, ["B", "3", "3"])等通用校验（kornia/geometry/depth.py），因此新的检查只负责拦截"形状合法但空间维度退化"这一此前漏掉的子集。

ShapeError的异常契约

ShapeError定义于 kornia/core/exceptions.py，继承自BaseError，并携带结构化属性：

• message：人类可读的错误说明；
• actual_shape：触发错误的实际张量形状（tuple或list）；
• expected_shape：期望的形状规格说明（如["B", "1", "H >= 2", "W >= 2"]）。

这意味着调用方可以不用解析字符串，直接通过exc.actual_shape拿到退化形状做程序化处理。

与既有守卫的层级关系

对比同文件其他算子的入口守卫可以发现一致的"通用形状校验 + 语义前置条件校验"模式：

• depth_to_3d/depth_to_3d_v2只要求(*, H, W)形状，不要求最小尺寸（kornia/geometry/depth.py），因为它们不做差分运算；
• warp_frame_depth同样只校验形状（kornia/geometry/depth.py），空 batch 时走显式的零输出快速路径；
• 唯独depth_to_normals因梯度运算的性质增加了H >= 2 and W >= 2的语义前置条件。

错误信息与测试验证：测试即文档

Kornia 的测试套件将本次修复固化为专门的回归测试，见 tests/geometry/test_depth.py 的TestDepthToNormals.test_convention_normals_require_two_spatial_axes_4398：

@pytest.mark.parametrize(("height", "width"), [(1, 3), (3, 1), (1, 1), (0, 3), (3, 0), (0, 0)]) @pytest.mark.parametrize("normalize_points", [False, True]) def test_convention_normals_require_two_spatial_axes_4398(self, height, width, normalize_points, device, dtype): depth = torch.full((1, 1, height, width), 2.0, device=device, dtype=dtype) camera_matrix = torch.eye(3, device=device, dtype=dtype)[None] with pytest.raises(ShapeError, match="H >= 2 and W >= 2") as exc_info: depth_to_normals(depth, camera_matrix, normalize_points) assert exc_info.value.actual_shape == list(depth.shape) assert f"H={height}, W={width}" in str(exc_info.value)

该测试覆盖了全部退化组合：(1, 3)、(3, 1)、(1, 1)单例轴，以及(0, 3)、(3, 0)、(0, 0)空维度，并且对normalize_points的两种取值（False表示 depth 为相机系 z 值、True表示欧氏射线长度）都做了验证。三个断言逐条印证了ShapeError的契约：

1. 错误消息必须包含"H >= 2 and W >= 2"（match正则）；
2. actual_shape属性等于输入的真实形状；
3. 消息中包含实际的H、W值，便于定位问题来源。

兼容性边界：合法输入行为不变

修复严格限定在退化输入上，H >= 2且W >= 2的输入路径完全不受影响。同文件测试提供了多组证据：

• 最小合法尺寸：(2, 2)、(2, 3)、(3, 2)的前平行平面测试断言法线恰为(0, 0, 1)且结果全有限（tests/geometry/test_depth.py）；
• 常规尺寸：(3, 4)smoke 测试验证输出形状为(B, 3, H, W)（tests/geometry/test_depth.py）；
• batch 与广播：(2, 3, 3, 4)等 batch 输入及camera_matrix为(1, 3, 3)的广播场景均正常工作（tests/geometry/test_depth.py）；
• 编译兼容：torch_optimizer(depth_to_normals, fullgraph=True)的 dynamo 全图编译测试确认守卫分支可被图编译器正确捕获（tests/geometry/test_depth.py）。

对调用方的迁移影响与建议

作为fixed类型迁移，本条目要求调用方关注两点：

1. 输入前置校验：若你的管线可能产生H == 1、W == 1或空尺寸的深度图（例如缩放后的低分辨率图、裁剪边界），应在调用前自行规避，或捕获ShapeError做降级处理：

   from kornia.core.exceptions import ShapeError try: normals = depth_to_normals(depth, K) except ShapeError as e: # e.actual_shape 可直接用于日志或条件分支 normals = fallback # 例如按前平行平面假设填充 (0, 0, 1)

2. 与同模块算子的区别对待：depth_to_3d_v2、unproject_meshgrid等函数接受任意空间尺寸（测试 tests/geometry/test_depth.py 明确验证了(1, 1)、(1, 3)、(3, 1)等退化网格仍能正确返回(B, H, W, 3)），它们不需要两个切向方向，因此不受本次收紧影响。若你的上游是这些算子、下游接depth_to_normals，需在两者之间补一次尺寸判断。

小结

depth_to_normals的ShapeError校验是 Kornia 对"数学定义域约束"显式化的典型范例：它将此前静默产生零/NaN/非有限法线的退化输入，转化为携带结构化形状信息的可捕获异常。对使用方而言，这消除了一个隐蔽的数值陷阱；对 Kornia 自身而言，test_convention_normals_require_two_spatial_axes_4398等回归测试确保了该契约在后续版本中持续生效。

• 计算机视觉
• 深度学习
• 图像处理