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. 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

Activity values are spread from the 10 242 ico-5 source vertices to all 163 842 fsaverage surface vertices via nearest-neighbour interpolation, giving a smooth spatial appearance.

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, ...])
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_display_mode(mode)	Switch the display mode label and reset clim to sensible defaults.
set_surface(surf)	Switch the cortical surface geometry.
stop_recording()	Stop recording and finalise the video file.
update(stc[, mode, interval])	Animate the brain from a source time-course estimate.
update_from_arrays(lh_scalars, rh_scalars[, ...])	Update the brain display from pre-computed per-source-vertex scalars.
write_frame_if_recording()	Capture a video frame if recording is active (no-op otherwise).

Attributes

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.

property custom_band: tuple[float, float] | None

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

Read this in the acquisition loop alongside display_mode to decide which frequency range to pass to update_from_arrays(). When not None it overrides the built-in band labels.

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 pre-computed per-source-vertex scalars.

Source values (10 242 per hemisphere) are spread to all 163 842 surface vertices via nearest-neighbour interpolation.

Parameters:

lh_scalarsndarray, shape (10242,)

Activity values for left-hemisphere source vertices.

rh_scalarsndarray, shape (10242,)

Activity values for right-hemisphere source vertices.

modestr, default “power”

Kept for API symmetry; unused internally.

deferredbool, default False

If True, skip the immediate render() call.

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

Animate the brain from a source time-course estimate.

Parameters:

stcmne.SourceEstimate

Source estimate returned by apply_inverse_raw or similar.

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

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

intervalfloat, default 0.05

Seconds to pause between frame updates.

set_display_mode(mode: str) → None

Switch the display mode label and reset clim to sensible defaults.

The display mode is a label only — it tells both the operator and the visualisation what kind of values are being streamed in. Configure record_main() with the matching modality to pass the correct data.

Parameters:

modestr

One of _DISPLAY_MODES. Choosing a band-power mode will also set the colour-range (clim) to a typical power scale; choosing “Source Activation” restores the activation scale.

Notes

For band power modes pass per-source-vertex spectral power (e.g., from modality="source_power") to update_from_arrays(). For activation mode pass eLORETA / dSPM amplitude values from update() (stc from MNE inverse operator).

property display_mode: str

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

Read this in the acquisition loop to decide which modality to compute and pass to update_from_arrays().

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='4861751520'>

The underlying pyvistaqt.BackgroundPlotter instance.

property surf: str

Currently displayed surface geometry name.