Skip to content

Visuals

Visuals describe how a data store is rendered, together with the appearance models that configure their look.

In-memory image

cellier.visuals.ImageVisual

Bases: BaseVisual

Model-layer visual for a single-resolution in-memory image.

Wraps a pygfx gfx.Image (2D scene) or gfx.Volume (3D scene). The associated data store must be an ImageMemoryStore.

Camera movement does not trigger a reslice because data is not view-dependent — the full slice is always loaded.

Parameters:

Name Type Description Default
visual_type Literal['image_memory']

Discriminator field; always "image_memory".

 required
name str

Human-readable label.

 required
data_store_id str

UUID (as a string) of the ImageMemoryStore this visual reads from.

 required
appearance InMemoryImageAppearance

Appearance parameters.

 required
requires_camera_reslice bool

Always False; frozen. Camera movement does not trigger reslicing.

 required

cellier.visuals.MultichannelImageVisual

Bases: BaseVisual

Model-layer visual for a multichannel in-memory image.

Parameters:

Name Type Description Default
channel_axis int

Data-axis index that corresponds to the channel dimension. Immutable after construction.

 required
channels dict[int, ChannelAppearance]

Maps each channel index to its appearance.

 required
interpolation str

Texture sampler filter applied to all channels. "nearest" or "linear". Default "nearest".

 required
data_store_id str

UUID (as a string) of the ImageMemoryStore this visual reads from.

 required
max_channels_2d int

Size of the 2D node pool. Default 8.

 required
max_channels_3d int

Size of the 3D node pool. Default 4.

 required
requires_camera_reslice bool

Always False (frozen).

 required

cellier.visuals.BaseImageAppearance

Bases: BaseAppearance

Base appearance parameters shared by all image visuals.

Parameters:

Name Type Description Default
color_map Colormap

Colourmap applied after contrast normalisation. Accepts any cmap-registered name string (e.g. "viridis", "bids:magma").

 required
clim tuple[float, float]

Contrast limits (min, max) used to normalise pixel values before colour-mapping. Default (0.0, 1.0).

 required
interpolation str

Texture sampler filter. "linear" (default) or "nearest".

 required
visible bool

Inherited from BaseAppearance. Default True.

 required

cellier.visuals.InMemoryImageAppearance

Bases: BaseImageAppearance

Appearance parameters for an in-memory image visual.

Parameters:

Name Type Description Default
render_mode str

Volume rendering mode used for the 3D view. One of "mip" (maximum intensity projection, the default), "iso" (isosurface raycast), or "minip" (minimum intensity projection). Ignored by the 2D view.

 required
iso_threshold float

Isosurface threshold used when render_mode == "iso". Default 0.5.

 required

Multiscale image

cellier.visuals.MultiscaleImageVisual

Bases: BaseVisual

Model for a multiscale image visual.

Parameters:

Name Type Description Default
visual_type Literal['multiscale_image']

Discriminator field. Always "multiscale_image".

 required
name str

The name of the visual

 required
data_store_id str

The id of the data store to be visualized.

 required
level_transforms list[AffineTransform]

Per-level transforms mapping level-k voxel coords to level-0 voxel coords. level_transforms[0] is the identity.

 required
appearance MultiscaleImageAppearance

The material to use for the labels visual.

 required
pick_write bool

If True, the visual can be picked. Default value is True.

 required
id str

The unique id of the visual. The default value is a uuid4-generated hex string. Do not populate this field manually.

 required

cellier.visuals.MultichannelMultiscaleImageVisual

Bases: BaseVisual

Model-layer visual for a multichannel multiscale image.

Parameters:

Name Type Description Default
channel_axis int

Data-axis index for the channel dimension. Immutable after construction.

 required
channels dict[int, ChannelAppearance]

Per-channel appearance; keys are channel indices.

 required
interpolation str

Texture sampler filter applied to all channels. "nearest" or "linear". Default "nearest".

 required
level_transforms list[AffineTransform]

Per-level voxel-level-k → voxel-level-0 AffineTransforms.

 required
render_config MultiscaleImageRenderConfig

Render-layer brick cache and LOD configuration.

 required
max_channels_2d int

2D node pool size. Default 8.

 required
max_channels_3d int

3D node pool size. Default 4.

 required
requires_camera_reslice bool

Always True (frozen). Camera movement triggers reslicing.

 required

cellier.visuals.MultiscaleImageAppearance

Bases: BaseImageAppearance

Appearance parameters for a multiscale image visual.

Extends BaseImageAppearance with LOD-control and volume rendering fields needed for multiscale brick-streamed visuals.

Parameters:

Name Type Description Default
color_map Colormap

Inherited from BaseImageAppearance.

 required
clim tuple[float, float]

