评价此页

torch.nn.functional.grid_sample#

torch.nn.functional.grid_sample(input, grid, mode='bilinear', padding_mode='zeros', align_corners=None)[source]#

计算网格采样。

给定一个 input 和一个流场 grid,使用 input 的值和 grid 的像素位置来计算 output

目前,仅支持空间(4D)和体积(5D) input

在空间(4D)情况下,对于形状为 (N,C,Hin,Win)(N, C, H_\text{in}, W_\text{in})input 和形状为 (N,Hout,Wout,2)(N, H_\text{out}, W_\text{out}, 2)grid,输出将具有形状 (N,C,Hout,Wout)(N, C, H_\text{out}, W_\text{out})

对于每个输出位置 output[n, :, h, w],大小为 2 的向量 grid[n, h, w] 指定了 input 的像素位置 xy,这些位置用于插值输出值 output[n, :, h, w]。对于 5D 输入,grid[n, d, h, w] 指定了用于插值 output[n, :, d, h, w]xyz 像素位置。mode 参数指定用于采样输入像素的 nearestbilinear 插值方法。

grid 指定了由 input 空间维度归一化的采样像素位置。因此,它应该有大部分值在 [-1, 1] 的范围内。例如,值为 x = -1, y = -1input 的左上像素,值为 x = 1, y = 1input 的右下像素。

如果 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 (张量) – 输入,形状为 (N,C,Hin,Win)(N, C, H_\text{in}, W_\text{in}) (4-D 情况) 或 (N,C,Din,Hin,Win)(N, C, D_\text{in}, H_\text{in}, W_\text{in}) (5-D 情况)

  • grid (张量) – 流场,形状为 (N,Hout,Wout,2)(N, H_\text{out}, W_\text{out}, 2) (4-D 情况) 或 (N,Dout,Hout,Wout,3)(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,则极值(-11)被认为是对应于输入角像素的中心点。如果设置为 False,则它们被认为是对应于输入角像素的角点,使得采样更具分辨率无关性。此选项与 interpolate() 中的 align_corners 选项平行,因此这里使用的选项也应该在调整输入图像大小后用于网格采样。默认为 False

返回

输出张量

返回类型

output (张量)

警告

align_corners = True 时,网格位置取决于像素大小相对于输入图像大小的比率,因此对于以不同分辨率输入(即经过放大或缩小后)的相同输入,grid_sample() 采样的位置将不同。直到 1.2.0 版本,默认行为都是 align_corners = True。此后,为了与 interpolate() 的默认行为保持一致,默认行为已更改为 align_corners = False

注意

mode='bicubic' 使用 三次卷积算法 实现,其中 α=0.75\alpha=-0.75α\alpha 的常数可能因不同包而异。例如,PILOpenCV 分别使用 -0.5 和 -0.75。此算法可能会“过冲”其正在插值的数值范围。例如,在插值 [0, 255] 范围内的输入时,它可能会产生负值或大于 255 的值。使用 torch.clamp() 夹住结果,以确保它们在有效范围内。