python_embed/Lib/site-packages/mne/viz/backends/renderer.py

"""Core visualization operations."""

# Authors: The MNE-Python contributors.
# License: BSD-3-Clause
# Copyright the MNE-Python contributors.

import importlib
import time
from contextlib import contextmanager
from functools import partial

import numpy as np

from ...utils import (
    _auto_weakref,
    _check_option,
    _validate_type,
    fill_doc,
    get_config,
    logger,
    verbose,
)
from .._3d import _get_3d_option
from ..utils import safe_event
from ._utils import VALID_3D_BACKENDS

MNE_3D_BACKEND = None
MNE_3D_BACKEND_TESTING = False


_backend_name_map = dict(
    pyvistaqt="._qt",
    notebook="._notebook",
)
backend = None


def _reload_backend(backend_name):
    global backend
    backend = importlib.import_module(
        name=_backend_name_map[backend_name], package="mne.viz.backends"
    )
    logger.info(f"Using {backend_name} 3d backend.")


def _get_backend():
    _get_3d_backend()
    return backend


def _get_renderer(*args, **kwargs):
    _get_3d_backend()
    return backend._Renderer(*args, **kwargs)


def _check_3d_backend_name(backend_name):
    _validate_type(backend_name, str, "backend_name")
    backend_name = "pyvistaqt" if backend_name == "pyvista" else backend_name
    _check_option("backend_name", backend_name, VALID_3D_BACKENDS)
    return backend_name


@verbose
def set_3d_backend(backend_name, verbose=None):
    """Set the 3D backend for MNE.

    The backend will be set as specified and operations will use
    that backend.

    Parameters
    ----------
    backend_name : str
        The 3d backend to select. See Notes for the capabilities of each
        backend (``'pyvistaqt'`` and ``'notebook'``).

        .. versionchanged:: 0.24
           The ``'pyvista'`` backend was renamed ``'pyvistaqt'``.
    %(verbose)s

    Returns
    -------
    old_backend_name : str | None
        The old backend that was in use.

    Notes
    -----
    To use PyVista, set ``backend_name`` to ``pyvistaqt`` but the value
    ``pyvista`` is still supported for backward compatibility.

    This table shows the capabilities of each backend ("✓" for full support,
    and "-" for partial support):

    .. table::
       :widths: auto

       +--------------------------------------+-----------+----------+
       | **3D function:**                     | pyvistaqt | notebook |
       +======================================+===========+==========+
       | :func:`plot_vector_source_estimates` | ✓         | ✓        |
       +--------------------------------------+-----------+----------+
       | :func:`plot_source_estimates`        | ✓         | ✓        |
       +--------------------------------------+-----------+----------+
       | :func:`plot_alignment`               | ✓         | ✓        |
       +--------------------------------------+-----------+----------+
       | :func:`plot_sparse_source_estimates` | ✓         | ✓        |
       +--------------------------------------+-----------+----------+
       | :func:`plot_evoked_field`            | ✓         | ✓        |
       +--------------------------------------+-----------+----------+
       | :func:`snapshot_brain_montage`       | ✓         | ✓        |
       +--------------------------------------+-----------+----------+
       | :func:`link_brains`                  | ✓         |          |
       +--------------------------------------+-----------+----------+
       +--------------------------------------+-----------+----------+
       | **Feature:**                                                |
       +--------------------------------------+-----------+----------+
       | Large data                           | ✓         | ✓        |
       +--------------------------------------+-----------+----------+
       | Opacity/transparency                 | ✓         | ✓        |
       +--------------------------------------+-----------+----------+
       | Support geometric glyph              | ✓         | ✓        |
       +--------------------------------------+-----------+----------+
       | Smooth shading                       | ✓         | ✓        |
       +--------------------------------------+-----------+----------+
       | Subplotting                          | ✓         | ✓        |
       +--------------------------------------+-----------+----------+
       | Inline plot in Jupyter Notebook      |           | ✓        |
       +--------------------------------------+-----------+----------+
       | Inline plot in JupyterLab            |           | ✓        |
       +--------------------------------------+-----------+----------+
       | Inline plot in Google Colab          |           |          |
       +--------------------------------------+-----------+----------+
       | Toolbar                              | ✓         | ✓        |
       +--------------------------------------+-----------+----------+
    """
    global MNE_3D_BACKEND
    old_backend_name = MNE_3D_BACKEND
    backend_name = _check_3d_backend_name(backend_name)
    if MNE_3D_BACKEND != backend_name:
        _reload_backend(backend_name)
        MNE_3D_BACKEND = backend_name
    return old_backend_name


