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。

对于形状为 $(N, C, H_\text{in}, W_\text{in})$ 的空间 (4-D) 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 后端时，此操作的后向传播可能会引起不确定的行为，且不易关闭。请参阅 Reproducibility（可复现性）部分的说明以了解背景信息。

注意

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, optional) – 在几何上，我们将输入像素视为方形而非点。如果设置为 True，则极限值（-1 和 1）被视为指向输入角像素的中心点。如果设置为 False，则它们被视为指向输入角像素的角点，使采样更具分辨率无关性。此选项平行于 interpolate() 中的 align_corners 选项，因此在此处使用的任何选项都应该在调整输入图像大小以进行网格采样时一并使用。默认值：False

返回

输出 Tensor

返回类型

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() 夹紧结果，以确保它们在有效范围内。