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

导读

本文围绕 Kornia 几何模块中Boxes.merge的一次关键缺陷修复展开，该修复记录在 changelog.d/+migration-093.fixed.md（关联 Issue #4168、#4175）。你读完本文后将掌握：为什么dim=1在批量(B, N, 4, 2)下正确、在非批量(N, 4, 2)下却会沿着顶点轴错误拼接；dim=-3为何能在两种形态下统一工作；以及 list 构造的Boxes在 merge 时如何重打包真实框、合并填充计数，确保to_tensor只裁剪 padding 而不丢失合并框。文章将结合 kornia/geometry/boxes.py 的实现细节与 tests/geometry/test_boxes.py 的回归测试逐层验证。

背景：Boxes容器的两种形态与merge的语义

一个四边形容器，两种存储形状

Kornia 的Boxes类（kornia/geometry/boxes.py）将每个 2D 框存储为 4 个(x, y)顶点，支持两种张量形态：

• 非批量：:math:(N, 4, 2)``，其中N是框数量，4是四个角点，2是坐标维度；
• 批量：:math:(B, N, 4, 2)``，B为批次大小。

构造器通过self._is_batched = False if boxes.ndim == 3 else True（boxes.py）来区分这两种形态。关键区别在于：维度 1 在两种形态下含义完全不同——在批量张量中维度 1 是"框轴"（N），而在非批量张量中维度 1 是"顶点轴"（4）。

merge的预期行为

Boxes.merge(boxes, inplace=False)（boxes.py）的文档明确声明其语义：

• 批量：:math:(B, N, 4, 2)+ `:math:`(B, M, 4, 2)→:math:(B, N+M, 4, 2)``；
• 非批量：:math:(N, 4, 2)+ `:math:`(M, 4, 2)→:math:(N+M, 4, 2)``。

即：把两个Boxes对象沿"框轴"拼接起来，使得合并后的对象包含两份框，形状上两边的框数量相加。这正是目标问题中"沿 box axis 拼接而非沿 vertex axis 拼接"的官方表述。

缺陷解剖：dim=1在非批量输入下的灾难

缺陷根因

旧实现使用torch.cat([self._data, boxes.data], dim=1)。从目标文档的精确描述看：

• 对于批量数据(B, N, 4, 2)，维度 1 正是框轴N，dim=1拼接结果正确；
• 但对于非批量数据(N, 4, 2)，维度 1 是顶点轴4，dim=1会把第二个对象的 4 个顶点"追加"到第一个对象的顶点后面，产生形状(N, 8, 2)的畸形张量——顶点数从 4 变成 8，框轴N保持不变。

实测后果

回归测试 tests/geometry/test_boxes.py 的注释直接记录了旧行为：

On base (dim=1) this produced shape (1, 8, 2) andto_tensor("xyxy")returned the single union row[[1, 2, 9, 8]]instead of two rows.

也就是说，两个框[1,2,5,4]与[6,3,9,8]合并后，本应得到(2, 4, 2)的两行数据，旧实现却产生(1, 8, 2)，且经to_tensor导出后只剩一行"并集包围盒"[1, 2, 9, 8]——第二个框的信息被amin/amax归约彻底吞掉了。这对于任何依赖merge后框数量保持正确的下游逻辑（如数据增强容器、检测后处理）都是静默的数据损坏。

修复方案：dim=-3的轴语义统一

为什么dim=-3两边都正确

目标文档给出的结论是：dim=-3在两种形态下都正确，且批量路径的行为与旧实现字节级一致（byte-identical）。

从源码验证：新实现的稠密（非 list）路径位于 boxes.py：

else: data = torch.cat([self._data, boxes.data], dim=-3)

dim=-3是倒数第三个维度：

• 批量(B, N, 4, 2)：倒数第三维是N（框轴），拼接得到(B, N+M, 4, 2)；
• 非批量(N, 4, 2)：倒数第三维同样是N（框轴），拼接得到(N+M, 4, 2)。

