ENH: support per-vertex opacity in 3D overlays (#13706)

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

Author: PragnyaKhandelwal

doc/changes/dev/13706.newfeature.rst

@@ -0,0 +1 @@
+Add support for scalar or per-vertex ``alpha`` (shape ``(n_vertices,)``) in distributed overlays, including validation/errors for invalid shapes, tests, and a visualization example in ``examples/visualization/brain.py`` using :meth:`mne.viz.Brain.add_data`, by :newcontrib:`Pragnya Khandelwal`. (:gh:`13706`)

doc/changes/names.inc

@@ -259,6 +259,7 @@
 .. _Pierre Guetschel: https://github.com/PierreGtch
 .. _Pierre-Antoine Bannier: https://github.com/PABannier
 .. _Ping-Keng Jao: https://github.com/nafraw
+.. _Pragnya Khandelwal: https://github.com/PragnyaKhandelwal
 .. _Proloy Das: https://github.com/proloyd
 .. _Qian Chu: https://github.com/qian-chu
 .. _Qianliang Li: https://www.dtu.dk/english/service/phonebook/person?id=126774

examples/visualization/brain.py

@@ -134,3 +134,35 @@
 norm = Normalize(vmin=0, vmax=dip.gof.max())
 fig.colorbar(ScalarMappable(norm=norm, cmap=cmap), cax=cax)
 fig.suptitle("Dipole Fits Scaled by Amplitude and Colored by GOF")
+
+
+# %%
+# Use per-vertex opacity for distributed data
+# --------------------------------------------
+#
+# You can provide an array for ``alpha`` in :meth:`mne.viz.Brain.add_data`
+# to control transparency per vertex. This can be useful to emphasize a
+# subset of vertices while still showing surrounding context.
+
+brain = mne.viz.Brain("sample", subjects_dir=subjects_dir, hemi="lh", **brain_kwargs)
+coords = brain.geo["lh"].coords
+n_vertices = len(coords)
+
+# Build synthetic data: a smooth left-to-right gradient color-wise in the Y
+# (front-back) direction, plus a matching opacity ramp from mostly transparent to
+# fully opaque in the X (left-right) direction.
+data = coords[:, 1]
+data = (data - data.min()) / (data.max() - data.min())
+vertex_alpha = -coords[:, 0]
+vertex_alpha = (vertex_alpha - vertex_alpha.min()) / (
+    vertex_alpha.max() - vertex_alpha.min()
+)
+
+brain.add_data(
+    data,
+    hemi="lh",
+    alpha=vertex_alpha,
+    colormap="viridis",
+    smoothing_steps=5,
+)
+brain.show_view(azimuth=190, elevation=70, distance=350, focalpoint=(0, 0, 20))

mne/viz/_3d_overlay.py

@@ -43,10 +43,29 @@ def to_colors(self):
         scalars = self._norm(rng)
 
         colors = cmap(scalars)
-        if self._opacity is not None:
-            colors[:, 3] *= self._opacity
+        opacity = self._check_opacity(colors.shape[0])
+        if opacity is not None:
+            colors[:, 3] *= opacity
         return colors
 
+    def _check_opacity(self, n_vertices):
+        if self._opacity is None:
+            return None
+        opacity = np.asarray(self._opacity)
+        if opacity.ndim == 0:
+            return float(opacity)
+        if opacity.ndim != 1:
+            raise ValueError(
+                "opacity must be a scalar or a 1D array with one value per "
+                f"vertex, got an array with shape {opacity.shape}"
+            )
+        if len(opacity) != n_vertices:
+            raise ValueError(
+                "opacity array must have one value per vertex, got "
+                f"{len(opacity)} values for {n_vertices} vertices"
+            )
+        return opacity
+
     def _norm(self, rng):
         if rng[0] == rng[1]:
             factor = 1 if rng[0] == 0 else 1e-6 * rng[0]

mne/viz/_brain/_brain.py

@@ -1709,8 +1709,12 @@ def add_data(
             between 0 and 255), the default "auto" chooses a default divergent
             colormap, if "center" is given (currently "icefire"), otherwise a
             default sequential colormap (currently "rocket").
-        alpha : float in [0, 1]
-            Alpha level to control opacity of the overlay.
+        alpha : float in [0, 1] | array, shape (n_vertices,)
+            Alpha level to control opacity of the overlay. A scalar applies
+            globally, while a 1D array applies per-vertex opacity.
+
+            .. versionchanged:: 1.12
+               Added support for per-vertex alpha.
         vertices : numpy array
             Vertices for which the data is defined (needed if
             ``len(data) < nvtx``).

mne/viz/_brain/tests/test_brain.py

@@ -162,6 +162,28 @@ def test_layered_mesh(renderer_interactive_pyvistaqt):
     assert "test2" not in mesh._overlays
     mesh.update()
     assert len(mesh._overlays) == 1
+
+    mesh.remove_overlay("test1")
+    mesh.update()
+
+    opacity = np.array([0.0, 0.5, 1.0, 0.25])
+    mesh.add_overlay(
+        scalars=np.array([0, 1, 1, 0]),
+        colormap=np.array([(255, 255, 255, 255), (0, 0, 0, 255)]),
+        rng=[0, 1],
+        opacity=opacity,
+        name="test3",
+    )
+    assert_allclose(mesh._current_colors[:, 3], opacity, atol=1.0 / 255.0)
+
+    with pytest.raises(ValueError, match="one value per vertex"):
+        mesh.add_overlay(
+            scalars=np.array([0, 1, 1, 0]),
+            colormap=np.array([(255, 255, 255, 255), (0, 0, 0, 255)]),
+            rng=[0, 1],
+            opacity=np.array([0.1, 0.2, 0.3]),
+            name="bad-opacity",
+        )
     mesh._clean()
 
 

mne/viz/tests/test_3d_overlay.py

@@ -0,0 +1,36 @@
+# Authors: The MNE-Python contributors.
+# License: BSD-3-Clause
+# Copyright the MNE-Python contributors.
+
+import numpy as np
+import pytest
+from numpy.testing import assert_allclose
+
+from mne.viz._3d_overlay import _Overlay
+
+
+def test_overlay_opacity_per_vertex():
+    """Test per-vertex opacity support in overlay color mapping."""
+    n_vertices = 4
+    overlay = _Overlay(
+        scalars=np.linspace(0, 1, n_vertices),
+        colormap="viridis",
+        rng=(0.0, 1.0),
+        opacity=np.array([0.0, 0.25, 0.5, 1.0]),
+        name="test",
+    )
+    colors = overlay.to_colors()
+    assert_allclose(colors[:, 3], [0.0, 0.25, 0.5, 1.0])
+
+
+def test_overlay_opacity_bad_shape():
+    """Test that invalid per-vertex opacity raises."""
+    overlay = _Overlay(
+        scalars=np.linspace(0, 1, 4),
+        colormap="viridis",
+        rng=(0.0, 1.0),
+        opacity=np.array([0.1, 0.2, 0.3]),
+        name="test",
+    )
+    with pytest.raises(ValueError, match="one value per vertex"):
+        overlay.to_colors()