@brainpilot/skills 0.0.6

package/skills/06_fMRI_Neuroimaging/pycortex-guide/references/mni-utils.md

@@ -0,0 +1,207 @@
+# MNI & Utilities Reference
+
+## Table of Contents
+1. [MNI Space Transforms](#mni-space-transforms)
+2. [Volume Utilities](#volume-utilities)
+3. [Anatomical Processing](#anatomical-processing)
+4. [General Utilities](#general-utilities)
+
+## MNI Space Transforms
+
+### compute_mni_transform
+
+```python
+cortex.mni.compute_mni_transform(subject, xfm, template=None)
+```
+
+Computes the combined transform from functional space to MNI standard space using FSL's FLIRT and FNIRT.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `subject` | str | Subject name |
+| `xfm` | str | Transform name (functional → anatomical) |
+| `template` | str | MNI template path (default: FSL's MNI152 1mm) |
+
+Returns: `func_to_mni` warp field.
+
+### transform_to_mni
+
+```python
+cortex.mni.transform_to_mni(volumedata, func_to_mni, template=None)
+```
+
+Transform volumetric data from functional space to MNI space.
+
+```python
+# Full workflow: subject space → MNI
+func_to_mni = cortex.mni.compute_mni_transform("S1", "fullhead")
+mni_data = cortex.mni.transform_to_mni(vol.volume, func_to_mni)
+```
+
+### transform_mni_to_subject
+
+```python
+cortex.mni.transform_mni_to_subject(subject, xfm, volarray, func_to_mni, template=None)
+```
+
+Transform data from MNI space back to subject's functional space.
+
+```python
+# MNI → subject space
+subject_data = cortex.mni.transform_mni_to_subject(
+    "S1", "fullhead", mni_volume, func_to_mni)
+vol = cortex.Volume(subject_data, "S1", "fullhead")
+```
+
+### transform_surface_to_mni
+
+```python
+cortex.mni.transform_surface_to_mni(subject, surfname)
+```
+
+Transform surface vertices to MNI coordinates.
+
+```python
+mni_pts = cortex.mni.transform_surface_to_mni("S1", "fiducial")
+```
+
+### Example: MNI Atlas on Subject Surface
+
+```python
+import cortex
+import numpy as np
+import nibabel as nib
+
+# Load MNI atlas
+atlas = nib.load("MNI_atlas.nii.gz").get_fdata()
+
+# Compute warp
+func_to_mni = cortex.mni.compute_mni_transform("S1", "fullhead")
+
+# Transform atlas to subject space
+subj_atlas = cortex.mni.transform_mni_to_subject(
+    "S1", "fullhead", atlas, func_to_mni)
+
+# Visualize
+vol = cortex.Volume(subj_atlas, "S1", "fullhead", cmap="tab20")
+cortex.quickshow(vol)
+```
+
+## Volume Utilities
+
+### mosaic
+
+```python
+cortex.mosaic(data, dim=0, show=True, **kwargs)
+```
+
+Creates a 2D mosaic view of 3D volumetric data (radiological convention).
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `data` | ndarray | required | 3D volume |
+| `dim` | int | 0 | Dimension to slice across |
+| `show` | bool | True | Display with matplotlib |
+
+```python
+import cortex
+import numpy as np
+
+data = np.random.randn(64, 64, 32)
+cortex.mosaic(data, dim=2)  # Axial slices
+```
+
+### unmask
+
+```python
+cortex.unmask(mask, data)
+```
+
+Reconstruct full volume from masked (1D) data.
+
+```python
+mask = cortex.db.get_mask("S1", "fullhead", "thick")
+masked_data = np.random.randn(mask.sum())
+full_volume = cortex.unmask(mask, masked_data)
+# full_volume.shape == mask.shape (MaskedArray)
+```
+
+### Detrending Functions
+
+```python
+from cortex.volume import detrend_median, detrend_gradient, detrend_poly
+
+# Median filter detrending
+detrended = detrend_median(data, kernel=15)
+
+# Gradient-based detrending
+grad = detrend_gradient(data, diff=3)
+
+# Polynomial detrending
+detrended = detrend_poly(data, polyorder=10, mask=None)
+```
+
+## Anatomical Processing
+
+### brainmask
+
+```python
+cortex.anat.brainmask(outfile, subject)
+```
+
+Creates a brain mask using FSL BET. Requires FSL installation.
+
+### whitematter
+
+```python
+cortex.anat.whitematter(outfile, subject, do_voxelize=False)
+```
+
+Creates white matter segmentation mask using FreeSurfer labels or FSL FAST.
+
+### voxelize
+
+```python
+cortex.anat.voxelize(outfile, subject, surf='wm', mp=True)
+```
+
+Voxelizes a surface to create a binary 3D mask.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `surf` | str | 'wm' | Surface to voxelize: 'wm' or 'pia' |
+| `mp` | bool | True | Use multiprocessing |
+
+## General Utilities
+
+### cortex.utils (imported to top-level)
+
+```python
+# Get ROI vertices (most commonly used utility)
+from cortex.utils import get_roi_verts, get_roi_mask
+
+# Get ROI vertex indices
+rois = get_roi_verts("S1")           # all ROIs
+v1 = get_roi_verts("S1", roi="V1")   # specific ROI
+
+# Get ROI mask in volume space
+masks = get_roi_mask("S1", "fullhead")
+v1_mask = get_roi_mask("S1", "fullhead", roi="V1")
+```
+
+### Vertex distance from surface
+
+```python
+# Compute voxel distance from cortical surface
+# (useful for defining cortical ribbon masks)
+from cortex.utils import get_vox_dist
+dist, argdist = get_vox_dist(subject, xfmname)
+```
+
+### Multiprocessing helper
+
+```python
+from cortex.mp import map as mp_map
+# Parallel map function used internally by pycortex
+results = mp_map(func, iterable)
+```

package/skills/06_fMRI_Neuroimaging/pycortex-guide/references/surface-analysis.md

@@ -0,0 +1,219 @@
+# Surface Analysis Reference
+
+## Table of Contents
+1. [Surface Properties (surfinfo)](#surface-properties)
+2. [Geodesic Distance](#geodesic-distance)
+3. [Surface Geometry (polyutils)](#surface-geometry)
+4. [ROI Operations](#roi-operations)
+5. [SVG Overlays](#svg-overlays)
+
+## Surface Properties
+
+### curvature
+
+```python
+cortex.surfinfo.curvature(outfile, subject, smooth=20)
+```
+
+Computes mean curvature of the cortical surface. Result is cached.
+
+### thickness
+
+```python
+cortex.surfinfo.thickness(outfile, subject)
+```
+
+Computes cortical thickness (distance between white matter and pial surfaces).
+
+### distortion
+
+```python
+cortex.surfinfo.distortion(outfile, subject, dist_type='areal', smooth=20)
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `dist_type` | str | 'areal' | Distortion type: 'areal' or 'metric' |
+| `smooth` | int | 20 | Smoothing iterations |
+
+Computes flatmap distortion (how much the flattening stretches/compresses the surface).
+
+### tissots_indicatrix
+
+```python
+cortex.surfinfo.tissots_indicatrix(outfile, subject, radius=10, spacing=50)
+```
+
+Computes Tissot's indicatrix for visualizing flatmap distortion patterns.
+
+### flat_border
+
+```python
+cortex.surfinfo.flat_border(outfile, subject)
+```
+
+Computes flatmap border information.
+
+```python
+# Example: visualize curvature
+curv = cortex.Vertex(cortex.db.get_surfinfo("S1", "curvature"), "S1")
+cortex.quickshow(curv)
+
+# Blend data with curvature
+vx = cortex.Vertex(my_data, "S1")
+blended = vx.blend_curvature(alpha=0.5, brightness=0.5, contrast=0.25, smooth=20)
+cortex.quickshow(blended)
+```
+
+## Geodesic Distance
+
+### Exact Geodesic
+
+```python
+from cortex.polyutils import exact_geodesic
+distances = exact_geodesic.geodesic_distance(surface, vertex_indices)
+```
+
+### Via Surface Class
+
+```python
+from cortex.polyutils import Surface
+
+pts, polys = cortex.db.get_surf("S1", "fiducial", "left")
+surf = Surface(pts, polys)
+
+# Geodesic distance from a seed vertex
+distances = surf.geodesic_distance(vertex_index)
+
+# Geodesic path between two vertices
+path = surf.geodesic_path(start_vertex, end_vertex)
+```
+
+```python
+# Example: compute and visualize geodesic distance
+pts, polys = cortex.db.get_surf("S1", "fiducial", merge=True)
+from cortex.polyutils import Surface
+surf = Surface(pts, polys)
+
+seed = 10000  # vertex index
+dists = surf.geodesic_distance([seed])
+
+vx = cortex.Vertex(dists, "S1", cmap="hot", vmin=0, vmax=100)
+cortex.quickshow(vx)
+```
+
+## Surface Geometry
+
+### Surface Class
+
+```python
+from cortex.polyutils import Surface
+
+pts, polys = cortex.db.get_surf("S1", "fiducial", "left")
+surf = Surface(pts, polys)
+```
+
+Key properties:
+- `surf.adj` — sparse adjacency matrix
+- `surf.face_normals` — normal vector per face
+- `surf.vertex_normals` — normal vector per vertex
+- `surf.face_areas` — area of each face
+- `surf.cotangent_weights` — cotangent Laplacian weights
+- `surf.laplace_operator` — Laplace-Beltrami operator (sparse matrix)
+- `surf.connected` — connected components
+
+Key methods:
+- `surf.geodesic_distance(verts)` — exact geodesic distance from vertices
+- `surf.smooth(data, iterations)` — smooth data on surface
+- `surf.subsurface(vertex_mask)` — extract subsurface
+
+### Distortion Analysis
+
+```python
+from cortex.polyutils import Distortion
+
+# Compare fiducial to flat surface
+fid_pts, polys = cortex.db.get_surf("S1", "fiducial", "left")
+flat_pts, _ = cortex.db.get_surf("S1", "flat", "left")
+
+dist = Distortion(fid_pts, flat_pts, polys)
+areal = dist.areal      # areal distortion per face
+metric = dist.metric     # metric distortion per face
+```
+
+### Utility Functions
+
+```python
+from cortex.polyutils.misc import (
+    voxelize,        # Surface → 3D voxel mask
+    marching_cubes,  # 3D volume → surface mesh
+    decimate,        # Reduce polygon count
+    boundary_edges,  # Find boundary edges of mesh
+    face_area,       # Compute face areas
+    face_volume,     # Volume between two surfaces
+    measure_volume,  # Total enclosed volume
+)
+
+# Voxelize a surface
+mask_3d = voxelize(pts, polys, shape=(256, 256, 256), center=(128, 128, 128))
+
+# Extract surface from volume
+new_pts, new_polys = marching_cubes(volume_data, smooth=True, decimate=True)
+```
+
+## ROI Operations
+
+### Get ROI Vertices
+
+```python
+from cortex.utils import get_roi_verts
+
+# Single ROI
+v1_verts = get_roi_verts("S1", roi="V1")  # {"V1": array([...])}
+
+# All ROIs
+all_rois = get_roi_verts("S1")  # {"V1": array, "V2": array, ...}
+```
+
+### Get ROI Volume Mask
+
+```python
+from cortex.utils import get_roi_mask
+
+# Get binary mask in volume space
+v1_mask = get_roi_mask("S1", "fullhead", roi="V1")
+# Returns dict: {"V1": 3D_boolean_array}
+```
+
+### Visualize ROI
+
+```python
+# Highlight ROI vertices
+roi_verts = get_roi_verts("S1", roi="V1")["V1"]
+data = np.zeros(cortex.db.get_surf("S1", "fiducial", merge=True)[0].shape[0])
+data[roi_verts] = 1.0
+vx = cortex.Vertex(data, "S1", cmap="hot", vmin=0, vmax=1)
+cortex.quickshow(vx, with_rois=True)
+```
+
+## SVG Overlays
+
+ROIs and overlays are stored as SVG files. The `svgoverlay` module manages them.
+
+```python
+# Get overlay object
+overlay = cortex.db.get_overlay("S1")
+
+# Access ROI definitions
+# ROIs are stored in {filestore}/{subject}/rois.svg
+
+# Custom overlay file
+fig = cortex.quickshow(vol, overlay_file="/path/to/custom_overlay.svg")
+```
+
+ROIs can be edited interactively using Inkscape:
+```python
+from cortex.rois import ROIpack
+rois = ROIpack("S1", "rois.svg")
+rois.to_svg(open_inkscape=True)  # Opens Inkscape for editing
+```

package/skills/06_fMRI_Neuroimaging/pycortex-guide/references/visualization.md

@@ -0,0 +1,251 @@
+# Visualization Reference
+
+## Table of Contents
+1. [Quickflat (2D Flatmaps)](#quickflat-2d-flatmaps)
+2. [WebGL (3D Interactive Viewer)](#webgl-3d-interactive-viewer)
+3. [Export (Multi-View Rendering)](#export-multi-view-rendering)
+
+## Quickflat (2D Flatmaps)
+
+### make_figure / quickshow
+
+```python
+cortex.quickshow(braindata, recache=False, pixelwise=True, thick=32,
+    sampler='nearest', height=1024, dpi=100, depth=0.5,
+    with_rois=True, with_sulci=False, with_labels=True,
+    with_colorbar=True, with_borders=False, with_dropout=False,
+    with_curvature=False, with_connected_vertices=False,
+    overlay_file=None, linewidth=None, linecolor=None,
+    roifill=None, shadow=None, labelsize=None, labelcolor=None,
+    cutout=None, curvature_brightness=None, curvature_contrast=None,
+    fig=None, colorbar_ticks=None, colorbar_location='center',
+    roi_list=None, sulci_list=None, nanmean=False)
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `braindata` | Volume/Vertex | required | Data to display |
+| `pixelwise` | bool | True | Pixel-accurate mapping (vs interpolated) |
+| `thick` | int | 32 | Number of cortical layers to sample |
+| `sampler` | str | 'nearest' | Sampling method: 'nearest', 'trilinear', 'lanczos' |
+| `height` | int | 1024 | Image height in pixels |
+| `depth` | float | 0.5 | Cortical depth (0=white matter, 1=pial) |
+| `with_rois` | bool | True | Show ROI boundaries |
+| `with_sulci` | bool | False | Show sulcal boundaries |
+| `with_curvature` | bool | False | Show curvature underlay |
+| `with_colorbar` | bool | True | Show colorbar |
+| `with_dropout` | bool | False | Show dropout regions |
+| `cutout` | str | None | ROI name to cut out and zoom |
+| `roi_list` | list | None | Specific ROIs to display |
+| `nanmean` | bool | False | Use nanmean for layer averaging |
+| `fig` | Figure | None | Existing matplotlib figure |
+| `extra_disp` | tuple | None | Extra display layer (name, colormap) |
+| `extra_hatch` | tuple | None | Hatch overlay (Dataview, color_tuple) |
+| `curvature_threshold` | bool | None | Threshold curvature display |
+
+```python
+import cortex
+vol = cortex.Volume.random("S1", "fullhead")
+
+# Basic flatmap
+fig = cortex.quickshow(vol)
+
+# With curvature and sulci
+fig = cortex.quickshow(vol, with_curvature=True, with_sulci=True,
+                       curvature_brightness=0.5, curvature_contrast=0.25)
+
+# Zoom to ROI
+fig = cortex.quickshow(vol, cutout="V1")
+
+# Custom ROI display
+fig = cortex.quickshow(vol, roi_list=["V1", "V2", "V3"],
+                       linewidth=2, linecolor=(1, 1, 1, 1))
+```
+
+### make_png
+
+```python
+cortex.quickflat.make_png(fname, braindata, recache=False, pixelwise=True,
+    sampler='nearest', height=1024, bgcolor=None, dpi=100, **kwargs)
+```
+
+```python
+cortex.quickflat.make_png("output.png", vol, bgcolor=(0,0,0,0))  # transparent
+cortex.quickflat.make_png("output.png", vol, height=2048, dpi=300)  # high-res
+```
+
+### make_svg
+
+```python
+cortex.quickflat.make_svg(fname, braindata, with_labels=False,
+    with_curvature=True, layers=['rois'], height=1024, overlay_file=None)
+```
+
+### make_gif
+
+```python
+cortex.quickflat.make_gif(output_path, volumes, frame_duration=1, **figure_kwargs)
+```
+
+```python
+vols = [cortex.Volume(data[t], "S1", "fullhead") for t in range(10)]
+cortex.quickflat.make_gif("animation.gif", vols, frame_duration=0.5,
+                          with_curvature=True)
+```
+
+### Compositing Functions
+
+For fine-grained control over flatmap layers:
+
+```python
+from cortex.quickflat import composite
+fig, ax = plt.subplots()
+composite.add_curvature(fig, braindata, ...)
+composite.add_data(fig, braindata, ...)
+composite.add_rois(fig, braindata, ...)
+composite.add_sulci(fig, braindata, ...)
+composite.add_colorbar(fig, braindata, ...)
+composite.add_cutout(fig, braindata, name="V1", ...)
+```
+
+---
+
+## WebGL (3D Interactive Viewer)
+
+### show / webshow
+
+```python
+cortex.webshow(data, autoclose=None, open_browser=None, port=None,
+    pickerfun=None, recache=False, template='mixer.html',
+    overlays_visible=('rois', 'sulci'), labels_visible=('rois',),
+    types=('inflated',), overlay_file=None,
+    curvature_brightness=None, curvature_contrast=None,
+    surface_specularity=None, title='Brain', layout=None)
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `data` | Dataset/Volume/Vertex | required | Data to display |
+| `autoclose` | bool | True | Close server when browser disconnects |
+| `open_browser` | bool | True | Auto-open browser |
+| `port` | int | random | Server port |
+| `pickerfun` | callable | None | Click callback: `fn(voxel, vertex, hemi)` |
+| `types` | tuple | ('inflated',) | Surface types to include |
+| `overlays_visible` | tuple | ('rois','sulci') | Default visible overlays |
+| `surface_specularity` | float | None | Surface shininess |
+
+```python
+# Basic viewer
+handle = cortex.webshow(vol)
+
+# Multi-dataset viewer with picker
+def on_click(voxel, vertex, hemi):
+    print(f"Clicked vertex {vertex} in {hemi}")
+
+ds = cortex.Dataset(map1=vol1, map2=vol2)
+handle = cortex.webshow(ds, pickerfun=on_click)
+
+# Programmatic control via handle
+handle._set_view(**{"camera.azimuth": 45, "camera.altitude": 30})
+handle.getImage("screenshot.png", size=(1920, 1080))
+```
+
+### make_static
+
+```python
+cortex.webgl.make_static(outpath, data, recache=False,
+    template='static.html', anonymize=False,
+    overlays_visible=('rois', 'sulci'), labels_visible=('rois',),
+    types=('inflated',), html_embed=True, title='Brain')
+```
+
+```python
+# Self-contained HTML file
+cortex.webgl.make_static("viewer.html", vol, html_embed=True)
+
+# Anonymized for sharing
+cortex.webgl.make_static("public_viewer.html", vol, anonymize=True)
+```
+
+### View Control (JSMixer handle)
+
+```python
+handle = cortex.webshow(vol)
+
+# Camera
+handle._set_view(**{"camera.azimuth": 90, "camera.altitude": 0})
+
+# Surface unfolding (0=folded, 1=flat)
+handle._set_view(**{"surface.S1.unfold": 0.5})
+
+# Save/load views
+handle.save_view("S1", "my_view")
+handle.get_view("S1", "my_view")
+
+# Screenshots and movies
+handle.getImage("shot.png", size=(1920, 1080))
+handle.makeMovie(animation_dict, "movie.mp4", fps=30)
+```
+
+---
+
+## Export (Multi-View Rendering)
+
+### save_3d_views
+
+```python
+cortex.export.save_3d_views(volume, base_name='fig',
+    list_angles=['lateral_pivot'], list_surfaces=['inflated'],
+    viewer_params=dict(labels_visible=[], overlays_visible=['rois']),
+    size=(4096, 3072), trim=True, sleep=10, headless=False)
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `list_angles` | list | ['lateral_pivot'] | View angles |
+| `list_surfaces` | list | ['inflated'] | Surface types |
+| `size` | tuple | (4096,3072) | Image size |
+| `trim` | bool | True | Auto-trim borders |
+| `headless` | bool | False | Use Playwright (no display) |
+
+Available angles: `'left'`, `'right'`, `'front'`, `'back'`, `'top'`, `'bottom'`, `'flatmap'`, `'medial_pivot'`, `'lateral_pivot'`, `'bottom_pivot'`, `'top_pivot'`
+
+Available surfaces: `'inflated'`, `'flatmap'`, `'fiducial'`, `'inflated_cut'`
+
+```python
+# Multiple views, headless
+paths = cortex.export.save_3d_views(
+    vol, base_name="results/brain",
+    list_angles=["lateral_pivot", "medial_pivot", "flatmap"],
+    list_surfaces=["inflated"],
+    headless=True, size=(4096, 3072))
+```
+
+### plot_panels
+
+```python
+cortex.export.plot_panels(volume, panels, figsize=(16, 9),
+    windowsize=(6400, 3600), save_name=None, sleep=10, headless=False)
+```
+
+```python
+panels = [
+    {"extent": [0, 0.5, 0.5, 0.5],
+     "view": {"hemisphere": "left", "angle": "lateral_pivot", "surface": "inflated"}},
+    {"extent": [0.5, 0.5, 0.5, 0.5],
+     "view": {"hemisphere": "right", "angle": "lateral_pivot", "surface": "inflated"}},
+    {"extent": [0, 0, 1, 0.5],
+     "view": {"angle": "flatmap", "surface": "flatmap"}}
+]
+fig = cortex.export.plot_panels(vol, panels, save_name="panels.png", headless=True)
+```
+
+### headless_viewer (context manager)
+
+```python
+with cortex.export.headless_viewer(vol) as handle:
+    handle._set_view(**{"camera.azimuth": 45})
+    handle.getImage("view.png")
+```
+
+Requires: `pip install 'pycortex[headless]' && playwright install chromium`