unravel.image_io.reorient_nii module#

Use io_reorient_nii (reorient) from UNRAVEL to set the orientation of a .nii.gz or its affine matrix.

Input:

  • path/input_image.nii.gz

Output:

  • A .nii.gz images with the new orientation (e.g., image_PIR.nii.gz or image_PIR_applied.nii.gz)

The axis codes are:

R: Right / L: Left A: Anterior / P: Posterior S: Superior / I: Inferior

The orientation code is a 3-letter code that indicates the direction of the axes in the image.

For the RAS+ orientation (default for NIfTI):

  • The right side is at the positive direction of the x-axis

  • The anterior side is at the positive direction of the y-axis

  • The superior side is at the positive direction of the z-axis

The orientation code also indicates the orientation of the axes in the affine matrix.

Example affine for RAS+ orientation:

[[1 0 0 0] [ 0 1 0 0] [ 0 0 1 0] [ 0 0 0 1]]

  • The 1st letter is R since the 1st diagonal value is positive (the right side is at the positive direction of the x-axis)

  • The 2nd letter is A since the 2nd diagonal value is positive (the anterior side is at the positive direction of the y-axis)

  • The 3rd letter is S since the 3rd diagonal value is positive (the superior side is at the positive direction of the z-axis)

Example affine for LPS+ orientation:

[[-1 0 0 0] [ 0 -1 0 0] [ 0 0 1 0] [ 0 0 0 1]]

-For LPS, the 1st letter is L since the 1st diagonal value is negative. -The 2nd letter is P since the 2nd diagonal value is negative. -The 3rd letter is S since the 3rd diagonal value is positive.

Example affine for PIR+ orientation (default for CCFv3):

[[ 0 0 1 0] [ -1 0 0 0] [ 0 -1 0 0] [ 0 0 0 1]]

For PIR:
First letter determination:

-The 1st column has a non-zero value at the 2nd row, so the 1st letter is either A or P (2nd letter of the default ‘RAS’ orientation code). -Since the valud is negative, the 1st letter is P

Second letter determination:

-The 2nd column has a non-zero value at the 3rd row, so the 2nd letter is either S or I (3rd letter of the default ‘RAS’ orientation code). -Since the value is negative, the 2nd letter is I

Third letter determination:

-The 3rd column has a non-zero value at the 1st row, so the 3rd letter is either R or L (1st letter of the default ‘RAS’ orientation code). -Since the value is positive, the 3rd letter is R

Usage:#

io_reorient_nii -i image.nii.gz -t PIR [-o image_PIR.nii.gz] [-z] [-a] [-fc 2] [-v]

unravel.image_io.reorient_nii.parse_args()[source]#
unravel.image_io.reorient_nii.transform_nii_affine(nii, target_ort, zero_origin=False)[source]#

Transform the affine matrix of a NIfTI image to a target orientation and return the new affine matrix

Parameters:

  • nii (nibabel.nifti1.Nifti1Image) – NIfTI image

  • target_ort (str) – Target orientation axis codes (e.g., RAS)

  • zero_origin (bool) – Zero the origin of the affine matrix. Default: False

unravel.image_io.reorient_nii.reorient_nii(nii, target_ort, zero_origin=False, apply=False, form_code=None)[source]#

Reorient a NIfTI image or its affine matrix to a target orientation.

Parameters:

  • nii (nibabel.nifti1.Nifti1Image) – Input NIfTI image.

  • target_ort (str) – Target orientation axis codes (e.g., RAS).

  • zero_origin (bool) – Whether to zero the origin of the affine matrix.

  • apply (bool) – Apply the orientation change to the image data.

  • form_code (int) – Code for spatial coordinate type (e.g., 1 = scanner; 2 = aligned).

Returns:

New NIfTI image with reoriented data and affine.

Return type:

nib.Nifti1Image

unravel.image_io.reorient_nii.main()[source]#