- torch.nn.functional.grid_sample(input, grid, mode='bilinear', padding_mode='zeros', align_corners=None)¶
inputand a flow-field
grid, computes the
inputvalues and pixel locations from
Currently, only spatial (4-D) and volumetric (5-D)
In the spatial (4-D) case, for
inputwith shape and
gridwith shape , the output will have shape .
For each output location
output[n, :, h, w], the size-2 vector
grid[n, h, w]specifies
y, which are used to interpolate the output value
output[n, :, h, w]. In the case of 5D inputs,
grid[n, d, h, w]specifies the
zpixel locations for interpolating
output[n, :, d, h, w].
bilinearinterpolation method to sample the input pixels.
gridspecifies the sampling pixel locations normalized by the
inputspatial dimensions. Therefore, it should have most values in the range of
[-1, 1]. For example, values
x = -1, y = -1is the left-top pixel of
input, and values
x = 1, y = 1is the right-bottom pixel of
gridhas values outside the range of
[-1, 1], the corresponding outputs are handled as defined by
padding_mode. Options are
0for out-of-bound grid locations,
padding_mode="border": use border values for out-of-bound grid locations,
padding_mode="reflection": use values at locations reflected by the border for out-of-bound grid locations. For location far away from the border, it will keep being reflected until becoming in bound, e.g., (normalized) pixel location
x = -3.5reflects by border
x' = 1.5, then reflects by border
x'' = -0.5.
When using the CUDA backend, this operation may induce nondeterministic behaviour in its backward pass that is not easily switched off. Please see the notes on Reproducibility for background.
NaN values in
gridwould be interpreted as
input (Tensor) – input of shape (4-D case) or (5-D case)
grid (Tensor) – flow-field of shape (4-D case) or (5-D case)
mode (str) – interpolation mode to calculate output values
mode='bicubic'supports only 4-D input. When
mode='bilinear'and the input is 5-D, the interpolation mode used internally will actually be trilinear. However, when the input is 4-D, the interpolation mode will legitimately be bilinear.
padding_mode (str) – padding mode for outside grid values
align_corners (bool, optional) – Geometrically, we consider the pixels of the input as squares rather than points. If set to
True, the extrema (
1) are considered as referring to the center points of the input’s corner pixels. If set to
False, they are instead considered as referring to the corner points of the input’s corner pixels, making the sampling more resolution agnostic. This option parallels the
interpolate(), and so whichever option is used here should also be used there to resize the input image before grid sampling. Default:
- Return type:
align_corners = True, the grid positions depend on the pixel size relative to the input image size, and so the locations sampled by
grid_sample()will differ for the same input given at different resolutions (that is, after being upsampled or downsampled). The default behavior up to version 1.2.0 was
align_corners = True. Since then, the default behavior has been changed to
align_corners = False, in order to bring it in line with the default for
mode='bicubic'is implemented using the cubic convolution algorithm with . The constant might be different from packages to packages. For example, PIL and OpenCV use -0.5 and -0.75 respectively. This algorithm may “overshoot” the range of values it’s interpolating. For example, it may produce negative values or values greater than 255 when interpolating input in [0, 255]. Clamp the results with :func: torch.clamp to ensure they are within the valid range.