torch.nn.functional.grid_sample

torch.nn.functional.grid_sample(input, grid, mode='bilinear', padding_mode='zeros', align_corners=None)

计算网格采样。

给定一个 input 和一个流场 grid ，使用 input 值和像素位置从 grid 计算 output 。

目前，仅支持空间（4-D）和体积（5-D） input 。

在空间（4-D）情况下，对于形状为 $(N, C, H_\text{in}, W_\text{in})$ 的 input 和形状为 $(N, H_\text{out}, W_\text{out}, 2)$ 的 grid ，输出将具有形状 $(N, C, H_\text{out}, W_\text{out})$ 。

对于每个输出位置 output[n, :, h, w] ，大小为 2 的向量 grid[n, h, w] 指定了 input 像素位置 x 和 y ，这些位置用于插值输出值 output[n, :, h, w] 。在 5D 输入的情况下， grid[n, d, h, w] 指定了用于插值 output[n, :, d, h, w] 的 x 、 y 、 z 像素位置。 mode 参数指定了 nearest 或 bilinear 插值方法以采样输入像素。

grid 指定了通过 input 空间维度归一化的采样像素位置。因此，它应该具有大多数值在 [-1, 1] 范围内。例如，值 x = -1, y = -1 是 input 的左上像素，值 x = 1, y = 1 是 input 的右下像素。

如果 grid 的值超出 [-1, 1] 的范围，则相应的输出将按照 padding_mode 定义的方式处理。选项有

• padding_mode="zeros" : 使用 0 处理出界网格位置，

• padding_mode="border" : 使用边界值处理出界网格位置，

• 使用边界处的值来处理超出网格范围的网格位置。对于远离边界的位置，它将不断反射，直到变为边界内，例如，（归一化）像素位置 x = -3.5 通过边界 -1 反射变为 x' = 1.5 ，然后通过边界 1 反射变为 x'' = -0.5 。

注意

此函数常与 affine_grid() 结合使用，以构建空间变换网络。

注意

当使用 CUDA 后端时，此操作的逆过程可能会产生不易关闭的非确定性行为。请参阅可重现性说明以获取背景信息。

注意

grid 中的 NaN 值将被解释为 -1 。

参数:

• 输入（张量）- 形状为 $(N, C, H_\text{in}, W_\text{in})$ （4 维情况）或 $(N, C, D_\text{in}, H_\text{in}, W_\text{in})$ （5 维情况）的输入

• grid（张量）- 流场形状为 $(N, H_\text{out}, W_\text{out}, 2)$ （4 维情况）或 $(N, D_\text{out}, H_\text{out}, W_\text{out}, 3)$ （5 维情况）

• mode（字符串）- 计算输出值的插值模式 'bilinear' | 'nearest' | 'bicubic' 。默认： 'bilinear' 注意： mode='bicubic' 仅支持 4 维输入。当 mode='bilinear' 和输入为 5 维时，内部使用的插值模式实际上是三线性。然而，当输入为 4 维时，插值模式将真正是双线性。

• padding_mode（字符串）- 外部网格值的填充模式 'zeros' | 'border' | 'reflection' 。默认： 'zeros'

• align_corners（布尔值，可选）- 几何上，我们将输入的像素视为正方形而不是点。如果设置为 True ，则极值（ -1 和 1 ）被视为指向输入角落像素的中心点。如果设置为 False ，则它们被视为指向输入角落像素的角落点，使采样更具分辨率无关性。此选项与 interpolate() 中的 align_corners 选项平行，因此在此处使用的任何选项也应用于那里，在网格采样之前调整输入图像的大小。默认： False

返回值:

输出张量

返回类型:

输出（张量）

警告

当 align_corners = True 时，网格位置取决于像素大小与输入图像大小的相对关系，因此 grid_sample() 采样的位置会因不同分辨率（即上采样或下采样后）的相同输入而有所不同。截至版本 1.2.0 的默认行为是 align_corners = True 。从那时起，默认行为已更改为 align_corners = False ，以便与 interpolate() 的默认行为保持一致。

注意

mode='bicubic' 使用立方卷积算法实现， $\alpha=-0.75$ 可能因包而异。例如，PIL 和 OpenCV 分别使用 -0.5 和 -0.75。此算法可能会“超出”其插值值的范围。例如，在插值输入 [0, 255] 时，可能会产生负值或大于 255 的值。使用 torch.clamp() 限制结果以确保它们在有效范围内。