Kornia 迁移指南:nms2d / nms3d 单元窗口(unit window)行为变更深度解析
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))andnms3d(x, (1, 1, 1))returnxunchanged. 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 to0.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 重写的一部分。为了让读者理解新实现的完整图景,这里补充与变更说明同批次落地的两个关键约定:
-
边界条带永远不是极大值(#4239):距离图像边界不足
(k - 1) // 2的位置,其窗口无法完整落在输入内,因而没有与“能够决定它的邻居”进行过比较,不会被判定为极大值。这在通用路径中体现为mask边界保持False、仅计算内部区域(nms.py 中通用分支)。 -
非方形窗口不再报错(#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) 的一致性。
七、迁移建议与兼容性提示
- 依赖“单元窗口置零”的代码必须更新:如果旧代码有意或无意依赖
nms2d(x, (1, 1))返回全零张量(例如当作“阈值过滤”用),迁移后需要显式改为x * (x > 0)之类的操作,因为新行为是恒等变换。 mask_only=True的返回值变化:单元窗口下掩码从“全零”变为“全True”,任何对掩码求和的统计逻辑都会发生量级变化。- 3D 用户终于可用任意核:此前除
(3, 3, 3)外都会报错的 3D 路径,现在支持(1, 1, 1)、(5, 5, 5)、(3, 5, 7)等任意组合,可以放心迁移。 - 检查点兼容:旧版本保存的含
kernelbuffer 的状态字典仍可通过load_state_dict(strict=True)加载,无需手动剔除。 - 验证方式:升级后直接运行 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 全面锁定。