brain_deer.surface.scene_model¶

Backend-agnostic description of a Surface Studio scene.

These are pure dataclasses plus canonical-view camera math. The renderer (brain_deer.rendering.surface_studio) consumes a SceneModel; keeping it VTK-free means scene construction and view geometry are unit-testable without a display.

Coordinate convention: all geometry is in RAS+ millimetres (surfaces sit in their native template mm; the template scene uses an identity world<->scene map). Camera “views” are named the same as yabplot (left_lateral etc.) so figures are directly comparable.

Classes¶

`CameraPose`	Camera placement relative to the focal point at the scene centre.
`Coloring`	How a layer's scalar values map to colour.
`SurfaceLayer`	A triangulated surface with optional per-vertex scalar values.
`PointsLayer`	Spheres at 3D positions (connectome nodes, subcortical centroids).
`EdgesLayer`	Tubes connecting node positions (connectome edges).
`TractLayer`	White-matter streamlines rendered as tubes.
`SceneModel`	A full Surface Studio scene: layers + presentation settings.

Functions¶

`camera_for_view`(→ CameraPose)	Return a `CameraPose` for a canonical (or aliased) view name.
`hemi_for_view`(→ Optional[str])	Which hemisphere a view emphasises ('lh'/'rh'), or None for symmetric views.

Module Contents¶

class brain_deer.surface.scene_model.CameraPose¶

Camera placement relative to the focal point at the scene centre.

position and view_up are unit-ish direction vectors; the renderer scales position by the scene bounds to frame the brain.

brain_deer.surface.scene_model.camera_for_view(view: str) → CameraPose¶: Return a CameraPose for a canonical (or aliased) view name.

brain_deer.surface.scene_model.hemi_for_view(view: str) → str | None¶: Which hemisphere a view emphasises (‘lh’/’rh’), or None for symmetric views.

class brain_deer.surface.scene_model.Coloring¶

How a layer’s scalar values map to colour.

mode is ‘scalar’ (colormap over [vmin, vmax]), ‘direct’ (per-vertex RGBA baked into the layer, matching 2D slice colours), ‘solid’ (single colour), or ‘label’ (per-region RGB baked into the layer). threshold hides values whose magnitude is below it (NaN’d out -> transparent), matching yabplot masking.

class brain_deer.surface.scene_model.SurfaceLayer¶

A triangulated surface with optional per-vertex scalar values.

vertices is (N,3) float mm, faces is (M,3) int. values is either per-vertex (len N) or None (solid/label colouring). vertex_rgb is optional baked per-vertex colour (N,3 or N,4 in 0..1) for label parcellations.

class brain_deer.surface.scene_model.PointsLayer¶: Spheres at 3D positions (connectome nodes, subcortical centroids).

class brain_deer.surface.scene_model.EdgesLayer¶: Tubes connecting node positions (connectome edges).

class brain_deer.surface.scene_model.TractLayer¶

White-matter streamlines rendered as tubes.

streamlines is a list of (P_i, 3) polylines in mm. scalars (optional) is a matching list of per-point values (tractometry) coloured via coloring; if absent, solid_color is used.

class brain_deer.surface.scene_model.SceneModel¶

A full Surface Studio scene: layers + presentation settings.

all_positions() → numpy.ndarray¶: Stack every layer’s coordinates for computing scene bounds/centre.