计算机视觉深度学习人工智能图像处理【免费下载链接】kornia 空间人工智能的几何计算机视觉库项目地址https://gitcode.com/kornia/kornia点击查看免费下载导读本文基于 kornia 仓库的变更记录 changelog.d/migration-123.fixed.md对应 GitHub issue #4006深入讲解本轮修复的核心内容像素坐标归一化normalization与反归一化denormalization在单像素singleton轴上的精确定义、非正尺寸的参数校验、空 warp 目标的保留行为以及eps参数的整体弃用。文章将结合 kornia/geometry/conversions.py 中的真实实现和 tests/geometry/test_conversions.py 等测试用例说明为什么旧实现会在float16/bfloat16下产生显著偏差、为什么 1 像素高的目标在过去会输出全nan以及如何用一段可运行的代码验证新行为。读完本文你将掌握 kornia 坐标约定的边界语义能够在自己的网格生成、warp 与 soft-argmax 流程中避免这些精度与nan陷阱。背景像素坐标归一化的作用域在 kornia 中像素坐标归一化是把整数像素网格映射到[-1, 1]标准化区间的核心步骤广泛服务于create_meshgrid/create_meshgrid3d生成与torch.nn.functional.grid_sample兼容的网格warp_perspective、warp_affine、crop_by_transform_mat、homography_warp、warp_image_tps图像几何变换的网格采样spatial_soft_argmax2d、spatial_expectation2d、conv_soft_argmax2d/conv_soft_argmax3d及其模块形式从热力图回归关键点坐标。这些函数共享同一套坐标约定corner-aligned角落对齐即x_norm 2 * x / (width - 1) - 1像素中心0和size - 1分别映射到-1和1。相关约定的完整说明见 kornia/geometry/conversions.py 的 docstring 及文档 docs/source/get-started 下的 Conventions 章节。修复一scale 从 size 直接推导不再先取整到坐标 dtype旧行为的问题修复前的实现先执行size.to(dtype)之类的取整操作再基于取整后的值计算缩放系数。对于float32/float64影响通常不超过 1 个 ulp但对于float16/bfloat16问题严重得多——这些低精度浮点格式根本无法精确表示大多数实际尺寸。文档给出的典型例子denormalize_pixel_coordinates在bfloat16且size 3000时旧代码返回1496而正确结果应为1504。新实现现在的实现直接从 size 推导 scale并在涉及低精度 dtype 时用更高精度做符号运算标量eager / TorchScript分支使用 Python 浮点计算2.0 / (width - 1.0)天然保持精度图捕获tracing /torch.compile分支中若输出 dtype 是float16/bfloat16则把work_dtype提升为float32完成尺寸运算最后再把构造好的 factor / offset 转回输出 dtype见 kornia/geometry/conversions.py 与 kornia/geometry/conversions.py。也就是说归一化与反归一化四条辅助函数normalize_pixel_coordinates、denormalize_pixel_coordinates、normalize_pixel_coordinates3d、denormalize_pixel_coordinates3d以及矩阵形式的normal_transform_pixel/normal_transform_pixel3d现在都遵循先在 ≥float32 中做尺寸算术、最后一次性舍入的策略。这一点在create_meshgrid中也有对应处理——网格归一化整体在float32中完成仅在最后收窄到float16/bfloat16见 kornia/geometry/grid.py。影响面float32/float64下的结果最多移动 1 个 ulp属于精度修正而非行为变更真正显著的变化集中在float16/bfloat16。如果你正在做半精度推理流水线旧的归一化路径在尺寸不能被半精度精确表示时会产生数个单位甚至数十个单位的像素偏差本轮修复值得注意。修复二singleton 轴映射到归一化中心消除除零旧行为除零或依赖 eps当一个轴尺寸为 1 时旧公式2 / (size - 1)出现除零产生inf/nan。文档明确指出这一缺陷不限于辅助函数本身——凡是包含尺寸为 1 的坐标帧归一化操作都会受到影响。典型现象包括create_meshgrid(1, 4, normalized_coordinatesTrue)的 singleton 分量返回nanwarp_perspective、crop_by_transform_mat、homography_warp、warp_image_tps输出高度为 1 时整图返回全nanspatial_soft_argmax2d与spatial_expectation2d输入高度为 1 时返回nanconv_soft_argmax2d/conv_soft_argmax3d及其模块形式在 kernel 或输入轴为 1 时产生一个单位的归一化偏移如conv_soft_argmax2d使用(3, 1)kernel 时由[-1.6667, -1.0, ...]变为[-1.0, -0.3333, ...]。新行为单位尺度、零偏移新实现为 singleton 轴显式定义映射唯一的有效像素坐标映射到归一化区间中心0scale 取 1offset 取 0。这一单位尺度扩展保证了函数在唯一有效坐标之外仍然严格可逆即归一化与反归一化互逆从而让单应矩阵合成homography composition能够处理 1 像素的源或目标尺寸。例如create_meshgrid(1, 4, normalized_coordinatesTrue)的 singleton 分量现在返回0输出高度为 1 的 warp 操作不再返回nan而是返回 2 像素控制情形下有限的那一行高度为 1 的输入在spatial_soft_argmax2d/spatial_expectation2d中现在返回0。在 kornia/geometry/conversions.py 中可见sx 1.0 if width 1 else 2.0 / (width - 1.0)tx 0.0 if width 1 else -1.0三维版本同样处理 depth/height/width见 kornia/geometry/conversions.py。矩阵形式的normal_transform_pixel/normal_transform_pixel3d在align_cornersTrue时采用同样的 singleton 中心策略见 kornia/geometry/conversions.py 与 kornia/geometry/conversions.py。需要注意align_cornersFalse半像素映射的情形(2x 1) / W - 1在W 1时天然得到 0scale 2、offset 0落在中心且不需要特殊分支——源码注释对此有明确说明见 kornia/geometry/conversions.py 与 kornia/geometry/grid.py。测试佐证对应的测试覆盖了 singleton 轴的中心映射与跨 singleton 边界的可逆性包括tests/geometry/test_conversions.py 中的test_singleton_axes_map_to_center_and_keep_unit_extension、test_singleton_axes_are_exact_inverses、test_normalize_and_denormalize_trace_cross_singleton_boundarytests/geometry/test_grid.py 中的test_normalized_meshgrid_singleton_axis_is_centered以及 export 相关的test_pixel_coordinate_export_crosses_singleton_boundarytorch.export动态尺寸下 singleton 边界同样成立。这些测试同时验证了 TorchScript 与torch.compile路径下的行为一致性。修复三拒绝非正尺寸保留空 warp 目标非正尺寸校验新实现规定高度、宽度以及三维的深度必须为正整数0和负数会抛出ValueError如Input image size must be positive. Got height0, width5.。这是归一化坐标系的语义要求——size - 1作为除数非正尺寸没有定义的坐标范围。需要说明一个例外create_meshgrid与 warp 输出的空目标被有意保留。零尺寸的网格产生一个对应的空网格见 kornia/geometry/grid.pywarp_affine/warp_perspective在输出维度为 0 时返回 autograd 连接的 empty 张量见 kornia/geometry/transform/imgwarp.py而homography_warp对负数dsize抛ValueError、对零尺寸走 empty 路径见 kornia/geometry/transform/imgwarp.py。也就是说坐标归一化拒绝零尺寸而网格生成 / warp 输出允许空结果——两者语义不同不要混淆。校验的代码路径限制校验逻辑形如if not torch.jit.is_tracing() and (height 0 or width 0): raise ValueError(...)。legacytorch.jit.trace图假设运行时尺寸为正因为 tracing 无法保留 Python 层的ValueError校验eager、TorchScript 与torch.compile调用则会校验尺寸。这与 kornia/geometry/conversions.py 的实现注释一致。如果你的代码使用torch.jit.trace并可能在运行时传入非正尺寸需要自行负责该约束。修复四eps参数弃用eps参数此前用于在除零时做微小保护默认1e-8normal_transform_pixel系列默认1e-14。既然 singleton 轴现在有了显式定义scale 1、offset 0eps不再参与映射计算四个{de,}normalize_pixel_coordinates{,3d}辅助函数与normal_transform_pixel{,3d}的eps参数在 eager 模式下传入非默认值会触发FutureWarning提示epsis deprecated and ignored在 TorchScript、tracing 与torch.compile路径下不触发警告源码中用not torch.jit.is_scripting() and not torch.jit.is_tracing() and not is_compiling()条件过滤因为这些路径无法或不宜发出 Python 警告参数将在未来破坏性版本中移除。迁移建议调用时直接删除eps参数即可无需任何替代值。详见 kornia/geometry/conversions.py、kornia/geometry/conversions.py 与 kornia/geometry/conversions.py。实战验证一段可运行的复现代码以下代码可在安装了当前仓库版本的 Python 环境中运行逐一验证文档所述行为import torch from kornia.geometry.conversions import ( normalize_pixel_coordinates, denormalize_pixel_coordinates, normal_transform_pixel, ) from kornia.geometry.grid import create_meshgrid from kornia.geometry.transform import warp_perspective from kornia.geometry.subpix import spatial_soft_argmax2d, conv_soft_argmax2d # 1) bfloat16 下 size3000 的反归一化不再严重偏差 x torch.tensor([[1.0, 1.0]], dtypetorch.bfloat16) out denormalize_pixel_coordinates(x, 3000, 3000) print(bfloat16 denorm:, out) # 旧实现约 1496新实现接近 1504 # 2) singleton 轴映射到归一化中心 0而不是 nan grid create_meshgrid(1, 4, normalized_coordinatesTrue) print(meshgrid(1,4) singleton component:, grid[0, 0, 0, 0]) # 0 # 3) 输出高度为 1 的 warp 不再全 nan img torch.rand(1, 3, 4, 4) M torch.eye(3)[None] w warp_perspective(img, M, (1, 4), align_cornersTrue) print(warp_perspective h1 finite:, torch.isfinite(w).all()) # True # 4) 1 像素高输入的空间 soft-argmax 返回 0 heat torch.zeros(1, 1, 1, 4) heat[..., 0, 2] 1.0 print(spatial_soft_argmax2d h1:, spatial_soft_argmax2d(heat)) # x 分量含 0 # 5) 轴为 1 的 conv_soft_argmax2d 不再偏移一个归一化单位 hm torch.zeros(1, 1, 1, 3) hm[..., 0, 1] 1.0 print(conv_soft_argmax2d (3,1) kernel:, conv_soft_argmax2d(hm, kernel_size(3, 1))) # 6) 非默认 eps 触发 FutureWarningeager with torch.cuda.amp.autocast(enabledFalse): # 仅为示意CPU 下直接调用亦可 pass import warnings with warnings.catch_warnings(recordTrue) as wlist: warnings.simplefilter(always) normalize_pixel_coordinates(torch.tensor([[0.0, 0.0]]), 4, 5, eps1e-6) print(eps warning issued:, any(deprecated in str(w.message) for w in wlist)) # 7) 零 / 负尺寸抛出 ValueError try: normalize_pixel_coordinates(torch.tensor([[0.0, 0.0]]), 0, 5) except ValueError as e: print(ValueError:, e) # 8) normal_transform_pixel 矩阵形式的 singleton 行为 print(normal_transform_pixel(1, 4)) # 对角线 [1.0, 0.5]偏移 [-0.0, -1.0]x 轴 singleton 中心映射提示conv_soft_argmax2d的 kernel 为(3, 1)时输出形状与数值可在本仓库对应源码 kornia/geometry/subpix/spatial_soft_argmax.py 中核对不同 torch 版本下个别数值的末位可能有 ulp 级差异行为finite / 0 / 中心映射不受影响。深入底层调用链与约定细节归一化在 warp 流程中的位置warp_perspective/warp_affine的核心链路是把像素单应变换通过normalize_homography变成归一化坐标下的变换再生成网格采样warp_affine内部调用normalize_homography(M_3x3, (H, W), dsize, align_cornersalign_corners)见 kornia/geometry/transform/imgwarp.pynormalize_homography再调用normal_transform_pixel(src_h, src_w)与normal_transform_pixel(dst_h, dst_w)构造源/目标归一化矩阵见 kornia/geometry/conversions.py。因此normal_transform_pixel对 singleton 轴的单位尺度、零偏移处理直接决定了crop_by_transform_mat输出高度为 1 时不再全nan。源码注释还指出输出维度等于 1 时(B, 3, 3)路径保留投影行并与(B, 2, 3)仿射路径在 affine 变换下一致见 kornia/geometry/transform/crop2d.py。homography_warp则先用create_meshgrid生成归一化网格再应用归一化单应见 kornia/geometry/transform/imgwarp.pywarp_image_tps同样通过create_meshgrid(..., normalized_coordinatesTrue, align_cornersalign_corners)生成网格见 kornia/geometry/transform/thin_plate_spline.py。这些函数共同受益于网格 singleton 轴中心映射的修复。soft-argmax 系列spatial_soft_argmax2d把热力图转成概率分布后调用spatial_expectation2d见 kornia/geometry/subpix/spatial_soft_argmax.pyconv_soft_argmax2d在normalized_coordinatesTrue时对窗口中心网格调用normalize_pixel_coordinates见 kornia/geometry/subpix/spatial_soft_argmax.py三维版本调用normalize_pixel_coordinates3d见 kornia/geometry/subpix/spatial_soft_argmax.py。这就是文档所述kernel 或输入轴为 1 时偏移一个归一化单位得到修正的代码位置。关键约定备忘分量顺序2D 辅助函数输入为(x, y)位置参数顺序为(pixel_coordinates, height, width)3D 辅助函数输入为(d, x, y)depth 优先位置参数为(pixel_coordinates, depth, height, width)。矩阵形式normal_transform_pixel3d作用于(x, y, z)与坐标辅助函数的槽位顺序是置换关系混用会静默交换轴见 kornia/geometry/conversions.py。输出不 clamp[-1, 1]之外的坐标线性外推这符合网格采样的语义。整数 dtype 拒绝normal_transform_pixel(4, 5, dtypetorch.int64)会抛ValueError因为2/(size-1)被整数截断为 0 会让矩阵退化为把全图映射到单点见 kornia/geometry/conversions.py。该拒绝是无条件的disable_checks()/python -O/KORNIA_CHECKS0均无法关闭。总结与迁移建议本轮修复#4006可归纳为四条对用户可见的行为变化变化点旧行为新行为低精度尺寸计算先把 size 取整到坐标 dtypebfloat16 下 size3000 反归一化得到 1496在 ≥float32 中计算结果接近精确值1504float32/64 最多移动 1 ulpsingleton 轴除零 →nan/inf波及 meshgrid、warp、soft-argmax映射到归一化中心 0scale 1、offset 0保持可逆非正尺寸行为未定义抛ValueErrortracing 图除外空 warp 目标仍保留空张量eps参数参与除零保护忽略并弃用eager 下非默认值触发FutureWarning未来版本移除如果你的代码满足以下任一条件建议优先升级并回归使用float16/bfloat16做归一化或网格生成结果数值会变化输入或输出存在尺寸为 1 的轴之前可能悄悄产出nan现在得到有限值显式传入了eps需要删除该参数以消除警告并适配未来版本。相关实现与测试均在仓库中可查核心实现见 kornia/geometry/conversions.py、kornia/geometry/grid.py下游调用见 kornia/geometry/transform/imgwarp.py、kornia/geometry/transform/crop2d.py、kornia/geometry/subpix/spatial_soft_argmax.py测试佐证见 tests/geometry/test_conversions.py 与 tests/geometry/test_grid.py。赞分享计算机视觉深度学习人工智能图像处理【免费下载链接】kornia 空间人工智能的几何计算机视觉库项目地址https://gitcode.com/kornia/kornia点击查看免费下载相关推荐Kornia 像素坐标归一化修复解读单例轴中心映射、非正尺寸校验与低精度精度提升4006Kornia 像素坐标归一化修复解读单例轴中心映射、非正尺寸校验与低精度精度提升 4006 本篇技术指南聚焦于 kornia 仓库中 changelog.计算机视觉人工智能深度学习图像处理Kornia 修复 PinholeCamera.from_parameters 批量图像尺寸填充缺陷4279问题根因、修复原理与回归测试解析Kornia 修复 PinholeCamera.from_parameters 批量图像尺寸填充缺陷 4279问题根因、修复原理与回归测试解析 本篇文章以计算机视觉人工智能深度学习图像处理Kornia 修复 3D 体素采样坐标轴顺序缺陷warp_perspective3d 与 homography_warp3d 的恒等变换还原Kornia 修复 3D 体素采样坐标轴顺序缺陷warp_perspective3d 与 homography_warp3d 的恒等变换还原 本篇技术指南聚焦计算机视觉深度学习人工智能图像处理创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考