bsplot 0.0.2__py3-none-any.whl

bsplot/surface.py

@@ -0,0 +1,2370 @@
+import os
+import matplotlib.pyplot as plt
+import nibabel
+import numpy as np
+from matplotlib.axes import Axes as MplAxes  # NEW
+from matplotlib.collections import PolyCollection
+from bsplot.colors import Colormap
+
+def vol_to_mesh(
+    img,
+    level=None,
+    smooth=True,
+    smooth_sigma=1.5,
+    mesh_smooth_iterations=20,
+    step_size=1,
+    world_coords=True,
+    return_values=False,
+    value_threshold=None,
+    threshold=None,
+    labels=None,
+    label_names=None,
+):
+    """
+    Extract a surface mesh from a 3D volume using marching cubes.
+
+    This is useful for visualizing subcortical structures (e.g., STN, GPi)
+    or any volumetric data as a 3D surface.
+
+    Parameters
+    ----------
+    img : str, pathlib.Path, or nibabel.Nifti1Image
+        Path to a NIfTI file or a loaded nibabel image.
+    level : float or None
+        The iso-value at which to extract the surface. If None and no
+        ``threshold`` is given, defaults to 10% of the volume maximum.
+    smooth : bool, default True
+        If True, apply Gaussian smoothing to the volume before extraction.
+    smooth_sigma : float, default 1.5
+        Standard deviation for Gaussian smoothing of the volume.
+    mesh_smooth_iterations : int, default 20
+        Number of Laplacian smoothing iterations to apply to the mesh.
+        Set to 0 to disable mesh smoothing.
+    step_size : int, default 1
+        Step size for marching cubes. Larger values give coarser meshes.
+    world_coords : bool, default True
+        If True, transform vertices to world (scanner) coordinates using
+        the image affine. If False, return voxel coordinates.
+    return_values : bool, default False
+        If True, also return the original volume intensity values sampled
+        at each vertex position (using trilinear interpolation). These can
+        be used directly as an overlay in plot_surf.
+    value_threshold : float or None, default None
+        If provided (and return_values=True), values below this threshold
+        are set to NaN. This allows only high-intensity regions to be
+        colored when used as an overlay.
+    threshold : float or None, default None
+        If provided, used as the iso-level for marching cubes on the
+        (optionally smoothed) continuous data.  The extracted mesh traces
+        the exact contour where volume intensity equals this value.
+        Overrides ``level`` when both are given.
+    labels : list of int, or None, default None
+        If provided, treat the volume as a label/segmentation image
+        (e.g. FreeSurfer aseg.mgz). A separate mesh is extracted for
+        each label ID. Returns a dict of ``{name: GiftiImage}`` instead
+        of a single GiftiImage.
+    label_names : dict or None, default None
+        Mapping from label ID (int) to human-readable name (str).
+        If None and the volume looks like a FreeSurfer segmentation,
+        names are looked up from the FreeSurfer color LUT automatically.
+        If a name cannot be resolved the integer ID is used as key.
+
+    Returns
+    -------
+    surface : nibabel.gifti.GiftiImage or dict
+        A single GiftiImage when ``labels`` is None.
+        A ``dict[str | int, GiftiImage]`` when ``labels`` is provided.
+        A GiftiImage that can be passed directly to plot_surf(surface=...).
+    values : ndarray, shape (n_vertices,), optional
+        Only returned if return_values=True. Original volume values
+        interpolated at each vertex position (can be used as overlay to
+        color the surface by the underlying volume intensity).
+
+    Examples
+    --------
+    >>> from bsplot.surface import vol_to_mesh, plot_surf
+    >>> # Simple usage - returns GiftiImage
+    >>> surface = vol_to_mesh('subcortical_structure.nii.gz')
+    >>> fig = plot_surf(surface)
+    >>>
+    >>> # With values for overlay
+    >>> surface, values = vol_to_mesh('subcortical_structure.nii.gz', return_values=True)
+    >>> fig = plot_surf(surface, overlay=values)
+    >>>
+    >>> # Only mesh voxels above a threshold
+    >>> surface = vol_to_mesh('efield.nii.gz', threshold=100)
+    >>>
+    >>> # Extract multiple labels from a segmentation volume
+    >>> meshes = vol_to_mesh('aseg.mgz', labels=[10, 11, 12, 13, 17, 18])
+    >>> # meshes is a dict: {"Left-Thalamus": GiftiImage, ...}
+    >>> plot_surf(list(meshes.values()), view="anterior")
+    """
+    from skimage import measure
+    from scipy import ndimage
+
+    # Load image if path provided
+    if isinstance(img, (str, os.PathLike)):
+        img = nibabel.load(os.fspath(img))
+
+    data = img.get_fdata()
+    affine = img.affine
+
+    # --- Multi-label path ---
+    if labels is not None:
+        import warnings
+
+        # Resolve label names and colors from FreeSurfer LUT
+        names, lut_colors = _resolve_label_names(labels, label_names)
+
+        result = LabeledMeshes()
+        result.colors = {}
+        for lab_id in labels:
+            binary = (np.round(data) == lab_id).astype(np.float32)
+            if binary.sum() == 0:
+                continue  # skip empty labels
+            name = names.get(lab_id, lab_id)
+
+            # Iteratively reduce smooth_sigma for small structures until
+            # marching cubes succeeds (Gaussian blur can push the max
+            # below the 0.5 iso-level for tiny masks).
+            _sigma = smooth_sigma
+            mesh = None
+            while _sigma >= 0:
+                try:
+                    mesh = vol_to_mesh(
+                        nibabel.Nifti1Image(binary, affine),
+                        level=0.5,
+                        smooth=smooth and _sigma > 0,
+                        smooth_sigma=max(_sigma, 0.1),
+                        mesh_smooth_iterations=mesh_smooth_iterations,
+                        step_size=step_size,
+                        world_coords=world_coords,
+                        return_values=False,
+                    )
+                    if _sigma < smooth_sigma:
+                        n_vox = int(binary.sum())
+                        warnings.warn(
+                            f"Label {lab_id} ({name}): reduced smooth_sigma "
+                            f"from {smooth_sigma} to {_sigma} ({n_vox} voxels).",
+                            stacklevel=2,
+                        )
+                    break
+                except ValueError:
+                    _sigma -= 0.5
+                    if _sigma < 0:
+                        n_vox = int(binary.sum())
+                        warnings.warn(
+                            f"Skipping label {lab_id} ({name}): marching cubes "
+                            f"failed even without smoothing "
+                            f"({n_vox} voxels).",
+                            stacklevel=2,
+                        )
+            if mesh is None:
+                continue
+            result[name] = mesh
+            if lab_id in lut_colors:
+                result.colors[name] = lut_colors[lab_id]
+        return result
+
+    # --- Single-volume path (original behavior) ---
+
+    # Optional smoothing for nicer surfaces
+    if smooth:
+        data = ndimage.gaussian_filter(data, sigma=smooth_sigma)
+
+    # Determine iso-level: explicit threshold overrides the default.
+    if threshold is not None:
+        level = threshold
+    elif level is None:
+        level = data.max() * 0.1
+
+    # Extract isosurface using marching cubes
+    verts, faces, normals, _ = measure.marching_cubes(
+        data, level=level, step_size=step_size
+    )
+
+    # Sample original volume values at vertex positions (before any transforms)
+    if return_values:
+        from scipy.ndimage import map_coordinates
+
+        # Load original (unsmoothed) data for value sampling
+        if isinstance(img, (str, os.PathLike)):
+            orig_data = nibabel.load(os.fspath(img)).get_fdata()
+        else:
+            orig_data = img.get_fdata()
+        # Interpolate values at vertex voxel coordinates
+        vertex_values = map_coordinates(
+            orig_data, verts.T, order=1, mode="constant", cval=0
+        )
+        # Apply threshold: set values below threshold to NaN
+        if value_threshold is not None:
+            vertex_values = vertex_values.astype(float)
+            vertex_values[vertex_values <= value_threshold] = np.nan
+
+    # Transform to world coordinates if requested
+    if world_coords:
+        verts = nibabel.affines.apply_affine(affine, verts)
+
+    # Apply Laplacian smoothing to the mesh
+    if mesh_smooth_iterations > 0:
+        verts = _laplacian_smooth(verts, faces, iterations=mesh_smooth_iterations)
+
+    # Create GiftiImage
+    surface = _create_gifti_surface(verts, faces)
+
+    if return_values:
+        return surface, vertex_values
+    return surface
+
+
+def _create_gifti_surface(vertices, faces):
+    """Create a GiftiImage from vertices and faces arrays.
+
+    Parameters
+    ----------
+    vertices : ndarray, shape (n_vertices, 3)
+        Vertex coordinates.
+    faces : ndarray, shape (n_faces, 3)
+        Triangle face indices.
+
+    Returns
+    -------
+    gifti : nibabel.gifti.GiftiImage
+        A GiftiImage containing the surface mesh.
+    """
+    # Create coordinate array (NIFTI_INTENT_POINTSET)
+    coords = nibabel.gifti.GiftiDataArray(
+        data=vertices.astype(np.float32),
+        intent=nibabel.nifti1.intent_codes["NIFTI_INTENT_POINTSET"],
+        datatype=nibabel.nifti1.data_type_codes["NIFTI_TYPE_FLOAT32"],
+    )
+
+    # Create triangle array (NIFTI_INTENT_TRIANGLE)
+    triangles = nibabel.gifti.GiftiDataArray(
+        data=faces.astype(np.int32),
+        intent=nibabel.nifti1.intent_codes["NIFTI_INTENT_TRIANGLE"],
+        datatype=nibabel.nifti1.data_type_codes["NIFTI_TYPE_INT32"],
+    )
+
+    # Create GiftiImage with both arrays
+    gifti = nibabel.gifti.GiftiImage(darrays=[coords, triangles])
+    return gifti
+
+
+class LabeledMeshes(dict):
+    """A dict subclass returned by ``vol_to_mesh(labels=...)``.
+
+    Behaves exactly like a regular ``dict[str, GiftiImage]`` but
+    additionally carries a ``.colors`` dict mapping the same keys
+    to RGBA tuples (0-1 range) parsed from the FreeSurfer color LUT.
+    ``plot_surf`` picks these up automatically when no explicit
+    ``color`` is provided.
+    """
+
+    colors: dict  # name → (r, g, b, a) in [0, 1]
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.colors = {}
+
+
+def _resolve_label_names(labels, label_names=None):
+    """Return ``(names, colors)`` dicts keyed by label ID.
+
+    Parameters
+    ----------
+    labels : list[int]
+        Integer label IDs to look up.
+    label_names : list[str], dict, or None
+        If a list of strings matching *labels* in order, converted into
+        a dict.  If a dict, used as-is.  If ``None``, the FreeSurfer
+        color LUT is queried.
+
+    Returns
+    -------
+    names : dict[int, str]
+        Mapping label-ID → human-readable name.
+    colors : dict[int, tuple]
+        Mapping label-ID → ``(r, g, b, a)`` with values in [0, 1].
+        Empty when the LUT cannot be found.
+    """
+    # Allow list-of-names shorthand
+    if isinstance(label_names, (list, tuple)):
+        if len(label_names) != len(labels):
+            raise ValueError(
+                f"label_names list ({len(label_names)}) must match "
+                f"labels list ({len(labels)})"
+            )
+        label_names = dict(zip(labels, label_names))
+
+    if isinstance(label_names, dict):
+        return label_names, {}  # no LUT colors when names are explicit
+
+    # Try FreeSurfer LUT
+    fs_home = os.environ.get("FREESURFER_HOME", "")
+    lut_path = os.path.join(fs_home, "FreeSurferColorLUT.txt") if fs_home else ""
+    lut_names: dict[int, str] = {}
+    lut_colors: dict[int, tuple] = {}
+    if os.path.isfile(lut_path):
+        with open(lut_path) as f:
+            for line in f:
+                line = line.strip()
+                if not line or line.startswith("#"):
+                    continue
+                parts = line.split()
+                if len(parts) >= 6:
+                    try:
+                        idx = int(parts[0])
+                        lut_names[idx] = parts[1]
+                        r, g, b, a = (
+                            int(parts[2]),
+                            int(parts[3]),
+                            int(parts[4]),
+                            int(parts[5]),
+                        )
+                        lut_colors[idx] = (r / 255, g / 255, b / 255, 1.0)
+                    except (ValueError, IndexError):
+                        continue
+
+    names = {lab: lut_names.get(lab, lab) for lab in labels}
+    return names, lut_colors
+
+
+def _laplacian_smooth(vertices, faces, iterations=10, lambda_factor=0.5):
+    """Apply Laplacian smoothing to a mesh.
+
+    Parameters
+    ----------
+    vertices : ndarray, shape (n_vertices, 3)
+        Vertex coordinates.
+    faces : ndarray, shape (n_faces, 3)
+        Triangle face indices.
+    iterations : int, default 10
+        Number of smoothing iterations.
+    lambda_factor : float, default 0.5
+        Smoothing factor (0-1). Higher values = more smoothing per iteration.
+
+    Returns
+    -------
+    vertices_smoothed : ndarray, shape (n_vertices, 3)
+        Smoothed vertex coordinates.
+    """
+    from collections import defaultdict
+
+    # Build adjacency list
+    n_verts = len(vertices)
+    neighbors = defaultdict(set)
+    for f in faces:
+        neighbors[f[0]].update([f[1], f[2]])
+        neighbors[f[1]].update([f[0], f[2]])
+        neighbors[f[2]].update([f[0], f[1]])
+
+    verts_new = vertices.copy().astype(np.float64)
+    for _ in range(iterations):
+        verts_smooth = np.zeros_like(verts_new)
+        for i in range(n_verts):
+            if neighbors[i]:
+                neighbor_verts = verts_new[list(neighbors[i])]
+                centroid = neighbor_verts.mean(axis=0)
+                verts_smooth[i] = verts_new[i] + lambda_factor * (
+                    centroid - verts_new[i]
+                )
+            else:
+                verts_smooth[i] = verts_new[i]
+        verts_new = verts_smooth
+    return verts_new
+
+
+# Maps view names to the world axis (0=x, 1=y, 2=z) the camera looks along.
+_PROJECTION_AXES = {
+    "lateral": 0, "medial": 0, "sagittal": 0,
+    "front": 1, "frontal": 1, "anterior": 1, "coronal": 1,
+    "back": 1, "posterior": 1,
+    "top": 2, "dorsal": 2, "superior": 2, "axial": 2, "horizontal": 2,
+    "bottom": 2, "ventral": 2, "inferior": 2,
+}
+
+
+def _sample_volume_at_vertices(
+    vol, world_vertices, threshold=None,
+    intensity_projection=None, projection_axis=None,
+):
+    """Sample a NIfTI volume at world-coordinate vertex positions.
+
+    Transforms vertex positions from world (RAS) space to voxel space
+    via the inverse of the volume's affine, then interpolates values
+    using ``scipy.ndimage.map_coordinates`` (trilinear, order=1).
+
+    When *intensity_projection* is set, sampling switches from point
+    evaluation to a sweep along the *projection_axis*: for each vertex
+    the volume is sampled at every voxel slice along that axis (keeping
+    the other two coordinates fixed) and the resulting column is reduced
+    with the chosen aggregation (``"max"``, ``"mean"``, etc.).  This
+    mirrors the behaviour of ``plot_slice(intensity_projection=...)``
+    but maps the result onto mesh vertices.
+
+    Parameters
+    ----------
+    vol : str, pathlib.Path, or nibabel.Nifti1Image
+        Path to a NIfTI file or a loaded nibabel image.
+    world_vertices : ndarray, shape (n_vertices, 3)
+        Vertex positions in world (RAS) coordinates, matching the
+        coordinate space of the volume.
+    threshold : float or None
+        If provided, sampled values at or below this threshold are set
+        to NaN. This excludes low-intensity regions from the colormap
+        range and causes them to render as grey in ``plot_surf``.
+    intensity_projection : str or None
+        Aggregation method along *projection_axis*.  One of ``"max"``,
+        ``"min"``, ``"mean"``, ``"median"``, ``"sum"``, ``"absmax"``.
+        When *None* (default), trilinear point sampling is used.
+    projection_axis : int or None
+        World axis to sweep along (0 = x, 1 = y, 2 = z).  Required
+        when *intensity_projection* is set.  Typically derived
+        automatically from the view in ``plot_surf``.
+
+    Returns
+    -------
+    values : ndarray, shape (n_vertices,)
+        Trilinearly interpolated volume values at each vertex position
+        (point mode) or aggregated intensity-projection values (sweep
+        mode).  Values outside the volume extent are 0 in point mode.
+    """
+    from scipy.ndimage import map_coordinates
+
+    if isinstance(vol, (str, os.PathLike)):
+        vol = nibabel.load(os.fspath(vol))
+    data = vol.get_fdata()
+    inv_affine = np.linalg.inv(vol.affine)
+    ijk = nibabel.affines.apply_affine(inv_affine, world_vertices)
+
+    # ------------------------------------------------------------------
+    # Intensity-projection mode: sweep along one voxel axis per vertex
+    # ------------------------------------------------------------------
+    if intensity_projection is not None:
+        if projection_axis is None:
+            raise ValueError(
+                "projection_axis is required when intensity_projection is set"
+            )
+        # Map world axis → voxel axis via the affine
+        vox_axis = int(np.argmax(np.abs(vol.affine[projection_axis, :3])))
+        n_slices = data.shape[vox_axis]
+        n_verts = len(world_vertices)
+
+        # Build (n_verts, n_slices, 3) sampling grid — keep two coords
+        # from the vertex, sweep the third across all slices.
+        ijk_sweep = np.broadcast_to(
+            ijk[:, np.newaxis, :], (n_verts, n_slices, 3)
+        ).copy()
+        ijk_sweep[:, :, vox_axis] = np.arange(n_slices)[np.newaxis, :]
+
+        coords_flat = ijk_sweep.reshape(-1, 3).T  # (3, n_verts*n_slices)
+        sampled = map_coordinates(
+            data, coords_flat, order=1, mode="constant", cval=0
+        ).reshape(n_verts, n_slices)
+
+        if threshold is not None:
+            sampled = sampled.astype(float)
+            sampled[sampled <= threshold] = np.nan
+
+        # Suppress "All-NaN slice" warnings — vertices whose entire
+        # column is below threshold legitimately become NaN (grey).
+        import warnings
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", RuntimeWarning)
+            if intensity_projection == "max":
+                values = np.nanmax(sampled, axis=1)
+            elif intensity_projection == "min":
+                values = np.nanmin(sampled, axis=1)
+            elif intensity_projection == "mean":
+                values = np.nanmean(sampled, axis=1)
+            elif intensity_projection == "median":
+                values = np.nanmedian(sampled, axis=1)
+            elif intensity_projection == "sum":
+                values = np.nansum(sampled, axis=1)
+            elif intensity_projection == "absmax":
+                max_vals = np.nanmax(sampled, axis=1)
+                min_vals = np.nanmin(sampled, axis=1)
+                values = np.where(
+                    np.abs(min_vals) > np.abs(max_vals), min_vals, max_vals
+                )
+            else:
+                raise ValueError(
+                    f"Unsupported intensity_projection: {intensity_projection}"
+                )
+        return values
+
+    # ------------------------------------------------------------------
+    # Default: trilinear point sampling
+    # ------------------------------------------------------------------
+    values = map_coordinates(data, ijk.T, order=1, mode="constant", cval=0)
+
+    if threshold is not None:
+        values = values.astype(float)
+        values[values <= threshold] = np.nan
+    return values
+
+
+def project_vol_to_surf(
+    img,
+    surf_mesh,
+    radius=3.0,
+    interpolation="linear",
+    kind="line",
+    n_samples=None,
+    mask_img=None,
+    inner_mesh=None,
+):
+    """
+    Project a volume onto a surface mesh using nilearn.
+
+    This is useful for visualizing cortical statistical maps on a surface.
+    For subcortical structures, consider using vol_to_mesh instead.
+
+    Parameters
+    ----------
+    img : str, pathlib.Path, or nibabel.Nifti1Image
+        Path to a NIfTI file or a loaded nibabel image.
+    surf_mesh : str, pathlib.Path, nibabel.GiftiImage, or tuple
+        Surface mesh. Can be:
+        - Path to a surface file (gifti, freesurfer format)
+        - A GiftiImage
+        - A tuple (vertices, faces)
+    radius : float, default 3.0
+        Neighborhood radius in mm for sampling.
+    interpolation : {'linear', 'nearest', 'nearest_most_frequent'}, default 'linear'
+        Interpolation method for sampling.
+    kind : {'auto', 'depth', 'line', 'ball'}, default 'line'
+        Sampling strategy.
+    n_samples : int or None
+        Number of samples per vertex.
+    mask_img : Niimg-like or None
+        Mask to restrict sampling.
+    inner_mesh : str, array, or None
+        Inner surface for depth sampling (e.g., white matter surface).
+
+    Returns
+    -------
+    texture : ndarray, shape (n_vertices,) or (n_vertices, n_timepoints)
+        Surface data values.
+
+    Examples
+    --------
+    >>> from bsplot.surface import project_vol_to_surf, plot_surf
+    >>> from bsplot.data.surface import get_surface_geometry
+    >>> vertices, faces = get_surface_geometry(hemi='lh', template='fsLR')
+    >>> texture = project_vol_to_surf('statistical_map.nii.gz', (vertices, faces))
+    >>> fig = plot_surf('fsLR', hemi='lh', overlay=texture)
+    """
+    from nilearn.surface import vol_to_surf as _nilearn_vol_to_surf
+
+    # Handle tuple input for surf_mesh
+    if isinstance(surf_mesh, tuple) and len(surf_mesh) == 2:
+        # Create an InMemoryMesh-like object
+        from nilearn.surface import InMemoryMesh
+
+        vertices, faces = surf_mesh
+        surf_mesh = InMemoryMesh(vertices, faces)
+
+    return _nilearn_vol_to_surf(
+        img=img,
+        surf_mesh=surf_mesh,
+        radius=radius,
+        interpolation=interpolation,
+        kind=kind,
+        n_samples=n_samples,
+        mask_img=mask_img,
+        inner_mesh=inner_mesh,
+    )
+
+
+def normalize_v3(arr):
+    """Normalize a numpy array of 3 component vectors shape=(n,3) safely."""
+    a = np.asarray(arr, dtype=float)
+    norms = np.linalg.norm(a, axis=1, keepdims=True)
+    norms = np.where(norms == 0.0, 1.0, norms)  # avoid division by zero
+    return a / norms
+
+
+def normal_vectors(vertices, faces):
+    norm = np.zeros(vertices.shape, dtype=vertices.dtype)
+    tris = vertices[faces]
+    n = np.cross(tris[::, 1] - tris[::, 0], tris[::, 2] - tris[::, 0])
+    n = normalize_v3(n)
+    return n
+
+
+def vertex_normals(vertices, faces):
+    norm = np.zeros(vertices.shape, dtype=vertices.dtype)
+    tris = vertices[faces]
+    n = np.cross(tris[::, 1] - tris[::, 0], tris[::, 2] - tris[::, 0])
+    n = normalize_v3(n)
+    norm[faces[:, 0]] += n
+    norm[faces[:, 1]] += n
+    norm[faces[:, 2]] += n
+    return normalize_v3(norm)
+
+
+def frustum(left, right, bottom, top, znear, zfar):
+    M = np.zeros((4, 4), dtype=np.float32)
+    M[0, 0] = +2.0 * znear / (right - left)
+    M[1, 1] = +2.0 * znear / (top - bottom)
+    M[2, 2] = -(zfar + znear) / (zfar - znear)
+    M[0, 2] = (right + left) / (right - left)
+    M[2, 1] = (top + bottom) / (top - bottom)
+    M[2, 3] = -2.0 * znear * zfar / (zfar - znear)
+    M[3, 2] = -1.0
+    return M
+
+
+def perspective(fovy, aspect, znear, zfar):
+    h = np.tan(0.5 * np.radians(fovy)) * znear
+    w = h * aspect
+    return frustum(-w, w, -h, h, znear, zfar)
+
+
+def translate(x, y, z):
+    return np.array(
+        [[1, 0, 0, x], [0, 1, 0, y], [0, 0, 1, z], [0, 0, 0, 1]], dtype=float
+    )
+
+
+def xrotate(theta):
+    t = np.pi * theta / 180
+    c, s = np.cos(t), np.sin(t)
+    return np.array(
+        [[1, 0, 0, 0], [0, c, -s, 0], [0, s, c, 0], [0, 0, 0, 1]], dtype=float
+    )
+
+
+def yrotate(theta):
+    t = np.pi * theta / 180
+    c, s = np.cos(t), np.sin(t)
+    return np.array(
+        [[c, 0, s, 0], [0, 1, 0, 0], [-s, 0, c, 0], [0, 0, 0, 1]], dtype=float
+    )
+
+
+def zrotate(theta):
+    t = np.pi * theta / 180
+    c, s = np.cos(t), np.sin(t)
+    return np.array(
+        [[c, -s, 0, 0], [s, c, 0, 0], [0, 0, 1, 0], [0, 0, 0, 1]], dtype=float
+    )
+
+
+def shading_intensity(vertices, faces, light=np.array([0, 0, 1]), shading=0.7):
+    """shade calculation based on light source
+    default is vertical light.
+    shading controls amount of shading.
+    Also saturates so top 20 % of vertices all have max intensity."""
+    face_normals = normal_vectors(vertices, faces)
+    intensity = np.dot(face_normals, light)
+    intensity[np.isnan(intensity)] = 1
+    shading = 0.7
+    # top 20% all become fully coloured
+    _int_range = np.percentile(intensity, 80) - np.min(intensity)
+    if _int_range == 0:
+        _int_range = 1.0
+    intensity = (1 - shading) + shading * (intensity - np.min(intensity)) / _int_range
+    # saturate
+    intensity[intensity > 1] = 1
+
+    return intensity
+
+
+def f7(seq):
+    # returns uniques but in order to retain neighbour triangle relationship
+    seen = set()
+    seen_add = seen.add
+    return [x for x in seq if not (x in seen or seen_add(x))]
+
+
+def get_ring_of_neighbours(island, neighbours, vertex_indices=None, ordered=False):
+    """Calculate ring of neighbouring vertices for an island of cortex
+    If ordered, then vertices will be returned in connected order"""
+    if not vertex_indices:
+        vertex_indices = np.arange(len(island))
+    if not ordered:
+
+        neighbours_island = neighbours[island]
+        unfiltered_neighbours = []
+        for n in neighbours_island:
+            unfiltered_neighbours.extend(n)
+        unique_neighbours = np.setdiff1d(
+            np.unique(unfiltered_neighbours), vertex_indices[island]
+        )
+        return unique_neighbours
+
+
+def get_neighbours_from_tris(tris, label=None):
+    """Get surface neighbours from tris
+    Input: tris
+     Returns Nested list. Each list corresponds
+    to the ordered neighbours for the given vertex"""
+    n_vert = np.max(tris + 1)
+    neighbours = [[] for i in range(n_vert)]
+    for tri in tris:
+        neighbours[tri[0]].extend([tri[1], tri[2]])
+        neighbours[tri[2]].extend([tri[0], tri[1]])
+        neighbours[tri[1]].extend([tri[2], tri[0]])
+    # Get unique neighbours
+    for k in range(len(neighbours)):
+        if label is not None:
+            neighbours[k] = set(neighbours[k]).intersection(label)
+        else:
+            neighbours[k] = f7(neighbours[k])
+    return np.array(neighbours, dtype=object)
+
+
+def mask_colours(colours, triangles, mask, mask_colour=None):
+    """grey out mask"""
+    if mask is not None:
+        if mask_colour is None:
+            mask_colour = np.array([0.86, 0.86, 0.86, 1])
+        verts_masked = mask[triangles].any(axis=1)
+        colours[verts_masked, :] = mask_colour
+    return colours
+
+
+def adjust_colours_pvals(
+    colours,
+    pvals,
+    triangles,
+    mask=None,
+    mask_colour=None,
+    border_colour=np.array([1.0, 0, 0, 1]),
+):
+    """red ring around clusters and greying out non-significant vertices"""
+    colours = mask_colours(colours, triangles, mask, mask_colour)
+    neighbours = get_neighbours_from_tris(triangles)
+    ring = get_ring_of_neighbours(pvals < 0.05, neighbours)
+    if len(ring) > 0:
+        ring_label = np.zeros(len(neighbours)).astype(bool)
+        ring_label[ring] = 1
+        ring = get_ring_of_neighbours(ring_label, neighbours)
+        ring_label[ring] = 1
+        colours[ring_label[triangles].any(axis=1), :] = border_colour
+    grey_out = pvals < 0.05
+    verts_grey_out = grey_out[triangles].any(axis=1)
+    colours[verts_grey_out, :] = (
+        1.5 * colours[verts_grey_out] + np.array([0.86, 0.86, 0.86, 1])
+    ) / 2.5
+    return colours
+
+
+def add_parcellation_colours(
+    colours,
+    parcel,
+    triangles,
+    labels=None,
+    mask=None,
+    filled=False,
+    mask_colour=None,
+    neighbours=None,
+):
+    """delineate regions"""
+    colours = mask_colours(colours, triangles, mask, mask_colour=mask_colour)
+    # normalise rois and colors
+    rois = list(set(parcel))
+    if 0 in rois:
+        rois.remove(0)
+    if labels is None:
+        labels = dict(zip(rois, np.random.rand(len(rois), 4)))
+    # remove transparent rois
+    # find vertices that delineate rois
+    if filled:
+        colours = np.zeros_like(colours)
+        for l, label in enumerate(rois):
+            colours[np.median(parcel[triangles], axis=1) == label] = labels[label]
+        return colours
+    if neighbours is None:
+        neighbours = get_neighbours_from_tris(triangles)
+    matrix_colored = np.zeros([len(triangles), len(rois)])
+    for l, label in enumerate(rois):
+        ring = get_ring_of_neighbours(parcel != label, neighbours)
+        if len(ring) > 0:
+            ring_label = np.zeros(len(neighbours)).astype(bool)
+            ring_label[ring] = 1
+            #          ring=get_ring_of_neighbours(ring_label,neighbours)
+            #           ring_label[ring]=1
+            #            matrix_colored[:,l] = ring_label[triangles].sum(axis=1)
+            matrix_colored[:, l] = np.median(
+                ring_label[triangles], axis=1
+            )  # ring_label[triangles].sum(axis=1)
+    # update colours with delineation
+    maxis = [max(matrix_colored[i, :]) for i in range(0, len(colours))]
+    colours = np.array(
+        [
+            (
+                labels[
+                    rois[np.random.choice(np.where(matrix_colored[i, :] == maxi)[0])]
+                ]
+                if maxi != 0
+                else colours[i]
+            )
+            for i, maxi in enumerate(maxis)
+        ]
+    )
+    return colours
+
+
+def adjust_colours_alpha(colours, alpha):
+    """grey out vertices according to scalar"""
+    # rescale alpha to 0.2-1.0
+    alpha_rescaled = 0.1 + 0.9 * (alpha - np.min(alpha)) / (
+        np.max(alpha) - np.min(alpha)
+    )
+    colours = (alpha_rescaled * colours.T).T + (
+        (1 - alpha_rescaled) * np.array([0.86, 0.86, 0.86, 1]).reshape(-1, 1)
+    ).T
+    colours = np.clip(colours, 0, 1)
+    return colours
+
+
+def frontback(T):
+    """
+    Sort front and back facing triangles
+    Parameters:
+    -----------
+    T : (n,3) array
+       Triangles to sort
+    Returns:
+    --------
+    front and back facing triangles as (n1,3) and (n2,3) arrays (n1+n2=n)
+    """
+    Z = (
+        (T[:, 1, 0] - T[:, 0, 0]) * (T[:, 1, 1] + T[:, 0, 1])
+        + (T[:, 2, 0] - T[:, 1, 0]) * (T[:, 2, 1] + T[:, 1, 1])
+        + (T[:, 0, 0] - T[:, 2, 0]) * (T[:, 0, 1] + T[:, 2, 1])
+    )
+    return Z < 0, Z >= 0
+
+
+def normalized(a, axis=-1, order=2):
+    l2 = np.atleast_1d(np.linalg.norm(a, order, axis))
+    l2[l2 == 0] = 1
+    return a / np.expand_dims(l2, axis)
+
+
+# ----------------------
+# Internal helper utilities
+# ----------------------
+
+
+def _resolve_surface_geometry(
+    surface,
+    *,
+    hemi: str,
+    surface_suffix: str | None,
+    surface_density: str | None,
+    surface_kwargs: dict | None,
+):
+    """Resolve vertices and faces from various surface specifications.
+
+    Accepts:
+    - GiftiImage
+    - File path to a surface (gifti)
+    - Template name string (e.g., "fsLR", "fsaverage") and fetches via get_surface_geometry
+
+    Returns (vertices, faces).
+    """
+    if surface_kwargs is None:
+        surface_kwargs = {}
+
+    # Already provided explicit vertices/faces handled by caller
+    loaded_vertices = None
+    loaded_faces = None
+
+    # File path (accept str and os.PathLike)
+    if isinstance(surface, (str, os.PathLike)) and os.path.isfile(os.fspath(surface)):
+        path_str = os.fspath(surface)
+        img = nibabel.load(path_str)
+        loaded_vertices = img.get_arrays_from_intent(
+            nibabel.nifti1.intent_codes["NIFTI_INTENT_POINTSET"]
+        )[0].data
+        loaded_faces = img.get_arrays_from_intent(
+            nibabel.nifti1.intent_codes["NIFTI_INTENT_TRIANGLE"]
+        )[0].data
+        return loaded_vertices, loaded_faces
+
+    # Template name (only for plain strings)
+    if isinstance(surface, str) and not os.path.isfile(surface):
+        from bsplot.data.surface import get_surface_geometry
+
+        tpl = surface
+        suffix = (
+            surface_kwargs.get("suffix")
+            or surface_kwargs.get("surface_suffix")
+            or surface_suffix
+        )
+        density = (
+            surface_kwargs.get("density")
+            or surface_kwargs.get("surface_density")
+            or surface_density
+        )
+        if suffix is None:
+            suffix = "midthickness" if tpl.lower() == "fslr" else "pial"
+        if density is None:
+            if tpl.lower() == "fslr":
+                density = "32k"
+            elif tpl.lower() == "fsaverage":
+                density = "164k"
+        geom_kwargs = dict(template=tpl, suffix=suffix, hemi=hemi)
+        if density is not None:
+            geom_kwargs["density"] = density
+        if surface_kwargs.get("desc") is not None:
+            geom_kwargs["desc"] = surface_kwargs.get("desc")
+        if surface_kwargs.get("extension") is not None:
+            geom_kwargs["extension"] = surface_kwargs.get("extension")
+        return get_surface_geometry(**geom_kwargs)
+
+    # Gifti image
+    if isinstance(surface, nibabel.gifti.gifti.GiftiImage):
+        loaded_vertices = surface.get_arrays_from_intent(
+            nibabel.nifti1.intent_codes["NIFTI_INTENT_POINTSET"]
+        )[0].data
+        loaded_faces = surface.get_arrays_from_intent(
+            nibabel.nifti1.intent_codes["NIFTI_INTENT_TRIANGLE"]
+        )[0].data
+        return loaded_vertices, loaded_faces
+
+    raise ValueError(
+        "Could not determine surface geometry. Provide a GiftiImage, a valid surface filepath, a template name (e.g., 'fsLR'/'fsaverage') with hemisphere, or explicit vertices/faces."
+    )
+
+
+def _map_view_to_rotations(view, hemi, x_rotate, z_rotate):
+    """Map view string or numeric to yaw (view), pitch (x_rotate), roll (z_rotate), and a view token.
+
+    Preserves legacy behavior and anatomical conventions used here.
+    """
+    view_token = None
+    if isinstance(view, str):
+        v = view.lower()
+        if v in ("top", "dorsal", "superior", "axial", "horizontal"):
+            view = 0.0
+            x_rotate = 0.0
+            view_token = "top"
+        elif v in ("bottom", "ventral", "inferior"):
+            view = 0.0
+            x_rotate = 180.0
+            z_rotate = 180.0
+            view_token = "bottom"
+        elif v in ("front", "frontal", "anterior", "coronal"):
+            view = 0.0
+            x_rotate = 90.0
+            z_rotate = 180.0
+            view_token = "front"
+        elif v in ("back", "posterior"):
+            view = 0.0
+            x_rotate = 270.0
+            view_token = "back"
+        elif v in ("lateral", "medial", "sagittal"):
+            if v == "sagittal":
+                # Sagittal view: show left side for lh, right side for rh
+                if hemi == "lh":
+                    view = 90.0
+                elif hemi == "rh":
+                    view = 270.0
+                else:
+                    view = 90.0
+                view_token = "lateral"
+            else:
+                if hemi == "lh":
+                    view = 90.0 if v == "lateral" else 270.0
+                elif hemi == "rh":
+                    view = 270.0 if v == "lateral" else 90.0
+                else:
+                    view = 90.0 if v == "lateral" else 270.0
+                view_token = v
+        else:
+            try:
+                view = float(view)
+            except Exception:
+                raise ValueError(
+                    f"Unknown view '{view}'. Use one of lateral/medial/sagittal, top/dorsal/superior/axial/horizontal, bottom/ventral/inferior, front/frontal/anterior/coronal, back/posterior, or a numeric yaw angle."
+                )
+    return view, x_rotate, z_rotate, view_token
+
+
+def _compute_shading_intensity(
+    proj_vertices, F, view_token, view, z_rotate, x_rotate
+):
+    """Compute per-face shading intensity with view-dependent light.
+
+    For lateral/medial views we keep the historical behaviour where the
+    light is rotated with the camera (good for side views). For top,
+    front, back and arbitrary yaw views we keep the light roughly aligned
+    with the viewer so that sulci/gyri remain well shaded irrespective of
+    the rotation, which improves those projections.
+    """
+
+    # Lateral / medial: original behaviour – light rotates with camera
+    if view_token in ("lateral", "medial"):
+        light = np.array([0, 0, 1, 1]) @ yrotate(z_rotate)
+
+    else:
+        # Keep light fixed in (approximate) camera space for other views.
+        # Use a slightly off-vertical direction so structures are shaded
+        # rather than completely flat.
+        if view_token == "top":
+            # Oblique light from front-left with minimal z-component to
+            # create strong shadows in sulci when viewing from dorsal.
+            light = np.array([0.6, 0.75, 0.25, 1.0])
+        elif view_token == "bottom":
+            # Oblique light from front-left with minimal z-component to
+            # reveal sulcal structure when viewing from ventral.
+            light = np.array([0.6, 0.75, -0.25, 1.0])
+        elif view_token == "front":
+            light = np.array([0.0, 0.0, 1.0, 1.0])
+        elif view_token == "back":
+            light = np.array([0.0, 0.0, -1.0, 1.0])
+        else:
+            # Generic numeric yaw or unknown token: pleasant oblique light
+            light = np.array([0.3, 0.3, 0.9, 1.0])
+
+    intensity = shading_intensity(proj_vertices, F, light=light[:3], shading=0.7)
+    return intensity, z_rotate
+
+
+def plot_surf(
+    surface: nibabel.gifti.gifti.GiftiImage | str | list | tuple = None,
+    overlay=None,
+    overlay_volume=None,
+    intensity_projection=None,
+    sampling_threshold=None,
+    vertices=None,
+    faces=None,
+    ax=None,
+    parcellated=False,
+    hemi="lh",
+    view="lateral",
+    cmap="viridis",
+    color=None,  # Base surface color when no overlay
+    label=False,
+    vmax=None,
+    vmin=None,
+    x_rotate=270,
+    pvals=None,
+    mask=None,
+    arrows=None,
+    arrow_subset=None,
+    arrow_size=0.5,
+    arrow_colours=None,
+    arrow_head=0.05,
+    arrow_width=0.001,
+    mask_colour=None,
+    transparency=1,
+    alpha=None,  # Alias for transparency
+    show_back=False,
+    border_colour=np.array([1, 0, 0, 1]),
+    alpha_colour=None,
+    flat_map=False,
+    z_rotate=0,
+    neighbours=None,
+    parcel=None,
+    parcel_cmap=None,
+    filled_parcels=False,
+    norm=None,
+    world_coords=True,
+    affine=None,
+    flip_x=False,  # Flip x-axis to match slice neurological convention
+    threshold=None,  # Values at or below threshold are shown in grey
+    threshold_color=None,  # Color for below-threshold regions (default: grey)
+    # NEW: allow direct template names ("fsLR", "fsaverage")
+    surface_suffix: str | None = None,
+    surface_density: str | None = None,
+    surface_kwargs: dict | None = None,
+    # NEW: additional surfaces for depth-correct rendering
+    additional_surfaces: list | None = None,
+    additional_overlays: list | None = None,
+    additional_colors: list | None = None,
+    additional_alphas: list | None = None,
+    additional_cmaps: list | None = None,
+    additional_vmins: list | None = None,
+    additional_vmaxs: list | None = None,
+    # NEW: separate styling for faces and vertices
+    faces_kwargs: dict | None = None,
+    vertices_kwargs: dict | None = None,
+    # NEW: decimate surface mesh before rendering
+    surface_decimate: float | None = None,
+    # PRIVATE: shared bounding box for list-of-surfaces path
+    # (vmin_3d, vmax_3d) — ensures all meshes share one normalization
+    _shared_bbox=None,
+    **kwargs,
+):
+    """Plot a surface mesh as a depth-sorted 2D projection.
+
+    Parameters
+    ----------
+    surface : GiftiImage, str, list, tuple, or dict
+        Surface mesh(es) to render. Accepts a single GiftiImage, a file
+        path, a template name (e.g. ``"fsLR"``), a list/tuple of surfaces
+        (rendered depth-correctly in one PolyCollection), or a dict
+        mapping labels to surfaces (e.g. from ``vol_to_mesh(labels=...)``).
+    overlay : array-like or list of array-like, optional
+        Per-vertex data to color-map onto the surface. When *surface* is a
+        list, *overlay* should be a list of equal length.
+    overlay_volume : str, path, or nibabel image, optional
+        A NIfTI volume to project onto each mesh by trilinear sampling at
+        world-coordinate vertex positions (``map_coordinates``). Populates
+        *overlay* automatically. Ignored when *overlay* is provided.
+    intensity_projection : str, optional
+        Aggregation method for sampling ``overlay_volume`` along the
+        viewing axis instead of at exact vertex positions.  Mirrors
+        ``plot_slice(intensity_projection=...)``.  Supported values:
+        ``"max"``, ``"min"``, ``"mean"``, ``"median"``, ``"sum"``,
+        ``"absmax"``.  The projection axis is derived from *view*
+        (lateral → x, frontal → y, top → z).  Requires a named view.
+    sampling_threshold : float, optional
+        Applied during ``overlay_volume`` sampling: vertex values at or
+        below this threshold are set to NaN so they appear grey and do not
+        affect the colormap range. Falls back to *threshold* when not set.
+        Use this when *threshold* alone produces poor contrast because the
+        colormap spans from 0 to max instead of from *threshold* to max.
+    threshold : float, optional
+        Rendering-time threshold applied after colormapping. Faces where
+        any vertex value is at or below *threshold* are shown in grey
+        (or *threshold_color*). When ``overlay_volume`` is used and
+        *sampling_threshold* is not set, *threshold* is also used as the
+        sampling threshold.
+    """
+    # Handle alpha as alias for transparency
+    if alpha is not None:
+        transparency = alpha
+
+    if isinstance(cmap, (list, tuple)):
+        cmap = [Colormap(c) if isinstance(c, str) else c for c in cmap]
+    elif isinstance(cmap, str):
+        cmap = Colormap(cmap)
+
+    # Unpack additional_surfaces dict → list, extracting labels and colors
+    _additional_labels = None
+    if isinstance(additional_surfaces, dict):
+        _additional_labels = list(additional_surfaces.keys())
+        # Auto-apply FreeSurfer LUT colors when available (LabeledMeshes)
+        if (
+            additional_colors is None
+            and hasattr(additional_surfaces, "colors")
+            and additional_surfaces.colors
+        ):
+            additional_colors = [
+                additional_surfaces.colors.get(k, None)
+                for k in additional_surfaces
+            ]
+            if all(c is None for c in additional_colors):
+                additional_colors = None
+        additional_surfaces = list(additional_surfaces.values())
+
+    # Normalize hemi="both" to ["lh", "rh"]
+    if isinstance(hemi, str) and hemi.lower() == "both":
+        hemi = ["lh", "rh"]
+
+    # Support hemi as a list (e.g., ["lh", "rh"]) to merge both hemispheres
+    # into a single combined mesh for proper depth-correct rendering
+    if isinstance(hemi, (list, tuple)) and not isinstance(surface, (list, tuple)):
+        hemis_list = list(hemi)
+
+        # Load and merge geometry from each hemisphere
+        all_vertices = []
+        all_faces = []
+        all_overlays = []
+        _layered_overlays = None  # For multi-layer overlays per hemisphere
+        vertex_offset = 0
+
+        for h in hemis_list:
+            h_normalized = "lh" if h.lower().startswith("l") else "rh"
+            h_verts, h_faces = _resolve_surface_geometry(
+                surface,
+                hemi=h_normalized,
+                surface_suffix=surface_suffix,
+                surface_density=surface_density,
+                surface_kwargs=surface_kwargs,
+            )
+            all_vertices.append(h_verts)
+            all_faces.append(h_faces + vertex_offset)
+            vertex_offset += len(h_verts)
+
+            # Handle overlay if provided (must be list/tuple matching hemis)
+            if overlay is not None:
+                if isinstance(overlay, (list, tuple)):
+                    h_idx = hemis_list.index(h)
+                    h_overlay = overlay[h_idx]
+                    if isinstance(h_overlay, (list, tuple)):
+                        # Multi-layer per hemisphere: each element is a layer
+                        if _layered_overlays is None:
+                            _layered_overlays = [[] for _ in range(len(h_overlay))]
+                        for layer_i, layer_arr in enumerate(h_overlay):
+                            _layered_overlays[layer_i].append(layer_arr)
+                    else:
+                        all_overlays.append(h_overlay)
+                else:
+                    # Single overlay - assume it's for a single hemi (use as-is)
+                    all_overlays.append(overlay)
+
+        # Combine geometry
+        vertices = np.vstack(all_vertices).astype(np.float32)
+        faces = np.vstack(all_faces).astype(np.int32)
+
+        # Combine overlays if provided
+        if _layered_overlays is not None:
+            # Multi-layer: concatenate each layer across hemispheres
+            overlay = [np.concatenate(layers) for layers in _layered_overlays]
+        elif all_overlays:
+            overlay = np.concatenate(all_overlays)
+
+        # Use first hemi for view calculations (lateral/medial)
+        hemi = hemis_list[0]
+        hemi = "lh" if hemi.lower().startswith("l") else "rh"
+
+        # Continue with merged geometry (skip surface resolution below)
+        # vertices and faces are already set
+
+    # Support rendering multiple surfaces into a single axes.
+    # Accept a dict (e.g. from vol_to_mesh with labels): keys → labels, values → surfaces.
+    if isinstance(surface, dict):
+        if label is False or label is None:
+            label = list(surface.keys())
+        # Auto-apply FreeSurfer LUT colors when available (LabeledMeshes)
+        if color is None and hasattr(surface, "colors") and surface.colors:
+            color = [
+                surface.colors.get(k, None) for k in surface.keys()
+            ]
+            # Fall back to None if no key matched
+            if all(c is None for c in color):
+                color = None
+        surface = list(surface.values())
+
+    if isinstance(surface, (list, tuple)):
+        n = len(surface)
+        # Normalize overlays to list length n
+        if isinstance(overlay, (list, tuple)):
+            overlays_list = list(overlay)
+        elif (
+            (overlay is not None)
+            and hasattr(overlay, "shape")
+            and hasattr(overlay, "__getitem__")
+        ):
+            try:
+                overlays_list = [overlay[i] for i in range(len(overlay))]
+            except Exception:
+                overlays_list = [overlay] * n
+        else:
+            overlays_list = [overlay] * n
+        if len(overlays_list) != n:
+            raise ValueError(
+                f"overlay must have first dimension equal to number of surfaces ({n}), got {len(overlays_list)}"
+            )
+
+        # Normalize hemis to per-surface list if provided as sequence
+        if isinstance(hemi, (list, tuple)):
+            hemis_list = list(hemi)
+            if len(hemis_list) != n:
+                raise ValueError(
+                    f"hemi must be a string or a sequence with length equal to number of surfaces ({n})"
+                )
+        else:
+            hemis_list = [hemi] * n
+
+        # Optional per-surface vertices/faces
+        vertices_list = None
+        faces_list = None
+        if isinstance(vertices, (list, tuple)):
+            if len(vertices) != n:
+                raise ValueError("vertices list must match number of surfaces")
+            vertices_list = list(vertices)
+        if isinstance(faces, (list, tuple)):
+            if len(faces) != n:
+                raise ValueError("faces list must match number of surfaces")
+            faces_list = list(faces)
+
+        # Sample overlay_volume at each mesh's world-coordinate vertices
+        if overlay_volume is not None and all(o is None for o in overlays_list):
+            _vol = (
+                nibabel.load(overlay_volume)
+                if isinstance(overlay_volume, (str, os.PathLike))
+                else overlay_volume
+            )
+            # Derive projection axis from view when intensity_projection is set
+            _proj_axis = None
+            if intensity_projection is not None:
+                _proj_axis = _PROJECTION_AXES.get(
+                    view.lower() if isinstance(view, str) else None
+                )
+                if _proj_axis is None:
+                    raise ValueError(
+                        "intensity_projection requires a named view "
+                        "(e.g. 'lateral', 'frontal', 'top') to determine "
+                        "the projection axis."
+                    )
+            for _ov_i in range(n):
+                _v_i = None if vertices_list is None else vertices_list[_ov_i]
+                if _v_i is None:
+                    _v_i, _ = _resolve_surface_geometry(
+                        surface[_ov_i],
+                        hemi=hemis_list[_ov_i],
+                        surface_suffix=surface_suffix,
+                        surface_density=surface_density,
+                        surface_kwargs=surface_kwargs,
+                    )
+                _v_i = np.asarray(_v_i, dtype=np.float32)
+                if affine is not None and affine.shape == (4, 4):
+                    _v_i = nibabel.affines.apply_affine(affine, _v_i)
+                overlays_list[_ov_i] = _sample_volume_at_vertices(
+                    _vol, _v_i,
+                    threshold=sampling_threshold if sampling_threshold is not None else threshold,
+                    intensity_projection=intensity_projection,
+                    projection_axis=_proj_axis,
+                )
+
+        # Normalize per-surface styling parameters: if a list is provided,
+        # index per surface; if scalar/None, broadcast to all surfaces.
+        def _broadcast(param, name):
+            if isinstance(param, (list, tuple)):
+                if len(param) != n:
+                    raise ValueError(
+                        f"{name} list length ({len(param)}) must match number of surfaces ({n})"
+                    )
+                return list(param)
+            return [param] * n
+
+        colors_list = _broadcast(color, "color")
+        cmaps_list = _broadcast(cmap, "cmap")
+        transparency_list = _broadcast(transparency, "alpha/transparency")
+        vmin_list = _broadcast(vmin, "vmin")
+        vmax_list = _broadcast(vmax, "vmax")
+        labels_list = _broadcast(label, "label")
+
+        # faces_kwargs: list of dicts → per-surface; single dict → broadcast
+        if isinstance(faces_kwargs, list):
+            if len(faces_kwargs) != n:
+                raise ValueError(
+                    f"faces_kwargs list length ({len(faces_kwargs)}) must match "
+                    f"number of surfaces ({n})"
+                )
+            fk_list = list(faces_kwargs)
+        else:
+            fk_list = [faces_kwargs] * n
+
+        # ------------------------------------------------------------------
+        # Depth-correct rendering: use the first surface as the main surface
+        # and pass the rest through `additional_surfaces` so all triangles
+        # are merged into one PolyCollection and depth-sorted together.
+        # ------------------------------------------------------------------
+        created_fig = False
+        if ax is None:
+            fig, ax = plt.subplots()
+            created_fig = True
+        else:
+            fig = ax.figure
+
+        # First surface is the "main" one
+        main_surf = surface[0]
+        main_verts = None if vertices_list is None else vertices_list[0]
+        main_faces = None if faces_list is None else faces_list[0]
+
+        # Remaining surfaces go through the additional_surfaces path
+        add_surfs = list(surface[1:]) if n > 1 else []
+        add_overlays = list(overlays_list[1:]) if n > 1 else []
+        add_colors = list(colors_list[1:]) if n > 1 else []
+        add_alphas = list(transparency_list[1:]) if n > 1 else []
+        add_cmaps = list(cmaps_list[1:]) if n > 1 else []
+        add_vmins = list(vmin_list[1:]) if n > 1 else []
+        add_vmaxs = list(vmax_list[1:]) if n > 1 else []
+
+        # Merge any user-supplied additional_surfaces into the list
+        _add_labels_for_legend = []
+        _add_colors_for_legend = []
+        if additional_surfaces is not None and len(additional_surfaces) > 0:
+            add_surfs.extend(additional_surfaces)
+            _n_user_add = len(additional_surfaces)
+            add_overlays.extend(
+                additional_overlays if additional_overlays else [None] * _n_user_add
+            )
+            _user_add_colors = (
+                additional_colors if additional_colors else [None] * _n_user_add
+            )
+            add_colors.extend(_user_add_colors)
+            add_alphas.extend(
+                additional_alphas if additional_alphas else [1] * _n_user_add
+            )
+            add_cmaps.extend(
+                additional_cmaps if additional_cmaps else [None] * _n_user_add
+            )
+            add_vmins.extend(
+                additional_vmins if additional_vmins else [None] * _n_user_add
+            )
+            add_vmaxs.extend(
+                additional_vmaxs if additional_vmaxs else [None] * _n_user_add
+            )
+            # Track labels from dict-unpacked additional_surfaces
+            if _additional_labels is not None:
+                _add_labels_for_legend = list(_additional_labels)
+                _add_colors_for_legend = list(_user_add_colors)
+
+        # Convert empty lists to None for downstream compatibility
+        if not add_surfs:
+            add_surfs = None
+            add_overlays = None
+            add_colors = None
+            add_alphas = None
+            add_cmaps = None
+            add_vmins = None
+            add_vmaxs = None
+
+        # Compute shared bounding box across ALL meshes so that the
+        # main surface and all additional surfaces share one normalization.
+        if _shared_bbox is None:
+            all_verts = []
+            _all_sources = list(surface)
+            if add_surfs is not None:
+                _all_sources.extend(add_surfs)
+            for _i, _s in enumerate(_all_sources):
+                _v_i = None
+                if _i < n and vertices_list is not None:
+                    _v_i = vertices_list[_i]
+                if _v_i is None:
+                    _h = hemis_list[_i] if _i < len(hemis_list) else hemi
+                    _v_i, _ = _resolve_surface_geometry(
+                        _s,
+                        hemi=_h,
+                        surface_suffix=surface_suffix,
+                        surface_density=surface_density,
+                        surface_kwargs=surface_kwargs,
+                    )
+                _v_i = np.asarray(_v_i, dtype=np.float32)
+                if affine is not None and affine.shape == (4, 4):
+                    _v_i = (np.c_[_v_i, np.ones(len(_v_i))] @ affine.T)[:, :3]
+                all_verts.append(_v_i)
+            _all = np.vstack(all_verts)
+            _shared_bbox = (_all.min(0), _all.max(0))
+
+        result = plot_surf(
+            main_surf,
+            overlay=overlays_list[0],
+            vertices=main_verts,
+            faces=main_faces,
+            ax=ax,
+            parcellated=parcellated,
+            hemi=hemis_list[0],
+            view=view,
+            cmap=cmaps_list[0],
+            color=colors_list[0],
+            label=False,  # legend proxies are added below for all surfaces
+            vmax=vmax_list[0],
+            vmin=vmin_list[0],
+            x_rotate=x_rotate,
+            pvals=pvals,
+            mask=mask,
+            arrows=arrows,
+            arrow_subset=arrow_subset,
+            arrow_size=arrow_size,
+            arrow_colours=arrow_colours,
+            arrow_head=arrow_head,
+            arrow_width=arrow_width,
+            mask_colour=mask_colour,
+            transparency=transparency_list[0],
+            faces_kwargs=fk_list,
+            show_back=show_back,
+            border_colour=border_colour,
+            alpha_colour=alpha_colour,
+            flat_map=flat_map,
+            z_rotate=z_rotate,
+            neighbours=neighbours,
+            parcel=parcel,
+            parcel_cmap=parcel_cmap,
+            filled_parcels=filled_parcels,
+            norm=norm,
+            world_coords=world_coords,
+            affine=affine,
+            flip_x=flip_x,
+            threshold=threshold,
+            threshold_color=threshold_color,
+            surface_suffix=surface_suffix,
+            surface_density=surface_density,
+            surface_kwargs=surface_kwargs,
+            additional_surfaces=add_surfs,
+            additional_overlays=add_overlays,
+            additional_colors=add_colors,
+            additional_alphas=add_alphas,
+            additional_cmaps=add_cmaps,
+            additional_vmins=add_vmins,
+            additional_vmaxs=add_vmaxs,
+            _shared_bbox=_shared_bbox,
+            **kwargs,
+        )
+
+        # Add legend proxy patches for all surfaces that have labels
+        for i in range(n):
+            lbl = labels_list[i]
+            if lbl and lbl is not False:
+                col = colors_list[i]
+                if col is None:
+                    col = (0.86, 0.86, 0.86, 1.0)
+                import matplotlib.patches as _mp
+                import matplotlib.colors as _mc
+                _proxy = _mp.Rectangle(
+                    (0, 0), 0, 0,
+                    facecolor=_mc.to_rgba(col),
+                    label=lbl,
+                )
+                ax.add_patch(_proxy)
+
+        # Add legend proxies for dict-unpacked additional surfaces
+        if _add_labels_for_legend:
+            import matplotlib.patches as _mp
+            import matplotlib.colors as _mc
+            for _al_i, _al_lbl in enumerate(_add_labels_for_legend):
+                _al_col = (
+                    _add_colors_for_legend[_al_i]
+                    if _al_i < len(_add_colors_for_legend)
+                    else None
+                )
+                if _al_col is None:
+                    _al_col = (0.86, 0.86, 0.86, 1.0)
+                _proxy = _mp.Rectangle(
+                    (0, 0), 0, 0,
+                    facecolor=_mc.to_rgba(_al_col),
+                    label=_al_lbl,
+                )
+                ax.add_patch(_proxy)
+
+        ax.set_aspect("equal")
+
+        if created_fig:
+            plt.close(fig)
+            return fig
+        return result
+    else:
+        hemi = "lh" if hemi.lower().startswith("l") else "rh"
+    # SINGLE-SURFACE CODE PATH BELOW
+    _is_true_flatmap = False
+    if flat_map and isinstance(surface, str) and not os.path.isfile(surface):
+        # Use a true cortical flatmap mesh if available for this template
+        from bsplot.data.surface import get_flat_surface_geometry
+
+        try:
+            flat_vertices, flat_faces = get_flat_surface_geometry(
+                template=surface, hemi=hemi
+            )
+            # Resolve the original surface only if we need overlay vertex count
+            if vertices is None or faces is None:
+                vertices, faces = _resolve_surface_geometry(
+                    surface,
+                    hemi=hemi,
+                    surface_suffix=surface_suffix,
+                    surface_density=surface_density,
+                    surface_kwargs=surface_kwargs,
+                )
+            # Use flat geometry for rendering; overlay is vertex-indexed so it
+            # stays valid as long as the vertex count matches.
+            if flat_vertices.shape[0] == vertices.shape[0]:
+                vertices = flat_vertices
+                faces = flat_faces
+                # Force a top-down view so the flat surface is seen face-on
+                view = "top"
+                x_rotate = 0
+                z_rotate = 0
+                _is_true_flatmap = True
+            else:
+                raise ValueError(
+                    f"Flat surface vertex count ({flat_vertices.shape[0]}) does not match "
+                    f"surface vertex count ({vertices.shape[0]}) for template '{surface}'."
+                )
+        except ValueError:
+            raise
+
+    if vertices is None or faces is None:
+        vertices, faces = _resolve_surface_geometry(
+            surface,
+            hemi=hemi,
+            surface_suffix=surface_suffix,
+            surface_density=surface_density,
+            surface_kwargs=surface_kwargs,
+        )
+
+    if ax is None:
+        fig, ax = plt.subplots()
+        return_fig = True
+    else:
+        return_fig = False
+    # Map text views to canonical rotations (preserve behavior)
+    view, x_rotate, z_rotate, view_token = _map_view_to_rotations(
+        view, hemi, x_rotate, z_rotate
+    )
+
+    vertices = vertices.astype(np.float32)
+    F = faces.astype(int)
+
+    # Optional: decimate mesh to reduce vertex/face count
+    if surface_decimate is not None and 0 < surface_decimate < 1:
+        decimated = False
+        orig_vertices = vertices.copy()  # keep for overlay remapping
+        # Try Open3D quadric decimation (best quality)
+        if not decimated:
+            try:
+                import open3d as o3d
+                mesh = o3d.geometry.TriangleMesh()
+                mesh.vertices = o3d.utility.Vector3dVector(vertices)
+                mesh.triangles = o3d.utility.Vector3iVector(F)
+                mesh.compute_vertex_normals()
+                target = max(int(len(F) * surface_decimate), 4)
+                mesh = mesh.simplify_quadric_decimation(
+                    target_number_of_triangles=target
+                )
+                vertices = np.asarray(mesh.vertices, dtype=np.float32)
+                F = np.asarray(mesh.triangles, dtype=int)
+                decimated = True
+                _decimate_method = "open3d"
+            except (ImportError, Exception):
+                pass
+        # Fallback: vertex clustering (spatial binning)
+        if not decimated:
+            # Estimate grid resolution from desired face fraction
+            n_target_verts = max(int(len(vertices) * surface_decimate), 12)
+            bbox_range = vertices.max(0) - vertices.min(0)
+            vol = np.prod(bbox_range + 1e-9)
+            cell_size = (vol / n_target_verts) ** (1.0 / 3.0)
+            # Assign each vertex to a grid cell
+            grid_idx = ((vertices - vertices.min(0)) / cell_size).astype(int)
+            # Unique cell keys
+            keys = (
+                grid_idx[:, 0] * 1000000
+                + grid_idx[:, 1] * 1000
+                + grid_idx[:, 2]
+            )
+            unique_keys, inverse = np.unique(keys, return_inverse=True)
+            # Compute cluster centroids
+            new_verts = np.zeros((len(unique_keys), 3), dtype=np.float32)
+            for i in range(len(unique_keys)):
+                mask = inverse == i
+                new_verts[i] = vertices[mask].mean(axis=0)
+            # Remap faces
+            new_F = inverse[F]
+            # Remove degenerate faces (collapsed edges)
+            valid = (
+                (new_F[:, 0] != new_F[:, 1])
+                & (new_F[:, 1] != new_F[:, 2])
+                & (new_F[:, 0] != new_F[:, 2])
+            )
+            new_F = new_F[valid]
+            # Remove duplicate faces
+            sorted_f = np.sort(new_F, axis=1)
+            _, uidx = np.unique(sorted_f, axis=0, return_index=True)
+            new_F = new_F[uidx]
+            vertices = new_verts
+            F = new_F
+            decimated = True
+            _decimate_method = "clustering"
+
+        # Remap overlay(s) to decimated vertices via nearest-neighbor lookup
+        def _remap_overlay_to_decimated(ov, orig_v, new_v):
+            """Map per-vertex overlay from original to decimated mesh."""
+            if ov is None or not hasattr(ov, '__len__'):
+                return ov
+            if len(ov) == len(new_v):
+                return ov  # already matching
+            if len(ov) != len(orig_v):
+                return None  # incompatible size
+            from scipy.spatial import cKDTree
+            tree = cKDTree(orig_v)
+            _, nn_idx = tree.query(new_v)
+            return ov[nn_idx]
+
+        if overlay is not None:
+            if isinstance(overlay, list):
+                overlay = [_remap_overlay_to_decimated(o, orig_vertices, vertices) for o in overlay]
+            else:
+                overlay = _remap_overlay_to_decimated(overlay, orig_vertices, vertices)
+
+    # Optional: transform vertices by a provided 4x4 affine (e.g., to MNI space).
+    if affine is not None:
+        if affine.shape == (4, 4):
+            vertices = (np.c_[vertices, np.ones(len(vertices))] @ affine.T)[:, :3]
+        else:
+            raise ValueError("affine must be a 4x4 matrix")
+
+    # Preserve world-space copy for axis extents
+    vertices_world = vertices.copy()
+
+    # Sample overlay_volume at world-coordinate vertices (single-surface path)
+    if overlay_volume is not None and overlay is None:
+        _proj_axis = None
+        if intensity_projection is not None:
+            _proj_axis = _PROJECTION_AXES.get(
+                view.lower() if isinstance(view, str) else None
+            )
+            if _proj_axis is None:
+                raise ValueError(
+                    "intensity_projection requires a named view "
+                    "(e.g. 'lateral', 'frontal', 'top') to determine "
+                    "the projection axis."
+                )
+        overlay = _sample_volume_at_vertices(
+            overlay_volume, vertices_world,
+            threshold=sampling_threshold if sampling_threshold is not None else threshold,
+            intensity_projection=intensity_projection,
+            projection_axis=_proj_axis,
+        )
+
+    # Always normalize for rendering stability
+    # When _shared_bbox is set (list-of-surfaces path), use the shared
+    # center/scale so all meshes keep their relative positions.
+    if _shared_bbox is not None:
+        _bbox_min, _bbox_max = _shared_bbox
+        _center = (_bbox_max + _bbox_min) / 2
+        _scale = max(_bbox_max - _bbox_min)
+    else:
+        _center = (vertices.max(0) + vertices.min(0)) / 2
+        _scale = max(vertices.max(0) - vertices.min(0))
+    # Guard against zero extent (degenerate mesh)
+    if _scale == 0:
+        _scale = 1.0
+    proj_vertices = (vertices - _center) / _scale
+
+    overlays = [overlay] if not isinstance(overlay, list) else overlay
+    n_overlays = len(overlays)
+
+    # Normalize cmap to per-overlay list
+    if isinstance(cmap, (list, tuple)):
+        cmaps = list(cmap)
+        if len(cmaps) != n_overlays:
+            raise ValueError(
+                f"cmap list length ({len(cmaps)}) must match number of overlays ({n_overlays})"
+            )
+    else:
+        cmaps = [cmap] * n_overlays
+
+    # Normalize transparency to per-overlay list
+    if isinstance(transparency, (list, tuple)):
+        transparencies = list(transparency)
+        if len(transparencies) != n_overlays:
+            raise ValueError(
+                f"transparency list length ({len(transparencies)}) must match number of overlays ({n_overlays})"
+            )
+    else:
+        transparencies = [transparency] * n_overlays
+
+    if parcel is not None and parcel.sum() == 0:
+        parcel = None
+
+    # Shading intensity based on normalized geometry
+    if _is_true_flatmap:
+        # Flat surface has uniform normals — skip 3D shading
+        intensity = np.ones(len(F))
+    else:
+        intensity, z_rotate = _compute_shading_intensity(
+            proj_vertices, F, view_token, view, z_rotate, x_rotate
+        )
+
+    collection = None
+    for k, overlay in enumerate(overlays):
+        # If no overlay provided, use a uniform base colour and still apply shading
+        if overlay is None:
+            C = np.ones((len(F), 4), dtype=float)
+            # Use custom color if provided, otherwise default grey
+            if color is not None:
+                import matplotlib.colors as mcolors
+
+                base_color = np.array(mcolors.to_rgba(color))
+                C[:] = base_color
+            else:
+                C[:] = np.array([0.86, 0.86, 0.86, 1.0])
+            # Allow parcel boundaries/fills even without overlay
+            if parcel is not None:
+                C = add_parcellation_colours(
+                    C,
+                    parcel,
+                    F,
+                    parcel_cmap,
+                    mask,
+                    mask_colour=mask_colour,
+                    filled=filled_parcels,
+                    neighbours=neighbours,
+                )
+        else:
+            # Identify faces where ALL vertices are NaN (before aggregation)
+            face_values = overlay[F]  # shape (n_faces, 3)
+            nan_faces = np.all(np.isnan(face_values), axis=1)
+
+            # Per-face colour aggregation (NaN-safe)
+            # For all-NaN faces, temporarily fill with 0 to avoid empty-slice warnings;
+            # these faces are overridden to grey below anyway.
+            face_values_filled = face_values.copy()
+            face_values_filled[nan_faces] = 0.0
+
+            if label:
+                colours = np.nanmedian(face_values_filled, axis=1)
+            elif parcellated:
+                colours = np.nanmax(face_values_filled, axis=1)
+            else:
+                colours = np.nanmean(face_values_filled, axis=1)
+
+            # Normalize to [0,1]
+            if norm is not None:
+                colours = norm(colours)
+            else:
+                if vmax is not None and vmin is not None:
+                    colours = (colours - vmin) / (vmax - vmin)
+                    colours = np.clip(colours, 0, 1)
+                else:
+                    cmin = np.nanmin(colours)
+                    cmax = np.nanmax(colours)
+                    if cmax > cmin:
+                        colours = (colours - cmin) / (cmax - cmin)
+                    else:
+                        colours = np.zeros_like(colours)
+
+            cmap_func = Colormap(cmaps[k])
+            C = cmap_func(np.clip(colours, 0, 1))
+
+            # Grey out triangles below threshold
+            # Default threshold color is light grey
+            if threshold_color is None:
+                below_thresh_color = np.array([0.86, 0.86, 0.86, 1.0])
+            else:
+                # Convert color to RGBA
+                import matplotlib.colors as mcolors
+                below_thresh_color = np.array(mcolors.to_rgba(threshold_color))
+
+            # Also grey out faces that were NaN
+            C[nan_faces] = below_thresh_color
+
+            # Apply threshold only when explicitly set
+            if threshold is not None:
+                # A triangle is below threshold if ANY of its vertices is at or below threshold
+                is_below_threshold = np.any(overlay[F] <= threshold, axis=1)
+                C[is_below_threshold] = below_thresh_color
+
+            # Optional adjustments
+            if alpha_colour is not None:
+                C = adjust_colours_alpha(C, np.mean(alpha_colour[F], axis=1))
+            if pvals is not None:
+                C = adjust_colours_pvals(
+                    C,
+                    pvals,
+                    F,
+                    mask,
+                    mask_colour=mask_colour,
+                    border_colour=border_colour,
+                )
+            elif mask is not None:
+                C = mask_colours(C, F, mask, mask_colour=mask_colour)
+            if parcel is not None:
+                C = add_parcellation_colours(
+                    C,
+                    parcel,
+                    F,
+                    parcel_cmap,
+                    mask,
+                    mask_colour=mask_colour,
+                    filled=filled_parcels,
+                    neighbours=neighbours,
+                )
+
+        # Capture pre-shading face color for legend proxy (before shading darkens it)
+        _legend_color = C[0].copy() if (label and label is not False) else None
+
+        # Apply lighting intensity to RGB channels
+        C[:, 0:3] *= intensity[:, None]
+
+        # Perspective MVP for robust drawing
+        MVP = (
+            perspective(25, 1, 1, 100)
+            @ translate(0, 0, -3)
+            @ yrotate(view)
+            @ zrotate(z_rotate)
+            @ xrotate(x_rotate)
+        )
+
+        # Initialize arrow placeholders for type checkers
+        A_base = None
+        A_dir = None
+
+        # Project all vertices
+        V_all = np.c_[proj_vertices, np.ones(len(proj_vertices))] @ MVP.T
+        V_all /= V_all[:, 3:4]
+
+        # Arrow bases/directions
+        if arrows is not None:
+            vertex_normal_orig = vertex_normals(proj_vertices, F)
+            A_base = (
+                np.c_[
+                    proj_vertices + vertex_normal_orig * 0.01,
+                    np.ones(len(proj_vertices)),
+                ]
+                @ MVP.T
+            )
+            A_base /= A_base[:, 3:4]
+
+            A_dir = np.copy(arrows)
+            max_arrow = np.max(np.linalg.norm(arrows, axis=1))
+            if max_arrow > 0:
+                A_dir = arrow_size * A_dir / max_arrow
+            A_dir = np.c_[A_dir, np.ones(len(A_dir))] @ MVP.T
+            A_dir /= A_dir[:, 3:4]
+
+        # Triangles
+        V = V_all[F]
+        T = V[:, :, :2]
+
+        # If world_coords requested, map projected plane to world-plane extents
+        if world_coords:
+            V_full_proj = V_all  # already projected all
+            pxmin, pxmax = V_full_proj[:, 0].min(), V_full_proj[:, 0].max()
+            pymin, pymax = V_full_proj[:, 1].min(), V_full_proj[:, 1].max()
+
+            ROT = (
+                yrotate(view)
+                @ zrotate(z_rotate)
+                @ xrotate(x_rotate)
+            )
+            V_world = np.c_[vertices_world, np.ones(len(vertices_world))] @ ROT.T
+            wxmin, wxmax = V_world[:, 0].min(), V_world[:, 0].max()
+            wymin, wymax = V_world[:, 1].min(), V_world[:, 1].max()
+
+            sx = (wxmax - wxmin) / (pxmax - pxmin) if (pxmax - pxmin) != 0 else 1.0
+            sy = (wymax - wymin) / (pymax - pymin) if (pymax - pymin) != 0 else 1.0
+
+            T[:, :, 0] = wxmin + (T[:, :, 0] - pxmin) * sx
+            T[:, :, 1] = wymin + (T[:, :, 1] - pymin) * sy
+
+            # Flip x-axis around x=0 (brain midline) to match slice neurological convention
+            if flip_x:
+                T[:, :, 0] = -T[:, :, 0]
+
+            if arrows is not None:
+                A_base[:, 0] = wxmin + (A_base[:, 0] - pxmin) * sx
+                A_base[:, 1] = wymin + (A_base[:, 1] - pymin) * sy
+                A_dir[:, 0] = A_dir[:, 0] * sx
+                A_dir[:, 1] = A_dir[:, 1] * sy
+
+                if flip_x:
+                    A_base[:, 0] = -A_base[:, 0]
+                    A_dir[:, 0] = -A_dir[:, 0]
+
+        # Depth sort and cull
+        Z = -V[:, :, 2].mean(axis=1)
+        front, back = frontback(T)
+        if show_back is False:
+            T = T[front]
+            s_C = C[front]
+            Z = Z[front]
+        else:
+            s_C = C
+
+        face_hash = (F[:, 0] * 73856093 + F[:, 1] * 19349663 + F[:, 2] * 83492791) % (
+            2**31
+        )
+        if show_back is False:
+            face_hash = face_hash[front]
+
+        # -------------------------
+        # Process additional surfaces for depth-correct rendering
+        # -------------------------
+        all_T = [T]
+        all_C = [s_C]
+        all_Z = [Z]
+        all_hash = [face_hash]
+        all_alpha = [np.full(len(T), transparencies[k])]
+        all_surf_idx = [np.zeros(len(T), dtype=int)]  # 0 = main surface
+
+        if additional_surfaces is not None and len(additional_surfaces) > 0:
+            n_add = len(additional_surfaces)
+
+            # Normalize parameters to lists
+            add_overlays = (
+                additional_overlays
+                if additional_overlays is not None
+                else [None] * n_add
+            )
+            add_colors = (
+                additional_colors if additional_colors is not None else [None] * n_add
+            )
+            add_alphas = (
+                additional_alphas if additional_alphas is not None else [1.0] * n_add
+            )
+            add_cmaps = (
+                additional_cmaps if additional_cmaps is not None else [cmaps[k]] * n_add
+            )
+            add_vmins = (
+                additional_vmins if additional_vmins is not None else [None] * n_add
+            )
+            add_vmaxs = (
+                additional_vmaxs if additional_vmaxs is not None else [None] * n_add
+            )
+
+            # Extend lists if needed
+            if len(add_overlays) < n_add:
+                add_overlays = list(add_overlays) + [None] * (n_add - len(add_overlays))
+            if len(add_colors) < n_add:
+                add_colors = list(add_colors) + [None] * (n_add - len(add_colors))
+            if len(add_alphas) < n_add:
+                add_alphas = list(add_alphas) + [1.0] * (n_add - len(add_alphas))
+            if len(add_cmaps) < n_add:
+                add_cmaps = list(add_cmaps) + [cmaps[k]] * (n_add - len(add_cmaps))
+            if len(add_vmins) < n_add:
+                add_vmins = list(add_vmins) + [None] * (n_add - len(add_vmins))
+            if len(add_vmaxs) < n_add:
+                add_vmaxs = list(add_vmaxs) + [None] * (n_add - len(add_vmaxs))
+
+            for surf_idx, add_surf in enumerate(additional_surfaces):
+                # Resolve surface geometry
+                add_verts, add_faces = _resolve_surface_geometry(
+                    add_surf,
+                    hemi=hemi,
+                    surface_suffix=surface_suffix,
+                    surface_density=surface_density,
+                    surface_kwargs=surface_kwargs,
+                )
+                add_verts = add_verts.astype(np.float32)
+                add_F = add_faces.astype(int)
+
+                # Apply affine if provided
+                if affine is not None and affine.shape == (4, 4):
+                    add_verts = (np.c_[add_verts, np.ones(len(add_verts))] @ affine.T)[
+                        :, :3
+                    ]
+
+                # Normalize for rendering (use same center/scale as main surface for consistency)
+                add_proj_verts = (add_verts - _center) / _scale
+
+                # Compute shading intensity
+                add_intensity, _ = _compute_shading_intensity(
+                    add_proj_verts,
+                    add_F,
+                    view_token,
+                    view,
+                    z_rotate,
+                    x_rotate,
+                )
+
+                # Get overlay and color for this surface
+                add_overlay = add_overlays[surf_idx]
+                add_color = add_colors[surf_idx]
+                add_alpha = add_alphas[surf_idx]
+                add_cmap = add_cmaps[surf_idx]
+                add_vmin = add_vmins[surf_idx]
+                add_vmax = add_vmaxs[surf_idx]
+
+                # Compute face colors (similar to main surface logic)
+                if add_overlay is None:
+                    add_C = np.ones((len(add_F), 4), dtype=float)
+                    if add_color is not None:
+                        import matplotlib.colors as mcolors
+
+                        base_color = np.array(mcolors.to_rgba(add_color))
+                        add_C[:] = base_color
+                    else:
+                        add_C[:] = np.array([0.86, 0.86, 0.86, 1.0])
+                else:
+                    # Per-face colour aggregation
+                    add_colours = np.mean(add_overlay[add_F], axis=1)
+
+                    # Handle NaN values in overlay (from value_threshold)
+                    nan_mask = np.isnan(add_colours)
+
+                    # Normalize to [0,1]
+                    if add_vmax is not None and add_vmin is not None:
+                        add_colours = (add_colours - add_vmin) / (add_vmax - add_vmin)
+                        add_colours = np.clip(add_colours, 0, 1)
+                    else:
+                        valid_colours = add_colours[~nan_mask]
+                        if len(valid_colours) > 0:
+                            cmin, cmax = np.nanmin(valid_colours), np.nanmax(
+                                valid_colours
+                            )
+                            if cmax > cmin:
+                                add_colours = (add_colours - cmin) / (cmax - cmin)
+                            else:
+                                add_colours = np.zeros_like(add_colours)
+                        else:
+                            add_colours = np.zeros_like(add_colours)
+
+                    cmap_func = Colormap(add_cmap)
+                    add_C = cmap_func(np.clip(np.nan_to_num(add_colours, nan=0), 0, 1))
+
+                    # Grey out NaN triangles (faces where any vertex has NaN)
+                    grey = np.array([0.86, 0.86, 0.86, 1.0])
+                    nan_faces = np.any(np.isnan(add_overlay[add_F]), axis=1)
+                    add_C[nan_faces] = grey
+
+                    # Grey out faces below threshold
+                    if threshold is not None:
+                        is_below = np.any(add_overlay[add_F] <= threshold, axis=1)
+                        add_C[is_below] = grey
+
+                # Apply shading intensity
+                add_C[:, 0:3] *= add_intensity[:, None]
+
+                # Project vertices
+                add_V_all = np.c_[add_proj_verts, np.ones(len(add_proj_verts))] @ MVP.T
+                add_V_all /= add_V_all[:, 3:4]
+
+                # Get triangles
+                add_V = add_V_all[add_F]
+                add_T = add_V[:, :, :2]
+
+                # Transform to world coords if needed
+                if world_coords:
+                    add_T[:, :, 0] = wxmin + (add_T[:, :, 0] - pxmin) * sx
+                    add_T[:, :, 1] = wymin + (add_T[:, :, 1] - pymin) * sy
+
+                    # Flip x-axis around x=0 to match slice neurological convention
+                    if flip_x:
+                        add_T[:, :, 0] = -add_T[:, :, 0]
+
+                # Depth and culling
+                add_Z = -add_V[:, :, 2].mean(axis=1)
+                add_front, _ = frontback(add_T)
+                if show_back is False:
+                    add_T = add_T[add_front]
+                    add_C = add_C[add_front]
+                    add_Z = add_Z[add_front]
+
+                add_face_hash = (
+                    add_F[:, 0] * 73856093
+                    + add_F[:, 1] * 19349663
+                    + add_F[:, 2] * 83492791
+                ) % (2**31)
+                if show_back is False:
+                    add_face_hash = add_face_hash[add_front]
+
+                # Append to combined lists
+                all_T.append(add_T)
+                all_C.append(add_C)
+                all_Z.append(add_Z)
+                all_hash.append(add_face_hash)
+                all_alpha.append(np.full(len(add_T), add_alpha))
+                all_surf_idx.append(np.full(len(add_T), surf_idx + 1, dtype=int))
+
+        # Combine all triangles and sort by depth
+        combined_T = np.concatenate(all_T, axis=0)
+        combined_C = np.concatenate(all_C, axis=0)
+        combined_Z = np.concatenate(all_Z, axis=0)
+        combined_hash = np.concatenate(all_hash, axis=0)
+        combined_alpha = np.concatenate(all_alpha, axis=0)
+
+        I = np.lexsort((combined_hash, combined_Z))
+        combined_T = combined_T[I]
+        combined_C = combined_C[I]
+        combined_alpha = combined_alpha[I]
+
+        # Apply per-face alpha
+        combined_C[:, 3] *= combined_alpha
+
+        # Mark fully transparent faces as NaN so matplotlib skips them.
+        # Only affect faces where alpha is exactly 0 (intentionally hidden).
+        _fully_transparent = combined_C[:, 3] == 0
+        combined_C[_fully_transparent] = np.nan
+        combined_surf_idx = np.concatenate(all_surf_idx, axis=0)[I]
+
+        # Per-face styling: faces_kwargs applies only to main surface by default.
+        # If faces_kwargs is a list, element 0 → main, 1 → additional[0], etc.
+        import matplotlib.colors as _mcolors
+
+        _fc = combined_C.copy()
+        _ec = np.zeros((len(combined_T), 4))  # no edges by default
+        _lw = np.zeros(len(combined_T))
+        _extra_kw = dict(antialiased=False)
+
+        if faces_kwargs is not None:
+            if isinstance(faces_kwargs, list):
+                fk_list = faces_kwargs
+            else:
+                fk_list = [faces_kwargs]  # single dict → apply to main only
+
+            for fk_idx, fk_dict in enumerate(fk_list):
+                if fk_dict is None:
+                    continue
+                mask = combined_surf_idx == fk_idx
+                if not mask.any():
+                    continue
+                # Process edgecolor first so "inherit"/"face" can grab
+                # the original face color before facecolor is cleared.
+                ordered_keys = sorted(fk_dict.keys(), key=lambda k: (k != "edgecolor", k))
+                for key in ordered_keys:
+                    val = fk_dict[key]
+                    if key == "facecolor":
+                        if val == "none" or val is None:
+                            _fc[mask] = [0, 0, 0, 0]
+                        else:
+                            _fc[mask] = np.array(_mcolors.to_rgba(val))
+                    elif key == "edgecolor":
+                        if val in ("inherit", "face"):
+                            # Copy the current face color as edge color
+                            _ec[mask] = _fc[mask]
+                        elif isinstance(val, (tuple, list)) and len(val) == 4:
+                            _ec[mask] = np.array(val)
+                        else:
+                            _ec[mask] = np.array(_mcolors.to_rgba(val))
+                    elif key == "linewidth":
+                        _lw[mask] = val
+                    else:
+                        _extra_kw[key] = val
+
+        collection = PolyCollection(
+            combined_T,
+            closed=True,
+            **_extra_kw,
+            **kwargs,
+        )
+        collection.set_facecolor(_fc)
+        collection.set_edgecolor(_ec)
+        collection.set_linewidths(_lw)
+        if label and label is not False:
+            import matplotlib.patches as mpatches
+            _proxy = mpatches.Rectangle(
+                (0, 0), 0, 0, facecolor=_legend_color, label=label
+            )
+            ax.add_patch(_proxy)
+
+        # Legend proxies for dict-unpacked additional surfaces
+        if _additional_labels is not None:
+            import matplotlib.patches as mpatches
+            import matplotlib.colors as _mcolors_leg
+            for _al_i, _al_lbl in enumerate(_additional_labels):
+                _al_col = (
+                    additional_colors[_al_i]
+                    if additional_colors and _al_i < len(additional_colors)
+                    else None
+                )
+                if _al_col is None:
+                    _al_col = (0.86, 0.86, 0.86, 1.0)
+                _proxy = mpatches.Rectangle(
+                    (0, 0), 0, 0,
+                    facecolor=_mcolors_leg.to_rgba(_al_col),
+                    label=_al_lbl,
+                )
+                ax.add_patch(_proxy)
+
+        for path in collection.get_paths():
+            path.codes[-1] = 0
+
+        ax.add_collection(collection)
+
+        # Optional vertex scatter overlay
+        if vertices_kwargs is not None:
+            _vkw = {
+                "s": 0.1,
+                "color": (0.6, 0.6, 0.6),
+                "alpha": 0.3,
+                "edgecolors": "none",
+                "rasterized": True,
+                "zorder": collection.get_zorder() + 0.5,
+            }
+            _vkw.update(vertices_kwargs)
+            # Decimate if requested
+            _v_decimate = _vkw.pop("decimate", None)
+            _v_dec_method = _vkw.pop("decimate_method", "uniform")
+            v_pts = V_all[:, :2].copy()
+            v_z = V_all[:, 2].copy()
+
+            # Transform to world coords (same as triangle coordinates)
+            if world_coords:
+                v_pts[:, 0] = wxmin + (v_pts[:, 0] - pxmin) * sx
+                v_pts[:, 1] = wymin + (v_pts[:, 1] - pymin) * sy
+                if flip_x:
+                    v_pts[:, 0] = -v_pts[:, 0]
+
+            if _v_decimate is not None and _v_decimate < 1.0:
+                step = max(1, int(1 / _v_decimate))
+                keep = np.arange(0, len(v_pts), step)
+                v_pts = v_pts[keep]
+                v_z = v_z[keep]
+            # Only show front-facing vertices (same depth cull as faces)
+            if show_back is False:
+                front_verts = np.unique(F[front].ravel()) if 'front' in dir() else np.arange(len(v_pts))
+                front_verts = front_verts[front_verts < len(v_pts)]
+                v_pts = v_pts[front_verts]
+                v_z = v_z[front_verts]
+            # Depth-based alpha
+            _v_alpha = _vkw.pop("alpha", 0.3)
+            z_range = v_z.max() - v_z.min()
+            z_norm = (v_z - v_z.min()) / (z_range + 1e-9)
+            per_point_alpha = _v_alpha * (0.3 + 0.7 * z_norm)
+            order = np.argsort(-v_z)  # back to front
+            ax.scatter(v_pts[order, 0], v_pts[order, 1], alpha=per_point_alpha[order], **_vkw)
+
+        # Axis limits - expand to include all surfaces
+        if world_coords:
+            # Start with main surface limits
+            all_wxmin, all_wxmax = wxmin, wxmax
+            all_wymin, all_wymax = wymin, wymax
+
+            # Expand for additional surfaces if present
+            if additional_surfaces is not None and len(additional_surfaces) > 0:
+                for add_surf in additional_surfaces:
+                    add_verts, _ = _resolve_surface_geometry(
+                        add_surf,
+                        hemi=hemi,
+                        surface_suffix=surface_suffix,
+                        surface_density=surface_density,
+                        surface_kwargs=surface_kwargs,
+                    )
+                    if affine is not None and affine.shape == (4, 4):
+                        add_verts = (
+                            np.c_[add_verts, np.ones(len(add_verts))] @ affine.T
+                        )[:, :3]
+                    add_V_world = np.c_[add_verts, np.ones(len(add_verts))] @ ROT.T
+                    all_wxmin = min(all_wxmin, add_V_world[:, 0].min())
+                    all_wxmax = max(all_wxmax, add_V_world[:, 0].max())
+                    all_wymin = min(all_wymin, add_V_world[:, 1].min())
+                    all_wymax = max(all_wymax, add_V_world[:, 1].max())
+
+            # Avoid singular transform when min == max
+            if all_wxmin == all_wxmax:
+                all_wxmin -= 0.5
+                all_wxmax += 0.5
+            if all_wymin == all_wymax:
+                all_wymin -= 0.5
+                all_wymax += 0.5
+            ax.set_xlim([all_wxmin, all_wxmax])
+            ax.set_ylim([all_wymin, all_wymax])
+        else:
+            x_min, x_max = V_all[:, 0].min(), V_all[:, 0].max()
+            y_min, y_max = V_all[:, 1].min(), V_all[:, 1].max()
+            if x_min == x_max:
+                x_min -= 0.5
+                x_max += 0.5
+            if y_min == y_max:
+                y_min -= 0.5
+                y_max += 0.5
+            ax.set_xlim([x_min, x_max])
+            ax.set_ylim([y_min, y_max])
+
+        ax.set_aspect("equal")
+
+        # Draw arrows (optional)
+        if arrows is not None and arrow_subset is not None:
+            front_arrows = F[front].ravel() if (show_back is False) else F.ravel()
+            center = np.array([0, 0, 0, 1]) @ MVP.T
+            center = center / center[3]
+            for arrow_index, i in enumerate(arrow_subset):
+                if i in front_arrows and A_base[i, 2] < center[2] + 0.01:
+                    arrow_colour = (
+                        arrow_colours[arrow_index] if arrow_colours is not None else "k"
+                    )
+                    if len(A_dir) == len(A_base):
+                        direction = A_dir[i]
+                    elif len(A_dir) == len(arrow_subset):
+                        direction = A_dir[arrow_index]
+                    else:
+                        direction = A_dir[i % len(A_dir)]
+                    half = direction * 0.5
+                    ax.arrow(
+                        A_base[i, 0] - half[0],
+                        A_base[i, 1] - half[1],
+                        direction[0],
+                        direction[1],
+                        head_width=arrow_head,
+                        width=arrow_width,
+                        color=arrow_colour,
+                    )
+
+    if return_fig:
+        plt.close()
+        return fig
+
+    return collection