IO

Reading and writing of transform files.

Base I/O

Read/write linear transforms.

class nitransforms.io.base.BaseLinearTransformList(xforms=None, binaryblock=None, endianness=None, check=True)

A string-based structure for series of linear transforms.

property xforms

Get the list of internal transforms.

class nitransforms.io.base.DisplacementsField

A data structure representing displacements fields.

classmethod from_filename(filename)

Import a displacements field from a NIfTI file.

classmethod from_image(imgobj)

Import a displacements field from a nibabel image object.

classmethod to_filename(img, filename)

Export a displacements field to a NIfTI file.

classmethod to_image(imgobj)

Export a displacements field image from a nitransforms image object.

class nitransforms.io.base.LinearParameters(parameters=None)

A string-based structure for linear transforms.

Examples

>>> lp = LinearParameters()
>>> np.array_equal(lp.structarr['parameters'], np.eye(4))
True

>>> p = np.diag([2., 2., 2., 1.])
>>> lp = LinearParameters(p)
>>> np.array_equal(lp.structarr['parameters'], p)
True

class nitransforms.io.base.LinearTransformStruct(binaryblock=None, endianness=None, check=True)

File data structure from linear transforms.

classmethod from_filename(filename)

Read the struct from a file given its path.

classmethod from_fileobj(fileobj, check=True)

Read the struct from a file object.

classmethod from_ras(ras, moving=None, reference=None)

Create an affine from a nitransform’s RAS+ matrix.

to_filename(filename)

Store this transform to a file with the appropriate format.

to_ras(moving=None, reference=None)

Return a nitransforms internal RAS+ matrix.

class nitransforms.io.base.StringBasedStruct(binaryblock=None, endianness=None, check=True)

File data structure from text files.

classmethod from_string(string)

Read the struct from string.

to_string()

Convert to a string directly writeable to file.

exception nitransforms.io.base.TransformFileError

Specific I/O exception when a file does not meet the expected format.

exception nitransforms.io.base.TransformIOError

General I/O exception while reading/writing transforms.

Tool Specific I/O

AFNI

Read/write AFNI’s transforms.

class nitransforms.io.afni.AFNIDisplacementsField

A data structure representing displacements fields.

classmethod from_image(imgobj)

Import a displacements field from a NIfTI file.

classmethod to_image(imgobj)

Export a displacements field from a nibabel object.

class nitransforms.io.afni.AFNILinearTransform(parameters=None)

A string-based structure for AFNI linear transforms.

classmethod from_ras(ras, moving=None, reference=None)

Create an AFNI affine from a nitransform’s RAS+ matrix.

AFNI implicitly de-obliques image affine matrices before applying transforms, so for consistency we update the transform to account for the obliquity of the images.

>>> moving.affine == ras @ reference.affine

We can decompose the affines into oblique and de-obliqued components:

>>> moving.affine == m_obl @ m_deobl
>>> reference.affine == r_obl @ r_deobl

To generate an equivalent AFNI transform, we need an effective transform (e_ras):

>>> m_obl @ m_deobl == ras @ r_obl @ r_deobl
>>> m_deobl == inv(m_obl) @ ras @ r_obl @ r_deobl

Hence,

>>> m_deobl == e_ras @ r_deobl
>>> e_ras == inv(m_obl) @ ras @ r_obl

classmethod from_string(string)

Read the struct from string.

to_ras(moving=None, reference=None)

Return a nitransforms internal RAS+ matrix.

to_string(banner=True)

Convert to a string directly writeable to file.

class nitransforms.io.afni.AFNILinearTransformArray(xforms=None, binaryblock=None, endianness=None, check=True)

A string-based structure for series of AFNI linear transforms.

classmethod from_ras(ras, moving=None, reference=None)

Create an ITK affine from a nitransform’s RAS+ matrix.

classmethod from_string(string)

Read the struct from string.

to_ras(moving=None, reference=None)

Return a nitransforms’ internal RAS matrix.

to_string()

Convert to a string directly writeable to file.

FSL

Read/write FSL’s transforms.

class nitransforms.io.fsl.FSLDisplacementsField

A data structure representing displacements fields.

classmethod from_image(imgobj)

Import a displacements field from a NIfTI file.

classmethod to_image(imgobj)

Export a displacements field from a nibabel object.

class nitransforms.io.fsl.FSLLinearTransform(parameters=None)

A string-based structure for FSL linear transforms.

classmethod from_ras(ras, moving=None, reference=None)

Create an FSL affine from a nitransform’s RAS+ matrix.

classmethod from_string(string)

Read the struct from string.

to_ras(moving=None, reference=None)

Return a nitransforms internal RAS+ matrix.

to_string()

Convert to a string directly writeable to file.

class nitransforms.io.fsl.FSLLinearTransformArray(xforms=None, binaryblock=None, endianness=None, check=True)

A string-based structure for series of FSL linear transforms.

classmethod from_filename(filename)

Read the struct from a file given its path.

If the file does not exist, then indexed names with the zero-padded suffix .NNN are attempted, following FSL’s MCFLIRT conventions.

classmethod from_fileobj(fileobj, check=True)

