计算机视觉深度学习人工智能图像处理【免费下载链接】kornia 空间人工智能的几何计算机视觉库项目地址https://gitcode.com/kornia/kornia点击查看免费下载导读kornia.geometry.grid是 Kornia 中负责为图像与体素生成坐标网格的核心模块提供了create_meshgrid2D与create_meshgrid3d3D两个公开 API。几乎所有涉及像素坐标 → 归一化坐标的几何运算——从图像畸变矫正、双目深度估计、特征点采样到 LoFTR 匹配、距离变换核生成——都以这两个函数生成的网格作为起点。读完本文你将掌握两个函数的全部参数语义、align_corners两种归一化约定的差异与陷阱、与torch.nn.functional.grid_sample的配套使用方式以及它们在 eager、TorchScript 与torch.compile等不同执行路径下的数值一致性细节。一、模块定位一行 API 文档背后的完整功能关联文档 docs/source/geometry.grid.rst 对该模块的定位非常明确The kornia.geometry.grid module provides functions for generating coordinate grids for images. It includes functions for creating 2D and 3D mesh grids with optional coordinate normalization, making it easy to work with grid-based transformations and sampling operations in computer vision tasks.即模块的核心使命有两个生成 2D / 3D 网格以及可选地做坐标归一化从而与基于网格的变换warp与采样sampling操作无缝衔接。RST 文档通过.. autofunction::指令直接继承了源码中的 docstring因此函数的完整签名、参数说明、返回值形状与 doctest 示例都以 kornia/geometry/grid.py 中的实现为唯一事实来源。模块通过 kornia/geometry/init.py 中的from .grid import *对外导出因此日常使用可以简写为kornia.geometry.create_meshgrid与kornia.geometry.create_meshgrid3d二者同时被登记在 tests/api_surface.json 的 API 表面清单中。迁移提示历史版本中这两个函数位于kornia.utils与顶层kornia命名空间。当前仓库在 kornia/init.py 与 kornia/utils/init.py 中保留了带deprecated装饰器的兼容别名自 0.8.3 起调用时会提示改用kornia.geometry.*新入口新代码应直接使用新命名空间。二、create_meshgrid2D 图像坐标网格2.1 函数签名与参数语义源码签名kornia/geometry/grid.pydef create_meshgrid( height: int, width: int, normalized_coordinates: bool True, device: Optional[torch.device] None, dtype: Optional[torch.dtype] None, align_corners: bool True, ) - torch.Tensor:各参数含义与默认值如下表参数类型默认值说明heightint—图像高度行数网格的 y 轴尺寸widthint—图像宽度列数网格的 x 轴尺寸normalized_coordinatesboolTrue是否将坐标归一化到[-1, 1]以与torch.nn.functional.grid_sample保持一致devicetorch.deviceNone网格生成的设备CPU / CUDA 等缺省取默认设备dtypetorch.dtypeNone网格的数据类型缺省取默认浮点类型align_cornersboolTrue仅在normalized_coordinatesTrue时生效选择哪种归一化约定见 2.3 节返回值形状固定为(1, H, W, 2)H、W为传入的高与宽最后一维依次存放(x, y)坐标x 是列索引、y 是行索引。2.2 三种模式的标准输出源码 docstring 中给出了三组可直接验证的 doctest 示例。以 2×2 网格为例 create_meshgrid(2, 2) tensor([[[[-1., -1.], [ 1., -1.]], [[-1., 1.], [ 1., 1.]]]])这是默认模式align_cornersTrue四个角恰好落在(-1,-1)、(1,-1)、(-1,1)、(1,1)把像素中心[0, size-1]线性映射到[-1, 1]。 create_meshgrid(2, 2, align_cornersFalse) tensor([[[[-0.5000, -0.5000], [ 0.5000, -0.5000]], [[-0.5000, 0.5000], [ 0.5000, 0.5000]]]])半像素half-pixel约定下±1对应的是最外层像素的外边缘因此 2×2 网格的中心像素坐标落在±0.5。 create_meshgrid(2, 2, normalized_coordinatesFalse) tensor([[[[0., 0.], [1., 0.]], [[0., 1.], [1., 1.]]]])关闭归一化后直接得到整数像素中心网格左上角为(0, 0)、右下角为(1, 1)。这种模式常用于需要原始像素坐标的环节例如 kornia/geometry/calibration/undistort.py 中为图像去畸变构建整数像素中心网格。2.3 align_corners 两种归一化约定与 grid_sample 的匹配这是整个模块最容易踩坑的地方源码 docstring 专门用一段强调grid_samplehas two such conventions, selected by its ownalign_cornersflag, andalign_cornershere picks the matching one. Feeding a grid built under one convention to agrid_samplecall using the other applies a spurious sub-pixel scale and shift, so the two flags must agree.具体公式kornia/geometry/grid.pyalign_cornersTrue默认角对齐x_norm (x / (W - 1) - 0.5) * 2即像素中心0与W-1分别映射到-1与1align_cornersFalse半像素对齐x_norm (2 * x 1) / W - 1即最外层像素的外边缘落在±1中心像素落在(2x1)/W - 1。两者相差一个亚像素级的平移与缩放。若用align_cornersTrue生成的网格去喂给align_cornersFalse的grid_sample采样结果会产生约半个像素的偏移。必须保证两侧标志一致。该行为在 tests/geometry/test_grid.py 的test_create_meshgrid_align_corners中有专门测试对W4align_cornersFalse时 x 坐标落在-0.75与0.75即(2*01)/4-1 -0.75并验证了align_corners对normalized_coordinatesFalse的调用是完全无影响的 no-op。补充Kornia 库级坐标约定文档位于 docs/source/get-startedConventions Pitfalls页面网格的像素中心约定与库内其他几何算子保持一致。2.4 实现细节从像素斜坡到 1×H×W×2源码的实现分四步kornia/geometry/grid.py确定工作 dtype未显式指定dtype时通过torch.empty(0, devicedevice).dtype读取默认浮点类型这样读取结果依赖device参数避免 TorchScript 优化器在首次运行后常量折叠掉这次读取测试用例 验证了脚本化后网格能随torch.set_default_dtype变化生成像素斜坡用torch.arange(width)/torch.arange(height)生成整数索引序列而不是linspace。源码注释解释了原因linspace会先把端点四舍五入到坐标 dtype 再反向填充斜坡上半段在 float16/bfloat16 下大尺寸如 bfloat16 中size 257会产生 1 ulp 的偏差且与 Inductor 的编译路径不一致arange在 eager 与编译路径下逐索引精确一致且能在导出export时保留动态长度归一化normalized_coordinatesTrue时按 2.3 节公式计算对 float16/bfloat16先提升到 float32 完成整个归一化链、最后一次性缩窄回原 dtype避免 eager 中逐算子舍入与编译路径不一致见 2.5 节组网torch.stack(torch.meshgrid([xs, ys], indexingij), dim-1)得到W×H×2再permute(1, 0, 2)调整为H×W×2并unsqueeze(0)补上 batch 维最终输出1×H×W×2。值得一提的还有**单例轴singleton axis**约定当height1或width1时该轴的所有坐标被置为归一化中心0通过xs * 0.0而非zeros_like以保持与整数提升路径一致而尺寸为 0 时则生成空网格。这与像素坐标归一化零尺寸系统无定义形成对比。测试 tests/geometry/test_grid.py 专门验证了单例轴居中。2.5 数值一致性eager 与 torch.compile / TorchScript / 导出当前实现高度关注跨执行路径的位级一致。从 tests/geometry/test_grid.py 可以看到一整套针对性的回归测试矩阵test_normalized_meshgrid_trace_crosses_singleton_boundarytorch.jit.trace在 2×1 与 1×2 之间跨越单例边界时trace 结果与 eager 完全一致atolrtol0test_normalized_meshgrid_trace_matches_eager_at_unrepresentable_sizes对 258/300/1000/2050/3000 等尺寸其前驱在 bfloat16/float16 下不可精确表示验证 trace 与 eager 不因除数舍入而分叉test_pixel_meshgrid_half_dtype_matches_compile与test_normalized_meshgrid_half_dtype_matches_compiletorch.compile(fullgraphTrue)下 float16/bfloat16 网格与 eager 一致float16 在 CUDA 上最多保留 1 ulp 残差因为 ATen 与 triton 的 float32 除法并非逐位相同test_meshgrid_export_crosses_singleton_boundarytorch.export动态维度导出后运行时尺寸 1 与 5 的结果与 eager 一致test_pixel_meshgrid_default_dtype_matches_compile默认 dtype 的读取在编译路径下也保持一致。这些测试表明create_meshgrid在设计上把**图捕获 / 编译 / 导出友好**作为一等公民适合直接嵌入到需要torch.compile、TorchScript 或 ONNX/导出部署的模型管线中。三、create_meshgrid3d体素坐标网格3.1 签名与返回值源码签名kornia/geometry/grid.pydef create_meshgrid3d( depth: int, height: int, width: int, normalized_coordinates: bool True, device: Optional[torch.device] None, dtype: Optional[torch.dtype] None, ) - torch.Tensor:与 2D 版本相比多了depth参数体素深度即通道方向且没有align_corners参数——3D 版本固定采用角对齐align_cornersTrue语义的归一化。返回值形状为(1, D, H, W, 3)最后一维存放坐标注意 kornia/geometry/conversions.py 明确约定其坐标顺序为(d, x, y)——深度在前与normalize_pixel_coordinates3d的输入约定一致而不是常见的(x, y, z)顺序。3.2 使用示例与实现要点import torch import kornia grid kornia.geometry.create_meshgrid3d( depth3, height4, width6, normalized_coordinatesTrue, devicetorch.device(cpu), dtypetorch.float32, ) print(grid.shape) # torch.Size([1, 3, 4, 6, 3])实现上与 2D 版本同构kornia/geometry/grid.py同样的arange像素斜坡、同样的单例轴居中逻辑depth/height/width任一为 1 时该轴归零、同样的 float16/bfloat16 提升到 float32 归一化后一次性缩窄最后通过torch.meshgrid([zs, xs, ys], indexingij)组网并permute(0, 2, 1, 3)得到1×D×H×W×3。对应的 tests/geometry/test_grid.py 验证了形状、角点坐标最远角为(depth-1, width-1, height-1)、单例轴居中以及 trace 跨单例边界的一致性。四、仓库内的真实调用场景create_meshgrid系列是整个 Kornia 几何管线的地基仓库中有大量直接调用。以下按用途归类方便读者对照学习1. 相机模型与去畸变kornia/geometry/calibration/undistort.py用create_meshgrid(rows, cols, False, ...)生成整数像素中心网格再经畸变模型反向映射完成图像去畸变kornia/geometry/camera/stereo.py双目几何中用非归一化网格枚举整数像素中心(x, y)注意uv[..., 0]是 x 列索引kornia/geometry/camera/pinhole.py针孔相机模型中以该网格作为反投影unprojection的像素坐标基准。2. 深度估计kornia/geometry/depth.pydepth_to_3d先由create_meshgrid生成(1, H, W, 2)网格、丢弃前导维再配合内参矩阵把像素坐标反投影为 3D 点云。3. 特征匹配与描述子kornia/feature/loftr/utils/fine_matching.pyLoFTR 细匹配阶段用归一化网格做坐标变换kornia/feature/loftr/utils/supervision.py用非归一化网格把两个特征图展平成[N, hw, 2]的像素坐标对用于监督kornia/feature/mkd.pyMKD 描述子在 patch 上生成归一化核网格。4. 图像变换与增强kornia/augmentation/_2d/geometric/fisheye.py鱼眼畸变增强用归一化网格作为采样的目标坐标。5. 距离变换与核构建kornia/contrib/distance_transform.py同时使用 2D 与 3D 版本生成与卷积核同尺寸的坐标网格关闭归一化作为欧氏距离变换的基座。6. 测试与验证tests/augmentation/test_augmentation.py、tests/geometry/camera/test_perspective.py、tests/geometry/test_conversions.py 等大量测试通过网格生成参考数据用于验证变换、归一化与反归一化函数的正确性。五、实践建议与常见陷阱与 grid_sample 配套时对齐 align_corners网格的align_corners必须与torch.nn.functional.grid_sample的align_corners一致否则引入亚像素偏移。Kornia 自身的kornia.geometry.transform.remap会把align_cornersNone解析为False见 kornia/geometry/conversions.py 的约定说明组合使用时要格外留意默认值。想拿整数像素坐标就关闭归一化normalized_coordinatesFalse返回(0..W-1, 0..H-1)的整数中心网格且此时align_corners被忽略。适合去畸变、反投影、特征点监督等需要真实像素索引的场景。坐标顺序是 (x, y) 而非 (row, col)2D 网格最后一维是(x, y)x 对应列、y 对应行3D 网格是(d, x, y)深度在前。与normalize_pixel_coordinates/normalize_pixel_coordinates3dkornia/geometry/conversions.py、kornia/geometry/conversions.py的约定保持一致拼接管线时不要写成(y, x)。单例轴与空网格height1或width1时归一化结果为 0网格中心尺寸为 0 时返回空网格。这在动态形状导出场景下是明确且经过测试的行为。低精度 dtype 的数值行为float16/bfloat16 下网格在内部以 float32 归一化后一次性缩窄保证 eager 与torch.compile一致但 float16 在 CUDA 上可能残留至多 1 ulp 的除法差异跨后端做位级对齐断言时需注意。迁移命名空间kornia.utils.create_meshgrid*与顶层kornia.create_meshgrid*已标记废弃自 0.8.3 起应改用kornia.geometry.create_meshgrid*。六、延伸阅读模块实现与完整 docstringkornia/geometry/grid.py坐标归一化 / 反归一化配套函数kornia/geometry/conversions.pynormalize_pixel_coordinates、denormalize_pixel_coordinates、normalize_pixel_coordinates3d、denormalize_pixel_coordinates3d网格函数的系统测试tests/geometry/test_grid.py库级坐标约定文档docs/source/get-started 中的Conventions Pitfalls页面真实调用示例kornia/geometry/depth.py、kornia/geometry/calibration/undistort.py、kornia/feature/loftr/utils/fine_matching.py、kornia/contrib/distance_transform.py无论是手写一个图像 warp 工具、复现相机去畸变流程还是把特征匹配网络接入部署管线kornia.geometry.grid的这两个函数都是最值得先掌握的坐标地基。赞分享计算机视觉深度学习人工智能图像处理【免费下载链接】kornia 空间人工智能的几何计算机视觉库项目地址https://gitcode.com/kornia/kornia点击查看免费下载相关推荐Kornia 几何网格生成指南深入理解 create_meshgrid 与 create_meshgrid3dKornia 几何网格生成指南深入理解 create_meshgrid 与 create_meshgrid3d kornia.geometry.grid 是计算机视觉人工智能深度学习图像处理Kornia 几何线模块完全指南ParametrizedLine、Hyperplane 与 fit_line 的实战与源码解析Kornia 几何线模块完全指南ParametrizedLine、Hyperplane 与 fit_line 的实战与源码解析 本文是 kornia.geom计算机视觉深度学习人工智能图像处理Pascal Editor工具架构指南如何开发一个自定义编辑工具Pascal Editor工具架构指南如何开发一个自定义编辑工具 Pascal Editor 是一个开源、本地优先的 3D 建筑编辑器基于 React Th3D渲染3D建模前端MCP 服务AI 技能上一篇10分钟快速上手 BabelDOC一条命令把英文 PDF 翻译成双语对照版下一篇网盘直链下载助手突破性智能工具一键获取九大平台真实下载地址创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
