Kornia Boxes3D.from_tensor “xyzwhd“ 模式修复解析：非对称 3D 框宽高深字段序保真与几何约定

计算机视觉深度学习人工智能图像处理【免费下载链接】kornia 空间人工智能的几何计算机视觉库项目地址https://gitcode.com/kornia/kornia点击查看免费下载本指南聚焦 Kornia 仓库中一条 changelog 修复记录changelog.d/migration-100.fixed.md对应 PR #4189深入剖析Boxes3D.from_tensor(..., modexyzwhd)在非对称asymmetric3D 边界框上保留width, height, depth字段顺序的修复原理。通过阅读本文你将掌握Boxes3D各模式xyzxyz、xyzxyz_plus、xyzwhd的字段语义、底层顶点vertices存储约定、相关校验逻辑与测试验证方法并能在自己的 3D 检测、点云与空间 AI 项目中正确使用该 API避免宽高深错位引发的几何错误。修复记录一览一条 changelog 片段说了什么修复记录的原文为FixBoxes3D.from_tensor(..., modexyzwhd)to preserve width, height, and depth field order for asymmetric boxes. (#4189)从中可以提取出三个核心信息受影响 APIkornia.geometry.boxes.Boxes3D.from_tensor(..., modexyzwhd)修复目标让width宽、height高、depth深三个字段的顺序在转换过程中被正确保留触发场景非对称asymmetric框——即宽、高、深各不相等的 3D 边界框当三个维度中存在相等值时旧的实现可能在字段顺序上产生歧义或错误。这条片段位于仓库的 changelog.d 目录下。该目录采用 Towncrier 的 changelog fragment 机制每个对用户可见的变更以PR.type.md命名其中fixed表示 Bug 修复见 changelog.d/README.md。文件名中的migration-*是仓库历史上遗留的临时命名release 时由 Towncrier 合并进CHANGELOG.md。为什么xyzwhd的字段顺序会出错模式语义与修复动机Boxes3D.from_tensor支持三种从(N, 6)或(B, N, 6)张量导入框的格式见 kornia/geometry/boxes.py模式输入格式宽/高/深定义xyzxyzxmin, ymin, zmin, xmax, ymax, zmaxwidth xmax - xminheight ymax - ymindepth zmax - zminxyzxyz_plusxmin, ymin, zmin, xmax, ymax, zmaxwidth xmax - xmin 1height ymax - ymin 1depth zmax - zmin 1xyzwhdxmin, ymin, zmin, width, height, depth后三个字段直接就是宽、高、深在xyzxyz/xyzxyz_plus模式下宽高深是从(xmax, ymax, zmax)与(xmin, ymin, zmin)之差推导出来的而在xyzwhd模式下后三个字段本身就是width, height, depth不再需要做减法# kornia/geometry/boxes.py 中的分支逻辑节选 elif mode xyzwhd: width, height, depth boxes[..., 3], boxes[..., 4], boxes[..., 5]修复前的旧实现在xyzwhd分支中曾沿用xyzxyz分支的减法推导逻辑将width错误地计算为xmax - xmin之类的差值。对于宽、高、深互不相同的非对称框这种错误推导会把字段顺序打乱——例如把depth的值写进width字段、把width的值写进height字段最终导致 3D 框在空间中变成错误的长方体。这正是本次修复要解决的核心问题。从源码看修复后的字段保真修复后的from_tensor逻辑如下kornia/geometry/boxes.pyxmin, ymin, zmin boxes[..., 0], boxes[..., 1], boxes[..., 2] mode mode.lower() if mode xyzxyz: width boxes[..., 3] - boxes[..., 0] height boxes[..., 4] - boxes[..., 1] depth boxes[..., 5] - boxes[..., 2] elif mode xyzxyz_plus: width boxes[..., 3] - boxes[..., 0] 1 height boxes[..., 4] - boxes[..., 1] 1 depth boxes[..., 5] - boxes[..., 2] 1 elif mode xyzwhd: width, height, depth boxes[..., 3], boxes[..., 4], boxes[..., 5] # 直接取字段不做减法 else: raise ValueError(fUnknown mode {mode})可以看到模式字符串在比较前会被mode.lower()统一小写测试test_convention_from_tensor_xyzxyz_stores_inclusive_front_then_back_vertices验证了modeXYZXYZ也能正常工作见 tests/geometry/test_boxes.py只有xyzxyz/xyzxyz_plus两种“角点格式”才做减法/加一推导xyzwhd则原样保留第 3、4、5 列作为width, height, depth字段顺序天然保真未知模式会抛出ValueError。Boxes3D 的内部表示为什么“字段保真”如此重要Boxes3D在内部并不直接保存(N, 6)的角点或宽高深表示而是保存为八顶点六面体hexahedron形状为(N, 8, 3)或(B, N, 8, 3)见 kornia/geometry/boxes.py 的 Convention 说明顶点顺序为前上左、前上右、前下右、前下左然后是同样的四个后部顶点每个顶点是一个(x, y, z)坐标存储形式是“包含式”inclusivewidth xmax - xmin 1height ymax - ymin 1depth zmax - zmin 1。这与 torchvision、COCO、albumentations 等常见库的约定不同仓库在文档中明确标注该差异并跟踪于 issue #3934。from_tensor拿到(xmin, ymin, zmin, width, height, depth)后会调用内部函数_boxes3d_to_polygons3dkornia/geometry/boxes.py构造八顶点# 前面四个顶点先全部放到前上左位置再按宽高偏移 front_vertices torch.zeros((xmin.shape[0], xmin.shape[1], 4, 3), ...) front_vertices[..., 0] xmin.unsqueeze(-1) front_vertices[..., 1] ymin.unsqueeze(-1) front_vertices[..., 2] zmin.unsqueeze(-1) front_vertices[..., 1, 0] width - 1 # 前上右 front_vertices[..., 2, 0] width - 1 # 前下右 front_vertices[..., 2, 1] height - 1 # 前下右 front_vertices[..., 3, 1] height - 1 # 前下左 # 后面四个顶点由前面顶点沿 z 方向平移 depth - 1 back_vertices front_vertices.clone() back_vertices[..., 2] depth.unsqueeze(-1) - 1关键点如果width, height, depth在进入该函数前就已经错位这正是修复前的问题那么构造出的 8 个顶点坐标也会全部错位——框在三个轴向上被错误拉伸或收缩。因此“字段顺序保真”是Boxes3D正确性的基石而不仅仅是一个导出格式问题。修复在非对称框上的具体表现一个可运行的示例以测试test_convention_from_tensor_xyzxyz_stores_inclusive_front_then_back_vertices中的非对称框为例见 tests/geometry/test_boxes.py其排他角点为x ∈ [1, 5]、y ∈ [2, 5]、z ∈ [3, 8]即宽 4、高 3、深 5——三个维度互不相等是典型的非对称框import torch from kornia.geometry.boxes import Boxes3D # 非对称框width4, height3, depth5 xyzxyz torch.tensor([[1.0, 2.0, 3.0, 5.0, 5.0, 8.0]]) # 从 xyzxyz 模式导入验证内部存储与导出 boxes Boxes3D.from_tensor(xyzxyz, modexyzxyz) print(boxes.data) # (1, 8, 3) 的包含式顶点 # 导出回各模式字段必须严格保真 assert torch.equal(boxes.to_tensor(xyzxyz), xyzxyz) assert torch.equal(boxes.to_tensor(xyzxyz_plus), torch.tensor([[1.0, 2.0, 3.0, 4.0, 4.0, 7.0]])) assert torch.equal(boxes.to_tensor(xyzwhd), torch.tensor([[1.0, 2.0, 3.0, 4.0, 3.0, 5.0]])) # width, height, depth其中to_tensor(xyzwhd)的期望结果[1, 2, 3, 4, 3, 5]中后三个字段(4, 3, 5)严格对应(width, height, depth)。修复前旧实现对非对称框导出时可能得到(5, 4, 3)之类的错位结果修复后无论从哪个模式导入、导出到哪个模式宽高深顺序都保持一致。直接以xyzwhd模式导入更直接的验证是绕过角点模式直接用xyzwhd字段导入并做 round-tripxyzwhd torch.tensor([[1.0, 2.0, 3.0, 4.0, 3.0, 5.0]]) # xmin, ymin, zmin, w, h, d boxes Boxes3D.from_tensor(xyzwhd, modexyzwhd) assert boxes.mode xyzwhd # to_tensor 默认导出为 xyzxyz见下节约定 assert torch.equal(boxes.to_tensor(), torch.tensor([[1.0, 2.0, 3.0, 5.0, 5.0, 8.0]]))对应的单元测试位于 tests/geometry/test_boxes.py 附近覆盖了from_tensor(xyzwhd)后.mode标签、默认to_tensor()结果以及transform_boxes/transform_boxes_的模式标签行为。配套约定验证逻辑、导出模式与已知边界围绕这次修复Boxes3D还有几个必须了解的配套约定全部在 kornia/geometry/boxes.py 的 Convention 与 Warning 块中有文档化校验规则validate_boxesfrom_tensor默认开启validate_boxesTrue会拒绝包含非有限值NaN / Inf的坐标在当前模式语义下宽度、高度或深度非正 0的框。注意校验是“按模式语义”的xmax xmin的框在xyzxyz下会被拒绝宽度为 0但在xyzxyz_plus下会被接受宽度为 1。xyzwhd模式下宽度字段直接为 0 会被拒绝0.5 这类正小数则通过见 tests/geometry/test_boxes.py。将validate_boxesFalse可跳过全部校验。此外源码在导出export场景下会跳过校验if validate_boxes and not is_exporting()因为校验需要读取张量数值而图捕获graph capture阶段无法执行该操作。to_tensor 的默认导出模式Boxes3D.to_tensor()的默认模式是xyzxyz与对象存储时的模式标签无关该行为差异被跟踪于 issue #4251。这与 2DBoxes.to_tensor()默认使用存储标签不同。也就是说即使from_tensor(..., modexyzwhd)创建的对象.mode xyzwhd不带参数调用to_tensor()仍会导出为xyzxyz格式。整数输入与数据类型构造函数Boxes3D(...)默认拒绝整型张量除非传入raise_if_not_floating_pointFalsefrom_tensor则会把整型输入静默转换为torch.get_default_dtype()并保留 float16 等输入类型见 tests/geometry/test_boxes.py。已知边界与坑位每个导出的框都是对存储顶点做amin/amax归约得到的轴对齐包围盒旋转后的框导出为xyzxyz/xyzwhd会丢失旋转信息to_tensor(vertices_plus)对旋转框而言也不是data的恒等变换to_tensor的amin/amax归约在多个顶点恰好并列轴极值时梯度会按 1/k 均分给并列顶点测试test_convention_to_tensor_backward_is_differentiable...验证了 4 路并列时的 0.25 梯度见 tests/geometry/test_boxes.py自由函数infer_bbox_shape3d/bbox_to_mask3d不接受mode参数且按“包含式”读取输入应向其传入vertices_plus导出而非vertices后者会被读大每个轴一个单位见 tests/geometry/test_boxes.py。测试如何锁定这次修复仓库用一组“约定钉”convention pin测试确保包括本次修复在内的行为不再回退主要分布在 tests/geometry/test_boxes.pytest_from_tensorL1259-L1282参数化(1, 6)与(1, 1, 6)两种形状对三种模式分别断言构造出的 8 顶点结果一致test_boxes_to_tensorL1301-L1329使用随机化顶点构造旋转框验证xyzxyz、xyzxyz_plus、xyzwhd、vertices、vertices_plus五种导出格式test_convention_from_tensor_xyzxyz_stores_inclusive_front_then_back_vertices以非对称框验证存储顶点顺序、get_boxes_shape()返回(depths, heights, widths)的顺序以及全模式 round-triptest_convention_from_tensor_rejects_non_positive_extents_in_mode_convention锁定按模式语义的宽度/高度/深度校验此外gradcheck测试验证了from_tensor(x, modexyzwhd).data全程可微tests/geometry/test_boxes.py即本次修复没有破坏反向传播。运行这些测试的标准方式在仓库根目录pytest tests/geometry/test_boxes.py -k convention or from_tensor or boxes_to_tensor总结非对称框字段保真的正确姿势导入 3D 框时xyzwhd的(xmin, ymin, zmin, width, height, depth)中后三列是原样字段不需要也不应该做差值推导——这正是 changelog.d/migration-100.fixed.md 所修复的行为Boxes3D内部统一保存为包含式八顶点所有导出格式含xyzwhd都从该存储推导因此只要from_tensor阶段字段保真后续任何转换都不会再错位非对称框宽高深互不相等是检验字段序错误的天然用例建议在自己的测试中以(w, h, d) (4, 3, 5)这类三值互异的框做 round-trip 断言涉及 3D 框与掩码互转、NMS、包围盒推断等下游操作时注意“包含式/排他式”约定差异与to_tensor默认导出模式避免在xyzwhd修复之外的边界上踩坑。赞分享计算机视觉深度学习人工智能图像处理【免费下载链接】kornia 空间人工智能的几何计算机视觉库项目地址https://gitcode.com/kornia/kornia点击查看免费下载相关推荐Kornia 3D 边界框非有限坐标校验修复Boxes3D.from_tensor 与 validate_bbox3d 的防御性改进解析Kornia 3D 边界框非有限坐标校验修复 Boxes3D.from_tensor 与 validate_bbox3d 的防御性改进解析 本文聚焦 Korn计算机视觉深度学习人工智能图像处理Kornia RandomMosaic 轴约定修复详解非方形输入的 (H, W) 保持与 start_ratio_range 宽高缩放语义Kornia RandomMosaic 轴约定修复详解非方形输入的 H, W 保持与 start_ratio_range 宽高缩放语义 导读 RandomMo计算机视觉人工智能深度学习图像处理Kornia RandomMosaic 修复深度解析非方形输入下的 (H, W) 保序与 start_ratio_range 轴语义修正Kornia RandomMosaic 修复深度解析非方形输入下的 H, W 保序与 start_ratio_range 轴语义修正 本篇技术指南以 Korn计算机视觉深度学习人工智能图像处理创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考