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] 指定 x、y、z 像素位置，用于插值 output[n, :, d, h, w]。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。

参数

• 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

返回

输出张量

返回类型

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