Kornia NMS 单元窗口语义修正:`nms2d(x, (1, 1))` 与 `nms3d(x, (1, 1, 1))` 破坏性变更深度解析
Kornia NMS 单元窗口语义修正:nms2d(x, (1, 1)) 与 nms3d(x, (1, 1, 1)) 破坏性变更深度解析
本篇技术指南围绕 Kornia 迁移变更记录 changelog.d/+migration-009.breaking.md 展开,解析非极大值抑制(Non-Maxima Suppression,NMS)在单元窗口(kernel_size = (1, 1) / (1, 1, 1))下的语义修正:新版本中单位窗口不再有任何抑制效果,而是原样返回输入。读者将从中理解该破坏性变更的来龙去脉、旧实现的数值伪影成因、新语义的数学依据,以及如何在源码与测试中验证这一行为,从而在升级 Kornia 后正确评估自己代码的兼容性。
变更速览:单位窗口现在"什么都不做"
迁移片段原文给出了本次变更的核心结论:
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)
一句话概括:单位窗口没有邻居,因此不存在任何可被抑制的对象,每个位置都是"真空"意义上的严格极大值,输入应当被完整保留。该条目归属于 breaking(破坏性变更)类别,因为旧版本的 2D 路径并不会返回 x 本身,而是产生一个由数值伪影导致的、近似"阈值化"的错误结果;3D 路径则更极端——直接抛出运行时异常。
该变更与同批次迁移记录中的多个修复条目(#4239、#4240、#4241、#4242)共同构成 Kornia 对 NMS 实现的整体重写,本节变更正是其中"单位窗口语义"的收尾一环。
旧行为错在哪里:卷积实现的数值伪影
要理解为什么这是一次破坏性变更,需要先回溯旧版 NMS 的实现方式。从 kornia/geometry/subpix/nms.py 中的代码注释与测试注释可以还原出旧版算法的大致形态:
-
旧的 2D 路径基于卷积实现:旧实现构建一个中心 tap 被置零的卷积核(
(k*k, 1, k, k)形状的 one-hot 变体),用卷积把每个邻居"收集"到各自通道中,再与中心值比较。这种设计的细节可以从迁移记录 changelog.d/+migration-081.fixed.md 佐证——该条目描述了旧版对k > 7窗口构建(k*k, 1, k, k)卷积核的行为,以及由此带来的巨大性能开销。 -
单元窗口下卷积核恒为 0:当
kernel_size = (1, 1)时,窗口内只有中心自身这一个 tap,而中心 tap 恰好被置零,于是卷积输出恒等于0.0。后续的"中心 > 邻居"比较退化成了x > 0.0的全局阈值判断——这完全不是 NMS 的语义,纯粹是"零中心卷积核求和为 0.0"带来的数值伪影。测试 tests/geometry/subpix/test_nms.py 中的注释对此有精确描述: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.
也就是说,旧版对
(1, 1)窗口的实际行为是"以 0 为阈值对输入做截断":所有非正值(包括负的响应值、甚至是-inf)都会被清零,只有严格大于 0 的位置被保留。 -
旧的 3D 路径直接抛错:旧版 3D 实现的 padding 计算函数
_compute_zero_padding3d存在缺陷——它定义了一个(k - 1) // 2的辅助函数,却返回了完整的内核尺寸,导致 padding 后的体数据与卷积核不匹配,后续的view操作必然失败(详见 changelog.d/+migration-083.fixed.md 对 #4241 的完整描述)。因此nms3d(x, (1, 1, 1))在旧版中根本无法运行。
新语义的数学依据:无邻居 ⇒ 真空严格极大值
新版 NMS 的定义非常清晰:一个位置成为局部极大值,当且仅当它的完整窗口都落在输入内部,且其值严格大于窗口内所有其他位置的值(中心点自身不是自己的邻居)。
按照这一定义:
- 当窗口为
(1, 1)(2D)或(1, 1, 1)(3D)时,窗口内除中心外不存在任何其他位置; - "严格大于空集"这一判断在逻辑上恒为真(即数学上所说的空真,vacuous truth);
- 因此每个位置都满足极大值条件,抑制掩码全为
True,x * mask的结果就是x本身。
这一规则在源码中有明确实现。查看 kornia/geometry/subpix/nms.py,NonMaximaSuppression2d.forward 对 (1, 1) 直接短路返回全真掩码:
if self.kernel_size == (1, 1):
mask = torch.ones(B, CH, H, W, device=x.device, dtype=torch.bool)
3D 版本完全对称(kornia/geometry/subpix/nms.py):
if self.kernel_size == (1, 1, 1):
mask = torch.ones(B, CH, D, H, W, device=x.device, dtype=torch.bool)
由于单位窗口没有邻居,实现甚至不需要分配任何比较运算——直接构造全 True 掩码即可,这在计算上也是零成本的。
源码级验证:从函数式 API 到模块化实现
Kornia 的 NMS 同时提供函数式 API 与 nn.Module 两种入口,两者共享同一套实现:
- 函数式:
nms2d(input, kernel_size, mask_only=False)与nms3d(input, kernel_size, mask_only=False),定义于 kornia/geometry/subpix/nms.py,内部直接实例化对应的nn.Module并调用; - 模块化:
NonMaximaSuppression2d(kornia/geometry/subpix/nms.py)与NonMaximaSuppression3d(kornia/geometry/subpix/nms.py),构造函数只接受tuple类型的kernel_size参数,长度必须分别为 2 和 3; - 两者均在 kornia/geometry/subpix/init.py 中导出,可通过
kornia.geometry.subpix.nms2d直接访问。
两个模块的 forward 还有一个可选的 mask_only 参数:为 True 时只返回布尔掩码;为 False(默认)时返回 x * mask.to(x.dtype)。在单元窗口下,无论 mask_only 取何值,结果都等价于"输入不变"(掩码全真时乘法不改变任何值)。
关于边界约定,新版实现还有一个与本次变更同源的统一规则(源自 #4239,详见 changelog.d/+migration-008.breaking.md):窗口无法完整落入输入内的边界条带(宽度为 (k - 1) // 2)永远不会报告极大值。这条规则此前只被 (3, 3)、(5, 5)、(7, 7) 的显式快速路径遵守,而通用路径(k > 7)此前使用 replicate-padding 导致边界行为不一致。新版让显式路径与通用路径遵循同一条边界规则,而单位窗口恰好是"边界条带宽度为 0"的特例——每个位置都能放进完整窗口,因此全部有效。
测试印证:单元窗口行为被显式钉死
Kornia 用专门的测试用例把单元窗口的语义固化下来,避免将来回归。在 tests/geometry/subpix/test_nms.py 中:
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、负值、正值等各类数值——来验证单元窗口下所有位置都保留。注意 float("-inf") 这个用例:在旧的"阈值化为 0"实现下,-inf 和负值必然被清零;而在新语义下它们被原样保留,这直接钉死了"真空严格极大值"的数学定义。
3D 侧有完全对称的测试 tests/geometry/subpix/test_nms.py,且两个维度还各有整数输入的变体(torch.int64,最小值为 torch.iinfo(torch.int64).min):
def test_unit_window_suppresses_nothing_integer(self, device):
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)
整数用例的意义在于:旧版的卷积实现根本无法处理整数输入,而新的短路路径直接构造布尔掩码,天然支持任意数值类型。
除了单元窗口本身,同一测试文件还用 _reference_nms_mask(tests/geometry/subpix/test_nms.py,从定义出发、用 torch.maximum 逐邻居归约实现的独立参考实现)对各类窗口做了参数化对拍,例如:
test_matches_the_reference_rule:对(3, 3)、(5, 5)、(7, 7)、(9, 9)、(15, 15)、(4, 4)等窗口逐一比对(tests/geometry/subpix/test_nms.py);test_a_plateau_holds_no_strict_maximum:验证"严格大于"语义——相邻相等的极大值会互相抑制,整个平台区一个都不留(tests/geometry/subpix/test_nms.py);test_the_border_strip_is_never_a_maximum:验证(k-1)//2宽度的边界条带永不报告极大值(tests/geometry/subpix/test_nms.py);test_window_larger_than_the_input_finds_no_maxima:窗口大于输入时结果全零(tests/geometry/subpix/test_nms.py)。
这些用例共同构成一张语义网,保证单元窗口的"输入不变"行为与整体 NMS 规则自洽。
同批次迁移记录:一次 NMS 实现的重写闭环
本次单位窗口变更并非孤立修复,而是 Kornia 对 NMS 系列缺陷整体重构的一部分,涉及四条相互关联的记录,全部围绕 changelog.d/ 目录下的迁移片段展开(该目录的命名与分类机制见 changelog.d/README.md,其中 +migration-* 是引入 Towncrier 工作流时保留的历史条目,使用孤儿前缀 + 以避免生成重复的 PR 链接):
| 迁移片段 | 关联 PR | 变更内容 | 与本次变更的关系 |
|---|---|---|---|
| +migration-008.breaking.md | #4239, #4242 | 统一所有窗口尺寸下的边界条带规则,通用路径不再 replicate-padding | 确立了"窗口不完整则不判定"的总体边界约定 |
| +migration-082.fixed.md | #4240, #4242 | nms2d 支持非方形窗口(如 (11, 5)),修复卷积核宽高互换导致的 view 报错 |
通用路径的健壮性修复 |
| +migration-083.fixed.md | #4241, #4242 | nms3d 支持任意 kernel_size,此前除 (3, 3, 3) 外全部抛错 |
直接解释了旧 3D 单元窗口为何抛错 |
| +migration-081.fixed.md | #4242 | k > 7 不再构建 one-hot 卷积,改用矩形 max_pool2d 区域覆盖,代价从 O(k*k) 降到 O(k + 1) |
新的池化实现是单位窗口短路分支得以成立的底层架构 |
| +migration-009.breaking.md | #4242 | 单位窗口语义修正:nms2d(x, (1, 1)) / nms3d(x, (1, 1, 1)) 返回 x 不变 |
本次文章的主题条目 |
从实现架构看,新版 kornia/geometry/subpix/nms.py 的分支策略可以归纳为:
(1, 1)/(1, 1, 1):短路,全真掩码(零开销);(3, 3)/(5, 5)/(7, 7)(3D 为(3, 3, 3)):手写显式比较路径,例如 3×3 做 8 次比较(kornia/geometry/subpix/nms.py),5×5 做 24 次(kornia/geometry/subpix/nms.py),7×7 做 48 次(kornia/geometry/subpix/nms.py);- 其他尺寸:通用路径,借助
_split_window与_neighbourhood_max2d/_neighbourhood_max3d(kornia/geometry/subpix/nms.py),将"窗口减中心"分区为若干矩形区域后用max_pool2d/max_pool3d归约,中心通过分区构造被天然排除,因此抑制保持严格性。
_split_window 是这一切的几何基础(kornia/geometry/subpix/nms.py):对长度为 k 的窗口,中心轴两侧分别有 (k-1)//2 和 k-(k-1)//2-1 个位置。当 k = 1 时两侧均为 0,这正是"无邻居"的精确几何表达。
迁移影响评估:你的代码需要改动吗
作为 breaking 类别的变更,升级后需要关注以下几点:
1. 行为层面:如果代码中显式调用了 nms2d(x, (1, 1)) 或 nms3d(x, (1, 1, 1))——无论是有意还是无意(例如 kernel_size 由变量动态传入)——旧版"以 0 阈值截断输入"的结果将变为"输入原样返回"。若你的后续逻辑依赖旧版对非正值的清零行为,需要显式改为 x.clamp_min(0) 或自行掩码。
2. 可用性层面:旧版 nms3d(x, (1, 1, 1)) 直接抛异常,新版可以正常执行,因此该变更同时是一处"修复"——此前无法运行的代码现在有了明确定义的行为。
3. 模块加载兼容性:重构后的 NonMaximaSuppression2d 不再持有卷积核,但通过重写 _load_from_state_dict(kornia/geometry/subpix/nms.py)主动弹出旧版 checkpoint 中的 kernel buffer,从而在严格模式下仍能加载旧权重,包括 NMS 嵌套在其他模块中的情况。对应的兼容性测试见 tests/geometry/subpix/test_nms.py,分别验证了 kernel 直接位于顶层(前缀为空)与嵌套在 nn.Sequential 中(前缀为 "0.")两种场景。
4. 性能层面:新版实现移除了卷积路径(旧版在 CPU 半精度下卷积开销可占 MultiResolutionDetector.detect 调用耗时的 99%,详见 changelog.d/+migration-081.fixed.md),单元窗口更是零比较开销,因此升级后即使调用频率不变,整体耗时也只降不升。
实践建议:什么时候会用到单元窗口
从语义上看,单元窗口 NMS 在日常特征检测管线中几乎没有实际用途——NMS 的意义恰恰在于"用邻居抑制冗余响应",而单元窗口没有任何抑制能力。但在以下场景中,理解该语义仍然重要:
- 动态参数化管线:
kernel_size由配置或超参传入时,极端配置(如自适应降级到(1, 1))应得到可预测、无异常的结果,新版语义保证了这一点; - 单元测试与模糊测试:任何响应图上的 NMS 恒等性质(
nms2d(x, (1, 1)) == x)都是值得固化的不变量,它同时验证了"输入输出形状与数值类型一致"; - 结合
nms3d_minmax使用:Kornia 还提供nms3d_minmax(kornia/geometry/subpix/nms.py),一次遍历同时计算 26 邻域的极大值与极小值掩码(等价于分别调用nms3d(x, (3,3,3))与nms3d(-x, (3,3,3))),供 DoG 等尺度空间检测器同时提取极大/极小响应。它固定使用(3, 3, 3)窗口,不受本次变更影响,但与之共享"严格比较、边界条带不判定"的语义约定,可作为对照理解 NMS 的整体规则。
总之,nms2d(x, (1, 1)) 与 nms3d(x, (1, 1, 1)) 的新行为——无邻居则无抑制,输入原样返回——是 Kornia NMS 重构后统一数学语义的自然结果。升级时只需留意"旧结果实为阈值截断伪影"这一事实,并确认自身代码没有依赖该伪影即可平滑迁移。