Kornia YUV422 转换中的色度平面形状校验：`yuv422_to_rgb` 如何用 `ShapeError` 取代裸 `RuntimeError`

• 计算机视觉
• 人工智能
• 深度学习
• 图像处理

导读

本文围绕 Kornia 颜色空间转换模块中的一个具体修复展开：在yuv422_to_rgb中新增对色度（chroma）平面高度的显式校验，使得输入形状不匹配时抛出语义明确的ShapeError，而不是在底层torch.cat处崩溃并抛出一个裸RuntimeError。通过本文，你将理解 4:2:2 色度子采样对张量形状的精确约束、Kornia 异常体系的继承关系（ShapeError为什么是"抓不到"的），以及这一改动对调用方错误处理代码的潜在影响。

背景：4:2:2 子采样下的 YUV 平面形状约定

Kornia 的 YUV 系列转换遵循 BT.470-5（M/PAL 标准）的取值，其中yuv422_to_rgb接收两个独立的平面张量：

• imagey：亮度（luma）平面，形状为(*, 1, H, W)；
• imageuv：色度（chroma）平面，形状为(*, 2, H, W/2)。

关键点在于4:2:2 只对宽度进行 1/2 子采样，高度保持不变，因此色度平面与亮度平面拥有相同的高度H。这一点与它的 4:2:0 "孪生兄弟"yuv420_to_rgb明显不同——后者要求色度平面在高度和宽度两个轴上都减半，即(*, 2, H/2, W/2)。相关实现位于 kornia/color/yuv.py。

在 Kornia 中，这两个函数分别对应的模块封装是Yuv420ToRgb与Yuv422ToRgb（见 kornia/color/yuv.py），并统一通过kornia.color命名空间导出（见 kornia/color/init.py）。

修复内容：为yuv422_to_rgb补上高度校验

本次变更（对应 changelog 条目 changelog.d/+migration-118.fixed.md）的核心是：校验yuv422_to_rgb中色度平面的高度。此前该函数的形状守卫只检查了宽度比例（色度宽度必须为亮度宽度的一半），却没有检查高度必须相等；当用户传入一个高度不匹配的色度平面时，代码会一路执行到torch.cat，在那里以一条难以定位的裸RuntimeError结束。

修复后的形状守卫位于 kornia/color/yuv.py，完整逻辑为：

if ( len(imageuv.shape) < 2 or len(imagey.shape) < 2 or imagey.shape[-2] != imageuv.shape[-2] or imagey.shape[-1] != 2 * imageuv.shape[-1] ): raise ShapeError( f"Input imageuv H must match the luma plane and W must be half its size. " f"Got {imagey.shape} and {imageuv.shape}" )

对照yuv420_to_rgb的守卫（kornia/color/yuv.py）可以看出两者的差异正是子采样约定的体现：

在守卫通过之后，函数才执行"先上采样、再拼接"的流程：色度平面沿宽度方向repeat_interleave(2, dim=-1)扩展为与亮度同宽，随后与亮度平面在通道维拼接成 4:4:4 张量，最后交给yuv_to_rgb（见 kornia/color/yuv.py）。

为什么异常类型很重要：ShapeError不属于RuntimeError

这次修复不仅是"提前报错"，还改变了错误的可捕获性。Kornia 的自定义异常体系定义在 kornia/core/exceptions.py：

class BaseError(Exception): """Base exception class for all Kornia errors.""" class ShapeError(BaseError): """Raised when tensor shape validation fails."""

也就是说，异常继承链为：

ShapeError -> BaseError -> Exception

BaseError直接继承自Exception，并没有经过RuntimeError。因此，任何在调用yuv422_to_rgb时用except RuntimeError来兜底"畸形色度平面"的代码，在这项修复之后将不再能捕获到该错误，因为现在抛出的是ShapeError。这是对调用方而言最重要的兼容性变化——如果你有这样的捕获逻辑，需要改为捕获ShapeError（或更宽泛的BaseError）。

行为不变性：正常输入不受影响

该修复刻意保持了向后兼容：任何之前能正常工作的输入，其行为都不会改变。原因在于旧代码中torch.cat本身就会拒绝所有高度不匹配的拼接——只是以一种晦涩的底层错误形式失败；新守卫只是把这些失败提前、并转化为语义清晰的ShapeError。换句话说，这是一次"错误路径上的可观测变化"（error-path observable change），而非功能行为变化。

边界情况与遗留问题：#4056

变更说明中还记录了一个值得注意的边界行为：宽度为零的色度平面。

• 当色度平面宽度为 0 且高度也不匹配时，新的高度校验子句会短路宽度除法，直接抛出ShapeError；
• 但当宽度为 0 且高度恰好匹配时，旧的宽度比例校验仍会执行除法imagey.shape[-1] != 2 * imageuv.shape[-1]，即W != 2 * 0，此时会抛出ZeroDivisionError。这一情况在本次变更中未被处理，被明确标注为遗留问题#4056。

测试套件中对此有专门钉住的用例：在 tests/color/test_yuv.py 中，imgy = torch.ones(1, 4, 6)搭配imguv = torch.ones(2, 4, 0)被断言抛出ShapeError；而 tests/color/test_yuv.py 则验证了"亮度/色度一致地为零尺寸"的输入（0 == 2 * 0通过守卫）会返回空的 RGB 平面，钉住了"空输入进、空输出出"的约定。

完整校验链：从KORNIA_CHECK_SHAPE到自定义守卫

值得注意的是，yuv422_to_rgb中的形状守卫是在KORNIA_CHECK_SHAPE基础之上的第二层检查。函数开头先对两个输入分别执行通道维规格校验（kornia/color/yuv.py）：

KORNIA_CHECK_SHAPE(imagey, ["*", "1", "H", "W"]) KORNIA_CHECK_SHAPE(imageuv, ["*", "2", "H", "W"])

KORNIA_CHECK_SHAPE定义于 kornia/core/check.py，负责校验张量的秩与通道数（例如亮度必须是单通道、色度必须是双通道），而新增的守卫则进一步校验具体的空间尺寸关系（高度相等、宽度减半）。两者分工互补：前者保证"形状规格"正确，后者保证"平面间相对尺寸"正确。

此外需要注意一个性能与可禁用性相关的细节：KORNIA_CHECK_SHAPE可通过disable_checks()或KORNIA_CHECKS环境变量在 Python 模式下关闭（见 kornia/core/check.py），但自定义守卫中的显式raise ShapeError不受该开关控制——它总是执行。因此，在关闭校验以追求极致性能的部署场景下，平面间尺寸错误仍会被拦截并抛出ShapeError，只是错误信息可能更晚暴露（仍会在torch.cat处失败）。

结论：从崩溃到契约

这次修复将yuv422_to_rgb从"让torch.cat用裸RuntimeError宣告失败"提升为"以ShapeError明确宣告形状契约违约"。对使用者而言，正确的姿势是：

1. 始终保证色度平面高度等于亮度平面高度、宽度为其一半（4:2:2 只子采样宽度）；
2. 错误处理优先捕获ShapeError（或BaseError），而非假设RuntimeError能兜住所有失败；
3. 留意 #4056：零宽度色度平面在高度匹配时仍会触发ZeroDivisionError，可提前自行校验。

相关代码与测试的入口为 kornia/color/yuv.py、kornia/core/exceptions.py 与 tests/color/test_yuv.py，可作为深入阅读的起点。

• 计算机视觉
• 人工智能
• 深度学习
• 图像处理