Upload folder using huggingface_hub

Dockerfile

@@ -3,7 +3,7 @@ FROM python:3.10-slim
 WORKDIR /app
 
 RUN apt-get update && apt-get install -y --no-install-recommends \
-    build-essential \
+    build-essential xvfb libgl1-mesa-glx libglib2.0-0 \
     && rm -rf /var/lib/apt/lists/*
 
 COPY requirements.txt .

README.md

@@ -1,26 +1,28 @@
----
-title: CortexLab Dashboard
-emoji: 🧠
-colorFrom: purple
-colorTo: blue
-sdk: docker
-app_port: 7860
-license: cc-by-nc-4.0
-short_description: Interactive fMRI brain encoding analysis toolkit
-tags:
-  - neuroscience
-  - fmri
-  - brain-alignment
-  - streamlit
----
-
 # CortexLab Dashboard
 
-Interactive analysis dashboard for [CortexLab](https://github.com/siddhant-rajhans/cortexlab).
+Interactive analysis dashboard for [CortexLab](https://github.com/siddhant-rajhans/cortexlab) - multimodal fMRI brain encoding toolkit.
+
+## Pages
+
+- **Brain Alignment Benchmark** - Compare AI model representations against brain responses (RSA, CKA, Procrustes)
+- **Cognitive Load Scorer** - Visualize cognitive demand across visual, auditory, language, and executive dimensions
+- **Temporal Dynamics** - Peak latency, lag correlations, sustained vs transient response decomposition
+- **ROI Connectivity** - Correlation matrices, network clustering, degree centrality, graph visualization
+
+## Quick Start
+
+```bash
+pip install -r requirements.txt
+streamlit run Home.py
+```
+
+Runs on **synthetic data** by default - no GPU or real fMRI data required.
+
+## Links
+
+- [CortexLab Library](https://github.com/siddhant-rajhans/cortexlab)
+- [CortexLab on HuggingFace](https://huggingface.co/SID2000/cortexlab)
 
-- Brain Alignment Benchmark (RSA, CKA, Procrustes + statistical testing)
-- Cognitive Load Scorer (timeline, radar, comparison mode)
-- Temporal Dynamics (peak latency, lag correlation, sustained/transient)
-- ROI Connectivity (partial correlation, clustering, network graph)
+## License
 
-Runs on biologically realistic synthetic data. No GPU required.
+CC BY-NC 4.0

app.py

@@ -103,6 +103,11 @@ with col2:
     st.page_link("pages/4_Connectivity.py", label="ROI Connectivity", icon="🔗")
     st.caption("Partial correlation, modularity, betweenness centrality, dendrogram, network graph")
 
+st.divider()
+st.subheader("3D Visualization")
+st.page_link("pages/5_Brain_Viewer.py", label="Interactive 3D Brain Viewer", icon="🧠")
+st.caption("Rotatable brain surface with activation overlays, publication-quality multi-view panels, ROI highlighting, and modality-specific patterns")
+
 # --- Analysis Log ---
 show_analysis_log()
 

brain_mesh.py

@@ -0,0 +1,344 @@
+"""3D brain mesh loading, data projection, and rendering utilities.
+
+Supports both publication-quality multi-view panels (Plotly) and
+interactive 3D exploration (PyVista/stpyvista with Plotly fallback).
+"""
+
+import numpy as np
+import streamlit as st
+import plotly.graph_objects as go
+from plotly.subplots import make_subplots
+
+from utils import ROI_GROUPS
+
+# --- Camera Presets ---
+
+VIEWS = {
+    "Lateral Left": dict(eye=dict(x=-1.7, y=0, z=0.3), up=dict(x=0, y=0, z=1)),
+    "Lateral Right": dict(eye=dict(x=1.7, y=0, z=0.3), up=dict(x=0, y=0, z=1)),
+    "Medial": dict(eye=dict(x=1.5, y=0.3, z=0.2), up=dict(x=0, y=0, z=1)),
+    "Dorsal": dict(eye=dict(x=0, y=0, z=2.2), up=dict(x=0, y=1, z=0)),
+    "Ventral": dict(eye=dict(x=0, y=0, z=-2.2), up=dict(x=0, y=1, z=0)),
+    "Anterior": dict(eye=dict(x=0, y=1.7, z=0.3), up=dict(x=0, y=0, z=1)),
+    "Posterior": dict(eye=dict(x=0, y=-1.7, z=0.3), up=dict(x=0, y=0, z=1)),
+}
+
+# --- Modality activation patterns ---
+
+ACTIVATION_PATTERNS = {
+    "visual": {
+        "V1": 1.0, "V2": 0.9, "V3": 0.8, "V4": 0.7,
+        "MT": 0.75, "MST": 0.65, "FFC": 0.6, "VVC": 0.55,
+        "A1": 0.05, "LBelt": 0.04, "44": 0.08, "45": 0.07,
+        "46": 0.25, "FEF": 0.35,
+    },
+    "auditory": {
+        "A1": 1.0, "LBelt": 0.9, "MBelt": 0.85, "PBelt": 0.8,
+        "A4": 0.7, "A5": 0.65,
+        "V1": 0.03, "44": 0.12, "45": 0.1, "TPOJ1": 0.25,
+        "46": 0.15,
+    },
+    "language": {
+        "44": 1.0, "45": 0.95, "IFJa": 0.85, "IFJp": 0.8,
+        "TPOJ1": 0.9, "TPOJ2": 0.85, "STV": 0.75, "PSL": 0.7,
+        "V1": 0.05, "A1": 0.25, "46": 0.45,
+    },
+    "multimodal": {
+        "V1": 0.6, "V2": 0.55, "MT": 0.5,
+        "A1": 0.6, "LBelt": 0.55,
+        "44": 0.55, "45": 0.5, "TPOJ1": 0.5,
+        "46": 0.35, "FEF": 0.3,
+    },
+}
+
+
+# --- Mesh Loading ---
+
+@st.cache_resource
+def load_fsaverage_mesh(hemi="left", resolution="fsaverage5"):
+    """Load fsaverage brain mesh via nilearn. Returns (coords, faces)."""
+    from nilearn.datasets import fetch_surf_fsaverage
+    from nilearn.surface import load_surf_mesh
+
+    fsaverage = fetch_surf_fsaverage(mesh=resolution)
+    key = f"pial_{hemi}"
+    coords, faces = load_surf_mesh(fsaverage[key])
+    return np.array(coords, dtype=np.float32), np.array(faces, dtype=np.int32)
+
+
+@st.cache_resource
+def load_sulcal_map(hemi="left", resolution="fsaverage5"):
+    """Load sulcal depth map for anatomical background."""
+    from nilearn.datasets import fetch_surf_fsaverage
+    from nilearn.surface import load_surf_data
+
+    fsaverage = fetch_surf_fsaverage(mesh=resolution)
+    sulc = load_surf_data(fsaverage[f"sulc_{hemi}"])
+    return np.array(sulc, dtype=np.float32)
+
+
+# --- Data Projection ---
+
+def generate_sample_activations(n_vertices, roi_indices, pattern="visual", seed=42):
+    """Generate demo activation data with modality-specific patterns.
+
+    Returns vertex-level activation array of shape (n_vertices,).
+    """
+    rng = np.random.default_rng(seed)
+    weights = ACTIVATION_PATTERNS.get(pattern, ACTIVATION_PATTERNS["visual"])
+
+    data = rng.standard_normal(n_vertices) * 0.05  # low baseline noise
+
+    for roi_name, vertices in roi_indices.items():
+        w = weights.get(roi_name, 0.02)
+        valid = vertices[vertices < n_vertices]
+        if len(valid) > 0:
+            # Smooth activation with per-vertex jitter
+            data[valid] = w + rng.standard_normal(len(valid)) * 0.05
+
+    return np.clip(data, 0, 1)
+
+
+def highlight_rois(vertex_data, roi_indices, selected_rois, boost=1.5):
+    """Amplify activation in selected ROIs for visual highlighting."""
+    data = vertex_data.copy()
+    for roi in selected_rois:
+        if roi in roi_indices:
+            valid = roi_indices[roi]
+            valid = valid[valid < len(data)]
+            if len(valid) > 0:
+                data[valid] = np.clip(data[valid] * boost, 0, 1)
+    return data
+
+
+def blend_with_sulcal(vertex_data, sulcal_map, data_opacity=0.85):
+    """Blend activation data with sulcal background for anatomical context."""
+    sulc_norm = (sulcal_map - sulcal_map.min()) / (sulcal_map.max() - sulcal_map.min() + 1e-8)
+    bg = 0.25 + sulc_norm * 0.3  # gray range 0.25-0.55
+
+    # Where activation is low, show more background
+    alpha = np.clip(vertex_data * 3, 0, data_opacity)
+    blended = alpha * vertex_data + (1 - alpha) * bg
+    return blended
+
+
+# --- Plotly Rendering ---
+
+def _make_mesh3d(coords, faces, vertex_data, cmap, vmin, vmax, opacity=1.0, name=""):
+    """Create a Plotly Mesh3d trace."""
+    return go.Mesh3d(
+        x=coords[:, 0], y=coords[:, 1], z=coords[:, 2],
+        i=faces[:, 0], j=faces[:, 1], k=faces[:, 2],
+        intensity=vertex_data,
+        intensitymode="vertex",
+        colorscale=cmap,
+        cmin=vmin, cmax=vmax,
+        opacity=opacity,
+        lighting=dict(ambient=0.4, diffuse=0.6, specular=0.3, roughness=0.5, fresnel=0.2),
+        lightposition=dict(x=100, y=200, z=300),
+        showscale=False,
+        name=name,
+        hovertemplate="Vertex: %{pointNumber}<br>Value: %{intensity:.3f}<extra></extra>",
+    )
+
+
+def _scene_layout(camera, bg_color="#0E1117"):
+    """Create a Plotly 3D scene layout."""
+    return dict(
+        camera=camera,
+        xaxis=dict(visible=False),
+        yaxis=dict(visible=False),
+        zaxis=dict(visible=False),
+        bgcolor=bg_color,
+        aspectmode="data",
+    )
+
+
+def render_publication_views(coords, faces, vertex_data, cmap="Hot", vmin=0, vmax=1, bg_color="#0E1117"):
+    """Render 4-panel publication-quality brain views.
+
+    Returns a Plotly figure with lateral left, lateral right, medial, and dorsal views.
+    """
+    view_keys = ["Lateral Left", "Lateral Right", "Medial", "Dorsal"]
+
+    fig = make_subplots(
+        rows=1, cols=4,
+        specs=[[{"type": "scene"}] * 4],
+        subplot_titles=view_keys,
+        horizontal_spacing=0.01,
+    )
+
+    for i, view_name in enumerate(view_keys, 1):
+        mesh = _make_mesh3d(coords, faces, vertex_data, cmap, vmin, vmax, name=view_name)
+        fig.add_trace(mesh, row=1, col=i)
+        fig.update_layout(**{f"scene{i if i > 1 else ''}": _scene_layout(VIEWS[view_name], bg_color)})
+
+    fig.update_layout(
+        height=350,
+        margin=dict(l=0, r=0, t=30, b=0),
+        paper_bgcolor=bg_color,
+        font=dict(color="white"),
+        showlegend=False,
+    )
+
+    # Add colorbar as a separate invisible trace
+    fig.add_trace(go.Mesh3d(
+        x=[0], y=[0], z=[0], i=[0], j=[0], k=[0],
+        intensity=[0], colorscale=cmap, cmin=vmin, cmax=vmax,
+        showscale=True,
+        colorbar=dict(
+            title=dict(text="Activation", side="right"),
+            len=0.8, thickness=15, x=1.02,
+            tickfont=dict(color="white"),
+        ),
+        opacity=0,
+        hoverinfo="none",
+    ))
+
+    return fig
+
+
+def render_interactive_3d(coords, faces, vertex_data, cmap="Hot", vmin=0, vmax=1,
+                          bg_color="#0E1117", initial_view="Lateral Left",
+                          roi_indices=None, roi_labels=None, show_labels=False):
+    """Render an interactive rotatable 3D brain.
+
+    First attempts PyVista via stpyvista, falls back to Plotly mesh3d.
+    """
+    # Try stpyvista first
+    try:
+        return _render_pyvista(coords, faces, vertex_data, cmap, vmin, vmax,
+                               bg_color, initial_view, roi_indices, show_labels)
+    except Exception:
+        pass
+
+    # Fallback: Plotly mesh3d (always works)
+    return _render_plotly(coords, faces, vertex_data, cmap, vmin, vmax,
+                          bg_color, initial_view, roi_indices, roi_labels, show_labels)
+
+
+def _render_pyvista(coords, faces, vertex_data, cmap, vmin, vmax,
+                    bg_color, initial_view, roi_indices, show_labels):
+    """Render with PyVista via stpyvista."""
+    import pyvista as pv
+    from stpyvista import stpyvista
+    from stpyvista.utils import start_xvfb
+
+    if "IS_XVFB_RUNNING" not in st.session_state:
+        try:
+            start_xvfb()
+        except Exception:
+            pass
+        st.session_state.IS_XVFB_RUNNING = True
+
+    pv_faces = np.column_stack([np.full(len(faces), 3), faces]).ravel()
+    mesh = pv.PolyData(coords, pv_faces)
+    mesh.point_data["activation"] = vertex_data
+
+    cmap_map = {"Hot": "hot", "Inferno": "inferno", "Plasma": "plasma",
+                "Viridis": "viridis", "RdBu_r": "RdBu_r", "Coolwarm": "coolwarm"}
+    pv_cmap = cmap_map.get(cmap, "hot")
+
+    plotter = pv.Plotter(window_size=[900, 600], off_screen=True)
+    plotter.add_mesh(
+        mesh, scalars="activation", cmap=pv_cmap,
+        clim=[vmin, vmax], smooth_shading=True,
+        ambient=0.4, diffuse=0.6, specular=0.3,
+        show_scalar_bar=True,
+    )
+
+    if show_labels and roi_indices:
+        for name, vertices in roi_indices.items():
+            valid = vertices[vertices < len(coords)]
+            if len(valid) > 0:
+                center = coords[valid].mean(axis=0)
+                plotter.add_point_labels(
+                    center.reshape(1, 3), [name],
+                    font_size=10, shape_opacity=0.3,
+                    text_color="white",
+                )
+
+    r, g, b = int(bg_color[1:3], 16), int(bg_color[3:5], 16), int(bg_color[5:7], 16)
+    plotter.background_color = (r / 255, g / 255, b / 255)
+
+    stpyvista(plotter, key="brain_3d_viewer")
+    return None  # stpyvista renders directly
+
+
+def _render_plotly(coords, faces, vertex_data, cmap, vmin, vmax,
+                   bg_color, initial_view, roi_indices, roi_labels, show_labels):
+    """Render with Plotly mesh3d (fallback)."""
+    fig = go.Figure()
+
+    fig.add_trace(_make_mesh3d(coords, faces, vertex_data, cmap, vmin, vmax))
+
+    # Add ROI labels as scatter3d annotations
+    if show_labels and roi_indices:
+        label_x, label_y, label_z, label_text = [], [], [], []
+        for name, vertices in roi_indices.items():
+            valid = vertices[vertices < len(coords)]
+            if len(valid) > 0:
+                center = coords[valid].mean(axis=0)
+                label_x.append(center[0])
+                label_y.append(center[1])
+                label_z.append(center[2])
+                label_text.append(name)
+
+        fig.add_trace(go.Scatter3d(
+            x=label_x, y=label_y, z=label_z,
+            mode="text",
+            text=label_text,
+            textfont=dict(size=9, color="white"),
+            hoverinfo="text",
+            showlegend=False,
+        ))
+
+    camera = VIEWS.get(initial_view, VIEWS["Lateral Left"])
+    fig.update_layout(
+        scene=_scene_layout(camera, bg_color),
+        height=600,
+        margin=dict(l=0, r=0, t=0, b=0),
+        paper_bgcolor=bg_color,
+    )
+
+    return fig
+
+
+# --- ROI Helpers ---
+
+def make_vertex_roi_indices(n_vertices_per_roi=20):
+    """Create ROI -> vertex index mapping matching utils.make_roi_indices."""
+    from utils import ALL_ROIS
+    indices = {}
+    offset = 0
+    for roi in ALL_ROIS:
+        indices[roi] = np.arange(offset, offset + n_vertices_per_roi)
+        offset += n_vertices_per_roi
+    return indices, offset
+
+
+def roi_summary_table(vertex_data, roi_indices, selected_rois):
+    """Compute summary stats for selected ROIs."""
+    import pandas as pd
+    rows = []
+    for roi in selected_rois:
+        if roi in roi_indices:
+            valid = roi_indices[roi]
+            valid = valid[valid < len(vertex_data)]
+            if len(valid) > 0:
+                vals = vertex_data[valid]
+                group = "Other"
+                for g, rois in ROI_GROUPS.items():
+                    if roi in rois:
+                        group = g
+                        break
+                rows.append({
+                    "ROI": roi,
+                    "Group": group,
+                    "Mean": float(vals.mean()),
+                    "Std": float(vals.std()),
+                    "Min": float(vals.min()),
+                    "Max": float(vals.max()),
+                    "Vertices": len(valid),
+                })
+    return pd.DataFrame(rows) if rows else None

pages/5_Brain_Viewer.py

@@ -0,0 +1,220 @@
+"""Interactive 3D Brain Viewer - Publication Quality + Explorer."""
+
+import streamlit as st
+import numpy as np
+import plotly.graph_objects as go
+
+from session import init_session, show_analysis_log, upload_npy_widget
+from brain_mesh import (
+    load_fsaverage_mesh,
+    load_sulcal_map,
+    generate_sample_activations,
+    highlight_rois,
+    blend_with_sulcal,
+    render_publication_views,
+    render_interactive_3d,
+    roi_summary_table,
+    VIEWS,
+    ACTIVATION_PATTERNS,
+)
+from utils import ROI_GROUPS, make_roi_indices
+
+st.set_page_config(page_title="3D Brain Viewer", page_icon="🧠", layout="wide")
+init_session()
+show_analysis_log()
+
+st.title("🧠 Interactive 3D Brain Viewer")
+st.markdown("Explore brain activation patterns on the cortical surface. Publication-quality multi-view panels + interactive 3D rotation.")
+
+# --- Sidebar ---
+with st.sidebar:
+    st.header("Brain Viewer")
+
+    hemi = st.selectbox("Hemisphere", ["left", "right"], index=0)
+    resolution = st.selectbox("Mesh resolution", ["fsaverage5", "fsaverage4"], index=0,
+                              help="fsaverage5: 10k vertices (detailed). fsaverage4: 2.5k vertices (fast).")
+
+    st.subheader("Data")
+    data_source = st.radio("Data source", ["Sample activations", "From current analysis", "Upload .npy"])
+
+    if data_source == "Sample activations":
+        pattern = st.selectbox("Activation pattern", list(ACTIVATION_PATTERNS.keys()),
+                               help="Modality-specific activation: visual lights up V1/V2/MT, language lights up Broca's/Wernicke's, etc.")
+        seed = st.number_input("Seed", value=42, min_value=0)
+
+    st.subheader("Appearance")
+    cmap = st.selectbox("Colormap", ["Hot", "Inferno", "Plasma", "Viridis", "RdBu_r", "Coolwarm"], index=0)
+    vmin, vmax = st.slider("Data range", 0.0, 1.0, (0.0, 1.0), 0.05)
+    bg_color = st.selectbox("Background", ["#0E1117", "#000000", "#1A1A2E"], index=0,
+                            format_func=lambda x: {"#0E1117": "Dark", "#000000": "Black", "#1A1A2E": "Navy"}[x])
+
+    st.subheader("ROI Highlighting")
+    roi_groups_selected = st.multiselect("Region groups", list(ROI_GROUPS.keys()))
+    available_rois = []
+    for g in roi_groups_selected:
+        available_rois.extend(ROI_GROUPS[g])
+    selected_rois = st.multiselect("Specific ROIs", available_rois, default=available_rois[:5] if available_rois else [])
+    show_labels = st.checkbox("Show ROI labels", value=True)
+
+# --- Load Mesh ---
+with st.spinner(f"Loading {resolution} brain mesh ({hemi} hemisphere)..."):
+    coords, faces = load_fsaverage_mesh(hemi, resolution)
+    n_vertices = coords.shape[0]
+
+# --- Load/Generate Data ---
+roi_indices, _ = make_roi_indices()
+
+# Map ROI indices to actual mesh vertices (scale to mesh size)
+# Since our ROI indices are synthetic (0-580), map them proportionally to actual mesh
+mesh_roi_indices = {}
+for name, idx in roi_indices.items():
+    scaled = (idx * n_vertices // 580).astype(int)
+    scaled = scaled[scaled < n_vertices]
+    mesh_roi_indices[name] = scaled
+
+if data_source == "Sample activations":
+    vertex_data = generate_sample_activations(n_vertices, mesh_roi_indices, pattern, seed)
+elif data_source == "Upload .npy":
+    uploaded = upload_npy_widget(f"Upload vertex data (.npy, {n_vertices} vertices)", "brain_upload")
+    if uploaded is not None and len(uploaded) == n_vertices:
+        vertex_data = uploaded
+    elif uploaded is not None:
+        st.warning(f"Expected {n_vertices} vertices, got {len(uploaded)}. Using sample data.")
+        vertex_data = generate_sample_activations(n_vertices, mesh_roi_indices, "visual", 42)
+    else:
+        vertex_data = generate_sample_activations(n_vertices, mesh_roi_indices, "visual", 42)
+elif data_source == "From current analysis":
+    preds = st.session_state.get("brain_predictions")
+    if preds is not None:
+        # Average across timepoints, take first n_vertices
+        avg = np.abs(preds).mean(axis=0)
+        if len(avg) >= n_vertices:
+            vertex_data = avg[:n_vertices]
+        else:
+            vertex_data = np.pad(avg, (0, n_vertices - len(avg)))
+        # Normalize to [0, 1]
+        vd_range = vertex_data.max() - vertex_data.min()
+        if vd_range > 0:
+            vertex_data = (vertex_data - vertex_data.min()) / vd_range
+    else:
+        st.info("No analysis data in session. Go to Home page to generate data, or use sample activations.")
+        vertex_data = generate_sample_activations(n_vertices, mesh_roi_indices, "visual", 42)
+
+# Apply ROI highlighting
+if selected_rois:
+    vertex_data = highlight_rois(vertex_data, mesh_roi_indices, selected_rois, boost=1.8)
+
+# Blend with sulcal map for anatomical context
+try:
+    sulc = load_sulcal_map(hemi, resolution)
+    vertex_data_display = blend_with_sulcal(vertex_data, sulc)
+except Exception:
+    vertex_data_display = vertex_data
+
+# --- Publication Views ---
+st.subheader("Publication Views")
+st.caption("Four standard neuroimaging views. Right-click any panel to save as image.")
+
+fig_pub = render_publication_views(coords, faces, vertex_data_display, cmap, vmin, vmax, bg_color)
+st.plotly_chart(fig_pub, use_container_width=True)
+
+# --- Interactive 3D ---
+st.divider()
+st.subheader("Interactive 3D Explorer")
+st.caption("Rotate: drag | Zoom: scroll | Pan: shift+drag")
+
+col_view, col_space = st.columns([1, 3])
+with col_view:
+    initial_view = st.selectbox("Initial view", list(VIEWS.keys()), index=0)
+
+result = render_interactive_3d(
+    coords, faces, vertex_data_display, cmap, vmin, vmax,
+    bg_color, initial_view, mesh_roi_indices,
+    roi_labels=selected_rois, show_labels=show_labels,
+)
+if result is not None:
+    st.plotly_chart(result, use_container_width=True)
+
+# --- ROI Summary ---
+if selected_rois:
+    st.divider()
+    col_table, col_hist = st.columns([1, 1])
+
+    with col_table:
+        st.subheader("ROI Summary")
+        summary = roi_summary_table(vertex_data, mesh_roi_indices, selected_rois)
+        if summary is not None:
+            st.dataframe(
+                summary.style.format({"Mean": "{:.4f}", "Std": "{:.4f}", "Min": "{:.4f}", "Max": "{:.4f}"}),
+                use_container_width=True, hide_index=True,
+            )
+
+    with col_hist:
+        st.subheader("Activation Distribution")
+        fig_hist = go.Figure()
+        fig_hist.add_trace(go.Histogram(
+            x=vertex_data, nbinsx=50,
+            marker_color="rgba(108, 92, 231, 0.7)",
+            name="All vertices",
+        ))
+        # Overlay selected ROI distributions
+        group_colors = {"Visual": "#00D2FF", "Auditory": "#FF6B6B", "Language": "#A29BFE", "Executive": "#FFEAA7"}
+        for roi in selected_rois[:3]:  # limit to 3 for clarity
+            if roi in mesh_roi_indices:
+                valid = mesh_roi_indices[roi]
+                valid = valid[valid < len(vertex_data)]
+                if len(valid) > 0:
+                    group = "Other"
+                    for g, rois in ROI_GROUPS.items():
+                        if roi in rois:
+                            group = g
+                            break
+                    fig_hist.add_trace(go.Histogram(
+                        x=vertex_data[valid], nbinsx=20,
+                        marker_color=group_colors.get(group, "#888"),
+                        name=roi, opacity=0.6,
+                    ))
+        fig_hist.update_layout(
+            xaxis_title="Activation", yaxis_title="Count",
+            height=350, template="plotly_dark",
+            barmode="overlay",
+            legend=dict(orientation="h", yanchor="bottom", y=1.02),
+        )
+        st.plotly_chart(fig_hist, use_container_width=True)
+
+# --- Stats ---
+st.divider()
+col1, col2, col3, col4 = st.columns(4)
+col1.metric("Vertices", f"{n_vertices:,}")
+col2.metric("Mean Activation", f"{vertex_data.mean():.4f}")
+col3.metric("Active Vertices", f"{(vertex_data > 0.1).sum():,} ({100 * (vertex_data > 0.1).mean():.0f}%)")
+col4.metric("Peak", f"{vertex_data.max():.4f}")
+
+# --- Methodology ---
+with st.expander("About the 3D Brain Viewer", expanded=False):
+    st.markdown("""
+**Surface Mesh**: The brain surface is the fsaverage template from FreeSurfer, loaded via
+nilearn. fsaverage5 has 10,242 vertices per hemisphere; fsaverage4 has 2,562.
+
+**Activation Overlay**: Vertex-level scalar data is projected onto the mesh surface as a
+colormap. The data is blended with the sulcal depth map (anatomical grooves) to provide
+spatial context.
+
+**Sample Activations**: Modality-specific patterns assign activation weights to HCP MMP1.0
+ROIs based on established functional neuroanatomy. Visual stimuli activate V1/V2/MT,
+auditory stimuli activate A1/belt areas, language stimuli activate Broca's (area 44/45)
+and Wernicke's (TPOJ1/2).
+
+**ROI Highlighting**: Selected ROIs are amplified (1.8x) to make them visually distinct.
+The summary table shows descriptive statistics for highlighted regions.
+
+**Publication Views**: Four standard views (lateral left, lateral right, medial, dorsal)
+match the conventions used in neuroimaging journals. Right-click to save individual panels.
+
+**Interactive View**: Supports rotation (drag), zoom (scroll), and pan (shift+drag).
+Uses PyVista when available, falls back to Plotly mesh3d.
+
+**References**:
+- Fischl, 2012, *NeuroImage* (FreeSurfer surface reconstruction)
+- Glasser et al., 2016, *Nature* (HCP MMP1.0 parcellation)
+""")

requirements.txt

@@ -6,3 +6,6 @@ pandas>=2.0
 networkx>=3.2
 matplotlib>=3.8
 seaborn>=0.13
+nilearn>=0.11.0
+pyvista>=0.47.0
+stpyvista>=0.2.1