Inherited from BaseImageAppearance.

 required
interpolation str

Inherited from BaseImageAppearance. Controls the shader sampler filter.

 required
lod_bias float

Multiplier on the screen-space LOD threshold. Default 1.0.

 required
force_level int | None

Overrides automatic LOD selection when set. Default None.

 required
frustum_cull bool

Skip bricks outside the camera frustum. Default True.

 required
iso_threshold float

Isosurface threshold for 3D raycast rendering. Default 0.2.

 required
render_mode str

Volume rendering mode. Default "iso".

 required
attenuation float

Depth attenuation coefficient for "attenuated_mip" mode. Default 1.0.

 required

cellier.visuals.MultiscaleImageRenderConfig pydantic-model

Bases: BaseModel

Config:

  • frozen: True

Fields:

  • block_size (int)
  • gpu_budget_bytes (int)
  • gpu_budget_bytes_2d (int)
  • paint_max_tiles (int)

model_config class-attribute instance-attribute 

model_config = ConfigDict(frozen=True)

Render-layer configuration for a multiscale image visual.

These parameters control GPU resource allocation and shader selection. They are stored in the model so they round-trip through serialization.

Parameters:

Name Type Description Default
block_size int

Brick / tile side length in voxels. Default 32.

 required
gpu_budget_bytes int

Maximum GPU memory for the 3-D brick cache. Default 1 GiB.

 required
gpu_budget_bytes_2d int

Maximum GPU memory for the 2-D tile cache. Default 64 MiB.

 required
paint_max_tiles int

Maximum number of finest-level tiles that can be simultaneously painted on during one paint session. Each slot consumes block_size**2 * 2 * 4 bytes of GPU memory (e.g. 8 KB at block_size=32). Default 512 = 4 MB. When exhausted during a session, further paint is staged to the WriteBuffer (and persisted on commit) but invisible until commit.

 required

In-memory labels

cellier.visuals.LabelMemoryVisual

Bases: BaseVisual

Model-layer visual for in-memory label arrays.

Parameters:

Name Type Description Default
appearance InMemoryLabelsAppearance

Colormap and rendering appearance.

 required

cellier.visuals.BaseLabelsAppearance

Bases: BaseAppearance

Base appearance parameters shared by all label visuals.

Parameters:

Name Type Description Default
colormap_mode 'random' or 'direct'

Frozen — raises ValidationError on mutation.

 required
background_label int

Label ID treated as transparent (discarded). Default 0.

 required
salt int

Hash seed for random colormap mode. Default 0.

 required
color_dict dict

Explicit label-ID → RGBA mapping for direct mode.

 required
render_mode 'iso_categorical' or 'flat_categorical'

3D rendering mode.

 required

cellier.visuals.InMemoryLabelsAppearance

Bases: BaseLabelsAppearance

Appearance parameters for an in-memory label visual.

Multiscale labels

cellier.visuals.MultiscaleLabelVisual

Bases: BaseVisual

Model for a multiscale label visual.

Parameters:

Name Type Description Default
level_transforms list[AffineTransform]

Per-level transforms mapping level-k voxel coords to level-0.

 required
appearance MultiscaleLabelsAppearance

Visual appearance configuration.

 required
render_config MultiscaleLabelRenderConfig

GPU resource configuration.

 required
requires_camera_reslice bool

Always True (camera movement triggers reslice for LOD). Frozen.

 required

cellier.visuals.MultiscaleLabelsAppearance

Bases: BaseLabelsAppearance

Appearance for multiscale label visuals.

Extends BaseLabelsAppearance with LOD-control fields required for brick-streamed multiscale rendering.

Parameters:

Name Type Description Default
colormap_mode random | direct

Inherited from BaseLabelsAppearance. Frozen.

 required
background_label int

Inherited from BaseLabelsAppearance.

 required
salt int

Inherited from BaseLabelsAppearance.

 required
color_dict dict

Inherited from BaseLabelsAppearance.

 required
render_mode str

Overrides BaseLabelsAppearance to widen the Literal to include "gradient_debug" and "smooth_iso". Not frozen — live-mutable.

 required
lod_bias float

Multiplier on the screen-space LOD threshold. Default 1.0.

 required
force_level int | None

Overrides automatic LOD selection when set. Default None.

 required
frustum_cull bool

Skip bricks outside the camera frustum. Default True.

 required

cellier.visuals.MultiscaleLabelRenderConfig pydantic-model

Bases: BaseModel

Config:

  • frozen: True

Fields:

  • block_size (int)
  • gpu_budget_bytes (int)
  • gpu_budget_bytes_2d (int)
  • paint_max_tiles (int)

model_config class-attribute instance-attribute 

model_config = ConfigDict(frozen=True)

