surfa.ImageGeometry#

class surfa.ImageGeometry(shape, voxsize=None, rotation=None, center=None, shear=None, vox2world=None)#

Defines the correspondence between voxel coordinates and “world” coordinates, eg, RAS, for an image.

This correspondence can be represented by either a singular affine (voxel-to-world transform matrix) or a set of linear components (voxel scale, position, rotation, and shear). These parameters and corresponding coordinates transforms are appropriately recomputed upon any modification.

Parameters

  • shape (array_like) – Associated 2D or 3D image shape.

  • voxsize (scalar or float) – Voxel size in millimeters.

  • rotation ((3, 3) float) – Voxel-to-world rotation matrix. If provided, cannot also provide vox2world.

  • center (array_like float) – World coordinate of the image center. If provided, cannot also provide vox2world.

  • shear ((3,) float) – Image shear. If provided, cannot also provide vox2world.

  • vox2world ((4, 4) float or Affine) – Voxel-to-world transform matrix.

Attributes

center

World coordinate of image center.

orientation

Orientation string of rotation matrix.

rotation

Voxel-to-world rotation matrix.

shape

Reference image shape.

shear

Image shear.

surf2vox

Affine transform that maps surface to voxel (image) coordinates.

surf2world

Affine transform that maps surface to world coordinates.

vox2surf

Affine transform that maps voxel (image) to surface coordinates.

vox2vxm

vox2world

Affine transform that maps voxel (image) to world coordinates.

voxsize

Voxel dimensions in millimeters.

vxm2vox

world2surf

Affine transform that maps world to surface coordinates.

world2vox

Affine transform that maps world to voxel (image) coordinates.

Methods

affine(source, target)#

Retrieve an affine transform based on the source and target space.

Parameters

  • source (Space) – Source coordinate space.

  • target (Space) – Target coordinate space.

Returns

Retrieved affine.

Return type

Affine

copy()#

Create a copy of the image geometry.

reshape(shape, copy=True)#

Change the geometry image shape while preserving parameters.

Parameters

  • shape (array_like) – Target image base shape.

  • copy (bool) – Return copy if geometry already matched shape.

Returns

Reshaped image geometry.

Return type

ImageGeometry

shearless_components()#

Decompose the image-to-world affine into image geometry parameters that don’t account for shear.

Returns

Tuple containing (voxelsize, rotation matrix, world-center) parameters.

Return type

tuple

update(voxsize=None, rotation=None, center=None, shear=None, vox2world=None)#

Update specific geometry parameters. Unspecified parameters will remain the same unless recomputation is necessary.

Parameters

  • voxsize (scalar or float) – Voxel size in millimeters.

  • rotation ((3, 3) float) – Voxel-to-world rotation matrix. If provided, cannot also provide vox2world.

  • center (array_like float) – World coordinate of the image center. If provided, cannot also provide vox2world.

  • shear ((3,) float) – Image shear. If provided, cannot also provide vox2world.

  • vox2world ((4, 4) float or Affine) – Voxel-to-world transform matrix.