regtricks.transforms package

Submodules

regtricks.transforms.linear module

class regtricks.transforms.linear.MotionCorrection(mats)

Bases: regtricks.transforms.linear.Registration

A sequence of Registration objects, one for each volume in a timeseries.

Parameters:mats – a path to a directory containing transformation matrices, in name order (all files will be loaded), or a list of individual filenames, or a list of np.arrays
from_flirt(*args)

Load an affine (4x4) transformation between two images directly from FLIRT’s -omat output.

Parameters:
  • src2ref (Pathlike, np.ndarray) – path to text-like file to load or np.ndarray
  • src – the source of the transform
  • ref – the reference (or target) of the transform
Returns:

Registration object
classmethod from_mcflirt(mats, src, ref)

Load a MotionCorrection object directly from MCFLIRT’s -omat directory. Note that for within-timeseries registration, the src and ref arguments should take the same value.

Parameters:
  • mats – a path to a directory containing transformation matrices, in name order (all files will be loaded), or a list of individual filenames, or a list of np.arrays
  • src – source of the transforms (ie, the image being corrected)
  • ref – the target of the transforms (normally same as src)
Returns:

MotionCorrection
classmethod from_registration(reg, length)

Produce a MotionCorrection by repeating a Registration object n times (eg, 10 copies of a single transform)

classmethod identity(length)
ref2src

List of ref to src transformation matrices

resolve(src, ref, at_idx)

Return a coordinate array and scale factor that maps reference voxels into source voxels, including the transform. Uses cached values, if available.

Parameters:
  • src (ImageSpace) – in which data currently exists and interpolation will be performed
  • ref (ImageSpace) – in which data needs to be expressed
  • at_idx (int) – index number within series of transforms to apply
Returns:

(np.ndarray, 1) coordinates on which to interpolate and identity

scale factor
save_fsl(outdir, src, ref, prefix='MAT_')

Save in FSL convention as textfiles at path

save_txt(outdir, prefix='MAT_')

Save individual transformation matrices in text format in outdir. Matrices will be named prefix_001…

Parameters:
  • outdir – directory in which to save
  • src – (optional) path to image, or ImageSpace, source space of transformation
  • ref – as above, for reference space of transformation
  • convention – “world” or “fsl”, if fsl then src/ref must be given
  • prefix – prefix for naming each matrix
src2ref

List of src to ref transformation matrices

to_fsl(src, ref)

Transformation matrices in FSL terms

transforms

List of Registration objects representing each volume of transform

class regtricks.transforms.linear.Registration(src2ref)

Bases: regtricks.transforms.transform.Transform

Affine (4x4) transformation between two images.

Parameters:src2ref (Pathlike, np.ndarray) – path to text-like file to load or np.ndarray
classmethod from_flirt(src2ref, src, ref)

Load an affine (4x4) transformation between two images directly from FLIRT’s -omat output.

Parameters:
  • src2ref (Pathlike, np.ndarray) – path to text-like file to load or np.ndarray
  • src – the source of the transform
  • ref – the reference (or target) of the transform
Returns:

Registration object
classmethod identity()
inverse()

Self inverse

prepare_cache(ref)

Cache re-useable data before interpolate_and_scale. Just the voxel index grid of the reference space is stored

ref2src
resolve(src, ref, *unused)

Return a coordinate array and scale factor that maps reference voxels into source voxels, including the transform. Uses cached values, if available.

Parameters:
  • src (ImageSpace) – in which data currently exists and interpolation will be performed
  • ref (ImageSpace) – in which data needs to be expressed
Returns:

(np.ndarray, 1) coordinates on which to interpolate and identity

scale factor
save_fsl(path, src, ref)

Save in FSL convention as textfile at path

save_txt(path)

Save as textfile at path

src2ref
to_flirt(src, ref)

Alias for self.to_fsl()

to_fsl(src, ref)

Return transformation in FSL convention, for given src and ref, as np.array. This will be 3D in the case of MotionCorrections

regtricks.transforms.nonlinear module

class regtricks.transforms.nonlinear.NonLinearMotionCorrection(warp, premat, postmat, intensity_correct=0, constrain_jac=False)

Bases: regtricks.transforms.nonlinear.NonLinearRegistration

Only to be created by multiplication of other classes. Don’t go here!

Parameters:
  • warp – FNIRTCoefficients object or NonLinearProduct
  • src – src of transform
  • ref – ref of transform
  • premat – list of Registration objects
  • postmat – list of Registration objects
  • intensity_correct – int (0/1/2/3), whether to apply intensity correction, and at what stage in the case of NLPs
  • constrain_jac (bool/array-like) – constrain Jacobian for intensity correction (default False). If True, limits of (0.01, 100) will be used, or explicit limits can be given as (min, max)
resolve(src, ref, at_idx)

Return a coordinate array and scale factor that maps reference voxels into source voxels, including the transform. Uses cached values, if available. A scale factor of 1 will be returned if no intensity correction was requested.

Parameters:
  • src (ImageSpace) – in which data currently exists and interpolation will be performed
  • ref (ImageSpace) – in which data needs to be expressed
  • at_idx (int) – index number within MC series of transforms to apply