因为两种形态的"框轴"恰好都位于倒数第三维，使用负索引-3而非绝对索引1就绕开了维度编号在两种形态下的歧义。这是负索引惯用法解决"形状多变"问题的典型范例：只要"框轴"在两种形态中相对位置一致，负索引就能无分支地统一处理。

批量路径为什么字节级不变

对批量输入而言，dim=1与dim=-3指向同一个维度，torch.cat的结果在数值与布局上完全一致。因此该修复对批量用户是零行为变更，不会引入任何兼容性回归——这一点由"batched path is byte-identical"的文档表述与回归测试共同背书（测试 test_merge 验证批量合并结果(2, 2, 4, 2)与逐框拼接的期望张量逐元素相等）。

list 构造路径：重打包与填充计数合并

list 输入的填充机制

当Boxes由 list 构造时，内部辅助函数_merge_box_list（boxes.py）会把不等长的各批次框填充到最大长度：

max_N = max(box.shape[0] for box in boxes) stats = [max_N - box.shape[0] for box in boxes] output = torch.nn.utils.rnn.pad_sequence(boxes, batch_first=True) return output, stats

返回的stats即为每批次填充行数，保存在self._N中（boxes.py）。_N是 list 构造对象区别于稠密对象的核心元数据：它精确记录了每张图像中"哪些行是真实框、哪些行是 padding"。

旧实现的缺陷

目标文档指出，旧实现直接沿框轴拼接后，list 对象的填充会变得混乱：旧的 padding 行会混入真实框之间，而to_tensor只能从尾部裁剪固定数量的行，于是出现两类错误：

• 丢弃合并框：若 padding 统计未更新，to_tensor裁剪的行数超过实际 padding 数，真实框被误删；
• 暴露旧 padding 为真实框：若旧 padding 行被拼到新框前面或中间，to_tensor裁剪不到它们，padding 被当成真实框输出。

修复后的重打包算法

新实现（boxes.py）在任一侧带有_N时进入专门的 list 路径：

if self._N is not None or boxes._N is not None: if self._data.shape[0] != boxes.data.shape[0]: raise ValueError(...) # 批次大小必须一致 self_padding = self._N if self._N is not None else [0] * self._data.shape[0] boxes_padding = boxes._N if boxes._N is not None else [0] * boxes.data.shape[0] data = torch.stack([ torch.cat([ self._data[i, : self._data.shape[-3] - self_pad], boxes.data[i, : boxes.data.shape[-3] - boxes_pad], self._data[i, self._data.shape[-3] - self_pad :], boxes.data[i, boxes.data.shape[-3] - boxes_pad :], ]) for i, (self_pad, boxes_pad) in enumerate(zip(self_padding, boxes_padding)) ]) padding = [self_pad + boxes_pad for self_pad, boxes_pad in zip(self_padding, boxes_padding)]

逐行解读其思路：

1. 逐批次重组：对每个批次i，先截取self的真实框（去掉尾部self_pad行 padding），再截取boxes的真实框（去掉尾部boxes_pad行 padding），两者拼接后统一把两边原有的 padding 追加到末尾。这样无论两个输入是稠密还是 list，输出每一行都保证"真实框在前、全部 padding 在后"。
2. 填充计数合并：padding = [self_pad + boxes_pad ...]将两侧每批次的填充行数相加，写入结果对象的_N。因为拼接后真实框数为(N - self_pad) + (M - boxes_pad)，新总长度为N + M，(N + M) - [(N - self_pad) + (M - boxes_pad)] = self_pad + boxes_pad，计数恰好自洽。
3. inplace语义：inplace=True时直接更新self._data与self._N并返回self；否则通过self.clone()构造新对象（boxes.py），保持默认非破坏性。

