Kornia 立体视差张量形状校验修复：强制 channels-last(B, H, W, 1)布局并报告实际形状（#4380）

【免费下载链接】kornia🐍 Geometric Computer Vision Library for Spatial AI项目地址: https://gitcode.com/GitHub_Trending/ko/kornia

本文聚焦 Kornia 中一项具体的立体视觉改进：reproject_disparity_to_3D系列的视差张量输入校验被修正，错误信息现在会明确描述必须使用 channels-last 的(B, H, W, 1)布局，并如实报告调用方实际传入的形状。读完本文，你将理解 Kornia 中视差张量与常规图像张量在布局约定上的本质差异，掌握StereoCamera.reproject_disparity_to_3D与模块级reproject_disparity_to_3D的完整输入校验规则，并能依据错误信息快速定位与修复形状、维度、数据类型三类常见报错。

变更条目解读：一次面向可诊断性的校验改进

本次变更记录在 changelog.d/+migration-036.fixed.md 中，属于 changelog.d 目录下的迁移碎片条目（以+migration-NNN.{type}.md命名，fixed表示缺陷修复）。条目原文为：

Corrected stereo disparity validation errors to describe the required channels-last(B, H, W, 1)layout and report the received shape. (#4380)

其核心语义有三层：

1. 校验对象：立体视差（disparity）相关的输入校验（validation）逻辑；
2. 修正内容：错误消息（error messages）此前描述含糊，现在明确写出所需布局是 channels-last 的(B, H, W, 1)；
3. 增强点：错误消息同时报告实际收到的形状（report the received shape），让用户在报错瞬间即可对照排查。

这本质上是面向可诊断性（diagnosability）的工程改进：不改变任何数学计算逻辑，只让校验失败时给出的信息真正可操作。

为什么视差张量必须是 channels-last：布局约定的底层原因

Kornia 内部大多数图像张量遵循 PyTorch 惯例，采用 channels-first 的(B, C, H, W)布局。但视差图是个例外。在 kornia/geometry/camera/stereo.py 的StereoCamera类文档中，这一约定被明确写死：

a disparity map is channels-last,(B, H, W, 1), forreproject_disparity_to_3Dand for the module-levelreproject_disparity_to_3Dalike -- the(B, 1, H, W)layout the rest of kornia uses for images is rejected -- and the returned point cloud is(B, H, W, 3).

即：

• 视差图输入必须是(B, H, W, 1)（channels-last）；
• Kornia 其余模块常用的(B, 1, H, W)（channels-first）图像布局在此被明确拒绝；
• 重投影输出的点云形状为(B, H, W, 3)，同样是 channels-last。

这一约定并非随意设计，而是与下游几何语义保持一致：

• reproject_disparity_to_3D内部通过create_meshgrid枚举像素整数中心，并逐像素计算X = (u - c_x)·Z / f_x、Y = (v - c_y)·Z / f_y（见 kornia/geometry/camera/stereo.py 的约定说明）；
• 在实现上，函数读取batch_size, rows, cols, _ = disparity_tensor.shape后，把网格坐标与视差堆叠为(B, 3, -1)再做齐次变换（kornia/geometry/camera/stereo.py），H、W与单通道视差必须处于末两位，才能与网格逐一对应；
• 这种布局也兼容 OpenCV 生态的cv2.reprojectImageTo3D习惯（u是列索引、v是行索引），便于与传统双目流程互操作。

修复落点：_check_disparity_tensor校验函数的现状

本次 #4380 修复的直接落点是 kornia/geometry/camera/stereo.py 中的私有函数_check_disparity_tensor。它被两处公开入口共用：

• StereoCamera.reproject_disparity_to_3D（kornia/geometry/camera/stereo.py）；
• 模块级函数reproject_disparity_to_3D（kornia/geometry/camera/stereo.py）。

当前实现依次执行四类校验，每类都给出包含期望与实际值的错误消息：

1. 类型校验

if not isinstance(disparity_tensor, torch.Tensor): raise StereoException( f"Expected 'disparity_tensor' to be an instance of torch.Tensor but got {type(disparity_tensor)}." )

传入非 Tensor（如 numpy 数组、list）时，错误消息会报告实际 Python 类型，提示先转换为torch.Tensor。

2. 维度校验

if len(disparity_tensor.shape) != 4: raise StereoException(f"Expected 'disparity_tensor' to have 4 dimensions. Got {disparity_tensor.shape}.")

视差张量必须是 4 维。常见错误是传入 3 维的(H, W, 1)单帧图或 2 维的(H, W)灰度图，此时消息会直接打印实际 shape。

3. 布局校验（本次修复的核心）

if disparity_tensor.shape[-1] != 1: raise StereoException( "Expected 'disparity_tensor' to have channels-last shape (B, H, W, 1) " f"Got {disparity_tensor.shape}." )

这是本次变更的核心改动：当末维不是 1 时，错误消息明确写出 channels-last 布局要求(B, H, W, 1)，并报告实际收到的形状。此前版本的报错往往只提示"形状不正确"而不说明期望布局，用户拿到(B, 1, H, W)（Kornia 图像的标准布局）时会一头雾水——现在错误消息直接点明二者约定相反，这是绝大多数误用的来源。

4. 数据类型校验

if disparity_tensor.dtype not in (torch.bfloat16, torch.float16, torch.float32, torch.float64): raise StereoException( "Expected 'disparity_tensor' to have dtype torch.bfloat16, torch.float16, torch.float32 or torch.float64." f"Got {disparity_tensor.dtype}" )

视差图只接受四种浮点类型：bfloat16、float16、float32、float64。整数类型（如从图像解码得到的uint8/int16视差图）会被拒绝，错误消息会报告实际 dtype。

所有校验抛出的都是StereoException（kornia/geometry/camera/stereo.py），该类会自动在消息末尾附加文档指引："Please check documents here: ... for further information and examples."，把用户导向geometry.camera.stereo文档页，进一步降低排障成本。

测试如何锁定修复行为

校验消息的修复行为由测试显式锁定。在 tests/geometry/camera/test_stereo.py 中，测试用例通过pytest.raises(StereoException, match=...)断言错误消息的精确内容：

• match=r"channels-last shape \(B, H, W, 1\)"—— 断言布局描述必须出现；
• match="to have 4 dimensions"—— 断言维度描述必须出现。

一旦有人将来改回含糊的报错文案，这两条断言会立即失败，从而保证 #4380 修复的可诊断性不会在后续重构中退化。这也是 Kornia 对"错误消息即用户体验"的一种工程化保障。

实战：正确构造视差张量并解读报错

正确的用法

import torch from kornia.geometry.camera import StereoCamera B, H, W = 2, 480, 640 # 双目已校正的投影矩阵：(B, 3, 4)，右相机最后一列为 -tx * fx left = torch.tensor([[[600.0, 0.0, 320.0, 0.0], [0.0, 600.0, 240.0, 0.0], [0.0, 0.0, 1.0, 0.0]]]).repeat(B, 1, 1) right = torch.tensor([[[600.0, 0.0, 320.0, -60.0], [0.0, 600.0, 240.0, 0.0], [0.0, 0.0, 1.0, 0.0]]]).repeat(B, 1, 1) cam = StereoCamera(left, right) # 关键：channels-last 布局 (B, H, W, 1) disparity = torch.zeros(B, H, W, 1, dtype=torch.float32) points = cam.reproject_disparity_to_3D(disparity) # 输出 (B, H, W, 3)

三种典型报错与修复

修复后错误消息中的Got torch.Size([...])直接复现了你的输入形状，对照上表即可一步定位问题来源。

延伸：与视差误差指标的布局差异

需要注意的是，形状约定的严格性仅适用于geometry.camera.stereo的重投影路径。同仓库的视差误差指标模块 kornia/metrics/disparity.py 则接受任意形状的视差图（docstring 中写的是 arbitrary shape(*)），例如mean_absolute_disparity_error、root_mean_squared_disparity_error、mean_bad_pixel_error与kitti_d1_error。它们的校验（_check_disparity_inputs）只要求input与target形状相同、浮点 dtype、valid_mask可广播，并不强制(B, H, W, 1)。

这提示了一个数据流要点：如果先调用reproject_disparity_to_3D完成几何重投影（输出(B, H, W, 3)），再把视差图交给指标函数，两者之间通常需要一次形状/布局的显式对齐。从源码结构看，几何模块与指标模块各自独立维护输入约定，跨模块传递张量时，以 kornia/geometry/camera/stereo.py 文档声明的 channels-last 约定为基准做转换是最稳妥的做法。

小结

本次 #4380 修复不涉及任何数值计算变化，而是一次典型的"错误信息工程"改进：把_check_disparity_tensor的报错从"你传错了"升级为"需要(B, H, W, 1)布局，你实际传的是 XXX"。这一改动配合维度、类型校验与StereoException的文档指引，构成了完整的输入可诊断闭环，并被 tests/geometry/camera/test_stereo.py 以正则断言的形式永久锁定。对于任何把深度估计/双目立体模块接入 Kornia 的开发者而言，牢记"视差图是 channels-last、图像是 channels-first"这一对偶约定，是绕开该类报错的关键心法。

【免费下载链接】kornia🐍 Geometric Computer Vision Library for Spatial AI项目地址: https://gitcode.com/GitHub_Trending/ko/kornia