def get_3d_backend():
    """Return the 3D backend currently used.

    Returns
    -------
    backend_used : str | None
        The 3d backend currently in use. If no backend is found,
        returns ``None``.

        .. versionchanged:: 0.24
           The ``'pyvista'`` backend has been renamed ``'pyvistaqt'``, so
           ``'pyvista'`` is no longer returned by this function.
    """
    try:
        backend = _get_3d_backend()
    except RuntimeError as exc:
        backend = None
        logger.info(str(exc))
    return backend


def _get_3d_backend():
    """Load and return the current 3d backend."""
    global MNE_3D_BACKEND
    if MNE_3D_BACKEND is None:
        MNE_3D_BACKEND = get_config(key="MNE_3D_BACKEND", default=None)
        if MNE_3D_BACKEND is None:  # try them in order
            errors = dict()
            for name in VALID_3D_BACKENDS:
                try:
                    _reload_backend(name)
                except ImportError as exc:
                    errors[name] = str(exc)
                else:
                    MNE_3D_BACKEND = name
                    break
            else:
                raise RuntimeError(
                    "Could not load any valid 3D backend\n"
                    + "\n".join(f"{key}: {val}" for key, val in errors.items())
                    + "\n".join(
                        (
                            "\n\n install pyvistaqt, using pip or conda:",
                            "'pip install pyvistaqt'",
                            "'conda install -c conda-forge pyvistaqt'",
                            "\n or install ipywidgets, "
                            + "if using a notebook backend",
                            "'pip install ipywidgets'",
                            "'conda install -c conda-forge ipywidgets'",
                        )
                    )
                )

        else:
            MNE_3D_BACKEND = _check_3d_backend_name(MNE_3D_BACKEND)
            _reload_backend(MNE_3D_BACKEND)
    MNE_3D_BACKEND = _check_3d_backend_name(MNE_3D_BACKEND)
    return MNE_3D_BACKEND


@contextmanager
def use_3d_backend(backend_name):
    """Create a 3d visualization context using the designated backend.

    See :func:`mne.viz.set_3d_backend` for more details on the available
    3d backends and their capabilities.

    Parameters
    ----------
    backend_name : {'pyvistaqt', 'notebook'}
        The 3d backend to use in the context.
    """
    old_backend = set_3d_backend(backend_name)
    try:
        yield
    finally:
        if old_backend is not None:
            try:
                set_3d_backend(old_backend)
            except Exception:
                pass


@contextmanager
def _use_test_3d_backend(backend_name, interactive=False):
    """Create a testing viz context.

    Parameters
    ----------
    backend_name : str
        The 3d backend to use in the context.
    interactive : bool
        If True, ensure interactive elements are accessible.
    """
    with _actors_invisible():
        with use_3d_backend(backend_name):
            with backend._testing_context(interactive):
                yield


@contextmanager
def _actors_invisible():
    global MNE_3D_BACKEND_TESTING
    orig_testing = MNE_3D_BACKEND_TESTING
    MNE_3D_BACKEND_TESTING = True
    try:
        yield
    finally:
        MNE_3D_BACKEND_TESTING = orig_testing


@fill_doc
def set_3d_view(
    figure,
    azimuth=None,
    elevation=None,
    focalpoint=None,
    distance=None,
    roll=None,
):
    """Configure the view of the given scene.

    Parameters
    ----------
    figure : object
        The scene which is modified.
    %(azimuth)s
    %(elevation)s
    %(focalpoint)s
    %(distance)s
    %(roll)s
    """
    backend._set_3d_view(
        figure=figure,
        azimuth=azimuth,
        elevation=elevation,
        focalpoint=focalpoint,
        distance=distance,
        roll=roll,
    )


