Eric comments

mne/_freesurfer.py

@@ -541,7 +541,8 @@ def _get_lut(fname=None):
     return lut
 
 
-def get_head_surface(surf, subject, subjects_dir, bem=None):
+@verbose
+def _get_head_surface(surf, subject, subjects_dir, bem=None, verbose=None):
     """Get a head surface from the Freesurfer subject directory.
 
     Parameters
@@ -551,13 +552,16 @@ def get_head_surface(surf, subject, subjects_dir, bem=None):
         or 'seghead'.
     %(subject)s
     %(subjects_dir)s
+    bem : mne.bem.ConductorModel | None
+        The conductor model that stores information about the head surface.
+    %(verbose)s
 
     Returns
     -------
-    verts : ndarray
-        The surface vertices or None if ``surf='auto'`` and none is found.
-    triangles : ndarray
-        The vertex triangles or None if ``surf='auto'`` and none is found.
+    head_surf : dict | None
+        A dictionary with keys 'rr', 'tris', 'ntri', 'use_tris', 'np'
+        and 'coord_frame' that store information for mesh plotting and other
+        useful information about the head surface.
 
     Notes
     -----

mne/viz/_3d.py

@@ -21,7 +21,7 @@
 
 from ..defaults import DEFAULTS
 from ..fixes import _crop_colorbar, _get_img_fdata, _get_args
-from .._freesurfer import _read_mri_info, _check_mri, get_head_surface
+from .._freesurfer import _read_mri_info, _check_mri, _get_head_surface
 from ..io import _loc_to_coil_trans
 from ..io.pick import pick_types, _picks_to_idx
 from ..io.constants import FIFF
@@ -687,7 +687,7 @@ def plot_alignment(info=None, trans=None, subject=None, subjects_dir=None,
                          f'got {heads}')
     elif heads:
         surfaces.pop(surfaces.index(heads[0]))
-        head_surf = get_head_surface(heads[0], subject, subjects_dir, bem=bem)
+        head_surf = _get_head_surface(heads[0], subject, subjects_dir, bem=bem)
         if head_surf is not None:
             surfs['head'] = head_surf
 

mne/viz/_brain/_brain.py

@@ -35,7 +35,7 @@
 from ...externals.decorator import decorator
 from ...defaults import _handle_default
 from ..._freesurfer import (vertex_to_mni, read_talxfm, read_freesurfer_lut,
-                            get_head_surface)
+                            _get_head_surface)
 from ...surface import mesh_edges, _mesh_borders, _marching_cubes
 from ...source_space import SourceSpaces
 from ...transforms import apply_trans, invert_transform
@@ -2339,8 +2339,8 @@ def add_head(self, dense=True, color=None, alpha=0.5):
         from matplotlib.colors import colorConverter
 
         # load head
-        surf = get_head_surface('seghead' if dense else 'head',
-                                self._subject_id, self._subjects_dir)
+        surf = _get_head_surface('seghead' if dense else 'head',
+                                 self._subject_id, self._subjects_dir)
         verts, triangles = surf['rr'], surf['tris']
         if color is None:
             color = 'gray'