Kornia 修复 MPS 边界补丁提取暗化问题：grid_sample边框填充的像素中心钳制原理
【免费下载链接】kornia🐍 Geometric Computer Vision Library for Spatial AI项目地址: https://gitcode.com/gh_mirrors/ko/kornia
本篇文章围绕 Kornia changelog 条目 changelog.d/+migration-126.fixed.md（issue #4063）展开，详细讲解补丁提取（patch extraction）在 Apple MPS（Metal Performance Shaders）后端上遇到图像边界时输出被"暗化"的根因、修复方案及其对下游描述子（descriptor）的影响。读完本文，你将理解torch.nn.functional.grid_sample在align_corners=False下的归一化坐标语义，掌握用"零填充 + 钳制网格"精确模拟padding_mode="border"的通用技巧，并能看懂 Kornia 中extract_patches_simple与extract_patches_from_pyramid的底层实现与对应测试。
背景：LAF 与补丁提取
在局部特征（local features）流程中，Kornia 用 LAF（Local Affine Frame，形状为(B, N, 2, 3)）描述每个关键点的仿射区域，并从图像中裁出对应的方形补丁，再交给 SIFT、HardNet 等描述子网络。这一环节的两个核心函数都位于 kornia/feature/laf.py：
- extract_patches_simple：不做平滑，直接按 LAF 定义的仿射网格在单张图上双线性采样，速度快但有混叠；
- extract_patches_from_pyramid：先对图像做高斯金字塔下采样，按 LAF 的尺度选择合适层级采样，抗混叠效果更好，也是 get_laf_descriptors 的默认路径。
两者的采样核心都是F.affine_grid(..., align_corners=False)生成网格后调用F.grid_sample。关键点在于：当 LAF 靠近甚至越过图像边界时，采样网格会落到图像范围之外，此时grid_sample的padding_mode决定"界外采样返回什么值"。
问题根因：MPS 缺少padding_mode="border"
padding_mode="border"的含义是：界外采样点被"钳制"到图像边缘像素的值，相当于边缘复制。然而 Apple 的 MPS 后端没有实现padding_mode="border"。为了让代码在所有设备上行为一致，Kornia 在 MPS 上改用padding_mode="zeros"（界外返回 0），同时手动把采样网格钳制回图像范围内，从而模拟边缘复制。
问题出在钳制的目标值上。旧实现使用：
grid.clamp(-1, 1)在align_corners=False的坐标系里，归一化坐标±1对应的是边界像素的外边缘，即像素索引-0.5，而不是该像素的中心。此时双线性采样会把边界像素与"界外零填充"各取一半进行混合，于是凡是触及图像边界的 LAF，其补丁边缘像素大约只返回真实值的一半——在[0, 1]区间的图像上表现为明显的暗化（darkened patches）。
修复后的实现位于 kornia/feature/laf.py 的_clamp_grid_to_pixel_centers：
def _clamp_grid_to_pixel_centers(grid: torch.Tensor, h: int, w: int) -> torch.Tensor: x = grid[..., 0].clamp(-1.0 + 1.0 / float(w), 1.0 - 1.0 / float(w)) y = grid[..., 1].clamp(-1.0 + 1.0 / float(h), 1.0 - 1.0 / float(h)) return torch.stack([x, y], dim=-1)核心变化：钳制上限从±1改为±(1 - 1/size)（size 为对应轴的长度）。在align_corners=False语义下，1 - 1/size恰好是最外侧像素的中心。把网格钳到像素中心，零填充模式下的双线性采样就只会取到该像素自身的值，从而精确复现padding_mode="border"。
修复如何落地：_grid_sample_patches的设备分流
钳制逻辑被封装进统一采样入口 _grid_sample_patches：
def _grid_sample_patches(img: torch.Tensor, grid: torch.Tensor, h: int, w: int) -> torch.Tensor: if img.device.type == "mps": return F.grid_sample(img, _clamp_grid_to_pixel_centers(grid, h, w), padding_mode="zeros", align_corners=False) return F.grid_sample(img, grid, padding_mode="border", align_corners=False)也就是说：
- CPU / CUDA 后端：继续使用原生
padding_mode="border"，不经过钳制分支； - MPS 后端：走"像素中心钳制 + 零填充"的模拟路径。
正如 changelog 所述，CPU 和 CUDA 路径从未进入该分支，其行为与修复前逐字节一致（byte-identical），因此本修复只影响 MPS 用户，不存在回归风险。
金字塔路径中的同样修正
extract_patches_from_pyramid使用两级策略：小图/大图走"打包图集（atlas）"路径，将各金字塔层级并排放置并做一格replicate边缘保护；在 atlas 路径中，层级常量同样以最外层像素中心为钳制界（kornia/feature/laf.py）：
-1.0 + 1.0 / float(w_l), # lo: 该层级最外侧像素中心 -1.0 + 1.0 / float(h_l), 1.0 - 1.0 / float(w_l), # hi 1.0 - 1.0 / float(h_l),这组lo/hi常量随后被应用到网格重映射（grid = grid.maximum(lo); grid = grid.minimum(hi)，见 laf.py），保证 MPS 上金字塔采样的边界行为与 CPU 一致。此外，kornia/feature/sift/pyramid.py 等 SIFT 内部路径也复用了_grid_sample_patches，因此同样受益于该修复。
影响面：所有基于补丁的描述子
补丁是描述子的输入。get_laf_descriptors在 kornia/feature/integrated.py 直接调用extract_patches_from_pyramid(timg, lafs, patch_size)，因此修复自动传导到所有基于 LAF 补丁的模块：
- get_laf_descriptors 与封装它的 LAFDescriptor；
- SIFTFeature 等 LocalFeature 组合模块；
- KeyNetAffNetHardNet；
- 以及 affine_shape.py、orientation.py 中所有以
extract_patches_from_pyramid提取补丁的环节。
一句话概括：凡是靠近图像边界的关键点，其补丁值此前在 MPS 上偏暗，描述子随之失真；修复后这些补丁与 CPU/CUDA 结果一致。
量化验证与测试保障
changelog 给出的量化结果（针对一张[0, 1]区间图像、补丁跨越图像角落的场景）：
- 与 CPU 结果的最大偏差从
0.395降至2.5e-6，后者已接近浮点精度极限； - 修复前有64.7% 的补丁像素偏差超过
1e-3，修复后全部回到1e-3以内。
这些结论有对应测试钉住，防止回归，见 tests/feature/test_laf.py 的TestClampGridToPixelCenters：
test_matches_border_padding：将"钳制到像素中心 + 零填充"与 CPU 上原生padding_mode="border"的结果做assert_close对比；test_naive_clamp_is_not_equivalent：显式断言旧的grid.clamp(-1, 1)与 border 参考结果偏差大于1e-3——这正是本 bug 的回归护栏；test_extractors_match_cpu_at_the_border：参数化覆盖extract_patches_simple与extract_patches_from_pyramid，用跨越图像角落的 LAF 验证"补丁不依赖设备"。
测试文件还通过_corner_border_laf构造旋转 LAF，让补丁同时越出两个边，确保测试真正命中边界分支（见 test_laf.py）。
经验总结
本次修复对使用 Kornia 的 MPS 开发者是一个重要提醒：
padding_mode="border"并非所有后端都支持，跨设备代码需要显式模拟；align_corners=False下±1不是像素中心，而是边界像素外边缘；任何手工钳制网格的代码都应钳到±(1 - 1/size)；- 补丁提取是特征流程的地基，边界上的像素级偏差会通过描述子放大，影响匹配质量；本修复让 MPS 上的局部特征流程与 CPU/CUDA 严格对齐。
如果你正在 MPS 上使用extract_patches_simple、extract_patches_from_pyramid、LAFDescriptor、SIFTFeature或KeyNetAffNetHardNet，升级到包含本次修复（issue #4063）的版本即可消除边界补丁暗化问题，无需改动任何调用代码。
【免费下载链接】kornia🐍 Geometric Computer Vision Library for Spatial AI项目地址: https://gitcode.com/gh_mirrors/ko/kornia
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
