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.

BIDS’ X5

Data structures for the X5 transform format.

Implements what’s drafted in the BIDS X5 specification draft.

class nitransforms.io.x5.X5Domain(grid: bool, size: Sequence[int], mapping: ndarray | None, coordinates: str | None = None)

Domain information of a transform representing reference/moving spaces.

coordinates: str | None = None

Indexing type of the Mapping field (for example, “cartesian”, “spherical” or “index”).

grid: bool

Whether sampling locations in the manifold are located regularly.

mapping: ndarray | None

A mapping to go from samples (pixel/voxel coordinates, indices) to space coordinates.

size: Sequence[int]

The number of sampling locations per dimension (or total if not a grid).

class nitransforms.io.x5.X5Transform(type: str, transform: ndarray, subtype: str | None = None, representation: str | None = None, metadata: Dict[str, Any] | None = None, dimension_kinds: Sequence[str] | None = None, domain: X5Domain | None = None, inverse: ndarray | None = None, jacobian: ndarray | None = None, additional_parameters: ndarray | None = None, array_length: int = 1)

Represent one transform entry of an X5 file.

additional_parameters: ndarray | None = None

An OPTIONAL field to store additional parameters, depending on the SubType of the transform.

array_length: int = 1

Undocumented field in the draft to enable a single transform group for 4D transforms.

dimension_kinds: Sequence[str] | None = None

Identifies what “kind” of information is represented by the samples along each axis.

domain: X5Domain | None = None

A dataset specifying the reference manifold for the transform (either a regularly gridded 3D space or a surface/sphere). REQUIRED for nonlinear Type, RECOMMENDED for linear Type.

inverse: ndarray | None = None

Placeholder to pre-calculated inverses.

jacobian: ndarray | None = None

A RECOMMENDED data array to keep cached the determinant of Jacobian of the transform in case tools have calculated it. For parametric models it is generally possible to obtain it analytically, so this dataset could not be as useful in that case.

metadata: Dict[str, Any] | None = None

An OPTIONAL string (JSON) to embed metadata.

representation: str | None = None

A string specifiying the transform representation or model, REQUIRED only for nonlinear Type.

subtype: str | None = None

An OPTIONAL extension of type to drive the interpretation of AdditionalParameters.

transform: ndarray

A REQUIRED array of parameters (e.g., affine matrix, or dense displacements field).

type: str

“linear”, “nonlinear”, “composite”.

Type:

A REQUIRED unicode string with possible values

nitransforms.io.x5.from_filename(fname: str | Path) → List[X5Transform]

Read a list of X5Transform objects from an X5 HDF5 file.

nitransforms.io.x5.to_filename(fname: str | Path, x5_list: List[X5Transform])

Write a list of X5Transform objects to an X5 HDF5 file.

Parameters:

• fname (os.PathLike) – The file name (preferably with the “.x5” extension) in which transforms will be stored.

• x5_list (list) – The list of transforms to be stored in the output dataset.

Returns:

fname – File containing the transform(s).

Return type:

os.PathLike

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.

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.