mne_rt.viz.BrainPlot

class mne_rt.viz.BrainPlot(subjects_fs_dir: str | Path, clim: tuple[float, float] = (0.0, 0.6), hemi_distance: float = 20.0, surf: str = 'inflated', cmap: str = 'hot', opacity: float = 0.6, window_size: tuple[int, int] = (1600, 1000), display_smoothing: float = 0.3, verbose: bool | str | None = None)

Bases: object

Interactive real-time 3D brain activation display.

Renders bilateral fsaverage cortical surfaces with a colour-mapped activity overlay and a Qt control panel docked on the right. Designed to run alongside NFPlot inside a shared Qt event loop — call update_from_arrays() or update() from the acquisition thread’s pump timer.

Parameters:

subjects_fs_dirstr | Path

FreeSurfer subjects directory. The MNE-bundled fsaverage template is used automatically (auto-downloaded on first use); this path is accepted for API compatibility.

climtuple of float, default (0.0, 0.6)

Initial (min, max) colour-map range for the activity overlay.

hemi_distancefloat, default 20.0

Gap in mm between the medial walls of the two hemispheres.

surf{“inflated”, “pial”, “white”, “sphere”}, default “inflated”

Initial cortical surface geometry to display.

cmapstr, default “hot”

Initial colour map name. Must be one of ["hot", "plasma", "viridis", "Reds", "YlOrRd", "RdBu_r"].

opacityfloat, default 0.6

Initial opacity of the activity overlay (0 = transparent, 1 = opaque).

window_sizetuple of int, default (1600, 1000)

Width × height of the render window in pixels.

display_smoothingfloat, default 0.3

EMA factor applied to the per-vertex activation arrays before each render, in (0, 1]. 1.0 disables smoothing; lower values blend consecutive frames so the cortical map transitions smoothly instead of jumping between analysis windows.

verbosebool | str | None, default None

Verbosity level.

See also

mne_rt.viz.NFPlot

Scrolling real-time NF signal plot.

mne_rt.RTStream.record_main

Main NF loop that drives both plots.

Notes

The cortex is drawn at the resolution of an ico-5 source space: the 10 242 vertices per hemisphere the activity is estimated on, which are the first 10 242 of fsaverage’s. Values are interpolated across each triangle. The full 163 842-vertex surface made every update upload sixteen times more data to the GPU for no extra information, about 0.2 s per frame.

Added in version 1.0.0.

__init__(subjects_fs_dir: str | Path, clim: tuple[float, float] = (0.0, 0.6), hemi_distance: float = 20.0, surf: str = 'inflated', cmap: str = 'hot', opacity: float = 0.6, window_size: tuple[int, int] = (1600, 1000), display_smoothing: float = 0.3, verbose: bool | str | None = None) → None

Methods

__init__(subjects_fs_dir[, clim, ...])
clear_custom_band()	Go back to the display mode's own band.
record_video([path])	Start recording the brain display to an MP4 video file.
reset_activity()	Zero out all activity scalars and refresh the display.
screenshot([path])	Save a PNG screenshot of the current brain view.
set_band(band)	Show activation (None) or source power in band, in Hz.
set_custom_band(lo, hi)	Show source power in lo–hi Hz, from the next window on.
set_display_mode(mode)	Choose what the display shows, from the next window on.
set_surface(surf)	Switch the cortical surface geometry.
stop_recording()	Stop recording and finalise the video file.
update(stc[, mode])	Show one frame of a surface source estimate on fsaverage.
update_from_arrays(lh_scalars, rh_scalars[, ...])	Update the brain display from per-source-vertex values.
write_frame_if_recording()	Capture a video frame if recording is active (no-op otherwise).

Attributes

band	What to compute for the display: a band in Hz, or None for activation.
custom_band	Active custom frequency band (lo, hi) in Hz, or None.
display_mode	Current display mode string (e.g. "Alpha Power  (8–13 Hz)").
plotter	The underlying pyvistaqt.BackgroundPlotter instance.
surf	Currently displayed surface geometry name.

set_custom_band(lo: float, hi: float) → None

Show source power in lo–hi Hz, from the next window on.

Parameters:

lo, hifloat

Band edges in Hz, lo < hi.

set_band(band: tuple[float, float] | None) → None

Show activation (None) or source power in band, in Hz.

A band that one of the display modes covers selects that mode; any other becomes a custom band.

clear_custom_band() → None

Go back to the display mode’s own band.

property custom_band: tuple[float, float] | None

Active custom frequency band (lo, hi) in Hz, or None.

property band: tuple[float, float] | None

What to compute for the display: a band in Hz, or None for activation.

The custom band when one is set, else the display mode’s. record_main() reads it for every window, so the controls change what is computed, not just the label.

set_surface(surf: str) → None

Switch the cortical surface geometry.

Parameters:

surf{“inflated”, “pial”, “white”, “sphere”}

Target surface geometry.

update_from_arrays(lh_scalars: ndarray, rh_scalars: ndarray, mode: str = 'power', deferred: bool = False) → None

Update the brain display from per-source-vertex values.

Parameters:

lh_scalars, rh_scalarsndarray, shape (10242,)

One value per ico-5 vertex of each hemisphere (NaN where there is none, which is drawn without activity).

modestr, default “power”

Kept for API symmetry; unused internally.

deferredbool, default False

If True, skip the immediate render() call.

update(stc, mode: str = 'power') → None

Show one frame of a surface source estimate on fsaverage.

Parameters:

stcmne.SourceEstimate

On an fsaverage ico-5 (or coarser) surface source space.

mode{“power”, “activation”}, default “power”

"power" displays mean squared amplitude; "activation" displays the time-averaged amplitude.

set_display_mode(mode: str) → None

Choose what the display shows, from the next window on.

Parameters:

modestr

One of _DISPLAY_MODES: "Source Activation", or source power in one of the named bands (see band). Clears any custom band.

property display_mode: str

Current display mode string (e.g. "Alpha Power  (8–13 Hz)").

"Custom  lo–hi Hz" while a custom band is set. What is computed is band.

reset_activity() → None

Zero out all activity scalars and refresh the display.

record_video(path: str | Path | None = None) → Path

Start recording the brain display to an MP4 video file.

Parameters:

pathstr | Path | None, default None

Destination file. Defaults to ~/ant_brain_<timestamp>.mp4.

Returns:

pathPath

stop_recording() → Path | None

Stop recording and finalise the video file.

Returns:

pathPath | None

write_frame_if_recording() → None

Capture a video frame if recording is active (no-op otherwise).

screenshot(path: str | Path | None = None) → Path

Save a PNG screenshot of the current brain view.

Parameters:

pathstr | Path | None, default None

Destination file. Defaults to ~/ant_brain_<timestamp>.png.

Returns:

pathPath

property plotter: <MagicMock name='mock.BackgroundPlotter' id='140324714477712'>

The underlying pyvistaqt.BackgroundPlotter instance.

property surf: str

Currently displayed surface geometry name.