kornia 视频框修复：`VideoBoxes.get_boxes_shape()` 与 `to_mask()` 的 `as_padded_sequence` 传递问题解析

计算机视觉深度学习图像处理【免费下载链接】kornia Geometric Computer Vision Library for Spatial AI项目地址https://gitcode.com/GitHub_Trending/ko/kornia点击查看免费下载导读本文围绕 kornia 仓库 changelog 条目migration-042.fixed.md记录的一项修复展开VideoBoxes视频序列专用 2D 框容器继承自Boxes的get_boxes_shape()与to_mask()方法此前会在每次调用时抛出TypeError根本原因在于VideoBoxes.to_tensor的 override 未声明并转发父类新增的as_padded_sequence关键字参数。读完本文你将理解该 bug 的触发链路、修复方式及其边界不影响既有工作调用并掌握VideoBoxes的时空轴约定、在AugmentationSequential视频增强管线中的角色以及该修复遗留的 #4249 索引问题。一、变更背景VideoBoxes是什么VideoBoxes是定义在 kornia/geometry/boxes.py 中的Boxes子类专门用于承载带显式时间维度的视频序列 2D 框对外接受与返回形状为(B, T, N, 4, 2)的角点张量vertices_plus模式即顺时针的左上、右上、右下、左下四个角点内部将角点扁平存储为(B·T, N, 4, 2)即把视频帧数并入 batch 维度通过temporal_channel_size: int属性boxes.py#L1111记录帧数T供导出时恢复时间轴。它的核心价值在于与增强容器协同在 kornia/augmentation/container/augment.py 的_preproc_boxes中当管线包含视频序列增强contains_video_sequential时输入框会被包装为VideoBoxes从而让几何变换后to_tensor能还原时间轴if isinstance(arg, Boxes): return arg if self.contains_video_sequential: arg cast(torch.Tensor, arg) return VideoBoxes.from_tensor(arg)二、故障现象TypeError从何而来按 changelog 记录migration-042.fixed.md故障表现非常直接VideoBoxes.get_boxes_shape()与VideoBoxes.to_mask()不再抛TypeError修复前每次调用都会抛错。触发链路需要追溯到Boxes父类的方法实现Boxes.get_boxes_shape()boxes.py#L328-L346内部调用self.to_tensor(xywh, as_padded_sequenceTrue)Boxes.to_mask()boxes.py#L819-L877内部调用self.to_tensor(xyxy, as_padded_sequenceTrue)而VideoBoxes的to_tensoroverride 此前只声明了mode一个参数没有**kwargs也没有as_padded_sequence。于是只要对任何VideoBoxes实例调用这两个继承方法就会以位置参数之外的方式多传一个关键字参数触发TypeError: to_tensor() got an unexpected keyword argument as_padded_sequence。由于AugmentationSequential为视频框输入构建的正是VideoBoxes容器这条链路在视频增强管线中几乎必然被触发影响面覆盖所有依赖get_boxes_shape如尺寸统计与to_mask如框转掩码的调用路径。三、根因分析override 签名与父类调用方的失配问题本质是子类 override 的签名落后于父类调用方父类Boxes.to_tensor的签名boxes.py#L738-L740为def to_tensor( self, mode: Optional[str] None, as_padded_sequence: bool False ) - torch.Tensor | list[torch.Tensor]:修复前的VideoBoxes.to_tensor只写了mode与父类的契约不一致更关键的是as_padded_sequence并不是无用参数——它控制 list-backed 容器的导出行为当对象由张量列表创建时as_padded_sequenceTrue返回填充后的单一张量否则返回按原始长度裁剪的张量列表见 boxes.py#L765-L768 对as_padded_sequence的说明。VideoBoxes的 override 在重建时间轴时把扁平存储(B·T, ...)重新view为(B, T, ...)boxes.py#L1169-L1173因此它必须原样接收并转发该关键字才能让父类的get_boxes_shape与to_mask正常工作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:]) # If returns a list of boxes. return [_out.view(-1, self.temporal_channel_size, *_out.shape[1:]) for _out in out]四、修复内容与行为边界按 changelog 记录关联 issue #4176、#4365修复要点如下override 现在接受并转发as_padded_sequence签名与父类对齐父类get_boxes_shape与to_mask的调用不再失配行为兼容性保证该关键字只对 list-backed 容器产生差异而由(B, T, N, 4, 2)张量构建的VideoBoxes并非 list-backed因此所有原本能正常工作的调用其结果保持不变文档同步更新VideoBoxes.to_tensor的 docstringboxes.py#L1150-L1168明确了as_padded_sequence仅改变 list-backed 容器的结果对由(B, T, N, 4, 2)张量构建的VideoBoxes无影响该关键字之所以被接受是因为继承的get_boxes_shape与to_mask会传入它。也就是说这是一次纯兼容性的签名修复修补的是父类调用方与子类 override 之间的契约断裂而不是改变任何导出语义。五、遗留问题索引仍会丢失时间轴#4249 的另一半changelog 明确指出了本修复的边界索引一个VideoBoxes仍会丢弃temporal_channel_size这是 #4249 的剩余一半。根因在Boxes.__getitem__boxes.py#L306-L309def __getitem__(self, key: slice | int | torch.Tensor) - Boxes: new_box type(self)(self._data[key], False) new_box._mode self._mode return new_box它通过type(self)(...)构造结果从不设置temporal_channel_size因此切片后的 wrapper 调用to_tensor()时会抛出AttributeErrorto_tensor中访问self.temporal_channel_size失败。这与本文修复的对象形成互补get_boxes_shape/to_mask问题已解决但索引路径的时间轴保留仍需跟进。该行为被测试用例显式钉住wart pintests/geometry/test_boxes.py#L1972-L1990 的test_wart_indexing_drops_the_temporal_size_4249断言video_boxes[0]仍是VideoBoxes但其to_tensor()抛出AttributeError同时验证clamp、filter_boxes_by_area、translate、pad、merge、to等方法在拷贝或原地更新后均能保持temporal_channel_size 3。六、源码级验证测试如何钉住该修复tests/geometry/test_boxes.py中的TestVideoBoxestests/geometry/test_boxes.py#L1881标注对应 #4016提供了完整的回归覆盖其中与本修复直接相关的两个用例值得关注test_convention_inherited_shape_and_mask_work_on_the_temporal_wrapper_4249tests/geometry/test_boxes.py#L2024作为约定convention钉住继承的get_boxes_shape与to_mask在时间轴 wrapper 上不再抛错这一半 #4249——即本文修复的核心断言test_convention_inherited_methods_split_copies_from_in_place_updatestests/geometry/test_boxes.py#L1992-L2022明确区分两类方法——transform_boxes、translate、clamp、filter_boxes_by_area、merge通过clone拷贝并返回携带时间轴的新VideoBoxes且不动源对象pad、unpad、to、type则原地更新self并返回自身但同样保持时间轴。此外TestVideoBoxes还覆盖了from_tensor的输入校验仅接受(B, T, N, 4, 2)张量拒绝 list 与非法维度见 boxes.py#L1136-L1148、整数输入自动转换为torch.get_default_dtype()、clone完整保留temporal_channel_size等行为。七、实践建议与迁移指引升级到包含本修复的版本后对VideoBoxes调用get_boxes_shape()返回高度与宽度元组与to_mask(height, width)返回(B, T, N, H, W)掩码不再需要任何 workaround可直接使用仍要避开索引陷阱video_boxes[i]得到的 wrapper 没有temporal_channel_size对其调用to_tensor()会抛AttributeError。需要逐帧处理时建议先在to_tensor()后再切片或等待 #4249 的后续修复as_padded_sequence的语义仅对 list-backed 容器有效由(B, T, N, 4, 2)张量构建的VideoBoxes传入该关键字不会改变结果这一点与Boxes的 list 创建路径对应 #4179 的切片元数据丢失问题保持一致的文档约定若自定义继承Boxes/VideoBoxes并 overrideto_tensor请务必保持(mode, as_padded_sequence)的完整签名或使用**kwargs转发避免重蹈本 bug 的覆辙。结语migration-042.fixed.md记录的是一次小而关键的 API 契约修复VideoBoxes.to_tensor补齐as_padded_sequence参数后get_boxes_shape与to_mask在视频框容器上恢复可用且不改变任何既有工作调用的结果同时它如实标注了 #4249 剩余的一半索引丢时间轴配合 tests/geometry/test_boxes.py 的约定钉住测试为后续维护者划清了已修复与待修复的明确边界。对于在 kornia 中使用视频序列增强管线的开发者理解这一修复的因果链路有助于正确使用VideoBoxes并规避已知的索引限制。赞分享计算机视觉深度学习图像处理【免费下载链接】kornia Geometric Computer Vision Library for Spatial AI项目地址https://gitcode.com/GitHub_Trending/ko/kornia点击查看免费下载相关推荐Kornia 视频框修复解析VideoBoxes.get_boxes_shape() 与 to_mask() 的 TypeError 消除migration-042Kornia 视频框修复解析 VideoBoxes.get_boxes_shape 与 to_mask 的 TypeError 消除migration 04人工智能计算机视觉深度学习图像处理上一篇番茄小说下载器完整指南打造你的个人离线图书馆下一篇Gofile下载终极指南告别繁琐拥抱高效的文件获取体验创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考