Render-layer configuration for a multiscale label visual.

Parameters:

Name Type Description Default
block_size int

Brick / tile side length in voxels. Default 32.

 required
gpu_budget_bytes int

Maximum GPU memory for the 3-D brick cache. Default 1 GiB.

 required
gpu_budget_bytes_2d int

Maximum GPU memory for the 2-D tile cache. Default 64 MiB.

 required

Points

cellier.visuals.PointsVisual

Bases: BaseVisual

Model-layer visual for a point cloud backed by PointsMemoryStore.

Parameters:

Name Type Description Default
appearance PointsMarkerAppearance

Initial appearance.

 required
requires_camera_reslice bool

Always False — points do not depend on camera position. Frozen.

 required

cellier.visuals.PointsMarkerAppearance

Bases: BaseAppearance

Appearance model for a points visual.

Parameters:

Name Type Description Default
color tuple[float, float, float, float]

RGBA uniform fallback colour. Used when color_mode is "uniform" or when no per-point colors are present.

 required
size float

Uniform point size, interpreted in size_space units.

 required
size_space str

Coordinate space for size. "screen" (pixels) or "world" (world-space units). Default "screen".

 required
color_mode str

"uniform" — use color for every point. "vertex" — use per-point colors from the geometry buffer.

 required
opacity float

Master opacity multiplier in [0, 1].

 required

Lines

cellier.visuals.LinesVisual

Bases: BaseVisual

Model-layer visual for a line-segment collection backed by LinesMemoryStore.

Parameters:

Name Type Description Default
appearance LinesMemoryAppearance

Initial appearance.

 required
requires_camera_reslice bool

Always False — lines do not depend on camera position. Frozen.

 required

cellier.visuals.LinesMemoryAppearance

Bases: BaseAppearance

Appearance model for a lines visual.

Parameters:

Name Type Description Default
color tuple[float, float, float, float]

RGBA uniform fallback colour. Used when color_mode is "uniform" or when no per-vertex colors are present.

 required
thickness float

Line thickness, interpreted in thickness_space units.

 required
thickness_space str

Coordinate space for thickness. "screen" (logical pixels) or "world" (world-space units). Default "screen".

 required
color_mode str

"uniform" — use color for every vertex. "vertex" — use per-vertex colors from the geometry buffer.

 required
opacity float

Master opacity multiplier in [0, 1].

 required

Meshes

cellier.visuals.MeshVisual

Bases: BaseVisual

Model-layer visual for an in-memory triangle mesh.

Parameters:

Name Type Description Default
visual_type Literal['mesh_memory']

Discriminator field; always "mesh_memory".

 required
data_store_id str

UUID string of the associated MeshMemoryStore.

 required
appearance MeshFlatAppearance | MeshPhongAppearance

Appearance parameters.

 required
requires_camera_reslice bool

Always False; frozen. Camera movement does not trigger reslicing.

 required

cellier.visuals.MeshAppearance module-attribute 

MeshAppearance = Annotated[Union[MeshFlatAppearance, MeshPhongAppearance], Field(discriminator='appearance_type')]

cellier.visuals.MeshFlatAppearance

Bases: BaseAppearance

Flat (unlit) mesh — maps to MeshBasicMaterial.

No lights required. Suitable for false-color meshes, wireframe overlays, and rapid inspection.

Parameters:

Name Type Description Default
color tuple[float, float, float, float]

Uniform RGBA, used when color_mode is "uniform".

 required
color_mode str

"uniform", "vertex", or "face".

 required
wireframe bool

Render only edges. Default False.

 required
wireframe_thickness float

Edge thickness in screen pixels. Default 1.0.

 required
opacity float

0-1 alpha multiplier. Default 1.0.

 required
side str

"both", "front", or "back". Default "both".

 required

cellier.visuals.MeshPhongAppearance

Bases: BaseAppearance

Phong-shaded mesh — maps to MeshPhongMaterial.

Requires lights in the scene. Pass lighting="default" to controller.add_scene() to add ambient + directional lights.

Parameters:

Name Type Description Default
color tuple[float, float, float, float]

Uniform RGBA diffuse color, used when color_mode is "uniform".

 required
color_mode str

"uniform", "vertex", or "face".

 required
shininess float

Specular exponent. Default 30.

 required
opacity float

0-1 alpha multiplier. Default 1.0.

 required
side str

"both", "front", or "back". Default "front".

 required
flat_shading bool

Use face normals instead of smooth vertex normals. Default False.

 required

Overlays

cellier.visuals.CanvasOverlay

Bases: EventedModel

Base model for all canvas-space overlays.

Overlays are rendered as a post-pass on top of the main scene using a gfx.ScreenCoordsCamera. They have no world-space transform and do not participate in the reslicing pipeline.

