Coordinate spaces

Image domain

Bounding box oriented in world space which defines a normalized domain.

Coordinates of points within this domain can be either with respect to the world coordinate system or the cube defined by the bounding box where coordinate axes are parallel to the cube edges and have a uniform side length of 2. The latter are the normalized coordinates used by torch.nn.functional.grid_sample(), in particular. In terms of the coordinate transformations, a Cube is thus equivalent to a Grid with three points along each dimension and align_corners=True.

A regular sampling Grid, on the other hand, subsamples the world space within the bounds defined by the cube into a number of equally sized cells or equally spaced points, respectivey. How the grid points relate to the faces of the cube depends on Grid.align_corners().

Image grid

Oriented regularly spaced data sampling grid.

The dimensions of Grid.shape are in reverse order of the dimensions of Grid.size(). The latter is consistent with SimpleITK, and the order of coordinates of Grid.origin(), Grid.spacing(), and Grid.direction(). Property Grid.shape, on the other hand, is consistent with the order of dimensions of an image data tensor of type torch.Tensor.

To not confuse Grid.size() with torch.Tensor.size(), it is recommended to prefer property torch.Tensor.shape. The shape property is also known from numpy.ndarray.shape.

A Grid instance stores the grid center point instead of the origin corresponding to the grid point with zero index along each grid dimension. This simplifies resizing and resampling operations, which do not need to modify the origin explicitly, but keep the center point fixed. To get the coordinates of the grid origin, use Grid.origin(). For convenience, the Grid initialization function also accepts an origin instead of a center point as keyword argument. Conversion between center point and origin are taken care internally. When both origin and center are specified, an error is raised if these are inconsistent with one another.

In addition, Grid.points(), Grid.transform(), and :meth`.Grid.apply_transform` support coordinates with respect to different axes: 1) (continuous) grid indices, 2) world space, and 3) grid-aligned cube with side length 2. The latter, i.e., Axes.CUBE or Axes.CUBE_CORNERS makes coordinates independent of Grid.size() and Grid.spacing(). These normalized coordinates are furthermore compatible with the grid argument of torch.nn.functional.grid_sample(). Use Grid.cube() to obtain a Cube defining the data domain without spatial sampling attributes.

Grid axes

Enumeration of grid axes with respect to which grid coordinates are defined.

Axes.CUBE = 'cube'

Oriented along grid axes with units corresponding to unit cube \([-1, 1]^D\) with origin with respect to world space at grid/image center and extrema -1/1 coinciding with the grid border (align_corners=False).

Axes.CUBE_CORNERS = 'cube_corners'

Oriented along grid axes with units corresponding to unit cube \([-1, 1]^D\) with origin with respect to world space at grid/image center and extrema -1/1 coinciding with the grid corner points (align_corners=True).

Axes.GRID = 'grid'

Oriented along grid axes with units corresponding to voxel units with origin with respect to world space at grid/image point with zero indices.

Axes.WORLD = 'world'

Oriented along world axes (physical space) with units corresponding to grid spacing (mm).