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": 对超出边界的网格位置使用边界值，

• padding_mode="reflection": 对超出边界的网格位置使用边界反射的位置的值。对于远离边界的位置，它会不断反射直到进入边界内，例如，(归一化) 像素位置 x = -3.5 经过边界 -1 反射后变为 x' = 1.5，然后经过边界 1 反射后变为 x'' = -0.5。

注意

此函数通常与 affine_grid() 结合使用，用于构建空间变换网络 (Spatial Transformer Networks) 。

注意

使用 CUDA 后端时，此操作在其反向传播过程中可能会导致不易关闭的非确定性行为。有关背景信息，请参阅可复现性 须知。

注意

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

参数

• input (Tensor) – 形状为 $(N, C, H_\text{in}, W_\text{in})$ (4-D 情况) 或 $(N, C, D_\text{in}, H_\text{in}, W_\text{in})$ (5-D 情况) 的输入

• grid (Tensor) – 形状为 $(N, H_\text{out}, W_\text{out}, 2)$ (4-D 情况) 或 $(N, D_\text{out}, H_\text{out}, W_\text{out}, 3)$ (5-D 情况) 的流场

• mode (str) – 用于计算输出值的插值模式：'bilinear' | 'nearest' | 'bicubic'。默认值：'bilinear' 注意：mode='bicubic' 仅支持 4-D 输入。当 mode='bilinear' 且输入为 5-D 时，内部使用的插值模式实际上是三线性插值。然而，当输入为 4-D 时，插值模式才是真正的双线性插值。

• padding_mode (str) – 超出网格范围值的填充模式：'zeros' | 'border' | 'reflection'。默认值：'zeros'

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

返回值

输出张量

返回类型

output (Tensor)

警告

当 align_corners = True 时，网格位置取决于像素大小相对于输入图像大小的比例，因此对于不同分辨率（即经过上采样或下采样后）的相同输入，grid_sample() 采样的位置将不同。直到 1.2.0 版本，默认行为是 align_corners = True。自那以后，默认行为已更改为 align_corners = False，以便与 interpolate() 的默认行为保持一致。

注意

mode='bicubic' 使用三次卷积算法实现，其中 $\alpha=-0.75$。常数 $\alpha$ 在不同软件包中可能有所不同。例如，PIL 和 OpenCV 分别使用 -0.5 和 -0.75。此算法可能会“超出”插值范围。例如，在对 [0, 255] 范围内的输入进行插值时，它可能会产生负值或大于 255 的值。使用 torch.clamp() 限制结果范围，确保它们在有效范围内。