Parameters:

Name Type Description Default
id UUID4

Unique identifier. Auto-generated.

 required
name str

Human-readable label.

 required
visible bool

Whether the overlay is rendered. Default True.

 required

cellier.visuals.CenteredAxes2D

Bases: CanvasOverlay

2D axis indicator rendered in screen space as a corner overlay.

Displays two line segments anchored to a fixed canvas corner, one for each displayed axis. The screen-space directions of the segments are computed from the world-space direction vectors supplied here and the live camera matrix, so the indicator correctly reflects any camera orientation. Geometry is recomputed only when the canvas resizes or the camera matrix changes — never on pan or zoom.

Parameters:

Name Type Description Default
overlay_type str

Discriminator literal "centered_axes_2d". Do not set manually.

 required
axis_a_direction tuple[float, float, float]

Unit vector in pygfx world-space XYZ defining the direction of axis A. Default (0.0, 1.0, 0.0) (world +Y, screen up for standard 2D cameras).

 required
axis_a_label str

Text label drawn at the tip of the axis-A segment. Default "A".

 required
axis_b_direction tuple[float, float, float]

Unit vector in pygfx world-space XYZ defining the direction of axis B. Default (1.0, 0.0, 0.0) (world +X, screen right for standard 2D cameras).

 required
axis_b_label str

Text label drawn at the tip of the axis-B segment. Default "B".

 required
appearance CenteredAxes2DAppearance

Visual style for the overlay.

 required

cellier.visuals.CenteredAxes2DAppearance

Bases: EventedModel

Appearance model for a :class:CenteredAxes2D overlay.

Parameters:

Name Type Description Default
axis_a_color tuple[float, float, float, float]

RGBA color for the first axis line segment. Default green (0.23, 0.67, 0.23, 1.0).

 required
axis_b_color tuple[float, float, float, float]

RGBA color for the second axis line segment. Default orange (0.80, 0.40, 0.00, 1.0).

 required
line_thickness_px float

Line thickness in screen pixels. Default 2.0.

 required
length_px float

Length of each axis segment in screen pixels. Default 60.0.

 required
corner ('bottom_left', 'bottom_right', 'top_left', 'top_right', 'center')

Canvas corner to anchor to, or "center" to place the origin at the canvas centre. Default "center".

 "bottom_left"
corner_offset_px tuple[float, float]

(x, y) offset in pixels from the anchor corner, where (0, 0) is the corner itself. The offset moves the origin inward (right for left corners, left for right corners; down for top corners, up for bottom corners). Default (20.0, 20.0).

 required
show_labels bool

Whether to render text labels at the arrow tips. Default True.

 required
font_size_px float

Label font size in screen pixels. Default 12.0.

 required
label_color tuple[float, float, float, float]

RGBA color for axis text labels. Default white (1.0, 1.0, 1.0, 1.0).

 required

cellier.visuals.CanvasOverlayType module-attribute 

CanvasOverlayType = Annotated[Union[CenteredAxes2D,], Field(discriminator='overlay_type')]

Common

cellier.visuals.AABBParams

Bases: EventedModel

Parameters for an axis-aligned bounding box wireframe overlay.

Parameters:

Name Type Description Default
enabled bool

If True, display the AABB wireframe. Default False.

 required
color str

Line color as a CSS color string. Default "#ffffff".

 required
line_width float

Line thickness in screen pixels. Default 2.0.

 required

cellier.visuals.ChannelAppearance

Bases: BaseAppearance

Appearance parameters for one channel in a multichannel image visual.

Parameters:

Name Type Description Default
color_map Colormap

Colormap applied to this channel's intensity values.

 required
clim tuple[float, float]

Contrast limits (min, max) for normalisation before colour-mapping.

 required
opacity float

Per-channel opacity in [0, 1].

 required
render_mode_3d str

Volume render mode for 3D: "mip" (default) or "iso".

 required
iso_threshold float

Isosurface threshold used when render_mode_3d == "iso". Default 0.5.

 required
visible bool

Inherited from BaseAppearance. Default True.

 required
Notes

validate_assignment is enabled so that a value assigned to a field is coerced to the field's declared type (a color_map name string becomes a cmap.Colormap; a clim list becomes a tuple) and a malformed value raises pydantic.ValidationError. Widget-driven mutations arrive as JSON-native types (list/str), so this coercion is what lets the render layer consume them.

cellier.visuals.VisualType module-attribute 

VisualType = Annotated[Union[MultiscaleImageVisual, ImageVisual, MultichannelImageVisual, MultichannelMultiscaleImageVisual, LabelMemoryVisual, MultiscaleLabelVisual, PointsVisual, LinesVisual, MeshVisual], Field(discriminator='visual_type')]