Skip to content

AcquisitionGeometry

voxel.AcquisitionGeometry(baseshape, matrix=None, slice_direction=None, device=None)

Bases: AffineMatrix

Geometry representing the linear relationship between volumetric image coordinates and a three-dimensional world space.

Parameters:

  • baseshape (Size) –

    The spatial shape (3D dimensions) of the acquisition.

  • matrix (AffineMatrix, default: None ) –

    Affine matrix representing a voxel-to-world coordinate transform. If None, it defaults to a shifted identity in which the image volume is centered at the world origin.

  • slice_direction (int, default: None ) –

    Voxel-space index representing the dimension of slice direction, also known as the through-plane acquisition direction. If None, the direction is inferred from the largest voxel spacing.

  • device (device, default: None ) –

    Device to store the matrix on.

device: torch.device property

Device of the matrix tensor.

baseshape: torch.Size property

Spatial shape (3D dimensions) of the acquisition.

spacing: torch.Tensor property

Spacing between voxel centers.

slice_direction: int property

Index representing the dimension of the slice acquisition direction, or through-plane, direction of the acquisition.

slice_direction_is_explicit: bool property

Whether or not the slice direction was explicitly set at construction or inferred through heuristics.

in_plane_directions: list property

List of two indices representing the dimensions of the in-plane acquisition directions, which are orthogonal to the slice direction.

slice_spacing: torch.Tensor property

Spacing (separation) between slices.

in_plane_spacing: torch.Tensor property

Spacings between voxel centers in the in-plane directions.

spacing_ratio: torch.Tensor property

Ratio of slice spacing to in-plane spacing.

orientation: Orientation property

Anatomical orientation of the voxel coordinate system.

fov: torch.Tensor property

Acquisition field of view in world coordinate space.

origin: torch.Tensor property

Origin coordinate of the acquisition grid in world space.

center: torch.Tensor property

Center coordinate of the acquisition grid in world space.

numel() -> int

Number of baseshape elements in the acquisition volume.

is_isotropic(rtol=0.01) -> bool

Determine if voxel spacing is isotropic within a relative tolerance.

Parameters:

  • rtol (float, default: 0.01 ) –

    Relative tolerance of difference across spacings.

Returns:

  • bool –

    True if isotropic spacing.

local_coordinate_transform(space='voxel', dtype=torch.float32) -> vx.AffineMatrix

Build the affine transform mapping coordinates in space to the flipped [-1, 1] local coordinates used by torch grid sampling, fused into a single matrix so repeated conversions cost one matmul-add pass.

Parameters:

  • space (Space, default: 'voxel' ) –

    Source coordinate space of the transform.

  • dtype (dtype, default: float32 ) –

    Data type of the constructed matrix.

Returns:

voxel_to_local_coordinates(coords) -> torch.Tensor

Transform voxel coordinates to flipped local grid coordinates in the range [-1, 1], as used for grid sampling in torch.

Parameters:

  • coords (Tensor) –

    Voxel coordinates of shape (..., 3).

Returns:

  • Tensor –

    Transformed local coordinates.

world_to_voxel_units(units) -> torch.Tensor

Convert world units to voxel units.

Parameters:

  • units (Tensor) –

    Units of size \((1,)\) or \((3,)\) or \((3, 2)\) in world space.

Returns:

  • Tensor –

    Units in voxel space.

voxel_to_world_units(units) -> torch.Tensor

Convert voxel units to world units.

Parameters:

  • units (Tensor) –

    Units of size \((1,)\) or \((3,)\) or \((3, 2)\) in voxel space.

Returns:

  • Tensor –

    Units in world space.

conform_units(units, source, target, num=None) -> torch.Tensor

Conform units to a target space, e.g. if the input space is 'world', the units are converted to world space. Scalars are repeated to length 3.

Parameters:

  • units (Tensor) –

    Units of size \((1,)\) or \((3,)\) or \((3, N)\)

  • source (Space) –

    Space of the input units.

  • target (Space) –

    Space to convert the units to.

  • num (int, default: None ) –

    Number of units \(N\) represented in the second dimension of the output tensor. If None, the output tensor will have shape \((3,)\).

Returns:

  • Tensor –

    Units of size \((3, N)\) or \((3,)\) in target space.

shift(delta, *components, space=None) -> AcquisitionGeometry

Shift, or translate, the acquisition geometry.

Parameters:

  • delta (Tensor) –

    The translation vector of length 3.

  • *components (float, default: () ) –

    Additional components of delta, allowing values to be passed as separate positional arguments, e.g. shift(1, 0, 0, 'voxel').

  • space (Space, default: None ) –

    The space in which to apply the shift. Can be provided as the last positional argument.

Returns:

shift_to_point(target, center=True) -> AcquisitionGeometry

Shift the geometry so that the center or origin maps to a target world coordinate.

