grid_sample

→Tensor

grid_sample(x: Tensor, grid: Tensor, mode: str = 'bilinear', padding_mode: str = 'zeros', align_corners: bool | None = None)

source

Sample an input feature map at flow-field coordinates.

For each output location, looks up a value in x at the (sub-pixel) location specified by grid, using bilinear (or nearest) interpolation. Forms the second half of a spatial transformer network (STN) when paired with affine_grid.

The grid uses normalised coordinates in $[-1, 1]$ : $(-1, -1)$ denotes the top-left corner of x and $(+1, +1)$ the bottom-right corner (with the align_corners=False convention placing corners just outside the edge pixels).

Parameters

xTensor

Source feature map of shape (N, C, H_in, W_in) (4-D) or (N, C, D_in, H_in, W_in) (5-D for volumetric sampling).

gridTensor

Sampling grid of shape (N, H_out, W_out, 2) for 2-D input or (N, D_out, H_out, W_out, 3) for 3-D input. Last axis stores (x, y) (or (x, y, z)) in

[-1, 1]

modestr= 'bilinear'

Interpolation mode: "bilinear" (default) or "nearest".

padding_modestr= 'zeros'

Behaviour for grid locations outside

[-1, 1]

: "zeros" (default), "border" (clamp to edge), or "reflection".

align_cornersbool= None

Controls whether ±1 denotes the centre of the corner pixels (True) or the outer edge of the image (False, default).

Returns

Tensor

Sampled output of shape (N, C, H_out, W_out) (or 5-D analogue), with the same dtype as x.

Notes

grid_sample is differentiable w.r.t. both x and grid. The gradient w.r.t. grid is what makes STN-style learned warps trainable end-to-end (Jaderberg et al., 2015).

Examples

>>> import lucid
>>> from lucid.nn.functional import affine_grid, grid_sample
>>> x = lucid.randn(1, 3, 32, 32)
>>> theta = lucid.eye(2, 3).unsqueeze(0)        # identity
>>> g = affine_grid(theta, (1, 3, 32, 32), align_corners=False)
>>> y = grid_sample(x, g, align_corners=False)
>>> y.shape
(1, 3, 32, 32)