Anatomy

Load cortical meshes or extract a surface from selected NIfTI labels.

load_surface

load_surface(source: PolyData | str | Path) -> PolyData

Read or copy a polygonal surface without changing its coordinates.

Parameters:

Name	Type	Description	Default
`source`	`PolyData \| str \| Path`	Mesh or local surface file. GIFTI files must contain one POINTSET and one TRIANGLE array; other formats are delegated to PyVista. Coordinates must already be RAS in millimetres. GIFTI coordinate transforms are not applied automatically.	required

Returns:

Name	Type	Description
`mesh`	`PolyData`	Independent surface retaining vertex order and connectivity. Modifying it does not modify an input mesh. No registration or rescaling occurs.

Raises:

Type	Description
`ValueError`	If geometry is empty, nonpolygonal, or has nonfinite coordinates.

roi_surface

roi_surface(
    image: Nifti1Image | Nifti2Image | str | Path,
    labels: ArrayLike,
    *,
    smoothing: bool = True,
) -> PolyData

Extract the outer surface of a selected union of discrete labels.

Parameters:

Name	Type	Description	Default
`image`	`Nifti1Image \| Nifti2Image \| str \| Path`	Three-dimensional NIfTI image or local path with finite, nonnegative integer-valued labels. Zero is background. Spatial units must be declared as mm, meter, or micron; unknown units are rejected. Probability and statistical maps need an explicit upstream conversion.	required
`labels`	`Sequence[int]`	Nonempty positive IDs present in the image. Selected labels form one region; their internal interfaces are omitted. Use separate calls for separately colored regions.	required
`smoothing`	`bool`	Use PyVista SurfaceNets smoothing with its default settings. Smoothing changes display geometry only. Sheared affines require False or explicit upstream resampling, because smoothing distances use orthogonal axes.	`True`

Returns:

Name	Type	Description
`mesh`	`PolyData`	Triangulated display surface in RAS millimetres, with the full image affine applied. The input image and its labels are unchanged.

Raises:

Type	Description
`ValueError`	If labels, units, or the affine violate the input contract.

Notes

Uses ImageData.contour_labels on a binary selection, with background padding. Boundaries lie between voxel centres. Thin or corner-connected regions need visual inspection; manifold geometry is not guaranteed.