# grid_sample¶

paddle.nn.functional. grid_sample ( x, grid, mode='bilinear', padding_mode='zeros', align_corners=True, name=None ) [source]

Sample input X by using bilinear interpolation or nearest interpolation based on flow field grid, which is usually generated by `affine_grid` . When the input X is 4-D Tensor, the grid of shape [N, H, W, 2] is the concatenation of (x, y) coordinates with shape [N, H, W] each, where x is indexing the 4th dimension (in width dimension) of input data x and y is indexing the 3rd dimension (in height dimension), finally results is the bilinear interpolation or nearest value of 4 nearest corner points. The output tensor shape will be [N, C, H, W]. When the input X is 5-D Tensor, the grid of shape [N, D, H, W, 3] is the concatenation of (x, y, z) coordinates with shape [N, D, H, W] each, where x is indexing the 5th dimension (in width dimension) of input data x, y is indexing the 4th dimension (in height dimension) and z is indexing the 3rd dimension (in depth dimension) finally results is the bilinear interpolation or nearest value of 8 nearest corner points. The output tensor shape will be [N, C, D, H, W].

Step 1:

Get (x, y) grid coordinates and scale to [0, H-1/W-1].

```grid_x = 0.5 * (grid[:, :, :, 0] + 1) * (W - 1)
grid_y = 0.5 * (grid[:, :, :, 1] + 1) * (H - 1)
```

Step 2:

Indices input data X with grid (x, y) in each [H, W] area, and bilinear interpolate point value by 4 nearest points or nearest interpolate point value by nearest point.

```wn ------- y_n ------- en
|           |           |
|          d_n          |
|           |           |
x_w --d_w-- grid--d_e-- x_e
|           |           |
|          d_s          |
|           |           |
ws ------- y_s ------- wn

For bilinear interpolation:
x_w = floor(x)              // west side x coord
x_e = x_w + 1               // east side x coord
y_n = floor(y)              // north side y coord
y_s = y_s + 1               // south side y coord
d_w = grid_x - x_w          // distance to west side
d_e = x_e - grid_x          // distance to east side
d_n = grid_y - y_n          // distance to north side
d_s = y_s - grid_y          // distance to south side
wn = X[:, :, y_n, x_w]      // north-west point value
en = X[:, :, y_n, x_e]      // north-east point value
ws = X[:, :, y_s, x_w]      // south-east point value
es = X[:, :, y_s, x_w]      // north-east point value

output = wn * d_e * d_s + en * d_w * d_s
+ ws * d_e * d_n + es * d_w * d_n
```
Parameters
• x (Tensor) – The input tensor, which is a 4-d tensor with shape [N, C, H, W] or a 5-d tensor with shape [N, C, D, H, W], N is the batch size, C is the channel number, D, H and W is the feature depth, height and width. The data type is float32 or float64.

• grid (Tensor) – Input grid tensor, which is a 4-d tensor with shape [N, grid_H, grid_W, 2] or a 5-d tensor with shape [N, grid_D, grid_H, grid_W, 3]. The data type is float32 or float64.

• mode (str, optional) – The interpolation method which can be ‘bilinear’ or ‘nearest’. Default: ‘bilinear’.

• padding_mode (str, optional) – is out of input images. It can be ‘zeros’, ‘reflection’ and ‘border’. Default: zeros.

• align_corners (bool, optional) – If align_corners is true, it will projects -1 and 1 to the centers of the corner pixels. Otherwise, it will projects -1 and 1 to the image edges.

• name (str, optional) – For detailed information, please refer to Name. Usually name is no need to set and None by default.

Returns

Tensor, The shape of output is [N, C, grid_H, grid_W] or [N, C, grid_D, grid_H, grid_W] in which grid_D is the depth of grid,

grid_H is the height of grid and grid_W is the width of grid. The data type is same as input tensor.

Examples

```>>> import paddle
>>> import paddle.nn.functional as F

>>> # x shape=[1, 1, 3, 3]
>>> x = paddle.to_tensor([[[[-0.6,  0.8, -0.5],
...                         [-0.5,  0.2,  1.2],
...                         [ 1.4,  0.3, -0.2]]]], dtype='float64')
>>> # grid.shape = [1, 3, 4, 2]
>>> grid = paddle.to_tensor([[[[ 0.2,  0.3],
...                            [-0.4, -0.3],
...                            [-0.9,  0.3],
...                            [-0.9, -0.6]],
...                           [[ 0.4,  0.1],
...                            [ 0.9, -0.8],
...                            [ 0.4,  0.5],
...                            [ 0.5, -0.2]],
...                           [[ 0.1, -0.8],
...                            [-0.3, -1. ],
...                            [ 0.7,  0.4],
...                            [ 0.2,  0.8]]]], dtype='float64')
>>> y_t = F.grid_sample(
...     x,
...     grid,
...     mode='bilinear',
...     padding_mode='border',
...     align_corners=True
... )
>>> print(y_t)
Tensor(shape=[1, 1, 3, 4], dtype=float64, place=Place(cpu), stop_gradient=True,
[[[[ 0.34000000,  0.01600000,  0.08600000, -0.44800000],
[ 0.55000000, -0.07600000,  0.35000000,  0.59000000],
[ 0.59600000,  0.38000000,  0.52000000,  0.24000000]]]])
```