Parameters:

  • target (Tensor) –

    Target coordinate to shift to.

  • center (bool, default: True ) –

    If True, shift the center to the target point. Otherwise, shift the origin to the target.

Returns:

scale(factor, *components, space=None) -> AcquisitionGeometry

Scale the acquisition geometry.

Parameters:

  • factor (float or Tensor) –

    The scaling factor.

  • *components (float, default: () ) –

    Additional components of factor, allowing values to be passed as separate positional arguments, e.g. scale(1, 1, 2, 'voxel').

  • space (Space, default: None ) –

    The space in which to apply the scale. Can be provided as the last positional argument.

Returns:

rotate(rotation, *components, space=None, corner=False, degrees=True) -> AcquisitionGeometry

Rotate the acquisition geometry.

Parameters:

  • rotation (Tensor) –

    Rotation angles (x, y, z). If degrees is True, the angles are in degrees, otherwise they are in radians.

  • *components (float, default: () ) –

    Additional components of rotation, allowing angles to be passed as separate positional arguments, e.g. rotate(0, 0, 45, 'world').

  • space (Space, default: None ) –

    The space in which to apply the rotation. Can be provided as the last positional argument.

  • corner (bool, default: False ) –

    Whether to rotate around the image corner or center. Only applicable when the space is 'voxel'. Defaults to True.

  • degrees (bool, default: True ) –

    Whether the angles are defined as degrees or, alternatively, as radians.

Returns:

shear(shear, *components, space=None, corner=False) -> AcquisitionGeometry

Shear (skew) the acquisition geometry.

Parameters:

  • shear (Tensor) –

    Shear factors of shape (3, 2).

  • *components (float, default: () ) –

    Additional components of shear, allowing the six flattened factors to be passed as separate positional arguments.

  • space (Space, default: None ) –

    The space in which to apply the shear. Can be provided as the last positional argument.

  • corner (bool, default: False ) –

    Whether to shear around the image corner or center. Only applicable when the space is 'voxel'. Defaults to False.

Returns:

reorient(target) -> AcquisitionGeometry

Reorient the acquisition geometry to a new anatomical voxel orientation.

Parameters:

  • target (Orientation) –

    Target orientation to reorient to.

Returns:

resample(spacing=None, *components, in_plane_spacing=None, slice_spacing=None) -> AcquisitionGeometry

Resample to a new voxel grid spacing.

Parameters:

  • spacing (float | Tensor, default: None ) –

    Target voxel spacing. An isotropic target is assumed if a scalar is provided.

  • *components (float, default: () ) –

    Additional components of spacing, allowing values to be passed as separate positional arguments, e.g. resample(1, 1, 2).

  • in_plane_spacing (float | Tensor, default: None ) –

    Target in-plane voxel spacing. Mutually exclusive with the spacing argument.

  • slice_spacing (float | Tensor, default: None ) –

    Target slice spacing. Mutually exclusive with the spacing argument.

Returns:

pool(scale=2, *components, space=None, spacing_ratio_thresh=None) -> AcquisitionGeometry

Pool the geometry with a sliding window.

By default, this will pool over all dimensions, but it can be conditionally disabled for the slice dimension based on the ratio of slice vs in-plane spacing, i.e. the value of geometry.spacing_ratio. For example, if the slice spacing is spacing_ratio_thresh times greater than the in-plane spacing, the slice dimension will not be pooled. Mind that if the resulting pooled volume has a slice spacing less than the in-plane spacing, it will be resampled to an isotropic resolution.

There is no analogous unpool method because there is complexity in determining the desired unpooling strategy. To return to the original geometry, instead use the resample_like method. If no reference geometry is available, just use the reshape method to upsample.

Note that this implementation must mirror the pooling operation used by the volume class. Any changes to the pooling operation in one class must be reflected in the other.

Parameters:

  • scale (int, default: 2 ) –

    The size of the pooling window. Defaults to 2.

  • *components (int, default: () ) –

    Additional components of scale, allowing values to be passed as separate positional arguments, e.g. pool(2, 2, 1).

  • space (Space, default: None ) –

    Space of the scale value. Can be provided as the last positional argument. Defaults to 'voxel'.

  • spacing_ratio_thresh (float, default: None ) –

    Slice spacing ratio that determines whether the slice dimension is pooled. This is disabled by default.

Returns:

reshape(baseshape, *components, from_origin=False) -> AcquisitionGeometry

Modify the spatial extent of the volume geometry, cropping or padding around the center image to fit a given baseshape.

This method is symmetric in that performing a reverse reshape operation will always yield the original geometry.

Parameters:

  • baseshape (int | Size) –

    Target spatial (3D) shape. An isotropic shape is assumed if a scalar is provided.

  • *components (int, default: () ) –

    Additional components of baseshape, allowing values to be passed as separate positional arguments, e.g. reshape(64, 64, 64).

  • from_origin (bool, default: False ) –

    If True, padding or cropping will be done at the ends of the image shape and not centered.

