kornia.geometry.grid#

Grids of pixel and voxel coordinates. create_meshgrid() returns the (1, H, W, 2) grid of (x, y) coordinates of an image and create_meshgrid3d() the (1, D, H, W, 3) grid of (d, x, y) coordinates of a volume, normalized to \([-1, 1]\) by default or in pixels. The normalized 2D grid is the identity grid of torch.nn.functional.grid_sample() called with the same align_corners, True by default. The 3D grid is corner-aligned only and depth first, while grid_sample reads (x, y, z): pass grid[..., [1, 2, 0]] with align_corners=True. See Coordinates and sizes for the pixel-centre and align_corners conventions.

kornia.geometry.grid.create_meshgrid(height, width, normalized_coordinates=True, device=None, dtype=None, align_corners=True)[source]#

Generate a (1, H, W, 2) grid of (x, y) pixel coordinates, in [-1, 1] by default.

grid = create_meshgrid(H, W) returns the (x, y) coordinates of every pixel of an H x W image as a (1, H, W, 2) tensor, grid[0, i, j] holding column j and row i: normalized to \([-1, 1]\) by default, or in pixels, 0 to W - 1 and H - 1, with normalized_coordinates=False. A normalized grid is the identity sampling grid of torch.nn.functional.grid_sample() called with the same align_corners. For the (1, D, H, W, 3) grid of a volume, use create_meshgrid3d().

Convention:

Coordinates follow Coordinates and sizes. With normalized_coordinates=True, the align_corners argument selects the matching torch.nn.functional.grid_sample() convention; pass the same flag to both calls. The default is corner-aligned (align_corners=True).
A size-1 axis is 0 under either flag, and a size-0 axis gives an empty grid.
An integer dtype is kept for a pixel grid; a normalized grid is then torch’s default floating dtype.

Parameters:

height (int) – the image height (rows).
width (int) – the image width (cols).
normalized_coordinates (bool, optional) – whether to normalize coordinates in the range \([-1,1]\) in order to be consistent with the PyTorch function torch.nn.functional.grid_sample(). Default: True
device (Optional[device], optional) – the device on which the grid will be generated. Default: None
dtype (Optional[dtype], optional) – the data type of the generated grid. Default: None
align_corners (bool, optional) – which normalization convention to use when normalized_coordinates is True. True maps pixel centers \([0, size-1]\) to \([-1, 1]\); False uses the half-pixel mapping \(x_{norm} = (2x + 1) / W - 1\), where \(\pm 1\) are the outer pixel edges. Ignored when normalized_coordinates is False. Default: True

Return type:

Tensor

Returns:

grid tensor with shape (1, H, W, 2).

See also

create_meshgrid3d(): the (1, D, H, W, 3) grid of (d, x, y) voxel coordinates, corner-aligned only.
normalize_pixel_coordinates(): normalizes given (x, y) pixel coordinates the way the default grid is normalized.
warp_grid(): applies homographies to this grid, without sampling.
remap(): samples an image at an x map and a y map, such as the two channels of a pixel grid plus a flow.
unproject_meshgrid(): the camera ray through every pixel instead of its coordinates.

Example

>>> create_meshgrid(2, 2)
tensor([[[[-1., -1.],
          [ 1., -1.]],

         [[-1.,  1.],
          [ 1.,  1.]]]])

>>> create_meshgrid(2, 2, align_corners=False)
tensor([[[[-0.5000, -0.5000],
          [ 0.5000, -0.5000]],

         [[-0.5000,  0.5000],
          [ 0.5000,  0.5000]]]])

>>> create_meshgrid(2, 2, normalized_coordinates=False)
tensor([[[[0., 0.],
          [1., 0.]],

         [[0., 1.],
          [1., 1.]]]])

kornia.geometry.grid.create_meshgrid3d(depth, height, width, normalized_coordinates=True, device=None, dtype=None)[source]#

Generate a (1, D, H, W, 3) grid of (d, x, y) voxel coordinates, in [-1, 1] by default.

grid = create_meshgrid3d(D, H, W) returns the (d, x, y) coordinates of every voxel of a D x H x W volume as a (1, D, H, W, 3) tensor, grid[0, k, i, j] holding depth k, column j and row i: normalized to \([-1, 1]\), corner-aligned, by default, or in voxels with normalized_coordinates=False. Depth comes first, unlike the (x, y, z) that torch.nn.functional.grid_sample() reads. For the (1, H, W, 2) grid of an image, use create_meshgrid().

Convention:

Coordinates follow Coordinates and sizes. A normalized grid is always corner-aligned; reorder its last axis with grid[..., [1, 2, 0]] before passing it to torch.nn.functional.grid_sample().
A size-1 axis is 0 and a size-0 axis gives an empty grid.
Known defect: there is no align_corners argument, so the half-pixel grid that grid_sample(..., align_corners=False) expects cannot be requested (#4503).

Parameters:

depth (int) – the volume depth (the D axis).
height (int) – the image height (rows).
width (int) – the image width (cols).
normalized_coordinates (bool, optional) – whether to normalize coordinates to \([-1, 1]\). Default: True
device (Optional[device], optional) – the device on which the grid will be generated. Default: None
dtype (Optional[dtype], optional) – the data type of the generated grid. Default: None

Return type:

Tensor

Returns:

grid tensor with shape (1, D, H, W, 3).