Returns:

(np.ndarray, np.ndarray/int) coordinates on which to interpolate,

scaling factor to apply after interpolation
class regtricks.transforms.nonlinear.NonLinearRegistration

Bases: regtricks.transforms.transform.Transform

Non linear registration transformation. Currently only FSL FNIRT warps are supported. Note that the –premat and –postmat used by FSL command line tools should not be supplied here. Instead, defined them as Registration objects and use chain() to concatenate them with NLRs.

classmethod from_fnirt(coefficients, src, ref, intensity_correct=False, constrain_jac=False)

FNIRT non-linear registration from a coefficients file. If a pre-warp and post-warp transformation need to be applied, create these as separate Registration objects and combine them via chain, ie, combined = chain(pre, non-linear, post)

Parameters:
  • coefficients (Pathlike) – FNIRT coefficient field
  • src (Pathlike, ImageSpace) – source image used for generating FNIRT coefficients
  • ref (Pathlike, ImageSpace) – reference image used for generating FNIRT coefficients
  • intensity_correct – intensity correct output via the Jacobian determinant of this warp (when self.apply_to*() is called)
  • constrain_jac (bool/array-like) – constrain Jacobian for intensity correction (default False). If True, limits of (0.01, 100) will be used, or explicit limits can be given as (min, max)
Returns:

NonLinearRegistration object
intensity_correct
inverse()

Iverse warpfield, via FSL invwarp

postmat_to_fsl(src, ref)

Return list of postmats in FSL convention

premat_to_fsl(src, ref)

Return list of premats in FSL convention

prepare_cache(ref)

Pre-compute and store the displacement field, including any postmats. This is because premats can be applied after calculating the field, but postmats must be included as part of that calculation. Note that get_cache_value() return None, signifying that the field could not be cached (which implies a NLMC)

Parameters:ref (ImageSapce) – the space in towards which the transform will be applied
resolve(src, ref, *unused)

Return a coordinate array and scale factor that maps reference voxels into source voxels, including the transform. Uses cached values, if available. A scale factor of 1 will be returned if no intensity correction was requested.

Parameters:
  • src (ImageSpace) – in which data currently exists and interpolation will be performed
  • ref (ImageSpace) – in which data needs to be expressed
Returns:

(np.ndarray, np.ndarray/int) coordinates on which to interpolate,

scaling factor to apply after interpolation

regtricks.transforms.transform module

class regtricks.transforms.transform.Transform

Bases: object

Base object for all transformations. This should never actually be instantiated but is instead used to provide common functions.

_cache

use for storing resolved displacement fields and sharing amongst workers in multiprocessing pool

islinear

Registrations or MotionCorrections

isnonlinear

NonLinearRegistrations or NLMCs

apply_to_array(data, src, ref, order=3, superfactor=True, mask=True, cval=0.0, cores=2, **kwargs)

Applies transformation to data array. If a registration is applied to 4D data, the same transformation will be applied to all volumes in the series.

Parameters:
  • data (array) – 3D or 4D array.
  • src (Pathlike/NII/MGZ/FSLImage/ImageSpace) – current space of data
  • ref (Pathlike/NII/MGZ/FSLImage/ImageSpace) – target space for data
  • order (int) – 0 for NN, 1 for linear, 2-5 for splines.
  • superfactor (bool/int/iterable) – default True for any order > 0, (chosen automatically); intermediate super-sampling (replicates applywarp -super), enabled by default when resampling from high to low resolution. Set as False to disable, or set an int/iterable to manually specify level for each image dimension.
  • mask (bool) – for order > 1, mask output to remove negligible values due to spline artefact
  • cval (float) – fill value for background, used for correcting spline artefact
  • cores (int) – CPU cores to use for 4D data
  • **kwargs – passed on to scipy.ndimage.map_coordinates
Returns:

(np.array) transformed image data in ref voxel grid.
apply_to_image(src, ref, order=3, superfactor=True, mask=True, cval=0.0, cores=2, **kwargs)

Applies transformation to data array. If a registration is applied to 4D data, the same transformation will be applied to all volumes in the series.

Parameters:
  • src (Pathlike/NII/MGZ/FSLImage) – image to transform
  • ref (Pathlike/NII/MGZ/FSLImage/ImageSpace) – target space for data
  • order (int) – 0 for NN, 1 for linear, 2-5 for splines.
  • superfactor (bool/int/iterable) – default True for any order > 0, (chosen automatically); intermediate super-sampling (replicates applywarp -super), enabled by default when resampling from high to low resolution. Set as False to disable, or set an int/iterable to manually specify level for each image dimension.
  • mask (bool) – for order > 1, mask output to remove negligible values due to spline artefact
  • cval (float) – fill value for background, used for correcting spline artefact
  • cores (int) – CPU cores to use for 4D data
  • **kwargs – passed on to scipy.ndimage.map_coordinates
Returns:

(np.array) transformed image data in ref voxel grid.
cache
is_linear
is_nonlinear
reset_cache()
save(path)

Save transformation at path in X5 format (experimental)

Module contents