Returns:

pad(margin, *components, space=None) -> AcquisitionGeometry

Pad the spatial extent of the volume geometry by a given margin. Note that a negative margin value will result in trimming (cropping).

Parameters:

  • margin (float or Tensor) –

    Delta of specified units to pad (or crop) the volume by in each direction. Can be of size \((1,)\), \((3,)\), or \((3, 2)\).

  • *components (float, default: () ) –

    Additional components of margin, allowing values to be passed as separate positional arguments, e.g. pad(1, 2, 3, 'voxel').

  • space (Space, default: None ) –

    The space of the margin, either 'voxel' or 'world'. Can be provided as the last positional argument.

Returns:

trim(margin, *components, space=None) -> AcquisitionGeometry

Trim the spatial extent of the volume geometry by a given margin. This is equivalent to padding with negative margin values.

Parameters:

  • margin (float or Tensor) –

    Delta of specified units to trim the volume by in each direction. Can be of size \((1,)\), \((3,)\), or \((3, 2)\).

  • *components (float, default: () ) –

    Additional components of margin, allowing values to be passed as separate positional arguments, e.g. trim(1, 2, 3, 'voxel').

  • space (Space, default: None ) –

    The space of the margin, either 'voxel' or 'world'. Can be provided as the last positional argument.

Returns:

bounds(margin=None, *components, space=None) -> vx.BoundingBox

Compute a world-space bounding box enclosing the grid. The box covers the full extent of the voxels, i.e. it is padded 0.5 voxels beyond the outermost voxel centers on every side.

Parameters:

  • margin (float or Tensor, default: None ) –

    Margin to expand the bounds. Can be a positive or negative delta.

  • *components (float, default: () ) –

    Additional components of margin, allowing values to be passed as separate positional arguments, e.g. bounds(1, 2, 3).

  • space (Space, default: None ) –

    Space of the margin values, either 'voxel' or 'world'. Can be provided as the last positional argument. Defaults to 'world'.

Returns:

  • BoundingBox –

    Bounding box in world-space coordinates.

crop(bounds, margin=None, space='world') -> AcquisitionGeometry

Crop the geometry grid to the voxel centers contained in a world-space bounding box, clamped to the current grid extent. Use fit_to_bounds to instead refit the grid without clamping.

Parameters:

  • bounds (BoundingBox) –

    Bounding box to crop to.

  • margin (float or Tensor, default: None ) –

    Margin to expand the cropping boundary. Can be a positive or negative delta. The boundary will be clipped if it extends beyond the shape of the grid.

  • space (Space, default: 'world' ) –

    Space of the margin values, either 'voxel' or 'world'.

Returns:

fit_to_bounds(bounds, margin=None, space='world') -> AcquisitionGeometry

Reposition and reshape the geometry grid to capture the voxel centers contained in a world-space bounding box. Unlike crop, the grid is not clamped to the current extent and may grow beyond it.

Parameters:

  • bounds (BoundingBox) –

    Bounding box to fit to.

  • margin (float or Tensor, default: None ) –

    Margin to expand the bounding box around the bounds. Can be a positive or negative delta.

  • space (Space, default: 'world' ) –

    Space of the margin values, either 'voxel' or 'world'.

Returns:

zeros_like(channels=1, dtype=None) -> vx.Volume

Create a volume of zeros.

Parameters:

  • channels (int, default: 1 ) –

    Number of channels for the new volume.

  • dtype (dtype, default: None ) –

    Target data type.

Returns:

  • Volume –

    A new volume instance filled with zeros.

ones_like(channels=1, dtype=None) -> vx.Volume

Create a volume of ones.

Parameters:

  • channels (int, default: 1 ) –

    Number of channels for the new volume.

  • dtype (dtype, default: None ) –

    Target data type.

Returns:

  • Volume –

    A new volume instance filled with ones.

full_like(fill, channels=1, dtype=None) -> vx.Volume

Create a volume filled with a specific value.

Parameters:

  • fill (float) –

    The fill value.

  • channels (int, default: 1 ) –

    Number of channels for the new volume.

  • dtype (dtype, default: None ) –

    Target data type.

Returns:

  • Volume –

    A new filled volume instance.

rand_like(channels=1, dtype=None) -> vx.Volume

Create a volume of random values. Values are sampled from a uniform distribution on the interval [0, 1).

Parameters:

  • channels (int, default: 1 ) –

    Number of channels for the new volume.

  • dtype (dtype, default: None ) –

    Target data type.

Returns:

  • Volume –

    A new random volume instance.

randn_like(channels=1, dtype=None) -> vx.Volume

Create a volume of random values. Values are sampled from a normal distribution with mean 0 and variance 1.

Parameters:

  • channels (int, default: 1 ) –

    Number of channels for the new volume.

  • dtype (dtype, default: None ) –

    Target data type.

Returns:

  • Volume –

    A new random volume instance.