Read the struct from a file object.

classmethod from_ras(ras, moving=None, reference=None)

Create an ITK affine from a nitransform’s RAS+ matrix.

classmethod from_string(string)

Read the struct from string.

to_filename(filename)

Store this transform to a file with the appropriate format.

to_ras(moving=None, reference=None)

Return a nitransforms’ internal RAS matrix.

to_string()

Convert to a string directly writeable to file.

ITK

Read/write ITK transforms.

class nitransforms.io.itk.ITKCompositeH5

A data structure for ITK’s HDF5 files.

classmethod from_filename(filename, only_linear=False)

Read the struct from a file given its path.

classmethod from_h5obj(fileobj, check=True, only_linear=False)

Read the struct from a file object.

class nitransforms.io.itk.ITKDisplacementsField

A data structure representing displacements fields.

classmethod from_image(imgobj)

Import a displacements field from a NIfTI file.

classmethod to_image(imgobj)

Export a displacements field from a nibabel object.

class nitransforms.io.itk.ITKLinearTransform(parameters=None, offset=None)

A string-based structure for ITK linear transforms.

classmethod from_binary(byte_stream, index=0)

Read the struct from a matlab binary file.

classmethod from_filename(filename)

Read the struct from a file given its path.

classmethod from_fileobj(fileobj, check=True)

Read the struct from a file object.

classmethod from_h5obj(fileobj, check=True)

Read the struct from a file object.

classmethod from_matlab_dict(mdict, index=0)

Read the struct from a matlab dictionary.

classmethod from_ras(ras, index=0, moving=None, reference=None)

Create an ITK affine from a nitransform’s RAS+ matrix.

classmethod from_string(string)

Read the struct from string.

to_filename(filename)

Store this transform to a file with the appropriate format.

to_ras(moving=None, reference=None)

Return a nitransforms internal RAS+ matrix.

to_string(banner=None)

Convert to a string directly writeable to file.

class nitransforms.io.itk.ITKLinearTransformArray(xforms=None, binaryblock=None, endianness=None, check=True)

A string-based structure for series of ITK linear transforms.

classmethod from_binary(byte_stream)

Read the struct from a matlab binary file.

classmethod from_filename(filename)

Read the struct from a file given its path.

classmethod from_fileobj(fileobj, check=True)

Read the struct from a file object.

classmethod from_h5obj(fileobj, check=True)

Read the struct from a file object.

classmethod from_ras(ras, moving=None, reference=None)

Create an ITK affine from a nitransform’s RAS+ matrix.

The moving and reference parameters are included in this method’s signature for a consistent API, but they have no effect on this particular method because ITK already uses RAS+ coordinates to describe transfroms internally.

classmethod from_string(string)

Read the struct from string.

to_filename(filename)

Store this transform to a file with the appropriate format.

to_ras(moving=None, reference=None)

Return a nitransforms’ internal RAS matrix.

to_string()

Convert to a string directly writeable to file.

property xforms

Get the list of internal ITKLinearTransforms.

FreeSurfer/LTA

Read/write linear transforms.

class nitransforms.io.lta.FSLinearTransform(binaryblock=None, endianness=None, check=True)

Represents a single LTA’s transform structure.

classmethod from_ras(ras, moving=None, reference=None)

Create an affine from a nitransform’s RAS+ matrix.

classmethod from_string(string, partial=False)

Read a transform from text.

set_type(new_type)

Convert the internal transformation matrix to a different type inplace.

Parameters:

new_type (str, int) – Tranformation type

to_ras(moving=None, reference=None)

Return a nitransforms’ internal RAS+ array.

Seemingly, the matrix of an LTA is defined such that it maps coordinates from the dest volume to the src volume. Therefore, without inversion, the LTA matrix is appropiate to move the information from src volume into the dest volume’s grid.

Important

The moving and reference parameters are dismissed because VOX2VOX LTAs are converted to RAS2RAS type before returning the RAS+ matrix, using the dest and src contained in the LTA. Both arguments are kept for API compatibility.

Parameters:

• moving (dismissed) – The spatial reference of moving images.

• reference (dismissed) – The spatial reference of moving images.

Returns:

matrix – The RAS+ affine matrix corresponding to the LTA.

Return type:

numpy.ndarray

to_string(partial=False)

Convert this transform to text.

class nitransforms.io.lta.FSLinearTransformArray(xforms=None, binaryblock=None, endianness=None, check=True)

A list of linear transforms generated by FreeSurfer.

classmethod from_ras(ras, moving=None, reference=None)

Create an affine from a nitransform’s RAS+ matrix.

classmethod from_string(string)

Read this LTA from a text string.

to_ras(moving=None, reference=None)

Set type to RAS2RAS and return the new matrix.

to_string()

Convert this LTA into text format.

class nitransforms.io.lta.VolumeGeometry(binaryblock=None, endianness=None, check=True)

Data structure for regularly gridded images.

as_affine()

Return the internal affine of this regular grid.

classmethod from_image(img)

Create struct from an image.

classmethod from_string(string)

Create a volume structure off of text.

to_string()

Format the structure as a text file.