mne.coreg.Coregistration

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

Class for MRI<->head coregistration.

Parameters
infoinstance of Info | None

The measurement info.

subjectstr

The FreeSurfer subject name.

subjects_dirstr | pathlib.Path | None

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

fiducialslistdict | str

The fiducials given in the MRI (surface RAS) coordinate system. If a dict is provided it must be a dict with 3 entries with keys ‘lpa’, ‘rpa’ and ‘nasion’ with as values coordinates in m. If a list it must be a list of DigPoint instances as returned by the read_fiducials function. If set to ‘estimated’, the fiducials are initialized automatically using fiducials defined in MNI space on fsaverage template. If set to ‘auto’, one tries to find the fiducials in a file with the canonical name (bem/{subject}-fiducials.fif) and if abstent one falls back to ‘estimated’. Defaults to ‘auto’.

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.

Attributes
transinstance of Transform

Return the head-mri transform.

Methods

__hash__(/)

Return hash(self).

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.

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.

Examples using compute_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.

Examples using fit_fiducials:

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.

Examples using fit_icp:

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.

Examples using omit_head_shape_points:

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:

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

Return the head-mri transform.

Examples using mne.coreg.Coregistration