torch.nn.functional.grid_sample#

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

Compute grid sample.

Given aninput and a flow-fieldgrid, computes theoutput usinginput values and pixel locations fromgrid.

Currently, only spatial (4-D) and volumetric (5-D)input aresupported.

In the spatial (4-D) case, forinput with shape$(N,C,H_{\text{in}},W_{\text{in}})$(N,C,Hin​,Win​) andgrid with shape$(N,H_{\text{out}},W_{\text{out}},2)$(N,Hout​,Wout​,2), the output will have shape$(N,C,H_{\text{out}},W_{\text{out}})$(N,C,Hout​,Wout​).

For each output locationoutput[n,:,h,w], the size-2 vectorgrid[n,h,w] specifiesinput pixel locationsx andy,which are used to interpolate the output valueoutput[n,:,h,w].In the case of 5D inputs,grid[n,d,h,w] specifies thex,y,z pixel locations for interpolatingoutput[n,:,d,h,w].mode argument specifiesnearest orbilinear interpolation method to sample the input pixels.

grid specifies the sampling pixel locations normalized by theinput spatial dimensions. Therefore, it should have most values inthe range of[-1,1]. For example, valuesx=-1,y=-1 is theleft-top pixel ofinput, and valuesx=1,y=1 is theright-bottom pixel ofinput.

Ifgrid has values outside the range of[-1,1], the correspondingoutputs are handled as defined bypadding_mode. Options are

• padding_mode="zeros": use0 for 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 bythe border for out-of-bound grid locations. For location far awayfrom the border, it will keep being reflected until becoming in bound,e.g., (normalized) pixel locationx=-3.5 reflects by border-1and becomesx'=1.5, then reflects by border1 and becomesx''=-0.5.

Note

This function is often used in conjunction withaffine_grid()to buildSpatial Transformer Networks .

Note

When using the CUDA backend, this operation may induce nondeterministicbehaviour in its backward pass that is not easily switched off.Please see the notes onReproducibility for background.

Note

NaN values ingrid would be interpreted as-1.

Parameters

• input (Tensor) – input of shape$(N,C,H_{\text{in}},W_{\text{in}})$(N,C,Hin​,Win​) (4-D case)or$(N,C,D_{\text{in}},H_{\text{in}},W_{\text{in}})$(N,C,Din​,Hin​,Win​) (5-D case)

• grid (Tensor) – flow-field of shape$(N,H_{\text{out}},W_{\text{out}},2)$(N,Hout​,Wout​,2) (4-D case)or$(N,D_{\text{out}},H_{\text{out}},W_{\text{out}},3)$(N,Dout​,Hout​,Wout​,3) (5-D case)

• mode (str) – interpolation mode to calculate output values'bilinear' |'nearest' |'bicubic'. Default:'bilinear'Note:mode='bicubic' supports only 4-D input.Whenmode='bilinear' and the input is 5-D, the interpolation modeused 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'zeros' |'border' |'reflection'. Default:'zeros'

• align_corners (bool,optional) – Geometrically, we consider the pixels of theinput as squares rather than points.If set toTrue, the extrema (-1 and1) are considered as referringto the center points of the input’s corner pixels. If set toFalse, theyare instead considered as referring to the corner points of the input’s cornerpixels, making the sampling more resolution agnostic.This option parallels thealign_corners option ininterpolate(), and so whichever option is used hereshould also be used there to resize the input image before grid sampling.Default:False

Returns

output Tensor

Return type

output (Tensor)

Warning

Whenalign_corners=True, the grid positions depend on the pixelsize relative to the input image size, and so the locations sampled bygrid_sample() will differ for the same input given at differentresolutions (that is, after being upsampled or downsampled).The default behavior up to version 1.2.0 wasalign_corners=True.Since then, the default behavior has been changed toalign_corners=False,in order to bring it in line with the default forinterpolate().

Note

mode='bicubic' is implemented using thecubic convolution algorithm with$\alpha =-0.75$α=−0.75.The constant$\alpha$α might be different from packages to packages.For example,PIL andOpenCV 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 withtorch.clamp() to ensure they are within the valid range.