Skip to content

Scene

The scene groups the cameras, canvas, and dimension management that together define what is rendered and how it is viewed.

Cameras

cellier.scene.CameraType module-attribute 

CameraType = Annotated[Union[PerspectiveCamera, OrthographicCamera], Field(discriminator='camera_type')]

cellier.scene.OrthographicCamera

Bases: BaseCamera

2D orthographic camera state.

Parameters:

Name Type Description Default
camera_type Literal['orthographic']

Discriminator field. Always "orthographic".

 required
width float

Width of the view volume. Default 10.0.

 required
height float

Height of the view volume. Default 10.0.

 required
zoom float

Zoom level. Default 1.0.

 required
near_clipping_plane float

Near clipping distance. Default -500.0.

 required
far_clipping_plane float

Far clipping distance. Default 500.0.

 required
position NumpyFloat32Array

World-space camera position, shape (3,).

 required
rotation NumpyFloat32Array

Quaternion [x, y, z, w], shape (4,).

 required

model_post_init 

model_post_init(__context: Any) -> None

Wire controller event relay after model initialization.

cellier.scene.PerspectiveCamera

Bases: BaseCamera

3D perspective camera state.

Parameters:

Name Type Description Default
camera_type Literal['perspective']

Discriminator field. Always "perspective".

 required
fov float

Field of view in degrees. Default 70.0.

 required
zoom float

Zoom level. Default 1.0.

 required
near_clipping_plane float

Near clipping distance. Default 1.0.

 required
far_clipping_plane float

Far clipping distance. Default 8000.0.

 required
position NumpyFloat32Array

World-space camera position, shape (3,).

 required
rotation NumpyFloat32Array

Quaternion [x, y, z, w], shape (4,).

 required
up_direction NumpyFloat32Array

World-space up vector, shape (3,).

 required
frustum NumpyFloat32Array

Near and far plane corners, shape (2, 4, 3).

 required

model_post_init 

model_post_init(__context: Any) -> None

Wire controller event relay after model initialization.

Camera controllers

cellier.scene.CameraControllerType module-attribute 

CameraControllerType = Annotated[Union[OrbitCameraController, PanZoomCameraController], Field(discriminator='controller_type')]

cellier.scene.OrbitCameraController

Bases: BaseCameraController

Config for a 3D orbit camera controller.

Parameters:

Name Type Description Default
controller_type Literal['orbit']

Discriminator field. Always "orbit".

 required

cellier.scene.PanZoomCameraController

Bases: BaseCameraController

Config for a 2D pan/zoom camera controller.

Parameters:

Name Type Description Default
controller_type Literal['pan_zoom']

Discriminator field. Always "pan_zoom".

 required

Canvas

cellier.scene.Canvas

Bases: EventedModel

One rendered canvas, holding one or more cameras.

Parameters:

Name Type Description Default
id UUID4

Unique identifier. Auto-generated.

 required
cameras dict[str, CameraType]

Mapping of "2d" and/or "3d" to camera models. At least one entry is required.

 required
overlays list[CanvasOverlayType]

Screen-space overlays attached to this canvas. Rendered as post-passes on top of the main scene. Default empty list.

 required

model_post_init 

model_post_init(__context: Any) -> None

Wire camera event relays after model initialization.

Dims

cellier.scene.CoordinateSystem

Bases: EventedModel

Names the scene's world coordinate axes.

Parameters:

Name Type Description Default
name str

Human-readable name, e.g. "world".

 required
axis_labels tuple[str, ...]

One label per axis, e.g. ("z", "y", "x").

 required

cellier.scene.DimsManager

Bases: EventedModel

Tracks which axes are displayed and the slice index for non-displayed axes.

Single source of truth for render dimensionality.

Parameters:

Name Type Description Default
id UUID4

Unique identifier. Auto-generated.

 required
coordinate_system CoordinateSystem

Defines the world axis names.

 required
selection SelectionType

The current axis selection (axis-aligned or plane).

 required

model_post_init 

model_post_init(__context: Any) -> None

Wire event relays after model initialization.

to_state 

to_state() -> DimsState

Return an immutable snapshot of the current dims state.

Scene

cellier.scene.Scene

Bases: EventedModel

One rendered scene.

Parameters:

Name Type Description Default
id UUID4

Unique identifier. Auto-generated.

 required
name str

Human-readable name, e.g. "main".

 required
dims DimsManager

Dimension manager; single source of truth for render dimensionality.

 required
visuals list[VisualType]

Discriminated union of visual model types.

 required
canvases dict[UUID4, Canvas]

Keyed by canvas.id.

 required
render_modes set[Literal['2d', '3d']]

Which rendering modes visuals added to this scene should support. Defaults to {"2d", "3d"}.

 required
lighting Literal['none', 'default']

"none" (default) or "default". Pass "default" to add ambient and directional lights — required for MeshPhongAppearance.

 required

model_post_init 

model_post_init(__context: Any) -> None

Wire dims and visual event relays after model initialization.