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。

在空间（4D）情况下，对于形状为 $(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() 结合使用以构建 空间变换网络。

注意

当使用 CUDA 后端时，此操作可能会在其反向传播过程中引发不可预测的行为，并且不容易关闭。请参阅有关 可重复性 的说明以获取背景信息。

注意

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

参数

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

• 网格 (张量) – 形状为 $(N, H_\text{out}, W_\text{out}, 2)$（4D情况）或 $(N, D_\text{out}, H_\text{out}, W_\text{out}, 3)$（5D情况）的流场。

• 模式 (字符串) – 用于计算输出值的插值模式 'bilinear' | 'nearest' | 'bicubic'。默认值：'bilinear' 注意：mode='bicubic' 仅支持 4D 输入。当 mode='bilinear' 且输入为 5D 时，内部使用的插值模式实际上将是三线性插值。但是，当输入为 4D 时，插值模式将合法地为双线性插值。

• 填充模式 (字符串) – 网格外值填充模式 'zeros' | 'border' | 'reflection'。默认值：'zeros'

• 对齐角点 (布尔值, 可选) – 从几何上讲，我们将输入的像素视为正方形而不是点。如果设置为 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$。常数 $\alpha$ 在不同的软件包中可能会有所不同。例如，PIL 和 OpenCV 分别使用 -0.5 和 -0.75。此算法可能会“超出”其插值值的范围。例如，在对 [0, 255] 范围内的输入进行插值时，它可能会产生负值或大于 255 的值。使用 torch.clamp() 对结果进行钳位，以确保它们在有效范围内。