brain_deer.surface.subcortical

Subcortical structure meshes from an aseg-style integer label volume.

Each selected label becomes its own surface (via VTK FlyingEdges on the binary mask), transformed from voxel space into RAS+ mm using the volume affine, so it registers with cortical template surfaces in the same scene. Structures can be coloured by the built-in FreeSurfer LUT or by user data (dict name->value).

The scene builder accepts an injectable mesh_extractor so region selection, LUT lookup, and value mapping are unit-testable without VTK.

Functions

discover_labels_in_volume(→ list[tuple[int, str]])	Return sorted (label_id, display_name) pairs present in a label NIfTI.
names_to_label_ids(→ list[int])	Map selected atlas label names (or ids) to integer label ids.
filter_label_ids_from_info(→ list[int])	Resolve which label ids should be visible for an atlas file row.
mask_nifti_to_label_ids(img, label_ids)	Return a NIfTI copy with voxels outside label_ids set to zero.
select_labels(→ list[int])	Resolve requested structures (ids or names) to label ids that exist in present.
extract_label_mesh(...)	Extract one label's surface (VTK FlyingEdges) as RAS+ mm SurfaceGeometry.
build_subcortical_scene(, lut, tuple[str, tuple[int, ...)	Build a scene of per-structure subcortical surfaces.

Module Contents

brain_deer.surface.subcortical.discover_labels_in_volume(img) → list[tuple[int, str]]

Return sorted (label_id, display_name) pairs present in a label NIfTI.

brain_deer.surface.subcortical.names_to_label_ids(names: Sequence, present: Sequence[tuple[int, str]] | None = None, lut: Mapping[int, tuple[str, tuple[int, int, int]]] | None = None) → list[int]

Map selected atlas label names (or ids) to integer label ids.

brain_deer.surface.subcortical.filter_label_ids_from_info(info: dict, image) → list[int]

Resolve which label ids should be visible for an atlas file row.

brain_deer.surface.subcortical.mask_nifti_to_label_ids(img, label_ids: Sequence[int])

Return a NIfTI copy with voxels outside label_ids set to zero.

brain_deer.surface.subcortical.select_labels(present: Sequence[int], structures: Sequence | None = None, lut: Mapping[int, tuple[str, tuple[int, int, int]]] | None = None) → list[int]

Resolve requested structures (ids or names) to label ids that exist in present.

structures may mix integer ids and structure names; None selects every known subcortical label found in the volume.

brain_deer.surface.subcortical.extract_label_mesh(label_data: numpy.ndarray, label: int, affine: numpy.ndarray, *, smoothing_iterations: int = 20, decimate: float = 0.0) → brain_deer.surface.meshes.SurfaceGeometry

Extract one label’s surface (VTK FlyingEdges) as RAS+ mm SurfaceGeometry.

brain_deer.surface.subcortical.build_subcortical_scene(label_volume_img, *, structures: Sequence | None = None, data: Mapping[str, float] | None = None, cmap: str = 'hot', vminmax: Sequence[float] | None = None, opacity: float = 1.0, views: Sequence[str] | None = None, background: tuple[float, float, float] = (1.0, 1.0, 1.0), lut: Mapping[int, tuple[str, tuple[int, int, int]]] | None = None, mesh_extractor: Callable[[numpy.ndarray, int, numpy.ndarray], brain_deer.surface.meshes.SurfaceGeometry] | None = None, smoothing_iterations: int = 20) → brain_deer.surface.scene_model.SceneModel

Build a scene of per-structure subcortical surfaces.

With data (structure name -> value), each surface is coloured by a scalar and a colorbar is shown; otherwise structures use their LUT colours.