Merge branch 'main' into jupyterlite-gh-actions

Author: natinew77-creator

doc/api/visualization.rst

@@ -14,6 +14,7 @@ Visualization
    :toctree: ../generated/
 
    Brain
+   LayeredMesh
    ClickableImage
    EvokedField
    Figure3D

doc/changes/dev/13680.other.rst

@@ -0,0 +1 @@
+Document :attr:`~mne.Annotations.onset`, :attr:`~mne.Annotations.duration`, :attr:`~mne.Annotations.description`, and :attr:`~mne.Annotations.ch_names` attributes of :class:`mne.Annotations`, by `Famous077`_.

doc/changes/dev/13970.newfeature.rst

@@ -0,0 +1 @@
+Added public :class:`mne.viz.LayeredMesh` class (previously private ``_LayeredMesh``) with a ``smooth_mat`` attribute for efficient real-time source-space data streaming. Added ``Brain.layered_meshes`` attribute to access meshes after plotting, and a ``key`` parameter to :meth:`mne.viz.Brain.add_data` for named overlays, by :newcontrib:`Payam Sadeghi-Shabestari`.

doc/changes/names.inc

@@ -145,10 +145,10 @@
 .. _Jacob Woessner: https://github.com/withmywoessner
 .. _Jair Montoya Martinez: https://github.com/jmontoyam
 .. _Jan Ebert: https://www.jan-ebert.com/
+.. _Jan Mathijs Schoffelen: https://github.com/schoffelen
 .. _Jan Sedivy: https://github.com/honzaseda
 .. _Jan Sosulski: https://jan-sosulski.de
 .. _Jan Zerfowski: https://github.com/jzerfowski
-.. _Jan-Mathijs Schoeffelen: https://github.com/schoffelen
 .. _Jasper van den Bosch: https://github.com/ilogue
 .. _Jean-Baptiste Schiratti: https://github.com/jbschiratti
 .. _Jean-Rémi King: https://github.com/kingjr
@@ -267,6 +267,7 @@
 .. _Paul Roujansky: https://github.com/paulroujansky
 .. _Pavel Navratil: https://github.com/navrpa13
 .. _Pavel Popov: https://github.com/paavalipopov
+.. _Payam Sadeghi-Shabestari: https://github.com/payamsash
 .. _Peter Molfese: https://github.com/pmolfese
 .. _Phillip Alday: https://palday.bitbucket.io
 .. _Pierre Ablin: https://pierreablin.com

doc/conf.py

@@ -430,6 +430,8 @@
     "polars",
     "default",
     # unlinkable
+    "_Renderer",
+    "n_triangles",
     "CoregistrationUI",
     "mne_qt_browser.figure.MNEQtBrowser",
     # pooch, since its website is unreliable and users will rarely need the links

doc/credits/leaders.rst

@@ -67,7 +67,7 @@ Advisory Board
 
 * `Alex Gramfort`_
 * `Bradley Voytek`_
-* `Jan-Mathijs Schoeffelen`_
+* `Jan Mathijs Schoffelen`_
 * `Liberty Hamilton`_
 * `Matti Hämäläinen`_
 * `Ole Jensen`_

examples/visualization/brain.py

@@ -136,6 +136,48 @@
 fig.suptitle("Dipole Fits Scaled by Amplitude and Colored by GOF")
 
 
+# %%
+# Update overlays via ``Brain.layered_meshes``
+# --------------------------------------------
+#
+# After :meth:`~mne.viz.Brain.add_data` is called, each hemisphere's surface
+# is backed by a :class:`~mne.viz.LayeredMesh` stored in
+# ``brain.layered_meshes``.  Calling
+# :meth:`~mne.viz.LayeredMesh.update_overlay` pushes new scalar data without
+# rebuilding the full rendering pipeline — the key operation for packages that
+# stream source-space data onto the brain in real time, such as
+# `MNE-RT <https://payamsash.github.io/mne-rt/>`_.
+#
+# Here we add an initial bottom-to-top gradient as the first data frame.
+
+brain = mne.viz.Brain("sample", subjects_dir=subjects_dir, hemi="lh", **brain_kwargs)
+coords = brain.geo["lh"].coords
+data_t0 = coords[:, 2]
+data_t0 = (data_t0 - data_t0.min()) / (data_t0.max() - data_t0.min())
+brain.add_data(
+    data_t0, hemi="lh", fmin=0, fmax=1, colormap="viridis", smoothing_steps=5
+)
+brain.show_view(azimuth=190, elevation=70, distance=350, focalpoint=(0, 0, 20))
+
+# %%
+# Simulate a new data frame arriving: call
+# :meth:`~mne.viz.LayeredMesh.update_overlay` on the **same** brain to replace
+# the scalars in-place — no new mesh, no new actor, no pipeline rebuild.
+
+# we create a new brain here for comparison purposes
+brain_update = mne.viz.Brain(
+    "sample", subjects_dir=subjects_dir, hemi="lh", **brain_kwargs
+)
+brain_update.add_data(
+    data_t0, hemi="lh", fmin=0, fmax=1, colormap="viridis", smoothing_steps=5
+)
+brain_update.show_view(azimuth=190, elevation=70, distance=350, focalpoint=(0, 0, 20))
+data_t1 = coords[:, 1]
+data_t1 = (data_t1 - data_t1.min()) / (data_t1.max() - data_t1.min())
+mesh = brain_update.layered_meshes["lh"]
+mesh.update_overlay(name="data", scalars=data_t1)
+mesh.update()
+
 # %%
 # Use per-vertex opacity for distributed data
 # --------------------------------------------