mindspore.ops.grid_sample

mindspore.ops.grid_sample(input, grid, mode='bilinear', padding_mode='zeros', align_corners=False)

给定一个输入和一个网格，使用网格中的输入值和像素位置计算输出。input 只支持4-D（GridSampler2D）和5-D（GridSampler3D）。

在4-D场景下，input 的shape为 \((N, C, H_{in}, W_{in})\)，grid 的shape为 \((N, H_{out}, W_{out}, 2)\)，output 的shape为 \((N, C, H_{out}, W_{out})\)。 对于每个输出位置 output[n, :, h, w]，grid[n, h, w] 指定 input 像素位置 x 和 y，用于计算 output[n, :, h, w] 的插值。以5D为例，grid[n, d, h, w] 指定 x， y，z 像素位置的插值位置为[n, :, d, h, w]。mode 参数指定 nearest 或 bilinear (bicubic暂不支持)插值法对输入像素进行采样。

grid 指定由 input 归一化的采样像素位置。因此，它应该在 \([-1, 1]\) 范围内的值最多。

如果 grid 的值在 \([-1, 1]\) 范围之外，则相应的输出将按照定义的 padding_mode 方式处理。如果 padding_mode 设置为 0 ，则使用 \(0\) 来表示出界的网格位置。 如果 padding_mode 设置为 border，对于出界网格位置，则使用border值。如果 padding_mode 设置为 reflection ，请使用边界所反映的位置的值用于指定出界网格位置。对于 远离边界的位置，它会一直被反射，直到在边界内。

参数：

• input (Tensor) - 4-D场景下，shape为 \((N, C, H_{in}, W_{in})\)，5-D场景下，shape为 \((N, C, D_{in}, H_{in}, W_{in})\)。数据类型为float32或float64。

• grid (Tensor) - 4-D场景下，shape为 \((N, H_{out}, W_{out}, 2)\)，5-D场景下，shape为 \((N, D_{out}, H_{out}, W_{out}, 3)\)。数据类型与 input 保持一致。

• mode (str) - 插值方法。可选方法为 'bilinear'， 'nearest'。默认值： 'bilinear' 。当 mode 为 'bilinear'，且输入为5-D，则 mode 为 'trilinear'。但是，当输入为4-D，则 mode 为 'bilinear'。默认值： 'bilinear' 。

  • 'nearest'：最近邻插值。每个输出像素的值为最近的输入像素的值。这种方法简单快速，但可能导致块状或像素化的输出。

  • 'bilinear'：双线性插值。每个输出像素是最接近的四个输入像素的加权平均值，使用双线性插值计算。与最近邻插值相比，此方法产生更平滑的结果。

  • 'trilinear'：三线性插值。这是双线性插值在三维数据上的扩展。它在两个空间维度上执行双线性插值，并沿第三个维度进行线性插值。通常用于体积或三维图像插值。

• padding_mode (str) - 填充方法。可选方法为 'zeros'，'border' 和 'reflection'。默认值： 'zeros' 。

• align_corners (bool) - 布尔值。如果设置成 True，-1和1被视为引用输入角像素的中心点。如果设置为 False，将被视为引用到输入角像素的角点，使采样更不受分辨率影响。默认值为 False。

返回：

Tensor，数据类型与 input 相同，4-D场景下，shape为 \((N, C, H_{out}, W_{out})\)，5-D场景下，shape为 \((N, C, D_{out}, H_{out}, W_{out})\)。

异常：

• TypeError - 如果 input 或 grid 不是Tensor类型。

• TypeError - 如果 input 和 grid 的数据类型不一致。

• TypeError - 如果 input 或 grid 的数据类型无效。

• TypeError - 如果 align_corners 不是一个布尔值。

• ValueError - 如果 input 或 grid 的维度不是四维或五维。

• ValueError - 如果 input 的第一个维度不等于 grid 的第一个维度。

• ValueError - 如果 grid 最后一个维度不等于2（4-D场景）或者3（5-D场景）。

• ValueError - 如果 mode 不是 bilinear，nearest，数据类型不为String。

• ValueError - 如果 padding_mode 不是 zeros，border，reflection，数据类型不为String。

支持平台：

Ascend GPU CPU

样例：

>>> import numpy as np
>>> from mindspore import Tensor, ops
>>> input_x = Tensor(np.arange(16).reshape((2, 2, 2, 2)).astype(np.float32))
>>> grid = Tensor(np.arange(0.2, 1, 0.1).reshape((2, 2, 1, 2)).astype(np.float32))
>>> output = ops.grid_sample(input_x, grid, mode='bilinear', padding_mode='zeros',
...                          align_corners=True)
>>> print(output)
[[[[ 1.9      ]
   [ 2.1999998]]
  [[ 5.9      ]
   [ 6.2      ]]]
 [[[10.5      ]
   [10.8      ]]
  [[14.5      ]
   [14.8      ]]]]