ENH: add overlay Brain GUI (#14031)

Co-authored-by: Eric Larson <larson.eric.d@gmail.com>

Author: payamsash

doc/changes/dev/14037.newfeature.rst

@@ -0,0 +1 @@
+When multiple overlays are active (via ``remove_existing=False`` in :meth:`~mne.viz.Brain.add_data`), the interactive Brain viewer now shows an "Overlay" drop-down in the *Color Limits* dock panel that lets the user switch which overlay's color limits and smoothing the sliders control. By `Payam Sadeghi-Shabestari`_.

examples/visualization/brain.py

@@ -219,8 +219,11 @@
 # alpha-composited by :class:`~mne.viz.LayeredMesh` so both datasets appear
 # at the same time.
 #
-# Here we simulate two focal patches of activity in different brain regions:
-# a temporal source (red/hot) and a frontal source (blue).
+# Here we simulate two focal patches of activity evolving over time in
+# different brain regions: a temporal source (red/hot) that peaks early and
+# a frontal source (blue) that peaks later.  In the interactive viewer an
+# "Overlay" drop-down appears in the *Color Limits* panel — use it to switch
+# which overlay's limits and smoothing the sliders control.
 
 brain = mne.viz.Brain(
     "sample",
@@ -246,6 +249,7 @@ def gaussian_patch(coords, center, sigma=15.0):
     fmin=0.1,
     fmax=1.5,
     colormap="hot",
+    transparent=True,
     key="temporal",
     smoothing_steps=5,
 )
@@ -257,6 +261,7 @@ def gaussian_patch(coords, center, sigma=15.0):
     fmin=0.1,
     fmax=0.6,
     colormap="Blues",
+    transparent=True,
     alpha=0.5,
     key="frontal",
     remove_existing=False,

mne/viz/_3d_overlay.py

@@ -263,7 +263,9 @@ def _clean(self):
         self._polydata = None
         self._renderer = None
 
-    def update_overlay(self, name, scalars=None, colormap=None, opacity=None, rng=None):
+    def update_overlay(
+        self, name, scalars=None, colormap=None, opacity=None, rng=None, update=True
+    ):
         """Update an existing overlay in-place.
 
         Parameters
@@ -281,6 +283,11 @@ def update_overlay(self, name, scalars=None, colormap=None, opacity=None, rng=No
             New opacity in ``[0, 1]``. If ``None``, opacity is unchanged.
         rng : array-like, shape (2,) | None
             New ``[min, max]`` colormap range. If ``None``, range is unchanged.
+        update : bool
+            If ``True`` (default), recompose overlays and refresh the mesh
+            immediately.  Pass ``False`` to stage the change without
+            triggering a recompose; the caller is then responsible for
+            calling :meth:`update` once all overlays have been staged.
         """
         overlay = self._overlays.get(name, None)
         if overlay is None:
@@ -304,6 +311,8 @@ def update_overlay(self, name, scalars=None, colormap=None, opacity=None, rng=No
             overlay._opacity = opacity
         if rng is not None:
             overlay._rng = rng
+        if not update:
+            return
         # partial update: use cache if possible
         if name == list(self._overlays.keys())[-1]:
             self.update(colors=overlay.to_colors())