@fill_doc
def set_3d_title(figure, title, size=40, *, color="white", position="upper_left"):
    """Configure the title of the given scene.

    Parameters
    ----------
    figure : object
        The scene which is modified.
    title : str
        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
    """
    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,
    title="MNE 3D Figure",
):
    """Return an empty figure based on the current 3d backend.

    .. warning:: Proceed with caution when the renderer object is
                 returned (with ``scene=False``) because the _Renderer
                 API is not necessarily stable enough for production,
                 it's still actively in development.

    Parameters
    ----------
    size : tuple
        The dimensions of the 3d figure (width, height).
    bgcolor : tuple
        The color of the background.
    smooth_shading : bool | None
        Whether to enable smooth shading. If ``None``, uses the config value
        ``MNE_3D_OPTION_SMOOTH_SHADING``. Defaults to ``None``.
    handle : int | None
        The figure identifier.
    scene : bool
        If True (default), the returned object is the Figure3D. If False,
        an advanced, undocumented Renderer object is returned (the API is not
        stable or documented, so this is not recommended).
    show : bool
        If True, show the renderer immediately.

        .. versionadded:: 1.0
    title : str
        The window title to use (if applicable).

        .. versionadded:: 1.9

    Returns
    -------
    figure : instance of Figure3D or ``Renderer``
        The requested empty figure or renderer, depending on ``scene``.
    """
    _validate_type(smooth_shading, (bool, None), "smooth_shading")
    if smooth_shading is None:
        smooth_shading = _get_3d_option("smooth_shading")
    renderer = _get_renderer(
        fig=handle,
        size=size,
        bgcolor=bgcolor,
        smooth_shading=smooth_shading,
        show=show,
        name=title,
    )
    if scene:
        return renderer.scene()
    else:
        return renderer


def close_3d_figure(figure):
    """Close the given scene.

    Parameters
    ----------
    figure : object
        The scene which needs to be closed.
    """
    backend._close_3d_figure(figure)


def close_all_3d_figures():
    """Close all the scenes of the current 3d backend."""
    backend._close_all()


def get_brain_class():
    """Return the proper Brain class based on the current 3d backend.

    Returns
    -------
    brain : object
        The Brain class corresponding to the current 3d backend.
    """
    from ...viz._brain import Brain

    return Brain


