ants.utils.nifti_utils

Functions

deshear_affine_transform_matrix(A[, ...])

Deshear an affine transform by removing shear components.

deshear_nifti_sform(metadata[, ...])

Deshear an sform matrix in the provided metadata dict.

get_nifti_qform_spatial_info(metadata)

Extract qform-derived spacing, origin, direction.

get_nifti_sform_shear(metadata)

Get the shear parameters from the sform matrix in metadata dictionary.

get_nifti_sform_spatial_info(metadata[, ...])

Extract sform-derived spacing, origin, direction.

get_nifti_spatial_transform_from_metadata(...)

Return a dict containing origin/spacing/direction in ITK (LPS) coordinates, derived from NIfTI header metadata.

set_nifti_spatial_transform_from_metadata(...)

Set the spatial transform of an ANTsImage from NIfTI header metadata.
get_nifti_qform_spatial_info(metadata)[source]

Extract qform-derived spacing, origin, direction. Uses the 4x4 ‘qto_xyz’ from the metadata dict. This is the rotation matrix derived from quaternion parameters in the NIfTI header, multiplied by the pixdim scales and with the qoffset translation.

Note: output is in ITK LPS coordinates

Returns:

pixdim_spacing = [sx, sy, sz] (from pixdim[1..3]) transform_spacing : [sx, sy, sz] origin : [ox, oy, oz] direction : 3x3 list (direction cosines)

Return type:

dict with keys

Example

>>> import ants
>>> metadata = ants.read_image_metadata( ants.get_ants_data('mni') )
>>> ants.get_nifti_qform_spatial_info(metadata)
get_nifti_sform_shear(metadata)[source]

Get the shear parameters from the sform matrix in metadata dictionary.

Return type:

[shear_xy, shear_xz, shear_yz]  (cosines between axes; 0 means orthogonal)

Example

>>> import ants
>>> metadata = ants.read_image_metadata( ants.get_ants_data('mni') )
>>> ants.get_nifti_sform_shear(metadata)
get_nifti_sform_spatial_info(metadata, deshear_threshold=1e-06, max_angle_deviation=0.5)[source]

Extract sform-derived spacing, origin, direction.

Note: output is in ITK LPS coordinates.

Parameters:

  • metadata (dict) – The NIfTI header metadata dictionary.

  • deshear_threshold (float) – Shear threshold for deshearing sform, if the shear is beneath this value, the sform is not modified.

  • max_angle_deviation (float) – Maximum angle deviation for directions after deshearing sform. If the desheared directions deviate from the original directions by more than this value (in degrees), deshearing fails and the return value is None.

Returns:

  • dict with keys – pixdim_spacing = [sx, sy, sz] (from pixdim[1..3]) transform_spacing : [sx, sy, sz] origin : [ox, oy, oz] direction : 3x3 list (direction cosines) desheared : bool original_shear : [shear_xy, shear_xz, shear_yz]

  • Returns None if no sform is present or if deshearing fails.

Example

>>> import ants
>>> metadata = ants.read_image_metadata( ants.get_ants_data('mni') )
>>> ants.get_nifti_sform_spatial_info(metadata)
get_nifti_spatial_transform_from_metadata(metadata, prefer_sform=True, deshear_threshold=1e-06, max_angle_deviation=0.5, verbose=False)[source]

Return a dict containing origin/spacing/direction in ITK (LPS) coordinates, derived from NIfTI header metadata.

This function only returns the 3D spatial transform information, including spacing for the first three dimensions. It does not modify time spacing or direction for 4D images.

Note that the spacing is always taken from the pixdim fields in the NIfTI header, as is standard in ITK. The transforms are checked for consistency with the pixdim spacing, if they are not the same, it indicates that the transform is something other than a reorientation to the native physical space.

If prefer_sform is True (default), the sform transform is used if it is present (sform_code > 0) and either has shear beneath the threshold, or the shear can be removed without exceeding the max_axis_deviation.

If prefer_sform is False, qform is used if it is present (qform_code > 0), otherwise sform is used if present and usable.

Parameters:

  • image (ants.ANTsImage) – The image to modify.

  • metadata (dict) – The NIfTI header metadata dictionary.

  • prefer_sform (bool) – Whether to prefer sform over qform if both are available.

  • deshear_threshold (float) – Shear threshold for deshearing sform.

  • max_angle_deviation (float) – Maximum angle deviation for deshearing sform.

  • verbose (bool) – Whether to print verbose output.

Returns:

  • { – “origin”: [ox, oy, oz], “pixdim_spacing”: [sx, sy, sz], # from the pixdims “transform_spacing”: [sx, sy, sz], # from the transform “direction”: [[…],[…],[…]], “transform_source”: “sform” | “qform”

  • }

Example

>>> import ants
>>> metadata = ants.read_image_metadata( ants.get_ants_data('mni') )
>>> ants.get_nifti_spatial_transform_from_metadata(metadata)
set_nifti_spatial_transform_from_metadata(image, metadata, prefer_sform=True, deshear_threshold=1e-06, max_angle_deviation=0.5, verbose=False)[source]

Set the spatial transform of an ANTsImage from NIfTI header metadata. This sets the 3D spatial transform but does not modify spacing or the fourth row / column of the direction matrix for 4D images. This function does not support 2D images, because the projection of a 3D spatial transform to 2D is not preserved in the ANTsImage.

The spacing is not modified but it is checked for consistency with the pixdim fields in the NIfTI header, as is standard in ITK. If the spacing does not match the pixdim, an error is raised.

Parameters:

  • image (ants.ANTsImage) – The image to modify.

  • metadata (dict) – The NIfTI header metadata dictionary.

  • prefer_sform (bool) – Whether to prefer sform over qform if both are available.

  • deshear_threshold (float) – Shear threshold for deshearing sform, shear below this will be ignored.

  • max_angle_deviation (float) – Maximum angle deviation for directions after deshearing sform. If the desheared directions deviate from the original directions by more than this value (in degrees), deshearing fails, and qform is used if available.

  • verbose (bool) – Whether to print verbose output.

Returns:

The modified image with updated spatial transform.

Return type:

ants.ANTsImage

Example

>>> import ants
>>> img = ants.image_read( ants.get_ants_data('mni') )
>>> metadata = ants.read_image_metadata( ants.get_ants_data('mni') )
>>> ants.set_nifti_spatial_transform_from_metadata(img, metadata)