Surface Workflows

---
name: surface-workflows
description: "Work with Nilearn surface meshes, surface images,
  volume-to-surface projection, fsaverage helpers, and surface maskers while
  routing plotting and raw image preparation to the right Nilearn skills."
disable-model-invocation: true
metadata:
  disco-role: operating
license: BSD 3-Clause
---

# Surface Workflows

Use this sub-skill when a task involves Nilearn cortical surface objects,
mesh/data contracts, `SurfaceImage` construction, volume-to-surface projection,
fsaverage meshes, or surface-specific maskers.

## Route Here

- Build or validate surface meshes with `InMemoryMesh`, `FileMesh`, `PolyMesh`,
  or `load_surf_mesh`.
- Build or validate surface data with `PolyData`, `load_surf_data`, or
  `SurfaceImage`.
- Project NIfTI volume data to surface vertices with `vol_to_surf` or
  `SurfaceImage.from_volume`.
- Load fsaverage meshes or fsaverage surface data with no-download awareness.
- Use `SurfaceMasker`, `SurfaceLabelsMasker`, or `SurfaceMapsMasker` enough to
  prepare arrays for analysis pipelines.

## Route Elsewhere

- For figure engine choices, `plot_surf`, `view_surf`, report display, Plotly,
  Matplotlib, or optional plotting dependencies, route to `../plotting-reporting/SKILL.md`.
- For raw NIfTI loading, resampling, confounds, signal cleaning, or volume image
  preparation before projection, route to `../data-io-signal/SKILL.md`.
- For deeper shared masker, labels, maps, atlas, and region-extraction behavior,
  route to `../maskers-regions/SKILL.md`; keep this sub-skill focused on
  surface-specific mesh/data contracts.

## Quick Checklist

1. Confirm whether the task is left-only, right-only, or both hemispheres.
2. Keep mesh parts and data parts keyed identically as `left` and/or `right`.
3. Match each data part's first dimension to the corresponding mesh vertex
   count before creating `SurfaceImage`.
4. Treat surface arrays as vertex-major: `(n_vertices,)` for a scalar map or
   `(n_vertices, n_samples_or_regions)` for time series, labels, or maps.
5. Avoid dataset downloads unless the user explicitly requests them; prefer the
   shipped `fsaverage5` helper for no-network examples.
6. Hand visualization choices off to plotting/reporting after producing a valid
   `SurfaceImage` or surface array.

## References

- `references/api-reference.md` summarizes public constructors, helpers, and
  object relationships.
- `references/data-formats.md` describes mesh, data, hemisphere, and file-format
  contracts.
- `references/workflows.md` gives recipes for minimal meshes, projection,
  fsaverage, surface maskers, and plotting handoff.
- `references/troubleshooting.md` maps common surface failures to likely fixes.

## Bundled Script

Run `python scripts/smoke_surface.py --help` for options or
`python scripts/smoke_surface.py` for a no-network sanity check that constructs
left/right in-memory meshes, builds a `SurfaceImage`, and verifies masker-style
array shapes.