brain_deer.surface.plotting¶

Headless scene builders: turn geometry + atlas + data into a SceneModel.

These mirror yabplot’s plot_* entry points but produce a backend-agnostic SceneModel instead of drawing. The VTK renderer (brain_deer.rendering.surface_studio) consumes the result. Keeping the mapping logic here (numpy only) makes every plot type unit-testable.

Functions¶

`build_cortical_scene`(, colorbar, colorbar_title)	Cortical region map: colour each parcel by `data` on one/both hemispheres.
`build_label_scene`(, opacity)	Show a parcellation's own colour table (no external data).
`build_vertexwise_scene`(, colorbar, colorbar_title)	Vertex-wise map: per-vertex scalar values directly on the surface.
`build_voxelwise_scene`(, colorbar, colorbar_title)	Voxel-wise map: colour supra-threshold voxels as points in template space.
`add_base_mesh`(...)	Add a translucent base surface (yabplot `bmesh`) behind data layers.

Module Contents¶

brain_deer.surface.plotting.build_cortical_scene(hemispheres: Sequence[tuple[brain_deer.surface.meshes.SurfaceGeometry, brain_deer.surface.atlas.Parcellation]], data: brain_deer.surface.atlas.DataInput, *, cmap: str = 'viridis', vminmax: Sequence[float] | None = None, threshold: float | None = None, opacity: float = 1.0, views: Sequence[str] | None = None, background: tuple[float, float, float] = (1.0, 1.0, 1.0), colorbar: bool = True, colorbar_title: str = '') → brain_deer.surface.scene_model.SceneModel¶

Cortical region map: colour each parcel by data on one/both hemispheres.

hemispheres pairs a surface geometry with its parcellation. data is mapped to regions per hemisphere (dict = name-based/partial; array = strict order across that hemisphere’s region list). Values expand to per-vertex scalars; parcels without data (or below threshold) become NaN and render transparent/grey.

brain_deer.surface.plotting.build_label_scene(hemispheres: Sequence[tuple[brain_deer.surface.meshes.SurfaceGeometry, brain_deer.surface.atlas.Parcellation]], *, views: Sequence[str] | None = None, background: tuple[float, float, float] = (1.0, 1.0, 1.0), opacity: float = 1.0) → brain_deer.surface.scene_model.SceneModel¶: Show a parcellation’s own colour table (no external data).

brain_deer.surface.plotting.build_vertexwise_scene(hemispheres: Sequence[tuple[brain_deer.surface.meshes.SurfaceGeometry, numpy.ndarray]], *, cmap: str = 'viridis', vminmax: Sequence[float] | None = None, threshold: float | None = None, opacity: float = 1.0, views: Sequence[str] | None = None, background: tuple[float, float, float] = (1.0, 1.0, 1.0), colorbar: bool = True, colorbar_title: str = '') → brain_deer.surface.scene_model.SceneModel¶: Vertex-wise map: per-vertex scalar values directly on the surface.

brain_deer.surface.plotting.build_voxelwise_scene(points_mm: numpy.ndarray, values: numpy.ndarray, *, cmap: str = 'hot', vminmax: Sequence[float] | None = None, base_radius: float = 1.0, opacity: float = 1.0, max_points: int = 200000, views: Sequence[str] | None = None, background: tuple[float, float, float] = (1.0, 1.0, 1.0), colorbar: bool = True, colorbar_title: str = '') → brain_deer.surface.scene_model.SceneModel¶

Voxel-wise map: colour supra-threshold voxels as points in template space.

If more than max_points voxels pass, keep the highest-magnitude ones so the 3D view stays interactive instead of trying to render millions of glyphs.

brain_deer.surface.plotting.add_base_mesh(scene: brain_deer.surface.scene_model.SceneModel, geom: brain_deer.surface.meshes.SurfaceGeometry, *, alpha: float = 0.1, color: tuple[float, float, float] = (0.8, 0.8, 0.8)) → brain_deer.surface.scene_model.SceneModel¶: Add a translucent base surface (yabplot bmesh) behind data layers.