Kornia 视频框修复解析VideoBoxes.get_boxes_shape()与to_mask()的TypeError消除migration-042【免费下载链接】kornia 空间人工智能的几何计算机视觉库项目地址: https://gitcode.com/kornia/kornia导读本文围绕 kornia 仓库changelog.d/migration-042.fixed.md记录的一次关键修复展开此前在视频增广管线中调用VideoBoxes.get_boxes_shape()与VideoBoxes.to_mask()会稳定抛出TypeError导致AugmentationSequential为视频框输入构建的容器链路不可用。修复后这两个继承自Boxes的方法可以正常工作且不改变任何既有合法调用的结果。读完本文你将理解 bug 的根因、修复的最小改动原则以及它在视频数据增广batch × frames × boxes场景下的实战影响。一、修复背景VideoBoxes与Boxes的继承关系1.1 两个核心类在 kornia/geometry/boxes.py 中Boxes第 190 行起2D 框容器存储形状为(N, 4, 2)、(B, N, 4, 2)或 list 形式VideoBoxes第 1072 行起继承Boxes专为视频序列设计接受(B, T, N, 4, 2)输入内部展平为(B·T, N, 4, 2)存储并保存temporal_channel_size T以便在导出时恢复时间轴。VideoBoxes.to_tensor()第 1150 行在super().to_tensor(...)之后通过out.view(-1, self.temporal_channel_size, *out.shape[1:])恢复时间维度是视频框回传张量的核心路径。1.2 Bug 的直接现场Boxes.get_boxes_shape()第 328 行内部调用boxes_xywh cast(torch.Tensor, self.to_tensor(xywh, as_padded_sequenceTrue))Boxes.to_mask()第 819 行内部调用clipped_boxes_xyxy cast(torch.Tensor, self.to_tensor(xyxy, as_padded_sequenceTrue))而VideoBoxes的重写只声明了mode参数旧签名def to_tensor(self, mode: Optional[str] None)未声明as_padded_sequence。因此任何从基类继承、内部向to_tensor传递as_padded_sequenceTrue的方法在VideoBoxes实例上都会触发TypeError: to_tensor() got an unexpected keyword argument as_padded_sequence二、根因分析与最小修复2.1 为什么每个调用都失败get_boxes_shape与to_mask是VideoBoxes继承自Boxes的方法它们固定向to_tensor传入as_padded_sequenceTrue。由于VideoBoxes的重写签名缺少该关键字这两个方法在VideoBoxes上必然失败——包括AugmentationSequential为视频框输入构建的容器路径见 kornia/augmentation/container/augment.py 第 722-739 行_preproc_boxes当contains_video_sequential为真时调用VideoBoxes.from_tensor(arg)。2.2 修复内容修复后的VideoBoxes.to_tensor签名改为def to_tensor(self, mode: Optional[str] None, as_padded_sequence: bool False) - torch.Tensor | list[torch.Tensor]: out super().to_tensor(mode, as_padded_sequenceas_padded_sequence) if isinstance(out, torch.Tensor): return out.view(-1, self.temporal_channel_size, *out.shape[1:]) return [_out.view(-1, self.temporal_channel_size, *_out.shape[1:]) for _out in out]关键点接受并转发关键字as_padded_sequence被完整透传给基类Boxes.to_tensor第 738 行不影响正常调用该参数只改变 list-backed 容器的输出形式。由(B, T, N, 4, 2)张量构建的VideoBoxes并非 list-backed_N is None因此该关键字对其结果无任何影响向后兼容默认值False与旧行为一致所有既有合法调用结果不变。三、源码佐证list-backed 语义Boxes.to_tensor中第 813-816 行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)] else: boxes boxes if self._is_batched else boxes.squeeze(0) return boxes_N为None时走 else 分支as_padded_sequence完全不生效——这正印证了修复文档的论断它只改变 list-backed 容器而从张量构建的VideoBoxes不是其中之一所以没有合法调用会改变其结果。四、测试验证与已知遗留4.1 测试覆盖tests/geometry/test_boxes.py 中TestVideoBoxes第 1881 行起针对本次修复提供双重验证test_convention_inherited_shape_and_mask_work_on_the_temporal_wrapper_4249第 2024 行直接断言get_boxes_shape()与to_mask(4, 5)不再抛出TypeError并以AssertionError捕获残留异常test_wart_indexing_drops_the_temporal_size_4249第 1972 行固定剩余的另一半 #4249——索引操作仍会丢失temporal_channel_sizeframe video_boxes[0] with pytest.raises(AttributeError, matchtemporal_channel_size): frame.to_tensor()4.2 遗留问题诚实边界从源码与测试可以确认索引仍丢失时间轴Boxes.__getitem__第 306 行用type(self)(...)构造结果从不设置temporal_channel_size导致切片后的to_tensor抛出AttributeError。这是 #4249 未修复的一半文档注释boxes.py 第 1100-1104 行同时标注了validate_boxes标志当前无效#4177。五、实战影响视频增广容器链路在 kornia/augmentation/container/augment.py 中视频框的处理流程为_preproc_boxes第 722 行检测contains_video_sequential后调用VideoBoxes.from_tensor(arg)第 735 行容器内几何变换作用于展平的(B·T, N, 4, 2)数据_postproc_boxes第 741 行调用out_arg.to_tensor(modemode)第 757 行恢复时间轴。本次修复保证了在管线中如需调用get_boxes_shape计算每个框的宽高或to_mask将框渲染为掩码图不再中断。可结合下列入口深入阅读kornia/geometry/boxes.pyBoxesL190、VideoBoxesL1072、Boxes.to_tensorL738、Boxes.get_boxes_shapeL328、Boxes.to_maskL819kornia/augmentation/container/augment.py_preproc_boxesL722、_postproc_boxesL741tests/geometry/test_boxes.pyTestVideoBoxesL1881。六、迁移建议升级到包含 #4176、#4365 修复的版本后现有VideoBoxes代码无需任何修改签名扩展完全向后兼容若此前因TypeError绕过了get_boxes_shape/to_mask例如先to_tensor再手写宽高计算现在可直接调用继承方法仍需注意索引切片后不要调用to_tensor应使用video_boxes.data或先恢复容器这是当前版本明确的已知限制#4249 剩余部分。【免费下载链接】kornia 空间人工智能的几何计算机视觉库项目地址: https://gitcode.com/kornia/kornia创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考