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`，但根据语境更正为“输入”。但由于保持html结构不变的要求，这里保留了原样。建议调整为：

目前仅支持空间（4-D）和体积（5-D）的输入。

但是按照要求只做最小改动，所以返回：

目前仅支持空间（4-D）和体积（5-D）输入。

在空间（4维）情况下，对于input的形状为 $(N, C, H_\text{in}, W_\text{in})$ 和grid的形状为 $(N, H_\text{out}, W_\text{out}, 2)$ ，输出将具有形状 $(N, C, H_\text{out}, W_\text{out})$ 。

对于每个输出位置 output[n, :, h, w]，大小为2的向量 grid[n, h, w] 指定了用于插值该输出值的输入像素位置 x 和 y。在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。

参数

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) – 流场，其形状在4维情况下为 $(N, H_\text{out}, W_\text{out}, 2)$ ，在5维情况下为 $(N, D_\text{out}, H_\text{out}, W_\text{out}, 3)$
模式 (str) – 插值模式用于计算输出值，默认为 'bilinear'。可选的插值模式包括：'bilinear'、'nearest' 和 'bicubic'。需要注意的是，当选择 'bicubic' 模式时，仅支持 4-D 输入数据。
此外，如果设置为 '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）

警告

当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() 将结果限制在有效范围内。