class _TimeInteraction:
    """Mixin enabling time interaction controls."""

    def _enable_time_interaction(
        self,
        fig,
        current_time_func,
        times,
        init_playback_speed=0.01,
        playback_speed_range=(0.01, 0.1),
    ):
        from ..ui_events import (
            PlaybackSpeed,
            TimeChange,
            publish,
            subscribe,
        )

        self._fig = fig
        self._current_time_func = current_time_func
        self._times = times
        self._init_time = current_time_func()
        self._init_playback_speed = init_playback_speed

        if not hasattr(self, "_dock"):
            self._dock_initialize()

        if not hasattr(self, "_tool_bar") or self._tool_bar is None:
            self._tool_bar_initialize(name="Toolbar")

        if not hasattr(self, "_widgets"):
            self._widgets = dict()

        # Dock widgets
        @_auto_weakref
        def publish_time_change(time_index):
            publish(
                fig,
                TimeChange(time=np.interp(time_index, np.arange(len(times)), times)),
            )

        layout = self._dock_add_group_box("")
        self._widgets["time_slider"] = self._dock_add_slider(
            name="Time (s)",
            value=np.interp(current_time_func(), times, np.arange(len(times))),
            rng=[0, len(times) - 1],
            double=True,
            callback=publish_time_change,
            compact=False,
            layout=layout,
        )
        hlayout = self._dock_add_layout(vertical=False)
        self._widgets["min_time"] = self._dock_add_label("-", layout=hlayout)
        self._dock_add_stretch(hlayout)
        self._widgets["current_time"] = self._dock_add_label(value="x", layout=hlayout)
        self._dock_add_stretch(hlayout)
        self._widgets["max_time"] = self._dock_add_label(value="+", layout=hlayout)
        self._layout_add_widget(layout, hlayout)

        self._widgets["min_time"].set_value(f"{times[0]: .3f}")
        self._widgets["current_time"].set_value(f"{current_time_func(): .3f}")
        self._widgets["max_time"].set_value(f"{times[-1]: .3f}")

        @_auto_weakref
        def publish_playback_speed(speed):
            publish(fig, PlaybackSpeed(speed=speed))

        self._widgets["playback_speed"] = self._dock_add_spin_box(
            name="Speed",
            value=init_playback_speed,
            rng=playback_speed_range,
            callback=publish_playback_speed,
            layout=layout,
        )

        # Tool bar buttons
        self._widgets["reset"] = self._tool_bar_add_button(
            name="reset", desc="Reset", func=self._reset_time
        )
        self._widgets["play"] = self._tool_bar_add_play_button(
            name="play",
            desc="Play/Pause",
            func=self._toggle_playback,
            shortcut=" ",
        )

        # Configure playback
        self._playback = False
        self._playback_initialize(
            func=self._play,
            timeout=17,
            value=np.interp(current_time_func(), times, np.arange(len(times))),
            rng=[0, len(times) - 1],
            time_widget=self._widgets["time_slider"],
            play_widget=self._widgets["play"],
        )

        # Keyboard shortcuts
        @_auto_weakref
        def shift_time(direction):
            amount = self._widgets["playback_speed"].get_value()
            publish(
                self._fig,
                TimeChange(time=self._current_time_func() + direction * amount),
            )

        if self.plotter.iren is not None:
            self.plotter.add_key_event("n", partial(shift_time, direction=1))
            self.plotter.add_key_event("b", partial(shift_time, direction=-1))

        # Subscribe to relevant UI events
        subscribe(fig, "time_change", self._on_time_change)
        subscribe(fig, "playback_speed", self._on_playback_speed)

    def _on_time_change(self, event):
        """Respond to time_change UI event."""
        from ..ui_events import disable_ui_events

        new_time = np.clip(event.time, self._times[0], self._times[-1])
        new_time_idx = np.interp(new_time, self._times, np.arange(len(self._times)))

        with disable_ui_events(self._fig):
            self._widgets["time_slider"].set_value(new_time_idx)
            self._widgets["current_time"].set_value(f"{new_time:.3f}")

    def _on_playback_speed(self, event):
        """Respond to playback_speed UI event."""
        from ..ui_events import disable_ui_events

        with disable_ui_events(self._fig):
            self._widgets["playback_speed"].set_value(event.speed)

    def _toggle_playback(self, value=None):
        """Toggle time playback."""
        from ..ui_events import TimeChange, publish

        if value is None:
            self._playback = not self._playback
        else:
            self._playback = value

        if self._playback:
            self._tool_bar_update_button_icon(name="play", icon_name="pause")
            if self._current_time_func() == self._times[-1]:  # start over
                publish(self._fig, TimeChange(time=self._times[0]))
            self._last_tick = time.time()
        else:
            self._tool_bar_update_button_icon(name="play", icon_name="play")

    def _reset_time(self):
        """Reset time and playback speed to initial values."""
        from ..ui_events import PlaybackSpeed, TimeChange, publish

        publish(self._fig, TimeChange(time=self._init_time))
        publish(self._fig, PlaybackSpeed(speed=self._init_playback_speed))

    @safe_event
    def _play(self):
        if self._playback:
            try:
                self._advance()
            except Exception:
                self._toggle_playback(value=False)
                raise

    def _advance(self):
        from ..ui_events import TimeChange, publish

        this_time = time.time()
        delta = this_time - self._last_tick
        self._last_tick = time.time()
        time_shift = delta * self._widgets["playback_speed"].get_value()
        new_time = min(self._current_time_func() + time_shift, self._times[-1])
        publish(self._fig, TimeChange(time=new_time))
        if new_time == self._times[-1]:
            self._toggle_playback(value=False)