Function head_to_mri

mne/_freesurfer.py:275–338

Convert pos from head coordinate system to MRI ones. Parameters ---------- pos : array, shape (n_pos, 3) The coordinates (in m) in head coordinate system. %(subject)s mri_head_t : instance of Transform MRI<->Head coordinate transformation. %(subjects_dir)s

(
    pos,
    subject,
    mri_head_t,
    subjects_dir=None,
    *,
    kind="mri",
    unscale=False,
    verbose=None,
)

@verbose
def head_to_mri(
    pos,
    subject,
    mri_head_t,
    subjects_dir=None,
    *,
    kind="mri",
    unscale=False,
    verbose=None,
):
    """Convert pos from head coordinate system to MRI ones.

    Parameters
    ----------
    pos : array, shape (n_pos, 3)
        The coordinates (in m) in head coordinate system.
    %(subject)s
    mri_head_t : instance of Transform
        MRI<->Head coordinate transformation.
    %(subjects_dir)s
    kind : str
        The  MRI coordinate frame kind, can be ``'mri'`` (default) for
        FreeSurfer surface RAS or ``'ras'`` (default in 1.2) to use MRI RAS
        (scanner RAS).

        .. versionadded:: 1.2
    unscale : bool
        For surrogate MRIs (e.g., scaled using ``mne coreg``), if True
        (default False), use the MRI scaling parameters to obtain points in
        the original/surrogate subject&#x27;s MRI space.

        .. versionadded:: 1.2
    %(verbose)s

    Returns
    -------
    coordinates : array, shape (n_pos, 3)
        The MRI RAS coordinates (in mm) of pos.

    Notes
    -----
    This function requires nibabel.
    """
    from .coreg import read_mri_cfg

    _validate_type(kind, str, "kind")
    _check_option("kind", kind, ("ras", "mri"))
    subjects_dir = get_subjects_dir(subjects_dir, raise_error=True)
    t1_fname = subjects_dir / subject / "mri" / "T1.mgz"
    head_mri_t = _ensure_trans(mri_head_t, "head", "mri")
    if kind == "ras":
        _, _, mri_ras_t, _, _ = _read_mri_info(t1_fname)
        head_ras_t = combine_transforms(head_mri_t, mri_ras_t, "head", "ras")
        head_dest_t = head_ras_t
    else:
        assert kind == "mri"
        head_dest_t = head_mri_t
    pos_dest = apply_trans(head_dest_t, pos)