mne.coreg.Coregistration#

class mne.coreg.Coregistration(info, subject, subjects_dir=None, fiducials='auto', *, on_defects='raise')[source]#

Class for MRI<->head coregistration.

Parameters:
infoinstance of Info | None

The measurement info.

subjectstr

The FreeSurfer subject name.

subjects_dirpath-like | None

The path to the directory containing the FreeSurfer subjects reconstructions. If None, defaults to the SUBJECTS_DIR environment variable.

fiducialslist | dict | str

The fiducials given in the MRI (surface RAS) coordinate system. If a dictionary is provided, it must contain the keys 'lpa', 'rpa', and 'nasion', with values being the respective coordinates in meters. If a list, it must be a list of DigPoint instances as returned by the mne.io.read_fiducials() function. If 'estimated', the fiducials are derived from the fsaverage template. If 'auto' (default), tries to find the fiducials in a file with the canonical name ({subjects_dir}/{subject}/bem/{subject}-fiducials.fif) and if absent, falls back to 'estimated'.

on_defects‘raise’ | ‘warn’ | ‘ignore’

What to do if the surface is found to have topological defects. Can be 'raise' (default) to raise an error, 'warn' to emit a warning, or 'ignore' to ignore when one or more defects are found. Note that a lot of computations in MNE-Python assume the surfaces to be topologically correct, topological defects may still make other computations (e.g., mne.make_bem_model and mne.make_bem_solution) fail irrespective of this parameter.

New in v1.0.

Attributes:
fiducialsinstance of DigMontage

A montage containing the MRI fiducials.

transinstance of Transform

The head->mri Transform.

Methods

compute_dig_mri_distances()

Compute distance between head shape points and MRI skin surface.

fit_fiducials([lpa_weight, nasion_weight, ...])

Find rotation and translation to fit all 3 fiducials.

fit_icp([n_iterations, lpa_weight, ...])

Find MRI scaling, translation, and rotation to match HSP.

omit_head_shape_points(distance)

Exclude head shape points that are far away from the MRI head.

reset()

Reset all the parameters affecting the coregistration.

set_fid_match(match)

Set the strategy for fitting anatomical landmark (fiducial) points.

set_grow_hair(value)

Compensate for hair on the digitizer head shape.

set_rotation(rot)

Set the rotation parameter.

set_scale(sca)

Set the scale parameter.

set_scale_mode(scale_mode)

Select how to fit the scale parameters.

set_translation(tra)

Set the translation parameter.

See also

mne.scale_mri

Notes

Internal computation quantities parameters are in the following units:

  • rotation are in radians

  • translation are in m

  • scale are in scale proportion

If using a scale mode, the scale_mri() should be used to create a surrogate MRI subject with the proper scale factors.

compute_dig_mri_distances()[source]#

Compute distance between head shape points and MRI skin surface.

Returns:
distarray, shape (n_points,)

The distance of the head shape points to the MRI skin surface.

See also

mne.dig_mri_distances
fit_fiducials(lpa_weight=1.0, nasion_weight=10.0, rpa_weight=1.0, verbose=None)[source]#

Find rotation and translation to fit all 3 fiducials.

Parameters:
lpa_weightfloat

Relative weight for LPA. The default value is 1.

nasion_weightfloat

Relative weight for nasion. The default value is 10.

rpa_weightfloat

Relative weight for RPA. The default value is 1.

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.

Returns:
selfCoregistration

The modified Coregistration object.

fit_icp(n_iterations=20, lpa_weight=1.0, nasion_weight=10.0, rpa_weight=1.0, hsp_weight=1.0, eeg_weight=1.0, hpi_weight=1.0, callback=None, verbose=None)[source]#

Find MRI scaling, translation, and rotation to match HSP.

Parameters:
n_iterationsint

Maximum number of iterations.

lpa_weightfloat

Relative weight for LPA. The default value is 1.

nasion_weightfloat

Relative weight for nasion. The default value is 10.

rpa_weightfloat

Relative weight for RPA. The default value is 1.

hsp_weightfloat

Relative weight for HSP. The default value is 1.

eeg_weightfloat

Relative weight for EEG. The default value is 1.

hpi_weightfloat

Relative weight for HPI. The default value is 1.

callbackcallable() | None

A function to call on each iteration. Useful for status message updates. It will be passed the keyword arguments iteration and n_iterations.

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.

Returns:
selfCoregistration

The modified Coregistration object.

omit_head_shape_points(distance)[source]#

Exclude head shape points that are far away from the MRI head.

Parameters:
distancefloat

Exclude all points that are further away from the MRI head than this distance (in m.). A value of distance <= 0 excludes nothing.

Returns:
selfCoregistration

The modified Coregistration object.

reset()[source]#

Reset all the parameters affecting the coregistration.

Returns:
selfCoregistration

The modified Coregistration object.

property scale#

Get the current scale factor.

Returns:
scalendarray, shape (3,)

The scale factors.

set_fid_match(match)[source]#

Set the strategy for fitting anatomical landmark (fiducial) points.

Parameters:
match‘nearest’ | ‘matched’

Alignment strategy; 'nearest' aligns anatomical landmarks to any point on the head surface; 'matched' aligns to the fiducial points in the MRI.

Returns:
selfCoregistration

The modified Coregistration object.

set_grow_hair(value)[source]#

Compensate for hair on the digitizer head shape.

Parameters:
valuefloat

Move the back of the MRI head outwards by value (mm).

Returns:
selfCoregistration

The modified Coregistration object.

set_rotation(rot)[source]#

Set the rotation parameter.

Parameters:
rotarray, shape (3,)

The rotation parameter (in radians).

Returns:
selfCoregistration

The modified Coregistration object.

set_scale(sca)[source]#

Set the scale parameter.

Parameters:
scaarray, shape (3,)

The scale parameter.

Returns:
selfCoregistration

The modified Coregistration object.

set_scale_mode(scale_mode)[source]#

Select how to fit the scale parameters.

Parameters:
scale_modeNone | str

The scale mode can be ‘uniform’, ‘3-axis’ or disabled. Defaults to None.

  • ‘uniform’: 1 scale factor is recovered.

  • ‘3-axis’: 3 scale factors are recovered.

  • None: do not scale the MRI.

Returns:
selfCoregistration

The modified Coregistration object.

Examples using set_scale_mode:

Using an automated approach to coregistration

Using an automated approach to coregistration
set_translation(tra)[source]#

Set the translation parameter.

Parameters:
traarray, shape (3,)

The translation parameter (in m.).

Returns:
selfCoregistration

The modified Coregistration object.

property trans#

The head->mri Transform.

Examples using mne.coreg.Coregistration#

Using an automated approach to coregistration

Using an automated approach to coregistration