注意一个细节：两侧都是稠密（_N is None）时走torch.cat(..., dim=-3)快速路径；只要任一侧是 list 就进入逐批次重打包路径，且稠密侧按[0]*B视为零填充——这保证了稠密 + list 混合合并（测试中的extra_batched.merge(other_list)场景）也正确。

对to_tensor的联动影响

裁剪逻辑

to_tensor（boxes.py）在对象带_N且未请求as_padded_sequence时，按_N逐行裁剪尾部 padding：

if self._N is not None and not as_padded_sequence: boxes = [torch.nn.functional.pad(o, (len(o.shape) - 1) * [0, 0] + [0, -n]) for o, n in zip(boxes, self._N)]

即返回一个按真实长度裁剪后的 list（每张图像一个张量）。

修复的收益链条

目标文档的核心论断是：修复后to_tensor只裁剪 padding。完整收益链条为：

1. merge 阶段逐批次重打包 → 每一行的 padding 必然位于末尾；
2. merge 阶段合并填充计数 →_N与实际 padding 行数严格一致；
3. to_tensor阶段按_N从尾部裁剪 → 恰好移除所有 padding，一个不多、一个不少。

于是：真实框（无论来自self还是boxes）全部保留，旧 padding 不会暴露为真实框，也不会出现真实框被误裁剪。目标文档提到的两个关联 Issue——#4168 与 #4175——正是围绕这两类数据损坏报告的。

需要注意的边界

• to_tensor导出前会先做amin/amax归约（boxes.py），因此对旋转框导出的是轴对齐包围盒，这属于既有设计而非本次修复范围；
• as_padded_sequence=True时返回未裁剪的填充张量，get_boxes_shape内部即使用该模式（boxes.py），其返回值会包含 padding 条目——文档明确标注了这一约定。

回归测试验证

tests/geometry/test_boxes.py 的test_merge是本次修复的完整验证矩阵，覆盖：

其中_N == [1, 0]这类断言直接验证了"合并后的填充计数"：list 侧原有 1 行 padding、稠密侧 0 行，合并后总 padding 恰为 1 行，且必须全部位于末尾。这些断言把目标文档中"combined per-image padding counts are retained"落到了可执行的测试代码上。

迁移与使用建议

对下游代码的影响

• 批量用户：dim=-3与旧dim=1等价，结果字节级一致，无需任何改动；
• 非批量用户：这是行为修复——之前被静默合并成一个包围盒的多个框，现在会正确保留为多行。如果你的代码之前依赖了旧的"并集行"行为（例如用merge计算多框并集包围盒），需改用显式的amin/amax归约（如to_tensor("xyxy")后自行归约）来保持原效果；
• list 用户：to_tensor现在只裁剪真正的 padding，输出 list 的长度与真实框数严格对应，可放心依赖"list 输出的每一行都是一张图像的真实框"这一不变量。

阅读与验证入口

• 变更记录原始描述：changelog.d/+migration-093.fixed.md；
• 实现与轴语义文档：kornia/geometry/boxes.py（merge）、kornia/geometry/boxes.py（to_tensor）、kornia/geometry/boxes.py（_merge_box_list）；
• 回归测试：tests/geometry/test_boxes.py（test_merge）；
• 变更记录体系：changelog.d/README.md（fragment 命名规则、pixi run changelog-preview预览方式）。

小结

Boxes.merge的本次修复是"轴语义统一 + 元数据守恒"的典型工程案例：用dim=-3一处改动同时修正了非批量路径的拼接轴，用逐批次重打包保证了 list 路径"真实框在前、padding 在后"的布局不变量，并用合并填充计数保证了_N与实际 padding 严格一致。最终效果正如目标文档所述——to_tensor只裁剪 padding，既不丢弃合并框，也不把旧 padding 暴露为真实框。批量路径的字节级不变则确保了修复对现有批量用户完全透明，配合test_merge的 7 类场景断言，为这一行为修复提供了充分的可验证性。

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