计算机视觉深度学习人工智能图像处理【免费下载链接】kornia 空间人工智能的几何计算机视觉库项目地址https://gitcode.com/kornia/kornia点击查看免费下载导读本篇文章围绕 Kornia 仓库 changelog 片段changelog.d/migration-084.fixed.md记录的迁移变更展开核心内容是Eager 模式下的边界框bounding box校验从“接受” NaN 与无穷坐标改为“拒绝”——kornia.geometry.bbox.validate_bbox对含非法坐标的框返回FalseBoxes.from_tensor(..., validate_boxesTrue)则对xyxy、xyxy_plus、xywh三种格式直接抛出ValueError对应 issue #4238PR #4243。读完本文你将掌握为什么非法坐标会穿透旧校验、新行为的精确语义与适用范围、底层源码实现细节、以及升级时如何排查与迁移代码。一、变更背景为什么必须拒绝 NaN 与无穷坐标边界框坐标在真实管线中可能因为多种原因退化为 NaNNot a Number或 ±inf上游检测器输出异常、坐标变换如透视投影除零、低精度张量计算溢出、数据加载缺帧等。在旧版本 Kornia 中这类“坏框”会被当作合法几何继续参与后续计算带来两类隐蔽问题静默污染validate_bbox旧实现只比较平行边长度不检查坐标是否有限NaN 框可以通过校验进入 mask 生成、NMS、裁剪等下游操作最终产出无意义的结果且不报错错误归因在 3D 场景validate_bbox3d中NaN 坐标会穿透正值范围检查——因为“NaN 与任何值比较都为 False”反而流进allclose边长比较抛出“Boxes must have be cube, while get different widths”这类指错病灶的异常让排查无从下手详见 changelog.d/migration-028.fixed.md3D 侧的对应修复 #4343。本次 migration-084 的修复思路是在 Eager非导出执行路径上对坐标有限性finiteness做显式检查让非法输入尽早、明确地失败而不是带病继续。二、变更语义速览两种 API两种失败方式API新行为Eager 模式触发条件validate_bbox(boxes)返回False输入形状非法或任意坐标为 NaN/±inf或平行边长差超过1e-4Boxes.from_tensor(boxes, mode..., validate_boxesTrue)抛出ValueError消息Some boxes have non-finite coordinates.mode为xyxy/xyxy_plus/xywh且存在非有限坐标或宽/高非正Boxes3D.from_tensor(..., validate_boxesTrue)抛出ValueError非有限坐标3D 对应修复见 changelog.d/migration-028.fixed.md两个关键边界条件模式范围只有xyxy、xyxy_plus、xywh三种 xy 系格式在from_tensor时执行坐标值校验vertices/vertices_plus顶点格式只校验形状不校验坐标值——这一不一致性在源码文档中标注为 issue #4177 跟踪见下文源码分析导出模式豁免在torch.export/ 图捕获graph capture场景下由于校验需要读取张量数据数据依赖分支会被is_exporting()门控跳过。这是有意的取舍保证导出图不出现数据依赖断点代价是导出路径不做坐标有限性校验。三、源码级解析校验逻辑到底在哪里、怎么实现的3.1validate_bbox纯谓词函数返回 False 而非抛错函数定义于 kornia/geometry/bbox.py#L43-L98是本次变更的主角。其校验流程分三步# 1) 形状检查只接受 (B, 4, 2) 或 (B, N, 4, 2)末两维必须是 [4, 2] if not (len(boxes.shape) in [3, 4] and boxes.shape[-2:] torch.Size([4, 2])): return False # 2) 有限性检查本次变更新增NaN / ±inf 直接判 False if not torch.isfinite(boxes).all(): return False # 3) 平行边校验top/bottom 边向量的 x、y 分量差 1e-4 则 False x_tl, y_tl boxes[..., 0, 0], boxes[..., 0, 1] ... width_t, width_b x_tr - x_tl 1, x_br - x_bl 1 height_t, height_b y_tr - y_tl 1, y_br - y_bl 1 if torch.any(torch.abs(width_t - width_b) 1e-4): return False if torch.any(torch.abs(height_t - height_b) 1e-4): return False return True注意第 2 步的“新代码”顺序有限性检查先于几何校验。这是因为 NaN 与任何数值比较结果都为False若不先拦截width_diff 1e-4这类比较对 NaN 会“静默通过”使旧实现把 NaN 框当作合法平行四边形接受。torch.isfinite同时覆盖NaN、inf、-inf三种情况一次调用全部拦截。该函数定位为“谓词”形状错误、非有限坐标都返回False而不抛异常。文档同时警告3D 版本的validate_bbox3d行为并不对称——它在形状与边长失败时抛AssertionError仅在坐标非有限时返回False该不一致在 issue #4013 跟踪见 kornia/geometry/bbox.py#L59-L61。3.2Boxes.from_tensor经由_boxes_to_quadrilaterals抛ValueError2D 盒类Boxes.from_tensorkornia/geometry/boxes.py#L683-L736把输入按mode交给内部函数_boxes_to_quadrilateralskornia/geometry/boxes.py#L99-L156。核心校验块在 kornia/geometry/boxes.py#L140-L147# Value validation reads the data, which graph capture cannot do; skip it under export. if validate_boxes and not is_exporting(): if not torch.isfinite(boxes).all(): raise ValueError(Some boxes have non-finite coordinates.) if (width 0).any(): raise ValueError(Some boxes have negative widths or 0.) if (height 0).any(): raise ValueError(Some boxes have negative heights or 0.)这段代码同时说明两个要点is_exporting()门控定义于 kornia/core/utils.py因为校验读取张量值并产生 Python 分支属于“数据依赖控制流”在torch.compile/torch.export图捕获下会引入 graph break因此导出模式下整段校验被跳过。仓库的导出支持用例中明确注记了这一点见 docs/export_support/cases_geomA.py#L662-L664三种 xy 模式共享同一校验xyxy的宽高按xmax - xminexclusive计算、xyxy_plus按xmax - xmin 1inclusive计算、xywh直接取width/height字段——三种模式分别计算宽高后统一走有限性与正性检查因此 migration-084 描述中“对xyxy、xyxy_plus、xywh三种模式均抛ValueError”正是来源于此。3.3 顶点模式为何“漏网”有意为之还是缺陷_boxes_to_quadrilaterals中vertices/vertices_plus分支kornia/geometry/boxes.py#L117-L129只做形状与模式名检查不校验坐标值。类级文档在 kornia/geometry/boxes.py#L267-L269 明确记录了该局限validate_boxesTrue时顶点模式不做值校验且vertices模式还会对固定顶点位置减一可能“变形输入而非拒绝输入”跟踪于 issue #4177。因此如果你的数据以顶点格式进入仍需自行调用torch.isfinite检查。四、实战验证如何复现新旧行为差异4.1validate_bbox谓词行为import torch from kornia.geometry.bbox import validate_bbox good torch.tensor([[[0., 0.], [10., 0.], [10., 10.], [0., 10.]]]) # (1,4,2) print(validate_bbox(good)) # True nan_box torch.tensor([[[0., 0.], [10., 0.], [10., float(nan)], [0., 10.]]]) print(validate_bbox(nan_box)) # False - migration-084 之后 inf_box torch.tensor([[[0., 0.], [10., 0.], [float(inf), 10.], [0., 10.]]]) print(validate_bbox(inf_box)) # False旧行为下nan_box的 NaN 出现在第 3 个顶点bottom-rightwidth_t/width_b的比较因 NaN 恒 False 而通过最终返回True本次修复后第 2 步torch.isfinite(...).all()直接返回False。4.2Boxes.from_tensor抛ValueErrorimport torch from kornia.geometry.boxes import Boxes # xyxy 模式xmax 为 NaN bad_xyxy torch.as_tensor([[0, 3, float(nan), 4]]) try: Boxes.from_tensor(bad_xyxy, modexyxy, validate_boxesTrue) except ValueError as e: print(e) # Some boxes have non-finite coordinates. # xywh 模式宽度为 inf bad_xywh torch.as_tensor([[0, 3, float(inf), 4]]) try: Boxes.from_tensor(bad_xywh, modexywh, validate_boxesTrue) except ValueError as e: print(e) # Some boxes have non-finite coordinates. # 显式退出校验旧行为仍然接受 box Boxes.from_tensor(bad_xyxy, modexyxy, validate_boxesFalse) print(box.data) # 构造成功但携带非有限顶点4.3 测试用例佐证仓库测试 tests/geometry/test_bbox.py#L127-L142 专门为本次修复新增了test_convention_validate_bbox_rejects_non_finite_coordinates_4238逐一对nan、inf、-inf三种非法值断言validate_bbox(...) is False把 #4238 的语义钉死在回归测试中tests/geometry/test_boxes.py#L62-L66 则验证了validate_boxesTrue时非法输入触发异常、False时放行的对照路径。你可以直接运行这两个测试确认本机行为pytest tests/geometry/test_bbox.py -k non_finite pytest tests/geometry/test_boxes.py -k invalid五、变更波及面哪些内部调用方受到影响validate_boxesFalse的内部调用点不受影响仓库内已有两处显式关闭校验kornia/contrib/augmentation_audit.py#L285审计工具导入框数据时关闭校验kornia/augmentation/_2d/mix/base.py#L241-L249RandomCutMix等混合增强从多种 mode 导入框时全部使用validate_boxesFalse避免合法内部数据被新校验误伤。对于普通用户需要注意的迁移点有两类依赖from_tensor默认校验的既有代码默认validate_boxesTrue不变但如果你的上游数据可能产生 NaN/inf例如低精度半精度计算、除零投影现在会在导入时抛ValueError——这是行为变化需在管线入口处先torch.nan_to_num/ 过滤坏框或显式传validate_boxesFalse并自行负责清理导出export场景由于校验被is_exporting()跳过torch.export后的模型不包含有限性检查请勿把导出版本当作有输入校验的防御层输入净化仍需放在导出图之外。六、与 3D 修复migration-028的关系本次 2D 修复#4243与 3D 侧修复changelog.d/migration-028.fixed.md#4343互为姊妹变更2D本文主题validate_bbox返回FalseBoxes.from_tensor(..., validate_boxesTrue)抛ValueError消息明确指出“non-finite coordinates”3DBoxes3D.from_tensor(..., validate_boxesTrue)同样拒绝非有限坐标validate_bbox3d对非有限坐标返回False此前 NaN 会错误地走到allclose边长比较并抛出“different widths”误导消息其四个内部调用方原本依赖抛错、丢弃返回值现在自行把False转换为同样抛出AssertionError且异常消息改指“non-finite coordinates”。两者共用同一原则非有限坐标是数据缺陷而非几何形状问题应在最靠近入口的位置以最明确的语义失败。七、迁移建议与最佳实践升级后先跑回归重点检查任何直接构造或转换边界框的路径检测后处理、数据增强、NMS 前处理确认没有 NaN/inf 输入被旧代码静默吞掉入口净化在Boxes.from_tensor之前对原始坐标执行torch.isfinite(...).all()预检或torch.nan_to_num兜底让错误更早暴露且可定位按需关闭校验对已知干净、但希望避免重复校验开销的批量路径可显式validate_boxesFalse参考仓库内部调用点的写法但需自行保证数据质量导出模型注意豁免导出图不含该校验生产部署时输入过滤必须留在图外留意顶点模式缺口vertices/vertices_plus输入仍不做值校验#4177涉及顶点格式时建议补一层torch.isfinite断言。本次变更让 Kornia 的边界框几何校验从“宽容但危险”走向“严格且明确”是 #3934 系列inclusive 坐标约定与 #4013 系列2D/3D 校验行为不一致之外又一例以可复现测试固定语义的防御性修复。理解它能帮助你在升级后快速定位因 NaN/inf 框而新出现的异常并正确设计输入净化策略。赞分享计算机视觉深度学习人工智能图像处理【免费下载链接】kornia 空间人工智能的几何计算机视觉库项目地址https://gitcode.com/kornia/kornia点击查看免费下载相关推荐Kornia 边界框校验增强Eager 验证正式拒绝 NaN 与无穷坐标migration-084 变更解析Kornia 边界框校验增强Eager 验证正式拒绝 NaN 与无穷坐标migration 084 变更解析 本文基于仓库 changelog.d/mi计算机视觉人工智能深度学习图像处理Kornia 边界框 API 形状校验修复解读infer_bbox_shape 与 bbox_to_mask 正式拒绝 rank-4 输入Kornia 边界框 API 形状校验修复解读 infer_bbox_shape 与 bbox_to_mask 正式拒绝 rank 4 输入 本篇技术指南围绕计算机视觉深度学习人工智能图像处理Kornia 3D 边界框 API 形状校验修复infer_bbox_shape3d 与 bbox_to_mask3d 拒绝 rank-4 输入Kornia 3D 边界框 API 形状校验修复 infer_bbox_shape3d 与 bbox_to_mask3d 拒绝 rank 4 输入 导读 本文计算机视觉深度学习人工智能图像处理创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
