PySourceviz 0.1.0__py3-none-any.whl

pysourceviz/plotting.py

@@ -0,0 +1,1718 @@
+"""Cortical source-estimate plotting for PySourceviz."""
+
+from __future__ import annotations
+
+import importlib
+import inspect
+import math
+import os
+import re
+import sys
+import warnings
+from dataclasses import dataclass
+from functools import lru_cache
+from numbers import Integral, Real
+from pathlib import Path
+from typing import Any, Literal
+
+import mne
+import numpy as np
+from nibabel.freesurfer.io import read_morph_data
+
+
+_import_module = importlib.import_module
+_NILEARN_SULC_RANGE = (0.03, 0.22)
+
+
+def _validate_choice(name: str, value: str, allowed: tuple[str, ...]) -> None:
+    if value not in allowed:
+        choices = ", ".join(repr(choice) for choice in allowed)
+        raise ValueError(f"{name} must be one of {choices}; got {value!r}.")
+
+
+def _finite_real(name: str, value: object) -> float:
+    if isinstance(value, bool) or not isinstance(value, Real):
+        raise TypeError(f"{name} must be a finite real number; got {value!r}.")
+    result = float(value)
+    if not math.isfinite(result):
+        raise ValueError(f"{name} must be finite; got {value!r}.")
+    return result
+
+
+def _validate_time_selection(
+    time: float | Literal["peak"] | None,
+    time_window: tuple[float, float] | None,
+) -> None:
+    if time is not None and time_window is not None:
+        raise ValueError("time and time_window are mutually exclusive.")
+    if time is not None:
+        if isinstance(time, str):
+            if time != "peak":
+                raise ValueError("time must be a finite number, 'peak', or None.")
+        else:
+            _finite_real("time", time)
+    if time_window is not None:
+        if not isinstance(time_window, tuple) or len(time_window) != 2:
+            raise TypeError("time_window must be a two-item tuple.")
+        start = _finite_real("time_window start", time_window[0])
+        stop = _finite_real("time_window stop", time_window[1])
+        if start > stop:
+            raise ValueError("time_window start must not exceed its stop.")
+
+
+def _validate_positive_int_pair(
+    name: str,
+    value: tuple[int, int],
+) -> tuple[int, int]:
+    if not isinstance(value, tuple) or len(value) != 2:
+        raise TypeError(f"{name} must be a two-item tuple of positive integers.")
+    if any(
+        isinstance(item, bool) or not isinstance(item, Integral) for item in value
+    ):
+        raise TypeError(f"{name} must contain positive integers.")
+    result = (int(value[0]), int(value[1]))
+    if any(item <= 0 for item in result):
+        raise ValueError(f"{name} values must be positive.")
+    return result
+
+
+def _validate_smoothing_steps(
+    value: int | Literal["nearest"] | None,
+) -> int | Literal["nearest"] | None:
+    if value is None:
+        return None
+    if isinstance(value, str):
+        if value == "nearest":
+            return value
+        raise ValueError(
+            "smoothing_steps must be None, 'nearest', or a non-negative "
+            f"integer; got {value!r}."
+        )
+    if isinstance(value, bool) or not isinstance(value, Integral):
+        raise TypeError(
+            "smoothing_steps must be None, 'nearest', or a non-negative "
+            f"integer; got {value!r}."
+        )
+    result = int(value)
+    if result < 0:
+        raise ValueError("smoothing_steps must be non-negative.")
+    return result
+
+
+def _resolve_output_and_show(
+    output: str | Path | None,
+    show: bool | None,
+) -> tuple[Path | None, bool]:
+    if output is not None and not isinstance(output, (str, os.PathLike)):
+        raise TypeError("output must be a string, path-like object, or None.")
+    if show is not None and not isinstance(show, bool):
+        raise TypeError("show must be a bool or None.")
+    output_path = Path(output) if output is not None else None
+    return output_path, (output_path is None if show is None else show)
+
+
+def _validate_phase_one_options(
+    *,
+    subjects_dir: str | Path,
+    backend: str,
+    surface: str,
+    time: float | str | None,
+    time_window: tuple[float, float] | None,
+    reduce: str,
+    mode: str,
+    robust_percentile: float,
+    layout: str,
+    output: str | Path | None,
+    size: tuple[int, int] | None,
+    scale: tuple[int, int],
+    show: bool | None,
+) -> None:
+    if not isinstance(subjects_dir, (str, os.PathLike)):
+        raise TypeError("subjects_dir must be a non-empty path-like value.")
+    if isinstance(subjects_dir, str) and not subjects_dir.strip():
+        raise ValueError("subjects_dir must not be empty.")
+    _validate_choice("backend", backend, ("brainspace", "nilearn"))
+    _validate_choice("surface", surface, ("inflated", "pial", "white"))
+    _validate_choice("layout", layout, ("row", "grid"))
+    _validate_choice("mode", mode, ("magnitude", "signed"))
+    _validate_choice("reduce", reduce, ("mean", "rms"))
+    _validate_time_selection(time, time_window)
+    percentile = _finite_real("robust_percentile", robust_percentile)
+    if not 0.0 < percentile <= 100.0:
+        raise ValueError("robust_percentile must be in the interval (0, 100].")
+    if size is not None:
+        _validate_positive_int_pair("size", size)
+    _validate_positive_int_pair("scale", scale)
+    _resolve_output_and_show(output, show)
+
+
+def _classify_stc(stc: Any) -> str:
+    kinds = (
+        (mne.SourceEstimate, "scalar"),
+        (mne.VectorSourceEstimate, "vector"),
+        (mne.MixedSourceEstimate, "mixed"),
+        (mne.MixedVectorSourceEstimate, "mixed-vector"),
+    )
+    if isinstance(stc, (mne.VolSourceEstimate, mne.VolVectorSourceEstimate)):
+        raise TypeError(
+            "PySourceviz v0.1 requires a real cortical surface source "
+            "estimate; volume-only STCs are not supported."
+        )
+    for cls, kind in kinds:
+        if isinstance(stc, cls):
+            if np.iscomplexobj(stc.data):
+                raise TypeError(
+                    "PySourceviz v0.1 requires real data; complex-valued "
+                    "STCs are not supported."
+                )
+            return kind
+    raise TypeError(
+        "PySourceviz v0.1 requires a real cortical surface SourceEstimate, "
+        "VectorSourceEstimate, or mixed equivalent."
+    )
+
+
+def _copy_surface_stc(
+    stc: mne.SourceEstimate,
+    data: np.ndarray,
+    *,
+    tmin: float | None = None,
+) -> mne.SourceEstimate:
+    return mne.SourceEstimate(
+        np.array(data, dtype=float, copy=True),
+        [
+            np.array(vertices, dtype=int, copy=True)
+            for vertices in stc.vertices
+        ],
+        tmin=float(stc.tmin if tmin is None else tmin),
+        tstep=float(stc.tstep),
+        subject=stc.subject,
+    )
+
+
+def _normalize_surface_stc(stc: Any, mode: str) -> mne.SourceEstimate:
+    kind = _classify_stc(stc)
+    working = stc.copy()
+    if kind in ("mixed", "mixed-vector"):
+        working = working.surface()
+    if kind in ("vector", "mixed-vector"):
+        working = working.magnitude()
+    data = np.asarray(working.data)
+    if mode == "magnitude":
+        data = np.abs(data)
+    return _copy_surface_stc(working, data)
+
+
+@dataclass(frozen=True)
+class _TimeSummary:
+    stc: mne.SourceEstimate
+    selection: str
+    selected_time: float | None
+    requested_window: tuple[float, float] | None
+    sampled_window: tuple[float, float] | None
+    reduce: str | None
+
+
+def _summarize_time(
+    stc: mne.SourceEstimate,
+    time: float | str | None,
+    time_window: tuple[float, float] | None,
+    reduce: str,
+) -> _TimeSummary:
+    times = np.asarray(stc.times, dtype=float)
+    if time is None and time_window is None:
+        if times.size != 1:
+            raise ValueError(
+                "STC has multiple time samples; specify time or time_window."
+            )
+        selected_time = float(times[0])
+        one_time = _copy_surface_stc(
+            stc,
+            stc.data[:, [0]],
+            tmin=selected_time,
+        )
+        return _TimeSummary(
+            one_time,
+            "single",
+            selected_time,
+            None,
+            None,
+            None,
+        )
+
+    if time == "peak":
+        score = np.abs(np.asarray(stc.data, dtype=float))
+        finite = np.isfinite(score)
+        if not finite.any():
+            raise ValueError(
+                "time='peak' requires at least one finite source value."
+            )
+        score = np.where(finite, score, -np.inf)
+        index = int(np.unravel_index(np.argmax(score), score.shape)[1])
+        selected_time = float(times[index])
+        one_time = _copy_surface_stc(
+            stc,
+            stc.data[:, [index]],
+            tmin=selected_time,
+        )
+        return _TimeSummary(
+            one_time,
+            "peak",
+            selected_time,
+            None,
+            None,
+            None,
+        )
+
+    if time is not None:
+        requested_time = float(time)
+        distances = np.abs(times - requested_time)
+        tolerance = (
+            np.finfo(float).eps
+            * max(1.0, abs(requested_time), float(np.max(np.abs(times))))
+            * 8
+        )
+        candidates = np.flatnonzero(
+            distances <= float(np.min(distances)) + tolerance
+        )
+        index = int(candidates[0])
+        selected_time = float(times[index])
+        one_time = _copy_surface_stc(
+            stc,
+            stc.data[:, [index]],
+            tmin=selected_time,
+        )
+        return _TimeSummary(
+            one_time,
+            "time",
+            selected_time,
+            None,
+            None,
+            None,
+        )
+
+    start, stop = (float(value) for value in time_window)
+    if start > stop:
+        raise ValueError("time_window start must not exceed its stop.")
+    tolerance = (
+        np.finfo(float).eps
+        * max(1.0, float(np.max(np.abs(times))))
+        * 8
+    )
+    if start < times[0] - tolerance or stop > times[-1] + tolerance:
+        raise ValueError(
+            f"time_window {(start, stop)!r} is outside STC coverage "
+            f"[{times[0]}, {times[-1]}]."
+        )
+    mask = (times >= start - tolerance) & (times <= stop + tolerance)
+    if not np.any(mask):
+        raise ValueError("time_window does not contain an STC sample.")
+    selected = np.asarray(stc.data[:, mask], dtype=float)
+    if reduce == "mean":
+        data = selected.mean(axis=1)
+    else:
+        data = np.sqrt(np.mean(np.square(selected), axis=1))
+    sampled_times = times[mask]
+    representative_time = float(sampled_times.mean())
+    one_time = _copy_surface_stc(
+        stc,
+        data[:, np.newaxis],
+        tmin=representative_time,
+    )
+    return _TimeSummary(
+        one_time,
+        "window",
+        None,
+        (start, stop),
+        (float(sampled_times[0]), float(sampled_times[-1])),
+        reduce,
+    )
+
+
+_PERCENT_THRESHOLD = re.compile(
+    r"\s*(?:\d+(?:\.\d*)?|\.\d+)\s*%\s*"
+)
+_ACTIVATION_OPACITY = 0.72
+
+
+def _finite_sparse_values(
+    values: np.ndarray,
+    *,
+    absolute: bool = False,
+) -> np.ndarray:
+    result = np.asarray(values, dtype=float).ravel()
+    result = result[np.isfinite(result)]
+    if absolute:
+        result = np.abs(result)
+    if result.size == 0:
+        raise ValueError(
+            "Display statistics require at least one finite sparse value."
+        )
+    return result
+
+
+def _parse_threshold(
+    threshold: float | str | None,
+    sparse_values: np.ndarray,
+) -> float | None:
+    if threshold is None:
+        return None
+    if isinstance(threshold, str):
+        if _PERCENT_THRESHOLD.fullmatch(threshold) is None:
+            raise ValueError(
+                "threshold must be a non-negative number or a percentage "
+                "such as '75%'."
+            )
+        percentile = float(threshold.strip()[:-1])
+        if not 0.0 <= percentile <= 100.0:
+            raise ValueError(
+                "threshold percentile must be in the interval [0, 100]."
+            )
+        values = _finite_sparse_values(sparse_values, absolute=True)
+        return float(np.percentile(values, percentile))
+    value = _finite_real("threshold", threshold)
+    if value < 0.0:
+        raise ValueError("threshold must be non-negative.")
+    return value
+
+
+@dataclass(frozen=True)
+class _ColorScale:
+    color_range: tuple[float, float]
+    control_points: tuple[float, float, float] | None
+
+
+def _resolve_color_scale(
+    clim: str | tuple[float, float] | dict[str, Any],
+    robust_percentile: float,
+    mode: str,
+    threshold: float | None,
+    sparse_values: np.ndarray,
+) -> _ColorScale:
+    values = _finite_sparse_values(
+        sparse_values,
+        absolute=(mode == "signed"),
+    )
+    control_points = None
+    if isinstance(clim, str):
+        if clim != "robust":
+            raise ValueError("clim string value must be 'robust'.")
+        vmax = float(np.percentile(values, robust_percentile))
+        if mode == "signed":
+            bounds = (-vmax, vmax)
+        else:
+            bounds = (
+                0.0 if threshold is None else threshold,
+                vmax,
+            )
+    elif isinstance(clim, dict):
+        allowed_keys = {"kind", "lims", "pos_lims"}
+        unsupported = set(clim).difference(allowed_keys)
+        if unsupported:
+            names = ", ".join(sorted(str(key) for key in unsupported))
+            raise ValueError(f"clim contains unsupported key(s): {names}.")
+        has_lims = "lims" in clim
+        has_pos_lims = "pos_lims" in clim
+        if has_lims + has_pos_lims != 1:
+            raise ValueError(
+                "clim must contain exactly one of 'lims' and 'pos_lims'."
+            )
+        required_key = "pos_lims" if mode == "signed" else "lims"
+        if required_key not in clim:
+            raise ValueError(
+                f"{mode} mode requires clim['{required_key}']."
+            )
+        kind = clim.get("kind", "percent")
+        if kind not in ("percent", "value"):
+            raise ValueError("clim kind must be 'percent' or 'value'.")
+        requested = clim[required_key]
+        if (
+            not isinstance(requested, (list, tuple, np.ndarray))
+            or len(requested) != 3
+        ):
+            raise TypeError(
+                f"clim['{required_key}'] must contain three controls."
+            )
+        controls = np.array(
+            [
+                _finite_real(f"clim {required_key} control", item)
+                for item in requested
+            ],
+            dtype=float,
+        )
+        if np.any(controls < 0.0):
+            raise ValueError("clim controls must be non-negative.")
+        if np.any(np.diff(controls) < 0.0):
+            raise ValueError(
+                "clim controls must be monotonically increasing or equal."
+            )
+        if kind == "percent":
+            if np.any(controls > 100.0):
+                raise ValueError(
+                    "clim percent controls must be in the interval [0, 100]."
+                )
+            controls = np.percentile(values, controls)
+        fmin, fmid, fmax = (float(item) for item in controls)
+        if fmax <= fmin:
+            raise ValueError(
+                "Resolved clim lower and upper controls must be distinct."
+            )
+        epsilon = 1e-5 * (fmax - fmin)
+        if fmid <= fmin:
+            fmid = fmin + epsilon
+        elif fmid >= fmax:
+            fmid = fmax - epsilon
+        control_points = (fmin, fmid, fmax)
+        bounds = (-fmax, fmax) if mode == "signed" else (fmin, fmax)
+    else:
+        if not isinstance(clim, tuple) or len(clim) != 2:
+            raise TypeError(
+                "clim must be 'robust', a two-item tuple, or an MNE-style "
+                "dictionary."
+            )
+        lower = _finite_real("clim lower", clim[0])
+        upper = _finite_real("clim upper", clim[1])
+        if upper <= lower:
+            raise ValueError(
+                "clim upper bound must exceed its lower bound."
+            )
+        if mode == "magnitude" and lower < 0.0:
+            raise ValueError(
+                "magnitude clim must have a non-negative lower bound."
+            )
+        if mode == "signed":
+            limit = max(abs(lower), abs(upper))
+            bounds = (-limit, limit)
+        else:
+            bounds = (lower, upper)
+    if bounds[1] <= bounds[0]:
+        raise ValueError(
+            "Resolved color range must have strictly increasing bounds."
+        )
+    if threshold is not None and threshold >= bounds[1]:
+        raise ValueError(
+            "threshold must be below the color-range upper bound."
+        )
+    return _ColorScale(
+        color_range=(float(bounds[0]), float(bounds[1])),
+        control_points=control_points,
+    )
+
+
+def _resolve_color_range(
+    clim: str | tuple[float, float] | dict[str, Any],
+    robust_percentile: float,
+    mode: str,
+    threshold: float | None,
+    sparse_values: np.ndarray,
+) -> tuple[float, float]:
+    return _resolve_color_scale(
+        clim,
+        robust_percentile,
+        mode,
+        threshold,
+        sparse_values,
+    ).color_range
+
+
+def _resolve_cmap(cmap: str | None, mode: str) -> str:
+    if cmap is not None and not isinstance(cmap, str):
+        raise TypeError("cmap must be a string or None.")
+    return cmap or ("Reds" if mode == "magnitude" else "RdBu_r")
+
+
+def _build_render_cmap(
+    cmap_name: str,
+    mode: str,
+    color_range: tuple[float, float],
+    control_points: tuple[float, float, float] | None,
+) -> str | Any:
+    if control_points is None:
+        return cmap_name
+    from matplotlib import colormaps
+    from matplotlib.colors import ListedColormap
+
+    fmin, fmid, fmax = control_points
+    vmin, vmax = color_range
+    samples = np.linspace(0.0, 1.0, 256)
+    if mode == "magnitude":
+        control_locations = np.array(
+            [fmin, fmid, fmax], dtype=float
+        )
+        control_locations = (control_locations - vmin) / (vmax - vmin)
+        palette_locations = np.array([0.0, 0.5, 1.0])
+        alpha_controls = np.array([0.0, _ACTIVATION_OPACITY, _ACTIVATION_OPACITY])
+    else:
+        control_locations = np.array(
+            [-fmax, -fmid, -fmin, 0.0, fmin, fmid, fmax],
+            dtype=float,
+        )
+        control_locations = (control_locations - vmin) / (vmax - vmin)
+        palette_locations = np.array(
+            [0.0, 0.25, 0.5, 0.5, 0.5, 0.75, 1.0]
+        )
+        alpha_controls = np.array(
+            [
+                _ACTIVATION_OPACITY,
+                _ACTIVATION_OPACITY,
+                0.0,
+                0.0,
+                0.0,
+                _ACTIVATION_OPACITY,
+                _ACTIVATION_OPACITY,
+            ]
+        )
+    palette_samples = np.interp(
+        samples,
+        control_locations,
+        palette_locations,
+    )
+    alpha_samples = np.interp(
+        samples,
+        control_locations,
+        alpha_controls,
+    )
+    rgba = np.asarray(colormaps[cmap_name](palette_samples), dtype=float)
+    rgba[:, 3] = alpha_samples
+    return ListedColormap(
+        rgba,
+        name=f"pysourceviz_{cmap_name}_control",
+    )
+
+
+def _expand_to_full_surface(
+    one_time_stc: mne.SourceEstimate,
+    template: str,
+    subjects_dir: str | Path,
+    smoothing_steps: int | Literal["nearest"] | None = None,
+) -> mne.SourceEstimate:
+    try:
+        morph = mne.compute_source_morph(
+            one_time_stc,
+            subject_from=template,
+            subject_to=template,
+            subjects_dir=str(subjects_dir),
+            spacing=None,
+            smooth=smoothing_steps,
+            warn=isinstance(smoothing_steps, Integral),
+        )
+        full_stc = morph.apply(one_time_stc)
+    except Exception as error:
+        raise RuntimeError(
+            f"Could not expand source data on template {template!r}."
+        ) from error
+    if (
+        not isinstance(full_stc, mne.SourceEstimate)
+        or len(full_stc.vertices) != 2
+    ):
+        raise TypeError(
+            "surface morph must return a scalar two-hemisphere "
+            "SourceEstimate."
+        )
+    return full_stc
+
+
+def _load_cortex_mask(
+    subjects_dir: str | Path,
+    template: str,
+    vertices: list[np.ndarray],
+) -> tuple[np.ndarray, np.ndarray]:
+    label_dir = Path(subjects_dir) / template / "label"
+    paths = (
+        label_dir / "lh.cortex.label",
+        label_dir / "rh.cortex.label",
+    )
+    missing = [path for path in paths if not path.is_file()]
+    if missing:
+        warnings.warn(
+            "Cortex label file(s) missing; medial-wall masking is disabled "
+            "for the affected hemisphere(s): "
+            + ", ".join(str(path) for path in missing),
+            RuntimeWarning,
+            stacklevel=2,
+        )
+    masks = []
+    for path, hemi_vertices in zip(paths, vertices):
+        if path.is_file():
+            label = mne.read_label(str(path))
+            masks.append(np.isin(hemi_vertices, label.vertices))
+        else:
+            masks.append(np.ones(len(hemi_vertices), dtype=bool))
+    return masks[0], masks[1]
+
+
+def _mask_dense_activation(
+    full_stc: mne.SourceEstimate,
+    threshold: float | None,
+    cortex_mask: tuple[np.ndarray, np.ndarray],
+) -> tuple[np.ndarray, np.ndarray]:
+    split = len(full_stc.vertices[0])
+    values = np.asarray(full_stc.data[:, 0], dtype=float)
+    activation = [values[:split].copy(), values[split:].copy()]
+    for hemi in range(2):
+        mask = np.asarray(cortex_mask[hemi], dtype=bool)
+        if mask.shape != activation[hemi].shape:
+            raise ValueError(
+                "cortex mask length must match full surface vertices."
+            )
+        if threshold is not None:
+            hidden = np.abs(activation[hemi]) < threshold
+            activation[hemi][hidden] = np.nan
+        activation[hemi][~mask] = np.nan
+    return activation[0], activation[1]
+
+
+@dataclass(frozen=True)
+class _PreparedSource:
+    activation: tuple[np.ndarray, np.ndarray]
+    sparse_values: np.ndarray
+    template: str
+    smoothing_steps: int | Literal["nearest"] | None
+    selection: str
+    selected_time: float | None
+    time_window: tuple[float, float] | None
+    sampled_time_window: tuple[float, float] | None
+    reduce: str | None
+    mode: str
+    threshold: float | None
+    color_range: tuple[float, float]
+    color_control_points: tuple[float, float, float] | None
+    cmap: str
+    render_cmap: Any
+
+
+@dataclass(frozen=True)
+class _HemisphereGeometry:
+    coordinates: np.ndarray
+    faces: np.ndarray
+    sulc: np.ndarray
+
+
+@dataclass(frozen=True)
+class _SurfaceGeometry:
+    lh: _HemisphereGeometry
+    rh: _HemisphereGeometry
+
+
+@dataclass(frozen=True)
+class _PanelSpec:
+    row: int
+    column: int
+    hemi: Literal["left", "right"]
+    view: Literal["lateral", "medial"]
+    label: str
+
+
+@dataclass(frozen=True)
+class _LayoutSpec:
+    surface_layout: list[list[str]]
+    views: list[list[str]]
+    label_text: dict[str, list[str]]
+    size: tuple[int, int]
+    shape: tuple[int, int]
+    panels: tuple[_PanelSpec, ...]
+
+
+def _normalize_sulc(sulc: np.ndarray) -> np.ndarray:
+    values = np.asarray(sulc, dtype=float)
+    finite = np.isfinite(values)
+    if not finite.any():
+        raise ValueError(
+            "sulc data must contain at least one finite value."
+        )
+    scale = float(np.percentile(np.abs(values[finite]), 95.0))
+    if scale == 0.0:
+        return np.zeros(values.shape, dtype=float)
+    clean = np.where(finite, values, 0.0)
+    return np.clip(clean / scale, -1.0, 1.0)
+
+
+def _readonly_array(array: np.ndarray, dtype: Any) -> np.ndarray:
+    result = np.array(array, dtype=dtype, copy=True)
+    result.setflags(write=False)
+    return result
+
+
+def _validate_hemisphere_geometry(
+    hemi: str,
+    coordinates: np.ndarray,
+    faces: np.ndarray,
+    sulc: np.ndarray,
+) -> _HemisphereGeometry:
+    coordinates = np.asarray(coordinates, dtype=float)
+    faces = np.asarray(faces)
+    sulc = np.asarray(sulc, dtype=float)
+    if coordinates.ndim != 2 or coordinates.shape[1] != 3:
+        raise ValueError(
+            f"{hemi} coordinates must have shape (n_vertices, 3)."
+        )
+    if not np.isfinite(coordinates).all():
+        raise ValueError(f"{hemi} coordinates must be finite.")
+    if faces.ndim != 2 or faces.shape[1] != 3:
+        raise ValueError(f"{hemi} faces must have shape (n_faces, 3).")
+    if not np.issubdtype(faces.dtype, np.integer):
+        raise ValueError(f"{hemi} faces must contain integer indices.")
+    if sulc.shape != (coordinates.shape[0],):
+        raise ValueError(
+            f"{hemi} sulc length {sulc.size} does not match surface "
+            f"vertex count {coordinates.shape[0]}."
+        )
+    if faces.size and (
+        int(faces.min()) < 0
+        or int(faces.max()) >= coordinates.shape[0]
+    ):
+        raise ValueError(
+            f"{hemi} faces contain out-of-range vertex indices."
+        )
+    return _HemisphereGeometry(
+        coordinates=_readonly_array(coordinates, float),
+        faces=_readonly_array(faces, int),
+        sulc=_readonly_array(_normalize_sulc(sulc), float),
+    )
+
+
+def _load_surface_geometry(
+    subjects_dir: str | Path,
+    template: str,
+    surface: str,
+) -> _SurfaceGeometry:
+    root = str(Path(subjects_dir).expanduser().resolve())
+    return _load_surface_geometry_cached(root, template, surface)
+
+
+@lru_cache(maxsize=16)
+def _load_surface_geometry_cached(
+    subjects_dir: str,
+    template: str,
+    surface: str,
+) -> _SurfaceGeometry:
+    surf_dir = Path(subjects_dir) / template / "surf"
+    paths = {
+        "lh_surface": surf_dir / f"lh.{surface}",
+        "rh_surface": surf_dir / f"rh.{surface}",
+        "lh_sulc": surf_dir / "lh.sulc",
+        "rh_sulc": surf_dir / "rh.sulc",
+    }
+    missing = [path for path in paths.values() if not path.is_file()]
+    if missing:
+        raise FileNotFoundError(
+            "Required FreeSurfer surface file(s) missing: "
+            + ", ".join(str(path) for path in missing)
+        )
+    hemispheres = []
+    for hemi in ("lh", "rh"):
+        coordinates, faces = mne.read_surface(
+            str(paths[f"{hemi}_surface"])
+        )
+        sulc = read_morph_data(str(paths[f"{hemi}_sulc"]))
+        hemispheres.append(
+            _validate_hemisphere_geometry(
+                hemi,
+                coordinates,
+                faces,
+                sulc,
+            )
+        )
+    return _SurfaceGeometry(
+        lh=hemispheres[0],
+        rh=hemispheres[1],
+    )
+
+
+def _configure_vtk_backend() -> None:
+    if (
+        sys.platform == "darwin"
+        and "VTK_DEFAULT_RENDER_WINDOW_TYPE" not in os.environ
+    ):
+        os.environ["VTK_DEFAULT_RENDER_WINDOW_TYPE"] = "Cocoa"
+
+
+@lru_cache(maxsize=1)
+def _brainspace_api() -> tuple[Any, Any, type]:
+    _configure_vtk_backend()
+    from brainspace.mesh.mesh_creation import build_polydata
+    from brainspace.plotting import plot_surf
+    from brainspace.plotting.utils import PTuple
+
+    return build_polydata, plot_surf, PTuple
+
+
+@lru_cache(maxsize=1)
+def _nilearn_api() -> tuple[Any, Any, Any, Any]:
+    """Import the optional Nilearn/Matplotlib renderer only on demand."""
+    try:
+        _import_module("nilearn")
+        pyplot = _import_module("matplotlib.pyplot")
+        figure_class = _import_module("matplotlib.figure").Figure
+        agg_canvas = _import_module(
+            "matplotlib.backends.backend_agg"
+        ).FigureCanvasAgg
+        nilearn_plotting = _import_module("nilearn.plotting")
+    except ImportError as error:
+        raise RuntimeError(
+            'backend="nilearn" requires the optional Nilearn renderer. '
+            'Install it with: python -m pip install "PySourceviz[nilearn]"'
+        ) from error
+    return (
+        pyplot,
+        nilearn_plotting.plot_surf_stat_map,
+        figure_class,
+        agg_canvas,
+    )
+
+
+@lru_cache(maxsize=1)
+def _cortex_cmap() -> Any:
+    from matplotlib import colormaps
+    from matplotlib.colors import LinearSegmentedColormap
+
+    soft_greys = colormaps["Greys_r"](np.linspace(0.72, 1.0, 256))
+    return LinearSegmentedColormap.from_list(
+        "pysourceviz_cortex",
+        soft_greys,
+        N=256,
+    )
+
+
+def _build_brainspace_meshes(
+    geometry: _SurfaceGeometry,
+    activation: tuple[np.ndarray, np.ndarray],
+) -> dict[str, Any]:
+    build_polydata, _, _ = _brainspace_api()
+    meshes = {}
+    for index, (hemi, hemi_geometry) in enumerate(
+        (("lh", geometry.lh), ("rh", geometry.rh))
+    ):
+        values = np.asarray(activation[index], dtype=float)
+        n_vertices = hemi_geometry.coordinates.shape[0]
+        if values.shape != (n_vertices,):
+            raise ValueError(
+                f"{hemi} activation length {values.size} does not match "
+                f"surface vertex count {n_vertices}."
+            )
+        mesh = build_polydata(
+            hemi_geometry.coordinates,
+            hemi_geometry.faces,
+        )
+        mesh.append_array(
+            hemi_geometry.sulc,
+            name="sulc",
+            at="p",
+        )
+        mesh.append_array(
+            values.copy(),
+            name="activation",
+            at="p",
+        )
+        meshes[hemi] = mesh
+    return meshes
+
+
+def _resolve_layout(
+    layout: str,
+    size: tuple[int, int] | None,
+    title: str | None,
+) -> _LayoutSpec:
+    # BrainSpace names global camera rotations, not hemisphere-relative
+    # anatomical views.  The right hemisphere therefore needs the
+    # complementary rotation name to match Nilearn's lateral/medial views.
+    if layout == "row":
+        surface_layout = [["lh", "lh", "rh", "rh"]]
+        views = [["lateral", "medial", "lateral", "medial"]]
+        label_text = {
+            "bottom": [
+                "LH lateral",
+                "LH medial",
+                "RH medial",
+                "RH lateral",
+            ]
+        }
+        default_size = (1600, 420)
+        shape = (1, 4)
+        panels = (
+            _PanelSpec(0, 0, "left", "lateral", "LH lateral"),
+            _PanelSpec(0, 1, "left", "medial", "LH medial"),
+            _PanelSpec(0, 2, "right", "medial", "RH medial"),
+            _PanelSpec(0, 3, "right", "lateral", "RH lateral"),
+        )
+    else:
+        surface_layout = [["lh", "rh"], ["lh", "rh"]]
+        views = [
+            ["lateral", "medial"],
+            ["medial", "lateral"],
+        ]
+        label_text = {
+            "bottom": ["LH", "RH"],
+            "left": ["Lateral", "Medial"],
+        }
+        default_size = (900, 760)
+        shape = (2, 2)
+        panels = (
+            _PanelSpec(0, 0, "left", "lateral", "LH lateral"),
+            _PanelSpec(0, 1, "right", "lateral", "RH lateral"),
+            _PanelSpec(1, 0, "left", "medial", "LH medial"),
+            _PanelSpec(1, 1, "right", "medial", "RH medial"),
+        )
+    if title is not None:
+        label_text["top"] = [title]
+    return _LayoutSpec(
+        surface_layout=surface_layout,
+        views=views,
+        label_text=label_text,
+        size=default_size if size is None else size,
+        shape=shape,
+        panels=panels,
+    )
+
+
+def _resolve_background(
+    background: str | tuple[float, float, float],
+) -> tuple[float, float, float]:
+    from matplotlib.colors import to_rgb
+
+    try:
+        resolved = to_rgb(background)
+    except (TypeError, ValueError) as error:
+        raise ValueError(
+            "background must be a valid color name or RGB triple."
+        ) from error
+    if len(resolved) != 3 or not all(
+        math.isfinite(float(value)) for value in resolved
+    ):
+        raise ValueError(
+            "background must resolve to three finite RGB values."
+        )
+    return tuple(float(value) for value in resolved)
+
+
+def _enforce_overlay_ranges(
+    plotter: Any,
+    color_range: tuple[float, float],
+) -> None:
+    view_count = 0
+    try:
+        renderer_groups = plotter.renderers.values()
+    except AttributeError as error:
+        raise RuntimeError(
+            "BrainSpace plotter does not expose renderer actors."
+        ) from error
+    for renderers in renderer_groups:
+        for renderer in renderers:
+            collection = renderer.actors.VTKObject
+            actor_count = int(collection.GetNumberOfItems())
+            if actor_count == 0:
+                continue
+            if actor_count != 2:
+                raise RuntimeError(
+                    "BrainSpace overlay compatibility requires exactly "
+                    "two actors in each brain view."
+                )
+            collection.InitTraversal()
+            sulc_actor = collection.GetNextActor()
+            activation_actor = collection.GetNextActor()
+            sulc_lut = sulc_actor.GetMapper().GetLookupTable()
+            activation_lut = (
+                activation_actor.GetMapper().GetLookupTable()
+            )
+            sulc_lut.SetRange(-1.0, 1.0)
+            activation_lut.SetRange(*color_range)
+            view_count += 1
+    if view_count != 4:
+        raise RuntimeError(
+            "BrainSpace overlay compatibility expected four brain-view "
+            f"actor groups; found {view_count}."
+        )
+
+
+def _build_brainspace_plotter(
+    meshes: dict[str, Any],
+    layout: _LayoutSpec,
+    prepared: _PreparedSource,
+    *,
+    background: tuple[float, float, float],
+    colorbar: bool,
+    units: str | None,
+    offscreen: bool,
+) -> Any:
+    _, plot_surf, PTuple = _brainspace_api()
+    control_points = getattr(prepared, "color_control_points", None)
+    render_cmap = getattr(prepared, "render_cmap", prepared.cmap)
+    activation_opacity = 1.0 if control_points is not None else 0.72
+    text_property = {
+        "fontSize": 14,
+        "bold": False,
+        "color": (0.0, 0.0, 0.0),
+    }
+    kwargs = {
+        "array_name": PTuple("sulc", "activation"),
+        "view": layout.views,
+        "color_bar": "right" if colorbar else None,
+        "color_range": PTuple((-1.0, 1.0), prepared.color_range),
+        "share": "both",
+        "label_text": layout.label_text,
+        "cmap": PTuple(_cortex_cmap(), render_cmap),
+        "nan_color": (0.0, 0.0, 0.0, 0.0),
+        "background": background,
+        "size": layout.size,
+        "return_plotter": True,
+        "suppress_warnings": True,
+        "offscreen": offscreen,
+        "actor__opacity": PTuple(1.0, activation_opacity),
+        "actor__forceOpaque": PTuple(True, False),
+        "actor__ambient": PTuple(0.3, 0.12),
+        "actor__specular": PTuple(0.08, 0.02),
+        "actor__diffuse": PTuple(0.7, 0.92),
+        "text__textScaleMode": "none",
+        "text__textProperty": text_property,
+        "cb__labelTextProperty": text_property,
+        "cb__titleTextProperty": text_property,
+    }
+    if colorbar and units:
+        kwargs["cb__title"] = units
+    plotter = plot_surf(meshes, layout.surface_layout, **kwargs)
+    _enforce_overlay_ranges(plotter, prepared.color_range)
+    return plotter
+
+
+def _resolve_png_output(
+    output: str | Path | None,
+) -> Path | None:
+    if output is None:
+        return None
+    path = Path(output)
+    if path.suffix != ".png":
+        raise ValueError("output must use the .png extension.")
+    return path
+
+
+def _validate_render_options(
+    *,
+    title: str | None,
+    units: str | None,
+    colorbar: bool,
+    transparent: bool,
+) -> None:
+    for name, value in (("title", title), ("units", units)):
+        if value is not None and not isinstance(value, str):
+            raise TypeError(f"{name} must be a string or None.")
+    if not isinstance(colorbar, bool):
+        raise TypeError("colorbar must be a bool.")
+    if not isinstance(transparent, bool):
+        raise TypeError("transparent must be a bool.")
+
+
+def _render_brainspace(
+    meshes: dict[str, Any],
+    layout: _LayoutSpec,
+    prepared: _PreparedSource,
+    *,
+    background: tuple[float, float, float],
+    colorbar: bool,
+    units: str | None,
+    output: Path | None,
+    scale: tuple[int, int],
+    transparent: bool,
+    show: bool,
+) -> Any | None:
+    if output is not None:
+        output.parent.mkdir(parents=True, exist_ok=True)
+        static_plotter = _build_brainspace_plotter(
+            meshes,
+            layout,
+            prepared,
+            background=background,
+            colorbar=colorbar,
+            units=units,
+            offscreen=True,
+        )
+        try:
+            static_plotter.screenshot(
+                str(output),
+                transparent_bg=transparent,
+                scale=scale,
+            )
+        finally:
+            static_plotter.close()
+    if show:
+        interactive_plotter = _build_brainspace_plotter(
+            meshes,
+            layout,
+            prepared,
+            background=background,
+            colorbar=colorbar,
+            units=units,
+            offscreen=False,
+        )
+        interactive_plotter.show(interactive=True)
+        return interactive_plotter
+    if output is None:
+        return _build_brainspace_plotter(
+            meshes,
+            layout,
+            prepared,
+            background=background,
+            colorbar=colorbar,
+            units=units,
+            offscreen=True,
+        )
+    return None
+
+
+def _nilearn_sulc_map(sulc: np.ndarray) -> np.ndarray:
+    """Map normalized sulcal depth to a textured white/light-gray cortex."""
+    values = np.asarray(sulc, dtype=float)
+    normalized = (np.clip(values, -1.0, 1.0) + 1.0) / 2.0
+    lower, upper = _NILEARN_SULC_RANGE
+    return lower + normalized * (upper - lower)
+
+
+def _render_nilearn(
+    geometry: _SurfaceGeometry,
+    layout: _LayoutSpec,
+    prepared: _PreparedSource,
+    *,
+    background: tuple[float, float, float],
+    colorbar: bool,
+    units: str | None,
+    output: Path | None,
+    scale: tuple[int, int],
+    transparent: bool,
+    show: bool,
+) -> Any | None:
+    """Render prepared vertex data with Nilearn's Matplotlib surface API."""
+    pyplot, plot_surf_stat_map, figure_class, agg_canvas = _nilearn_api()
+    logical_inches = (
+        layout.size[0] / 100.0,
+        layout.size[1] / 100.0,
+    )
+    figure_kwargs = {
+        "figsize": logical_inches,
+        "dpi": 100,
+        "facecolor": background,
+    }
+    if show:
+        figure = pyplot.figure(**figure_kwargs)
+    else:
+        figure = figure_class(**figure_kwargs)
+        agg_canvas(figure)
+    keep_open = False
+    try:
+        figure.patch.set_facecolor(background)
+        title = layout.label_text.get("top", [None])[0]
+        if title is not None:
+            figure.suptitle(title, fontsize=14, y=0.98)
+
+        hemispheres = {
+            "left": (
+                geometry.lh,
+                np.asarray(prepared.activation[0], dtype=float),
+            ),
+            "right": (
+                geometry.rh,
+                np.asarray(prepared.activation[1], dtype=float),
+            ),
+        }
+        try:
+            supports_darkness = "darkness" in inspect.signature(
+                plot_surf_stat_map
+            ).parameters
+        except (TypeError, ValueError):
+            supports_darkness = False
+        control_points = prepared.color_control_points
+        render_cmap = getattr(prepared, "render_cmap", prepared.cmap)
+        rows, columns = layout.shape
+        axes = []
+        for panel in layout.panels:
+            hemi_geometry, activation = hemispheres[panel.hemi]
+            expected = (hemi_geometry.coordinates.shape[0],)
+            if activation.shape != expected:
+                raise ValueError(
+                    f"{panel.hemi} activation shape {activation.shape} does "
+                    f"not match surface vertex shape {expected}."
+                )
+            index = panel.row * columns + panel.column + 1
+            axis = figure.add_subplot(
+                rows,
+                columns,
+                index,
+                projection="3d",
+            )
+            axis.set_facecolor(background)
+            axes.append(axis)
+            plot_kwargs = {
+                "surf_mesh": [
+                    hemi_geometry.coordinates,
+                    hemi_geometry.faces,
+                ],
+                "stat_map": activation,
+                "bg_map": _nilearn_sulc_map(hemi_geometry.sulc),
+                "hemi": panel.hemi,
+                "view": panel.view,
+                "engine": "matplotlib",
+                "cmap": render_cmap,
+                "colorbar": False,
+                "avg_method": "mean",
+                "threshold": None,
+                "alpha": 1.0,
+                "bg_on_data": control_points is None,
+                "vmin": prepared.color_range[0],
+                "vmax": prepared.color_range[1],
+                "symmetric_cbar": prepared.mode == "signed",
+                "cbar_tick_format": "%.2g",
+                "title": panel.label,
+                "axes": axis,
+                "figure": figure,
+            }
+            if supports_darkness:
+                plot_kwargs["darkness"] = None
+            plot_surf_stat_map(**plot_kwargs)
+
+        if rows == 1:
+            figure.subplots_adjust(
+                left=0.0,
+                right=0.94 if colorbar else 0.99,
+                bottom=0.0,
+                top=0.88 if title else 0.98,
+                wspace=-0.08,
+            )
+        else:
+            figure.subplots_adjust(
+                left=0.0,
+                right=0.92 if colorbar else 0.98,
+                bottom=0.0,
+                top=0.91 if title else 0.98,
+                wspace=-0.12,
+                hspace=-0.16,
+            )
+
+        if colorbar:
+            normalizer = pyplot.Normalize(
+                vmin=prepared.color_range[0],
+                vmax=prepared.color_range[1],
+            )
+            mappable = pyplot.cm.ScalarMappable(
+                norm=normalizer,
+                cmap=render_cmap,
+            )
+            mappable.set_array([])
+            colorbar_kwargs: dict[str, Any] = {
+                "ax": axes,
+                "fraction": 0.018,
+                "pad": 0.01,
+                "shrink": 0.65,
+                "aspect": 18,
+            }
+            if control_points is not None:
+                fmin, fmid, fmax = control_points
+                if prepared.mode == "signed":
+                    colorbar_kwargs["ticks"] = (
+                        -fmax,
+                        -fmid,
+                        -fmin,
+                        0.0,
+                        fmin,
+                        fmid,
+                        fmax,
+                    )
+                else:
+                    colorbar_kwargs["ticks"] = control_points
+            shared_colorbar = figure.colorbar(mappable, **colorbar_kwargs)
+            if units:
+                shared_colorbar.set_label(units)
+
+        if output is not None:
+            output.parent.mkdir(parents=True, exist_ok=True)
+            original_size = tuple(
+                float(value) for value in figure.get_size_inches()
+            )
+            raster_scale = min(scale)
+            output_dpi = 100 * raster_scale
+            figure.set_size_inches(
+                layout.size[0] * scale[0] / output_dpi,
+                layout.size[1] * scale[1] / output_dpi,
+                forward=False,
+            )
+            try:
+                figure.savefig(
+                    output,
+                    dpi=output_dpi,
+                    facecolor=background,
+                    transparent=transparent,
+                )
+            finally:
+                figure.set_size_inches(
+                    original_size[0],
+                    original_size[1],
+                    forward=False,
+                )
+        if show:
+            pyplot.show()
+            keep_open = True
+            return figure
+        if output is None:
+            keep_open = True
+            return figure
+        return None
+    finally:
+        if not keep_open:
+            pyplot.close(figure)
+
+
+def _prepare_source_data(
+    stc: Any,
+    *,
+    subjects_dir: str | Path,
+    template: str,
+    smoothing_steps: int | Literal["nearest"] | None = None,
+    time: float | str | None,
+    time_window: tuple[float, float] | None,
+    reduce: str,
+    mode: str,
+    threshold: float | str | None,
+    clim: str | tuple[float, float] | dict[str, Any],
+    robust_percentile: float,
+    cmap: str | None,
+) -> _PreparedSource:
+    resolved_smoothing_steps = _validate_smoothing_steps(smoothing_steps)
+    normalized = _normalize_surface_stc(stc, mode)
+    summary = _summarize_time(
+        normalized,
+        time,
+        time_window,
+        reduce,
+    )
+    sparse_values = np.asarray(
+        summary.stc.data[:, 0],
+        dtype=float,
+    ).copy()
+    parsed_threshold = _parse_threshold(threshold, sparse_values)
+    color_scale = _resolve_color_scale(
+        clim,
+        robust_percentile,
+        mode,
+        parsed_threshold,
+        sparse_values,
+    )
+    full_stc = _expand_to_full_surface(
+        summary.stc,
+        template,
+        subjects_dir,
+        resolved_smoothing_steps,
+    )
+    cortex_mask = _load_cortex_mask(
+        subjects_dir,
+        template,
+        full_stc.vertices,
+    )
+    activation = _mask_dense_activation(
+        full_stc,
+        parsed_threshold,
+        cortex_mask,
+    )
+    cmap_name = _resolve_cmap(cmap, mode)
+    return _PreparedSource(
+        activation=activation,
+        sparse_values=sparse_values,
+        template=template,
+        smoothing_steps=resolved_smoothing_steps,
+        selection=summary.selection,
+        selected_time=summary.selected_time,
+        time_window=summary.requested_window,
+        sampled_time_window=summary.sampled_window,
+        reduce=summary.reduce,
+        mode=mode,
+        threshold=parsed_threshold,
+        color_range=color_scale.color_range,
+        color_control_points=color_scale.control_points,
+        cmap=cmap_name,
+        render_cmap=_build_render_cmap(
+            cmap_name,
+            mode,
+            color_scale.color_range,
+            color_scale.control_points,
+        ),
+    )
+
+
+def _resolve_template(stc: Any, template: str) -> str:
+    if not isinstance(template, str):
+        raise TypeError("template must be a non-empty string.")
+    if not template.strip():
+        raise ValueError("template must not be empty.")
+    subject = stc.subject
+    if template == "native":
+        if not isinstance(subject, str) or not subject.strip():
+            raise ValueError(
+                "template='native' requires stc.subject to identify the "
+                "FreeSurfer subject."
+            )
+        return subject
+    if subject != template:
+        current = subject if subject else "<unknown>"
+        raise ValueError(
+            f"STC subject space {current!r} does not match requested template "
+            f"{template!r}. Morph the STC externally with "
+            "mne.compute_source_morph before calling plot_source()."
+        )
+    return template
+
+
+def plot_source(
+    stc: Any,
+    *,
+    subjects_dir: str | Path,
+    backend: Literal["brainspace", "nilearn"] = "brainspace",
+    template: str = "native",
+    surface: Literal["inflated", "pial", "white"] = "inflated",
+    smoothing_steps: int | Literal["nearest"] | None = None,
+    time: float | Literal["peak"] | None = None,
+    time_window: tuple[float, float] | None = None,
+    reduce: Literal["mean", "rms"] = "mean",
+    mode: Literal["magnitude", "signed"] = "magnitude",
+    threshold: float | str | None = None,
+    clim: (
+        Literal["robust"]
+        | tuple[float, float]
+        | dict[str, Any]
+    ) = "robust",
+    robust_percentile: float = 98.0,
+    cmap: str | None = None,
+    units: str | None = None,
+    layout: Literal["row", "grid"] = "row",
+    title: str | None = None,
+    colorbar: bool = True,
+    background: str | tuple[float, float, float] = "white",
+    output: str | Path | None = None,
+    size: tuple[int, int] | None = None,
+    scale: tuple[int, int] = (2, 2),
+    transparent: bool = False,
+    show: bool | None = None,
+) -> dict[str, Any]:
+    """Plot a cortical MNE source estimate with BrainSpace or Nilearn.
+
+    Numerical processing converts a supported real MNE source estimate into one
+    full-surface activation map without modifying the input. FreeSurfer anatomy
+    supplies the requested mesh, sulcal background, and medial wall mask. The
+    four views use one shared whole-brain activation range and colorbar.
+
+    Parameters
+    ----------
+    stc
+        A real MNE surface, vector-surface, mixed, or mixed-vector source
+        estimate. Mixed inputs contribute only their cortical surface part;
+        vector inputs are displayed by vector magnitude.
+    subjects_dir
+        Directory containing the resolved FreeSurfer subject. It must provide
+        ``surf/lh.*``, ``surf/rh.*``, and ``surf/lh.sulc``/``rh.sulc``. Cortex
+        labels are used to hide the medial wall when available.
+    backend
+        ``"brainspace"`` (default) or the optional ``"nilearn"`` renderer.
+        Both receive the same prepared surface geometry, vertex values,
+        threshold, color controls, and medial-wall mask.
+    template
+        ``"native"`` to use ``stc.subject``, or the name of the matching
+        FreeSurfer subject. If anatomical spaces differ, morph the STC externally
+        with :func:`mne.compute_source_morph` before plotting.
+    surface
+        FreeSurfer surface: ``"inflated"``, ``"pial"``, or ``"white"``.
+    smoothing_steps
+        Display interpolation used while expanding sparse source vertices to
+        the full cortical mesh. ``None`` lets MNE choose enough adjacency
+        iterations to cover the surface, ``"nearest"`` preserves the legacy
+        nearest-source assignment, and a non-negative integer requests an
+        exact number of iterations. This does not alter the pre-morph sparse
+        values used for thresholds and color limits.
+    time
+        Time in seconds, ``"peak"``, or ``None``. A numeric request uses the
+        nearest sample and the returned ``selected_time`` records the actual
+        sample. A multi-time STC requires ``time`` or ``time_window``.
+    time_window
+        Inclusive ``(start, stop)`` interval in seconds. Mutually exclusive
+        with ``time``; returned metadata records both requested and sampled
+        bounds.
+    reduce
+        Whole-window reduction: ``"mean"`` or non-negative ``"rms"``.
+    mode
+        ``"magnitude"`` takes scalar absolute values or vector magnitude.
+        ``"signed"`` preserves real scalar signs and is incompatible with
+        vector inputs and RMS reduction.
+    threshold
+        Non-negative numeric display threshold, percentage string such as
+        ``"95%"``, or ``None``. Hidden values become transparent. This is a
+        visualization control, not a test of statistical significance.
+    clim
+        ``"robust"``, an explicit ``(lower, upper)`` tuple, or an MNE-shaped
+        dictionary such as ``{"kind": "percent", "lims": [99, 99.9,
+        99.99]}``. The three dictionary controls set the lower, middle, and
+        upper color/opacity points. Signed mode uses ``pos_lims``. Robust
+        limits, percentage controls, and percentage thresholds use combined
+        pre-morph sparse values from both hemispheres, so dense display
+        expansion cannot bias them. These are display controls, not tests of
+        statistical significance.
+    robust_percentile
+        Percentile used as the robust upper magnitude or symmetric signed
+        limit. Must be in ``(0, 100]``.
+    cmap
+        Matplotlib colormap name. Defaults to ``"Reds"`` for magnitude and
+        ``"RdBu_r"`` for signed data.
+    units
+        Optional activation colorbar title.
+    layout
+        ``"row"`` orders LH lateral, LH medial, RH medial, RH lateral;
+        ``"grid"`` places lateral views above medial views.
+    title
+        Optional figure title.
+    colorbar
+        Whether to draw the single shared activation colorbar.
+    background
+        Matplotlib color name or RGB tuple for the render background.
+    output
+        Optional ``.png`` screenshot path. Missing parent directories are
+        created.
+    size
+        Logical figure canvas ``(width, height)``. Layout-specific defaults
+        are used when omitted.
+    scale
+        Positive integer PNG screenshot scale for each pixel axis.
+    transparent
+        Whether a saved PNG has a transparent background. Control-point data
+        transparency is encoded separately in the activation colormap.
+    show
+        Whether to display an interactive plotter. Defaults to ``False`` when
+        ``output`` is set and ``True`` otherwise.
+
+    Returns
+    -------
+    dict
+        Resolved source-selection, display, and output metadata. Static-only
+        PNG output returns ``plotter=None``; interactive or explicitly retained
+        scenes return the BrainSpace plotter or Nilearn Matplotlib figure.
+        ``selected_time`` is always an actual STC sample rather than the
+        numeric request.
+
+    Raises
+    ------
+    TypeError
+        If an argument or source-estimate family has an unsupported type.
+    ValueError
+        If an argument value is invalid or incompatible with another option.
+    FileNotFoundError
+        If a required FreeSurfer surface or sulc file is missing.
+    RuntimeError
+        If MNE cannot expand sparse vertices on the matching subject surface or
+        the selected renderer is unavailable or cannot create the scene.
+
+    Notes
+    -----
+    Sparse-to-dense expansion uses an MNE same-subject morph as display
+    interpolation only. The default automatically fills the cortical mesh;
+    it does not apply Gaussian smoothing or create additional independent
+    measurements. Cross-subject registration and statistical inference remain
+    the caller's responsibility.
+    """
+    _validate_phase_one_options(
+        subjects_dir=subjects_dir,
+        backend=backend,
+        surface=surface,
+        time=time,
+        time_window=time_window,
+        reduce=reduce,
+        mode=mode,
+        robust_percentile=robust_percentile,
+        layout=layout,
+        output=output,
+        size=size,
+        scale=scale,
+        show=show,
+    )
+    _validate_render_options(
+        title=title,
+        units=units,
+        colorbar=colorbar,
+        transparent=transparent,
+    )
+    resolved_smoothing_steps = _validate_smoothing_steps(smoothing_steps)
+    stc_kind = _classify_stc(stc)
+    if mode == "signed" and stc_kind in ("vector", "mixed-vector"):
+        raise ValueError("mode='signed' is not available for vector STCs.")
+    if mode == "signed" and reduce == "rms":
+        raise ValueError("mode='signed' cannot be combined with reduce='rms'.")
+    resolved_template = _resolve_template(stc, template)
+    output_path, resolved_show = _resolve_output_and_show(output, show)
+    output_path = _resolve_png_output(output_path)
+    resolved_background = _resolve_background(background)
+    resolved_size = (
+        None if size is None else _validate_positive_int_pair("size", size)
+    )
+    resolved_scale = _validate_positive_int_pair("scale", scale)
+    layout_spec = _resolve_layout(layout, resolved_size, title)
+    geometry = _load_surface_geometry(
+        subjects_dir,
+        resolved_template,
+        surface,
+    )
+    prepared = _prepare_source_data(
+        stc,
+        subjects_dir=subjects_dir,
+        template=resolved_template,
+        smoothing_steps=resolved_smoothing_steps,
+        time=time,
+        time_window=time_window,
+        reduce=reduce,
+        mode=mode,
+        threshold=threshold,
+        clim=clim,
+        robust_percentile=robust_percentile,
+        cmap=cmap,
+    )
+    render_kwargs = {
+        "background": resolved_background,
+        "colorbar": colorbar,
+        "units": units,
+        "output": output_path,
+        "scale": resolved_scale,
+        "transparent": transparent,
+        "show": resolved_show,
+    }
+    if backend == "brainspace":
+        meshes = _build_brainspace_meshes(geometry, prepared.activation)
+        plotter = _render_brainspace(
+            meshes,
+            layout_spec,
+            prepared,
+            **render_kwargs,
+        )
+    else:
+        plotter = _render_nilearn(
+            geometry,
+            layout_spec,
+            prepared,
+            **render_kwargs,
+        )
+    return {
+        "backend": backend,
+        "template": prepared.template,
+        "surface": surface,
+        "smoothing_steps": prepared.smoothing_steps,
+        "selection": prepared.selection,
+        "selected_time": prepared.selected_time,
+        "time_window": prepared.time_window,
+        "sampled_time_window": prepared.sampled_time_window,
+        "reduce": prepared.reduce,
+        "mode": prepared.mode,
+        "threshold": prepared.threshold,
+        "color_range": prepared.color_range,
+        "color_control_points": prepared.color_control_points,
+        "cmap": prepared.cmap,
+        "layout": layout,
+        "size": layout_spec.size,
+        "scale": resolved_scale,
+        "background": resolved_background,
+        "transparent": transparent,
+        "show": resolved_show,
+        "colorbar": colorbar,
+        "title": title,
+        "units": units,
+        "output": output_path,
+        "plotter": plotter,
+    }