mne.transforms.compute_volume_registration(moving, static, pipeline='all', zooms=None, niter=None, *, starting_affine=None, verbose=None)[source]#

Align two volumes using an affine and, optionally, SDR.

movinginstance of SpatialImage

The image to morph (“from” volume).

staticinstance of SpatialImage

The image to align with (“to” volume).

pipelinestr | tuple

The volume registration steps to perform (a str for a single step, or tuple for a set of sequential steps). The following steps can be performed, and do so by matching mutual information between the images (unless otherwise noted):




Rigid-body, i.e., rotation and translation.


A full affine transformation, which includes translation, rotation, scaling, and shear.


Symmetric diffeomorphic registration [1], a non-linear similarity-matching algorithm.

The following string shortcuts can also be used:

'all' (default)

All steps will be performed above in the order above, i.e., ('translation', 'rigid', 'affine', 'sdr').


The rigid steps (first two) will be performed, which registers the volume without distorting its underlying structure, i.e., ('translation', 'rigid'). This is useful for example when registering images from the same subject, such as CT and MR images.


The affine steps (first three) will be performed, i.e., omitting the SDR step.

zoomsfloat | tuple | dict | None

The voxel size of volume for each spatial dimension in mm. If None (default), MRIs won’t be resliced (slow, but most accurate). Can be a tuple to provide separate zooms for each dimension (X/Y/Z), or a dict with keys ['translation', 'rigid', 'affine', 'sdr'] (each with values that are float`, tuple, or None) to provide separate reslicing/accuracy for the steps.

niterdict | tuple | None

For each phase of the volume registration, niter is the number of iterations per successive stage of optimization. If a tuple is provided, it will be used for all steps (except center of mass, which does not iterate). It should have length 3 to correspond to sigmas=[3.0, 1.0, 0.0] and factors=[4, 2, 1] in the pipeline (see dipy.align.affine_registration for details). If a dictionary is provided, number of iterations can be set for each step as a key. Steps not in the dictionary will use the default value. The default (None) is equivalent to:

niter=dict(translation=(100, 100, 10),

rigid=(100, 100, 10), affine=(100, 100, 10), sdr=(5, 5, 3))


The affine to initialize the registration with.

New in v1.2.

verbosebool | str | int | None

Control verbosity of the logging output. If None, use the default verbosity level. See the logging documentation and mne.verbose() for details. Should only be passed as a keyword argument.

reg_affinendarray of float, shape (4, 4)

The affine that registers one volume to another.

sdr_morphinstance of dipy.align.DiffeomorphicMap

The class that applies the the symmetric diffeomorphic registration (SDR) morph.


This function is heavily inspired by and extends dipy.align.affine_registration.

New in v0.24.