seek_localize.convert_coord_space¶

seek_localize.convert_coord_space(sensors: seek_localize.electrodes.Sensors, to_frame: str, subjects_dir: Optional[str] = None, verbose: bool = True)[source]¶

Convert electrode voxel coordinates between coordinate systems.

To obtain the sensors, one can use seek_localize.bids.read_dig_bids().

Parameters

sensorsSensors: An instance of the electrode sensors with the coordinates, coordinate system and coordinate units. It is assumed that the coordinates are already in voxel units, in one of the accepted coordinate frames. See Notes on coordinate frames for more details.
to_framestr: The type of coordinate unit to convert to. Must be one of ['mri', 'tkras', 'mni']. tkras is the FreeSurfer special RAS space, described in Notes. mni is the Montreal Neurological Institute space, corresponding to the fsaverage subject in FreeSurfer.
subjects_dirstr | pathlib.Path: The FreeSurfer SUBJECTS-DIR that houses the output of FreeSurfer reconstruction. A matching subject corresponding to the subject of sensors should be in there. Only required if to_coord = 'mni'.
verbosebool: Verbosity.

Returns

sensorsSensors: The electrode sensors with converted coordinates.

Notes

Nibabel processes everything in units of millimeters.

To convert from xyz (e.g. ‘mm’) to voxel and vice versa, one simply needs the IntendedFor image that contains the affine vox2ras transformation. For example, this might be a T1w image. One can use nibabel.affines.apply_affine() to then apply the corresponding transformation from vox to xyz space.

Note, if you want to go from xyz to vox, then you need the inverse of the vox2ras transformation.

If one wants to convert to tkras, which is FreeSurfer’s surface xyz space, this is the xyz space of the closest surface [1,2,3]. This corresponds to the vox2rask_tkr # noqa function in nibabel. The tkrvox2ras transformation can be obtained from FreeSurfer’s mri_info command via:

mri_info --vox2ras-tkr <img>

This will generally be the 4x4 matrix for FreeSurfer output.:

[
    [-1.0, 0.0, 0.0, 128.0],
    [0.0, 0.0, 1.0, -128.0],
    [0.0, -1.0, 0.0, 128.0],
    [0.0, 0.0, 0.0, 1.0],
]

but may be different depending on how some FreeSurfer hyperparameters.

References

1: FieldTrip explanation: https://www.fieldtriptoolbox.org/faq/how_are_the_different_head_and_mri_coordinate_systems_defined/#details-of-the-freesurfer-coordinate-system # noqa
2: How MNE handles FreeSurfer data: https://mne.tools/dev/auto_tutorials/source-modeling/plot_background_freesurfer_mne.html # noqa
3: FreeSurfer Wiki: https://surfer.nmr.mgh.harvard.edu/fswiki/CoordinateSystems # noqa