ENH: Add some options for 3D renderer titles (mne-tools#12871)

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

doc/changes/devel/12871.newfeature.rst

@@ -0,0 +1,2 @@
+Added the ``title`` argument to :func:`mne.viz.create_3d_figure`, and
+``color`` and ``position`` arguments to :func:`mne.viz.set_3d_title`, by `Eric Larson`_.

mne/viz/backends/_abstract.py

@@ -34,7 +34,8 @@ def _init(
         fig=None,
         size=(600, 600),
         bgcolor=(0.0, 0.0, 0.0),
-        name=None,
+        *,
+        title="MNE 3D Figure",
         show=False,
         shape=(1, 1),
         splash=False,
@@ -60,7 +61,8 @@ def __init__(
         fig=None,
         size=(600, 600),
         bgcolor=(0.0, 0.0, 0.0),
-        name=None,
+        *,
+        name="MNE-Python 3D Figure",
         show=False,
         shape=(1, 1),
         splash=False,

mne/viz/backends/_pyvista.py

@@ -93,7 +93,7 @@ def _init(
         self,
         plotter=None,
         show=False,
-        title="PyVista Scene",
+        title="MNE-Python 3D Figure",
         size=(600, 600),
         shape=(1, 1),
         background_color="black",
@@ -200,7 +200,8 @@ def __init__(
         fig=None,
         size=(600, 600),
         bgcolor="black",
-        name="PyVista Scene",
+        *,
+        name=None,
         show=False,
         shape=(1, 1),
         notebook=None,
@@ -1187,10 +1188,17 @@ def _set_3d_view(
         _process_events(figure.plotter)
 
 
-def _set_3d_title(figure, title, size=16):
-    figure.plotter.add_text(title, font_size=size, color="white", name="title")
+def _set_3d_title(figure, title, size=16, *, color="white", position="upper_left"):
+    handle = figure.plotter.add_text(
+        title,
+        font_size=size,
+        color=color,
+        position=position,
+        name="title",
+    )
     figure.plotter.update()
     _process_events(figure.plotter)
+    return handle
 
 
 def _check_3d_figure(figure):

mne/viz/backends/renderer.py

@@ -283,7 +283,8 @@ def set_3d_view(
     )
 
 
-def set_3d_title(figure, title, size=40):
+@fill_doc
+def set_3d_title(figure, title, size=40, *, color="white", position="upper_left"):
     """Configure the title of the given scene.
 
     Parameters
@@ -294,12 +295,37 @@ def set_3d_title(figure, title, size=40):
         The title of the scene.
     size : int
         The size of the title.
+    color : matplotlib color
+        The color of the title.
+
+        .. versionadded:: 1.9
+    position : str
+        The position to use, e.g., "upper_left". See
+        :meth:`pyvista.Plotter.add_text` for details.
+
+        .. versionadded:: 1.9
+
+    Returns
+    -------
+    text : object
+        The text object returned by the given backend.
+
+        .. versionadded:: 1.0
     """
-    backend._set_3d_title(figure=figure, title=title, size=size)
+    return backend._set_3d_title(
+        figure=figure, title=title, size=size, color=color, position=position
+    )
 
 
 def create_3d_figure(
-    size, bgcolor=(0, 0, 0), smooth_shading=None, handle=None, *, scene=True, show=False
+    size,
+    bgcolor=(0, 0, 0),
+    smooth_shading=None,
+    handle=None,
+    *,
+    scene=True,
+    show=False,
+    title="MNE 3D Figure",
 ):
     """Return an empty figure based on the current 3d backend.
 
@@ -327,6 +353,10 @@ def create_3d_figure(
         If True, show the renderer immediately.
 
         .. versionadded:: 1.0
+    title : str
+        The window title to use (if applicable).
+
+        .. versionadded:: 1.9
 
     Returns
     -------
@@ -342,6 +372,7 @@ def create_3d_figure(
         bgcolor=bgcolor,
         smooth_shading=smooth_shading,
         show=show,
+        name=title,
     )
     if scene:
         return renderer.scene()