Kornia Boxes3D 的 xyzwhd 模式修复：非对称 3D 框中 width/height/depth 字段顺序的保持与验证

Kornia Boxes3D 的 xyzwhd 模式修复非对称 3D 框中 width/height/depth 字段顺序的保持与验证【免费下载链接】kornia Geometric Computer Vision Library for Spatial AI项目地址: https://gitcode.com/GitHub_Trending/ko/korniaBoxes3D是 Kornia 中用于表示三维边界框八顶点六面体的核心容器其from_tensor(..., modexyzwhd)接口允许以(xmin, ymin, zmin, width, height, depth)格式导入 3D 框。本篇文章聚焦于一项具体的 bug 修复对应变更片段 changelog.d/migration-100.fixed.md修复后xyzwhd模式在转换非对称盒子width、height、depth 互不相等时会严格保留字段顺序不再发生宽高深度错位。读完本文你将掌握Boxes3D的坐标表示约定、xyzwhd模式的导入/导出实现原理以及如何在自定义管线中规避同类字段顺序陷阱。修复背景一个 changelog 片段背后的数据表示问题该修复以 Towncrier 变更片段的形式记录在 changelog.d/migration-100.fixed.md全文如下FixBoxes3D.from_tensor(..., modexyzwhd)to preserve width, height, and depth field order for asymmetric boxes. (#4189)这段文字对应 PR #4189属于fixedbug 修复类别。按仓库的变更管理约定见 changelog.d/README.md每个产生用户可见变更的 PR 都会在changelog.d目录下添加一个独立片段文件命名规则为PR号.类型.md最终由 Towncrier 在发版时合并进CHANGELOG.md。migration-*前缀文件是迁移工作流引入时一次性保留的遗留条目使用 Towncrier 的 orphan 前缀以避免重复生成 PR 链接。要理解这个修复的实际影响必须回到Boxes3D本身的数据表示与转换逻辑。Boxes3D 的数据表示与三种输入模式Boxes3D类定义于 kornia/geometry/boxes.py。与 2D 的Boxes存储四边形顶点类似Boxes3D将每个盒子存储为八顶点六面体张量形状为(N, 8, 3)或(B, N, 8, 3)顶点顺序为前上左、前上右、前下右、前下左、后上左、后上右、后下右、后下左front-top-left, front-top-right, front-bottom-right, front-bottom-left, 以及相同的四个 back 顶点。from_tensor是导入其他表示的入口kornia/geometry/boxes.py接受形状(N, 6)或(B, N, 6)的输入共支持三种模式模式字符串匹配不区分大小写模式字段格式尺寸定义xyzxyzxmin, ymin, zmin, xmax, ymax, zmaxwidth xmax - xmin不含端点xyzxyz_plusxmin, ymin, zmin, xmax, ymax, zmaxwidth xmax - xmin 1含端点xyzwhdxmin, ymin, zmin, width, height, depth第 3、4、5 个字段直接就是宽、高、深其中xyzwhd是本修复的核心对象其第 3 个字段是宽度width第 4 个是高度height第 5 个是深度depth对应 x/y/z 三个轴。对于非对称盒子三个方向尺寸互不相等一旦这个顺序被打乱宽高深就会互相错位且数值上无法察觉——因为三个值本身不同错位后仍能通过简单的合法性检查。修复的源码实现字段顺序的严格保持在from_tensor中xyzwhd分支的实现非常直接kornia/geometry/boxes.pyelif mode xyzwhd: width, height, depth boxes[..., 3], boxes[..., 4], boxes[..., 5]即从输入张量的第 3、4、5 列分别取出 width、height、depth然后交给_boxes3d_to_polygons3dkornia/geometry/boxes.py构造八顶点六面体。修复确保的正是这一步的映射关系字段 3 → width字段 4 → height字段 5 → depth三个量在各分支中保持一致的命名与赋值顺序。对称地to_tensor(modexyzwhd)的导出分支kornia/geometry/boxes.py也以相同顺序回写elif mode in (xyzwhd, vertices, vertices_plus): width boxes[..., 3] - boxes[..., 0] 1 height boxes[..., 4] - boxes[..., 1] 1 depth boxes[..., 5] - boxes[..., 2] 1 boxes[..., 3] width boxes[..., 4] height boxes[..., 5] depth导出时先以amin/amax对 8 个顶点求轴对齐包围盒再换算成含端点的尺寸并回填到字段 3/4/5。导入与导出两侧的顺序约定完全一致这正是字段顺序被保留的保证from_tensor(x, modexyzwhd).to_tensor(modexyzwhd)可以精确还原输入。另一个与该顺序强相关的点是get_boxes_shapekornia/geometry/boxes.pyboxes_xyzwhd self.to_tensor(modexyzwhd) widths, heights, depths boxes_xyzwhd[..., 3], boxes_xyzwhd[..., 4], boxes_xyzwhd[..., 5] return depths, heights, widths它内部正是依赖xyzwhd字段顺序来提取尺寸然后按(depths, heights, widths)的约定顺序返回。也就是说xyzwhd的字段顺序一旦出错会连带污染get_boxes_shape的返回结果影响所有依赖该方法的几何计算如to_mask的 mask 尺寸。这解释了为何该修复的优先级较高它不只影响显式使用xyzwhd模式的用户。测试佐证对称与非对称盒子的回归覆盖仓库测试 tests/geometry/test_boxes.py 为xyzwhd模式提供了多组回归用例其中最能体现本次修复价值的是一组非对称盒子测试。非对称盒子的字段顺序校验test_convention_from_tensor_xyzxyz_stores_inclusive_front_then_back_verticestests/geometry/test_boxes.py构造了一个三个方向尺寸均不同的盒子x 从 1 到 5宽度 4、y 从 2 到 5高度 3、z 从 3 到 8深度 5随后断言expected_whd torch.tensor([[1.0, 2.0, 3.0, 4.0, 3.0, 5.0]], devicedevice, dtypedtype) self.assert_close(boxes.to_tensor(xyzwhd), expected_whd, atol0.0, rtol0.0)输出严格为[xmin1, ymin2, zmin3, width4, height3, depth5]——width(4)、height(3)、depth(5) 三个互不相同的数值落在正确的字段位置上。如果修复前存在字段顺序错乱例如 width 与 height 互换该断言会立即失败因为 4、3、5 无法与错位后的排列匹配。这正是 changelog 中 preserve width, height, and depth field order for asymmetric boxes 的测试级体现只有非对称盒子才能暴露顺序错误对称盒子三个值相同顺序错了也测不出来。其他 xyzwhd 相关回归test_boxes_to_tensortests/geometry/test_boxes.py用一组随机化顶点构造六面体逐一校验xyzxyz、xyzxyz_plus、xyzwhd、vertices、vertices_plus五种导出模式的输出其中xyzwhd期望输出[[1, 2, 1, 2, 2, 2]]。test_from_tensortests/geometry/test_boxes.py对(1, 6)与(1, 1, 6)两种布局验证三种模式导入到八顶点表示的结果一致。test_convention_from_tensor_rejects_non_positive_extents_in_mode_conventiontests/geometry/test_boxes.py验证validate_boxesTrue时按各模式自身约定校验正尺寸如xyzwhd下 width0 会抛出匹配widths的ValueError而 width0.5 可正常通过。test_wart_to_tensor_default_mode_ignores_the_stored_label_4251tests/geometry/test_boxes.py验证Boxes3D.to_tensor()无参时默认导出xyzxyz且transform_boxes复制路径会把标签重置为xyzxyz_plus。此外tests/geometry/test_boxes.py 中还包含对Boxes3D.from_tensor(x, modexyzwhd).data的 gradcheck 验证说明该路径在可微性上也被纳入了测试保障。实战要点正确使用 xyzwhd 模式结合源码与测试在实际项目中使用Boxes3D的xyzwhd模式时有几点值得注意1. 明确字段语义。xyzwhd的第 3、4、5 个字段是尺寸而非角点坐标width xmax - xmin、height ymax - ymin、depth zmax - zmin不含端点与xyzxyz的尺寸定义一致区别于含端点的xyzxyz_plus。导入示例import torch from kornia.geometry.boxes import Boxes3D # 非对称盒子width4, height3, depth5 boxes Boxes3D.from_tensor(torch.tensor([[1.0, 2.0, 3.0, 4.0, 3.0, 5.0]]), modexyzwhd) print(boxes.data.shape) # (1, 8, 3)内部为八顶点六面体 print(boxes.mode) # xyzwhd # 导出可精确还原第 3/4/5 字段仍为 width/height/depth print(boxes.to_tensor(modexyzwhd)) # tensor([[1., 2., 3., 4., 3., 5.]])2. 注意get_boxes_shape的返回顺序。它返回的是(depths, heights, widths)与xyzwhd字段顺序width, height, depth不同。如果你的下游代码按宽、高、深解包需要显式调整depths, heights, widths boxes.get_boxes_shape()3. 留意to_tensor的默认导出模式。Boxes3D.to_tensor()无参时默认导出xyzxyz与 2DBoxes默认导出存储模式不同这是仓库已知的 API 分歧见类文档中的 #4251 注释。若需xyzwhd格式务必显式传modexyzwhd。4. 尺寸合法性校验。from_tensor默认validate_boxesTrue会拒绝非有限坐标与按模式约定非正的尺寸在xyzwhd下 width/height/depth 必须为正width0 会报错width0.5 合法。若在导出图捕获export场景下校验会被跳过源码中通过is_exporting()判断以便支持图捕获。小结Boxes3D的xyzwhd模式修复#4189看似只是 changelog 中一行描述实际修复的是一个隐蔽的数据正确性问题在 width、height、depth 互不相同的非对称盒子上字段顺序错位会产生看似合法、实则错误的结果并波及依赖同一顺序的get_boxes_shape等内部逻辑。仓库通过 kornia/geometry/boxes.py 中导入/导出两侧的对称实现以及 tests/geometry/test_boxes.py 中以非对称盒子为主的回归测试将这一约定牢牢固定下来。对于在 3D 检测、体素化或空间 AI 管线中使用 KorniaBoxes3D的开发者理解这一字段顺序约定是避免宽高深错位类 bug 的第一步。【免费下载链接】kornia Geometric Computer Vision Library for Spatial AI项目地址: https://gitcode.com/GitHub_Trending/ko/kornia创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考