Kornia 迁移指南:nms2d / nms3d 单元窗口(unit window)行为变更深度解析

原创2026-09-22 17:30:111,924 阅读
文章标签:计算机视觉图像处理深度学习人工智能库

Kornia 迁移指南:nms2d / nms3d 单元窗口(unit window)行为变更深度解析

导读

本文围绕 Kornia 仓库 changelog.d/+migration-009.breaking.md 记录的一则破坏性变更(breaking change)展开:在最新代码中,nms2d(x, (1, 1)) 与 nms3d(x, (1, 1, 1)) 将原样返回输入张量 x,而旧版本中 2D 路径会输出一个被“阈值化到 0”的伪影结果、3D 路径则直接抛出异常。读完本文,你将理解单元窗口 NMS 的数学语义、旧卷积实现产生伪影的根源(零化中心抽头求和为 0.0)、3D 路径报错的问题背景(#4241),以及迁移到新行为时需要注意的边界约定与测试验证方法。


一、变更概要:单元窗口不再“抑制”任何内容

原始变更说明(changelog.d/+migration-009.breaking.md)全文如下:

nms2d(x, (1, 1)) and nms3d(x, (1, 1, 1)) return x unchanged. A unit window has no neighbours, so nothing can be suppressed; the old 2-D result was an artifact of the zeroed centre tap of the convolution kernel summing to 0.0, while the old 3-D path raised because of #4241. (#4242)

拆解这则变更的核心语义:

行为维度 旧实现 新实现
nms2d(x, (1, 1)) 返回被置零的结果(卷积核中心抽头为 0 的伪影) 原样返回 x
nms3d(x, (1, 1, 1)) 抛出异常(#4241 导致) 原样返回 x
单元窗口语义 无明确定义 窗口没有邻居 → 无可抑制 → 恒等变换

从数学上讲,非极大值抑制(Non-Maxima Suppression, NMS)的定义是“严格大于窗口内所有邻居”。当窗口为 (1, 1)(或 (1, 1, 1))时,窗口内只有中心点自身、没有任何邻居参与比较,因此每一个位置都“空洞地”(vacuously)满足严格极大条件,任何值都不应被抑制。新的行为正是这一语义的直接落地。


二、旧 2D 实现的伪影根源:零化中心抽头的卷积核

旧版 2D NMS 采用卷积实现:构造一个与窗口等大的卷积核,将中心抽头置为 0.0,其余抽头置为 1.0,用卷积结果与原始响应图比较来判定极大值。

问题出在单元窗口 (1, 1) 上:此时卷积核只有一个元素——也就是那个被零化的中心抽头。于是:

  • 卷积核的元素和(sum)为 0.0;
  • 卷积输出恒为 0.0;
  • 比较逻辑把“响应值 > 0.0”当作极大值判定条件,导致所有非正数响应被误判为非极大、被置零。

也就是说,旧 2D 单元窗口的结果并非 NMS 语义,而是**“核求和为 0.0”这一数值伪影的副产品**。这也是为什么迁移说明将其明确标注为 “an artifact”(伪影)——它不是设计出来的行为,而是实现细节泄漏到了 API 语义中。

从当前源码看,这一卷积实现已被彻底移除,取而代之的是显式比较与池化方案(详见下文第三节),实现文件为 kornia/geometry/subpix/nms.py。


三、新实现的单元窗口路径:恒等掩码

在当前源码 nms.py 中,2D 与 3D 的单元窗口路径都非常直白。

3.1 nms2d 的 (1, 1) 路径

NonMaximaSuppression2d.forward 中对 kernel_size == (1, 1) 直接构造全 True 掩码:

if self.kernel_size == (1, 1):
    mask = torch.ones(B, CH, H, W, device=x.device, dtype=torch.bool)

随后在函数末尾:

if mask_only:
    return mask
return x * (mask.to(x.dtype))

因此:

  • mask_only=False(默认)时,x * 1 恒等于 x,输入原样返回;
  • mask_only=True 时,返回一个形状为 (B, C, H, W) 的全 True 布尔掩码。

3.2 nms3d 的 (1, 1, 1) 路径

3D 路径完全对称(nms.py 中 NonMaximaSuppression3d.forward):

if self.kernel_size == (1, 1, 1):
    mask = torch.ones(B, CH, D, H, W, device=x.device, dtype=torch.bool)

即 nms3d(x, (1, 1, 1)) 返回原输入,mask_only=True 时返回全 True 的 (B, C, D, H, W) 掩码。值得注意的是,该分支在旧版本中根本走不到——旧 3D 路径在进入比较逻辑前就会因 #4241 报错(见第五节)。

3.3 函数式 API

nms2d 与 nms3d 是轻量函数式封装,直接实例化对应模块并调用:

def nms2d(input: torch.Tensor, kernel_size: tuple[int, int], mask_only: bool = False) -> torch.Tensor:
    return NonMaximaSuppression2d(kernel_size)(input, mask_only)

def nms3d(input: torch.Tensor, kernel_size: tuple[int, int, int], mask_only: bool = False) -> torch.Tensor:
    return NonMaximaSuppression3d(kernel_size)(input, mask_only)

四、边界约定与“非方形窗口”修复(#4239 / #4240)

单元窗口行为只是本次 NMS 重写的一部分。为了让读者理解新实现的完整图景,这里补充与变更说明同批次落地的两个关键约定:

  1. 边界条带永远不是极大值(#4239):距离图像边界不足 (k - 1) // 2 的位置,其窗口无法完整落在输入内,因而没有与“能够决定它的邻居”进行过比较,不会被判定为极大值。这在通用路径中体现为 mask 边界保持 False、仅计算内部区域(nms.py 中通用分支)。

  2. 非方形窗口不再报错(#4240):旧实现构造卷积核时交换了两个方向的尺寸、且把 padding 加错了边,导致非方形窗口(如 (11, 5)、(13, 9))在内部 view 时报错;新实现按轴分别展开,支持任意 (ky, kx) / (kd, ky, kx) 组合。

对单元窗口而言,(1, 1) 的边界条带宽度为 (1-1)//2 = 0,即没有边界条带——每个位置都能完整放下窗口,这与“全 True 掩码”的恒等行为自洽。

4.1 通用路径的分治实现

对于除 (1,1)、(3,3)、(5,5)、(7,7)(2D)和 (1,1,1)、(3,3,3)(3D)之外的任意窗口,源码使用邻居极大值的分治池化:把“窗口挖掉中心”后的区域拆成若干矩形/长方体子块,用 max_pool2d / max_pool3d 分别归约再取 torch.maximum,从而把每位置的代价从字面意义的 ky*kx - 1(2D)次比较降为 O(ky + kx) 量级(见 nms.py 中 _neighbourhood_max2d / _neighbourhood_max3d 的 docstring)。


五、旧 3D 路径为何报错(#4241)

迁移说明指出旧 3D 路径“raised because of #4241”。结合 nms.py 通用分支的注释可以还原根因:

  • 旧 _compute_zero_padding3d 定义了一个 (k - 1) // 2 的辅助量,却在返回值中直接返回了完整核尺寸;
  • 卷积后的 padding 尺寸与卷积核尺寸不匹配,随后的 view 操作形状对不上,于是对除 (3, 3, 3) 之外的任意核都会抛出运行时错误。

这解释了为什么旧版本中 nms3d(x, (1, 1, 1)) 会直接报错——它根本无法完成一次合法的卷积形状变换。新实现彻底去掉了 padding 与 view,改为基于切片的显式比较和基于池化的通用归约,任何合法窗口尺寸都能运行。

另外,NonMaximaSuppression2d._load_from_state_dict 中保留了兼容旧检查点的逻辑:旧卷积实现把卷积核注册为持久 buffer,新实现会弹出 prefix + "kernel",从而允许严格模式(strict=True)加载旧版本保存的权重(包括 NMS 被嵌套在其他模块中的情况)。相关测试见 tests/geometry/subpix/test_nms.py 中的 test_loads_legacy_kernel_state_dict_strictly。


六、测试验证:单元窗口恒等语义

仓库测试 tests/geometry/subpix/test_nms.py 为本变更提供了直接的可执行证据,是迁移验证的最佳参照。

6.1 2D 单元窗口测试

def test_unit_window_suppresses_nothing(self, device, dtype):
    # A 1x1 window has no neighbours, so every position is vacuously a strict maximum and the
    # input comes back untouched. It used to come back thresholded at zero, an artifact of the
    # zeroed centre tap summing to 0.0 rather than anything NMS means.
    inp = torch.tensor([[[[float("-inf"), 0.0, 2.0], [0.5, -0.5, 0.0]]]], device=device, dtype=dtype)
    assert bool(kornia.geometry.subpix.nms2d(inp, (1, 1), mask_only=True).all())
    self.assert_close(kornia.geometry.subpix.nms2d(inp, (1, 1)), inp)

注意测试输入故意包含 float("-inf")、0.0、负数等边界值——即使是最极端的值也不会被抑制,这强有力地证明了“恒等”而非“阈值化为 0”的语义。

6.2 3D 单元窗口测试

def test_unit_window_suppresses_nothing(self, device, dtype):
    inp = torch.tensor([[[[[float("-inf"), 0.0, 2.0]]]]], device=device, dtype=dtype)
    assert bool(kornia.geometry.subpix.nms3d(inp, (1, 1, 1), mask_only=True).all())
    self.assert_close(kornia.geometry.subpix.nms3d(inp, (1, 1, 1)), inp)

6.3 整数类型同样成立

两个维度都提供了 torch.int64 版本(包含 torch.iinfo(torch.int64).min),确认恒等语义与 dtype 无关:

inp = torch.tensor([[[[torch.iinfo(torch.int64).min, 0, 2]]]], device=device, dtype=torch.int64)
assert bool(kornia.geometry.subpix.nms2d(inp, (1, 1), mask_only=True).all())
self.assert_close(kornia.geometry.subpix.nms2d(inp, (1, 1)), inp)

此外,测试套件还覆盖了与本次变更同一批次的周边行为:test_the_border_strip_is_never_a_maximum(#4239 边界约定)、test_non_square_kernel_size(#4240)、test_matches_the_reference_rule(3D 任意核与参考实现逐元素一致,#4241),以及 nms3d_minmax 与 nms3d(x) / nms3d(-x) 的一致性。


七、迁移建议与兼容性提示

  1. 依赖“单元窗口置零”的代码必须更新:如果旧代码有意或无意依赖 nms2d(x, (1, 1)) 返回全零张量(例如当作“阈值过滤”用),迁移后需要显式改为 x * (x > 0) 之类的操作,因为新行为是恒等变换。
  2. mask_only=True 的返回值变化:单元窗口下掩码从“全零”变为“全 True”,任何对掩码求和的统计逻辑都会发生量级变化。
  3. 3D 用户终于可用任意核:此前除 (3, 3, 3) 外都会报错的 3D 路径,现在支持 (1, 1, 1)、(5, 5, 5)、(3, 5, 7) 等任意组合,可以放心迁移。
  4. 检查点兼容:旧版本保存的含 kernel buffer 的状态字典仍可通过 load_state_dict(strict=True) 加载,无需手动剔除。
  5. 验证方式:升级后直接运行 tests/geometry/subpix/test_nms.py 中 TestNMS2d / TestNMS3d 的 test_unit_window_suppresses_nothing 系列用例,即可确认行为符合预期。

八、变更记录的背景:changelog 片段机制

本变更说明存放在 changelog.d 目录下,文件命名为 +migration-009.breaking.md。根据 changelog.d/README.md 的约定:

  • 每个带用户可见变更的 PR 在 changelog.d 下新增一个 <PR>.<type>.md 片段,由 Towncrier 在发布时合并进 CHANGELOG.md;
  • 类型 breaking 对应“破坏性变更”章节,要求同时描述旧行为与新行为——本文档正是这一要求的范例:明确写清了旧 2D 的伪影、旧 3D 的报错与新的一致语义;
  • +migration-* 前缀是引入该工作流时保留的一次性历史例外(保留迁移前的未发布条目,避免重复 PR 链接);
  • 本地预览可用 pixi run changelog-preview(从仓库根目录执行,不会修改 changelog 或删除片段)。

理解这套机制有助于在查阅 CHANGELOG.md 时追溯每个条目的原始上下文。


小结

nms2d(x, (1, 1)) 与 nms3d(x, (1, 1, 1)) 从“伪影置零 / 报错”统一为“原样返回”,是 Kornia 将 NMS 从卷积实现重构为显式比较 + 分治池化实现的自然结果。单元窗口没有邻居,因此无可抑制——这是数学语义的回归,而非特判修补。迁移时只需记住:单元窗口即恒等变换,且整个 NMS 家族(含 nms3d_minmax、边界约定、任意核尺寸)的行为均已由 tests/geometry/subpix/test_nms.py 全面锁定。

登录后查看全文
kornia