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维）和体积（5维）input。

在空间（4维）情况下，对于形状为 $(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。

Parameters

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

• 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 情况)

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

• padding_mode (str) – 外部网格值的填充模式 'zeros' | 'border' | 'reflection'。默认值: 'zeros'

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

Returns

输出张量

Return type

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