Skip to content

Visuals

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

Images

One image visual draws single-channel or composited. channel_axis names the data axis channels lie along; composite picks the mode. The shared appearance applies to both modes, single to single mode, and channels to composite mode (one appearance per channel index).

cellier.visuals.BaseImageAppearance

Bases: BaseDrawAppearance

Appearance shared by both modes of an image visual.

Parameters:

Name Type Description Default
visible bool

The master switch. In single mode it is the only visibility; in composite mode each channel's visible is gated by it (D12).

 required
transparency_mode str or None

The pygfx alpha mode for every drawn channel. None (the default) is automatic: "blend" in single mode and "add" in composite mode, following the mode as it switches. An explicit value always wins.

 required
interpolation str

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

 required

cellier.visuals.effective_transparency_mode 

effective_transparency_mode(visual: Any) -> str

The alpha mode an image visual draws its channels with.

appearance.transparency_mode when set; otherwise "add" in composite mode and "blend" in single mode.

Parameters:

Name Type Description Default
visual BaseImageVisual

The image visual.

 required

Returns:

Type Description
str

A pygfx alpha mode.

In-memory image

cellier.visuals.ImageVisual

Bases: BaseImageVisual

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

Backed by an ImageMemoryStore. Camera movement does not trigger a reslice because the data is not view-dependent -- the whole slice is always loaded.

Parameters:

Name Type Description Default
visual_type Literal['image_memory']

Discriminator field; always "image_memory".

 required
appearance InMemoryImageAppearance

Shared by both modes.

 required
single InMemoryImageSingleAppearance

Single mode's appearance.

 required
channels dict[int, InMemoryImageChannelAppearance]

Composite mode's per-channel appearances.

 required
requires_camera_reslice bool

Always False; frozen.

 required

__setattr__ 

__setattr__(name: str, value: object) -> None

Keep the old channels when a new dict is refused.

The rules on channels (one render mode, max_channels) are checked after pydantic has assigned the field, and a failed check does not undo the assignment.

plans_coarse_while_moving 

plans_coarse_while_moving(n_displayed_dims: int) -> bool

Whether an interactive dims tick plans this visual BACKSTOP_ONLY.

While the scene's dims are being scrubbed, the controller plans a visual that returns True coarse only, and plans it in full once when the scrub ends. A subclass derives the answer from its own explicit config; the base answer is False.

Parameters:

Name Type Description Default
n_displayed_dims int

Displayed dimensions of the view being planned (2 or 3): a visual may have a setting for each.

 required

drawn_channels 

drawn_channels(size: int | None = None) -> tuple[int, ...]

The channel indices composite mode draws, ascending.

D = {k in channels : appearance.visible and channels[k].visible and 0 <= k < size} (design 3.3). Empty when the visual is hidden.

Parameters:

Name Type Description Default
size int or None

The length of the channel axis. None skips the range check.

 None

Returns:

Type Description
tuple[int, ...]

The drawn indices.

plane_mode 

plane_mode() -> bool

Whether a 3D view draws this visual on its render_planes.

Single mode reads single.render_mode. Composite mode reads its drawn channels, which share one render mode like all the channels.

draws_nothing 

draws_nothing(size: int | None = None) -> bool

Whether the visual draws nothing and so needs no slicing (3.3).

Hidden, or in composite mode with no drawn channel.

cellier.visuals.InMemoryImageAppearance

Bases: BaseImageAppearance

Shared appearance of an in-memory image visual.

Every field has a default, so a plain image needs no appearance=.

cellier.visuals.InMemoryImageSingleAppearance

Bases: BaseImageSingleAppearance

Single-mode appearance of an in-memory image visual.

Parameters:

Name Type Description Default
render_mode str

Rendering mode for the 3D view: "mip" (default), "iso", "minip", or "plane", which draws the data on the visual's render_planes instead of as a volume. Ignored by the 2D view.

 required

cellier.visuals.InMemoryImageChannelAppearance

Bases: InMemoryImageSingleAppearance

One channel's appearance on an in-memory image, in composite mode.

Parameters:

Name Type Description Default
visible bool

Whether composite mode draws this channel. Gated by the shared appearance.visible. Default True.

 required

Multiscale image

cellier.visuals.MultiscaleImageVisual

Bases: BaseImageVisual

Model for a multiscale image visual.

Parameters:

Name Type Description Default
visual_type Literal['multiscale_image']

Discriminator field. Always "multiscale_image".

 required
level_transforms list[AffineTransform]

Per-level transforms mapping level-k voxel coords to level-0 voxel coords. Copied from the data store by the controller.

 required
appearance MultiscaleImageAppearance

Shared by both modes.

 required
single MultiscaleImageSingleAppearance

Single mode's appearance.

 required
channels dict[int, MultiscaleImageChannelAppearance]

Composite mode's per-channel appearances.

 required
render_config MultiscaleImageRenderConfig

GPU cache configuration.

 required

__setattr__ 

__setattr__(name: str, value: object) -> None

Keep the old channels when a new dict is refused.

The rules on channels (one render mode, max_channels) are checked after pydantic has assigned the field, and a failed check does not undo the assignment.

drawn_channels 

drawn_channels(size: int | None = None) -> tuple[int, ...]

The channel indices composite mode draws, ascending.

D = {k in channels : appearance.visible and channels[k].visible and 0 <= k < size} (design 3.3). Empty when the visual is hidden.

Parameters:

Name Type Description Default
size int or None

The length of the channel axis. None skips the range check.

 None

Returns:

Type Description
tuple[int, ...]

The drawn indices.

plane_mode 

plane_mode() -> bool

Whether a 3D view draws this visual on its render_planes.

Single mode reads single.render_mode. Composite mode reads its drawn channels, which share one render mode like all the channels.

draws_nothing 

draws_nothing(size: int | None = None) -> bool

Whether the visual draws nothing and so needs no slicing (3.3).

Hidden, or in composite mode with no drawn channel.

plans_coarse_while_moving 

plans_coarse_while_moving(n_displayed_dims: int) -> bool

The moving setting of the view being planned.

appearance.coarsest_while_moving_3d for a 3D view, appearance.coarsest_while_moving_2d for a 2D one.

cellier.visuals.MultiscaleImageAppearance

Bases: BaseImageAppearance

Shared appearance of a multiscale image visual.

Adds the fields both modes share on a brick-streamed visual.

Parameters:

Name Type Description Default
attenuation float

Depth attenuation coefficient for "attenuated_mip". Default 1.0.

 required
settled_lod_bias float

Level-of-detail bias of a settled view, 2D and 3D. Divisor on the screen-space LOD threshold: higher is coarser. Default 1.0.

 required
coarsest_while_moving_3d bool

In a 3D view, plan no target while the visual moves. A visual moves while its scene's dims are scrubbed, or while its clipping planes are dragged (CellierController.plane_interaction). A dims tick then loads the new slice's coarse backstop only; a plane drag plans nothing and keeps the last plan. The target is planned once every motion has ended. False plans in full on every tick and nothing more at the end. Default True.

 required
coarsest_while_moving_2d bool

The same, for a 2D view, whose only motion is a dims scrub. True saves most of a scrub's reads and is the setting for a slow store. Default False.

 required
force_level int or None

Overrides automatic LOD selection when set. Default None.

 required
frustum_cull bool

Skip bricks outside the camera frustum. Default True.

 required
ray_steps_per_voxel float

3D ray-march samples per voxel of the drawn level, measured along the ray. Lower is faster but can skip features a voxel or two thick and dims MIP peaks (a one-voxel spot can lose up to 1 / (2 * ray_steps_per_voxel) of its value). Must be in [0.5, 8]: below 0.5 a bisection probe can overshoot the brick's ghost border. Default 1.0.

 required

cellier.visuals.MultiscaleImageSingleAppearance

Bases: BaseImageSingleAppearance

Single-mode appearance of a multiscale image visual.

Parameters:

Name Type Description Default
render_mode str

"iso" (default), "mip", "smooth_iso", "attenuated_mip", or "plane", which draws the data on the visual's render_planes instead of as a volume.

 required
iso_threshold float

Isosurface threshold. Default 0.2.

 required

cellier.visuals.MultiscaleImageChannelAppearance

Bases: MultiscaleImageSingleAppearance

One channel's appearance on a multiscale image, in composite mode.

Parameters:

Name Type Description Default
visible bool

Whether composite mode draws this channel. Default True.

 required

cellier.visuals.MultiscaleImageRenderConfig pydantic-model

Bases: BaseModel

Render-layer configuration for a multiscale image visual.

These parameters control GPU resource allocation. 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 caches, split evenly between the channels the visual can draw -- its channels, not the slot pool's max_channels, so an unused slot takes no budget from a drawing one. A visual with no channel axis, or none configured, gets all of it. Default 1 GiB.

 required
gpu_budget_bytes_2d int

Maximum GPU memory for the 2-D tile caches, split likewise. Default 64 MiB.

 required
loading ProgressiveLoadingConfig

The coarse backstop loaded ahead of the target level. Changing only this reslices; the other fields reallocate GPU resources.

 required

Config:

  • frozen: True

Fields:

cellier.visuals.ProgressiveLoadingConfig pydantic-model

Bases: BaseModel

How a multiscale visual loads: a coarse backstop, then the target.

A coarse backstop level is always loaded ahead of the target level, so the view is blurry rather than blank (or showing the previous slice) while the target loads. Backstop reads go before every target read, from every visual.

Every setting is explicit, with a fixed default, and never changed by the library at runtime. Replacing a visual's render_config with one that differs only here reslices the visual without reallocating its atlases.

Parameters:

Name Type Description Default
backstop_level int or None

1-based level of the backstop, like force_level (1 is the finest). Clamped to the pyramid. None (the default) is the coarsest level.

 required
backstop_extent ('full', 'view')

"full" (default): the whole volume in 3D, so orbiting never exposes black, and the whole slice in 2D. "view": frustum-culled in 3D, and the viewport plus one backstop tile of margin in 2D.

 "full"
backstop_max_slot_fraction float

At most this share of an atlas's slots holds backstop bricks, filled nearest the camera (3D) or canvas centre (2D) first. Only shallow pyramids reach it; when it truncates, one INFO line per visual on cellier.render.cache names the settings that would avoid it. Default 0.1.

 required

Config:

  • frozen: True

Fields:

  • backstop_level (int | None)
  • backstop_extent (Literal['full', 'view'])
  • backstop_max_slot_fraction (float)

Validators:

  • _refuse_removed_fields

cellier.visuals.GeometryLodConfig pydantic-model

Bases: BaseModel

How a multiscale geometry visual uses its levels of detail.

Two levels are kept loaded: the finest, and one coarse level. Every setting is explicit, with a fixed default, and never changed by the library at runtime. The config is frozen: replace it to change it.

Parameters:

Name Type Description Default
coarse_level int or None

1-based level kept beside the finest (1 is the finest, so the smallest value is 2). None (the default) is the coarsest level the store has. A level the store does not have is refused when the visual is added. Level numbers on a pick (MeshPickInfo.level) and on a store request are 0-based instead.

 required
dims_drag ('coarse', 'full')

What a dims scrub loads for each new position. "coarse" (the default) loads the coarse level while the slider moves and the finest when it rests; "full" loads both on every tick.

 "coarse"
dims_drag_draw ('coarse', 'full')

What a dims scrub draws of a visual the scrub does not change (a static mesh next to a time series). "coarse" (the default) draws the coarse level while the slider moves, so a very large mesh does not slow the scrub's frames; the finest stays loaded and returns when the scrub ends. "full" keeps drawing the finest. Applies at once, with no read.

 "coarse"
camera_motion ('coarse', 'full')

What is drawn while the camera moves in a 3D view. "coarse" (the default) draws the coarse level on the canvas whose camera is moving; "full" keeps drawing the finest. Applies at once, with no read.

 "coarse"

Config:

  • frozen: True

Fields:

  • coarse_level (int | None)
  • dims_drag (Literal['coarse', 'full'])
  • dims_drag_draw (Literal['coarse', 'full'])
  • camera_motion (Literal['coarse', 'full'])

coarse_scale_index 

coarse_scale_index(level_count: int) -> int | None

The 0-based level kept beside the finest, for a store's levels.

Parameters:

Name Type Description Default
level_count int

How many levels the store has.

 required

Returns:

Type Description
int or None

None when the store has one level: there is no coarse level.

Raises:

Type Description
ValueError

If coarse_level names a level the store does not have.

In-memory labels

cellier.visuals.LabelMemoryVisual

Bases: BaseLabelsVisual

Model-layer visual for in-memory label arrays.

Parameters:

Name Type Description Default
appearance InMemoryLabelsAppearance

Colormap and rendering appearance.

 required

__setattr__ 

__setattr__(name: str, value: object) -> None

Validate clipping_planes and render_planes on assignment.

The model does not validate assignments in general; without this a list would stay a list and a wrong element would be found only when the planes are drawn.

plans_coarse_while_moving 

plans_coarse_while_moving(n_displayed_dims: int) -> bool

Whether an interactive dims tick plans this visual BACKSTOP_ONLY.

While the scene's dims are being scrubbed, the controller plans a visual that returns True coarse only, and plans it in full once when the scrub ends. A subclass derives the answer from its own explicit config; the base answer is False.

Parameters:

Name Type Description Default
n_displayed_dims int

Displayed dimensions of the view being planned (2 or 3): a visual may have a setting for each.

 required

plane_mode 

plane_mode() -> bool

Whether a 3D view draws this visual on its render_planes.

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', 'flat_categorical' or 'plane')

3D rendering mode. "plane" draws the labels on the visual's render_planes instead of as a volume.

 required

cellier.visuals.InMemoryLabelsAppearance

Bases: BaseLabelsAppearance

Appearance parameters for an in-memory label visual.

Multiscale labels

cellier.visuals.MultiscaleLabelVisual

Bases: BaseLabelsVisual

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

__setattr__ 

__setattr__(name: str, value: object) -> None

Validate clipping_planes and render_planes on assignment.

The model does not validate assignments in general; without this a list would stay a list and a wrong element would be found only when the planes are drawn.

plane_mode 

plane_mode() -> bool

Whether a 3D view draws this visual on its render_planes.

plans_coarse_while_moving 

plans_coarse_while_moving(n_displayed_dims: int) -> bool

The moving setting of the view being planned.

appearance.coarsest_while_moving_3d for a 3D view, appearance.coarsest_while_moving_2d for a 2D one.

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" (and "plane", as on the base). Not frozen — live-mutable.

 required
settled_lod_bias float

Level-of-detail bias of a settled view, 2D and 3D. Divisor on the screen-space LOD threshold: higher is coarser. Default 1.0.

 required
coarsest_while_moving_3d bool

In a 3D view, plan no target while the visual moves. A visual moves while its scene's dims are scrubbed, or while its clipping planes are dragged (CellierController.plane_interaction). A dims tick then loads the new slice's coarse backstop only; a plane drag plans nothing and keeps the last plan. The target is planned once every motion has ended. False plans in full on every tick and nothing more at the end. Default True.

 required
coarsest_while_moving_2d bool

The same, for a 2D view, whose only motion is a dims scrub. True saves most of a scrub's reads and is the setting for a slow store. Default False.

 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
ray_steps_per_voxel float

3D ray-march samples per voxel of the drawn level, measured along the ray. Lower is faster but can skip labels a voxel or two thick. Must be in [0.5, 8]: below 0.5 a bisection probe can overshoot the brick's ghost border. Default 1.0.

 required

cellier.visuals.MultiscaleLabelRenderConfig pydantic-model

Bases: BaseModel

Config:

  • frozen: True

Fields:

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
paint_max_tiles int

Tiles the 2-D paint overlay can hold. Default 512.

 required
loading ProgressiveLoadingConfig

The coarse backstop loaded ahead of the target level. Changing only this reslices; the other fields reallocate GPU resources.

 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

__setattr__ 

__setattr__(name: str, value: object) -> None

Validate clipping_planes and render_planes on assignment.

The model does not validate assignments in general; without this a list would stay a list and a wrong element would be found only when the planes are drawn.

plans_coarse_while_moving 

plans_coarse_while_moving(n_displayed_dims: int) -> bool

Whether an interactive dims tick plans this visual BACKSTOP_ONLY.

While the scene's dims are being scrubbed, the controller plans a visual that returns True coarse only, and plans it in full once when the scrub ends. A subclass derives the answer from its own explicit config; the base answer is False.

Parameters:

Name Type Description Default
n_displayed_dims int

Displayed dimensions of the view being planned (2 or 3): a visual may have a setting for each.

 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

Declares where RGB comes from. "uniform" — use color for every point. "vertex" — use per-point colors from the store. A caller declaration, never inferred from the data and never overwritten at commit time.

 required
size_mode str

Declares where the size comes from, on the same terms as color_mode. "uniform" — use size for every point. "vertex" — use per-point sizes from the store. Declaring "vertex" with no sizes in the store raises at commit rather than falling back.

 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

__setattr__ 

__setattr__(name: str, value: object) -> None

Validate clipping_planes and render_planes on assignment.

The model does not validate assignments in general; without this a list would stay a list and a wrong element would be found only when the planes are drawn.

plans_coarse_while_moving 

plans_coarse_while_moving(n_displayed_dims: int) -> bool

Whether an interactive dims tick plans this visual BACKSTOP_ONLY.

While the scene's dims are being scrubbed, the controller plans a visual that returns True coarse only, and plans it in full once when the scrub ends. A subclass derives the answer from its own explicit config; the base answer is False.

Parameters:

Name Type Description Default
n_displayed_dims int

Displayed dimensions of the view being planned (2 or 3): a visual may have a setting for each.

 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: BaseMeshVisual

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
section MeshSectionConfig

How the mesh is drawn in a 2D view: outline and fill of its cross-section.

 required
requires_camera_reslice bool

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

 required

__setattr__ 

__setattr__(name: str, value: object) -> None

Validate clipping_planes and render_planes on assignment.

The model does not validate assignments in general; without this a list would stay a list and a wrong element would be found only when the planes are drawn.

plans_coarse_while_moving 

plans_coarse_while_moving(n_displayed_dims: int) -> bool

Whether an interactive dims tick plans this visual BACKSTOP_ONLY.

While the scene's dims are being scrubbed, the controller plans a visual that returns True coarse only, and plans it in full once when the scrub ends. A subclass derives the answer from its own explicit config; the base answer is False.

Parameters:

Name Type Description Default
n_displayed_dims int

Displayed dimensions of the view being planned (2 or 3): a visual may have a setting for each.

 required

draws_nothing 

draws_nothing() -> bool

Whether the mesh is hidden, and so loads nothing.

A hidden mesh is not planned, and its reads stop. Shown again at the same position it reads nothing: what it held is still there.

cellier.visuals.MultiscaleMeshVisual

Bases: BaseMeshVisual

Model-layer visual for a mesh with levels of detail.

Two levels are kept loaded, the finest and one coarse level (lod.coarse_level). A change of position loads the coarse level first, so the mesh is back on screen sooner, and the finest replaces it when it has loaded. With a store of one level it behaves as a MeshVisual.

Parameters:

Name Type Description Default
visual_type Literal['mesh_multiscale']

Discriminator field; always "mesh_multiscale".

 required
data_store_id str

UUID string of the associated MultiscaleMeshStore.

 required
appearance MeshFlatAppearance | MeshPhongAppearance

Appearance parameters, shared by both levels.

 required
section MeshSectionConfig

How the mesh is drawn in a 2D view: outline and fill of its cross-section, at whichever level is drawn.

 required
lod GeometryLodConfig

Which coarse level is kept, and when it is loaded and drawn.

 required
requires_camera_reslice bool

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

 required

__setattr__ 

__setattr__(name: str, value: object) -> None

Validate clipping_planes and render_planes on assignment.

The model does not validate assignments in general; without this a list would stay a list and a wrong element would be found only when the planes are drawn.

draws_nothing 

draws_nothing() -> bool

Whether the mesh is hidden, and so loads nothing.

A hidden mesh is not planned, and its reads stop. Shown again at the same position it reads nothing: what it held is still there.

plans_coarse_while_moving 

plans_coarse_while_moving(n_displayed_dims: int) -> bool

True when lod.dims_drag is "coarse", in 2D and 3D.

While the scene's dims are scrubbed the mesh then loads its coarse level only, and the finest once when the scrub ends.

cellier.visuals.MeshSectionConfig

Bases: EventedModel

How a mesh is drawn in a 2D view: its cross-section.

A 2D view cuts the mesh with the slice plane and draws the cut: an outline where the surface crosses the plane, and a fill where the outline closes into loops. Both use the mesh's appearance (colour, opacity). An open surface has no closed loop, so it draws its outline only. A 3D view is not affected.

Only spatial, continuous axes are cut. Along any other sliced axis (a time axis, a discrete axis) the mesh is filtered face by face, as in 3D.

Parameters:

Name Type Description Default
mode (cut, slab)

"cut" (default) draws the cut by the slice plane itself; the scene's thickness on the cut axis is ignored, so a thick slab that shows many image planes still shows one mesh outline. "slab" draws what lies inside the scene's slab: the surface between its two faces, flattened, with a cap at each face and both cuts as the outline. With no thickness the two are the same.

 "cut"
outline bool

Draw the outline. Default True.

 required
fill bool

Draw the fill. Default True.

 required
outline_width float

Outline thickness in screen pixels. Default 2.

 required
Changing
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')]

Clipping planes

Every visual has a clipping_planes tuple, in the level-0 data coordinates of the store it reads. See Clip a visual with planes.

cellier.visuals.ClippingPlane pydantic-model

Bases: BaseModel

One clipping plane of a visual.

The visual is drawn where plane.normal . p >= plane.offset: the half-space the normal points into. Several planes on one visual keep the intersection of their half-spaces.

The plane is in the visual's level-0 data coordinate system, the system its store owns. Build the store first, then the plane from store.data_coordinate_systems[0], then the visual. Units are data units: voxels for an image. On anisotropic data the normal is a covector in voxel space, so a plane tilted 45 degrees in the sample is not (1, 1, 0) when the voxels are not cubes.

A plane may be defined on some of the data axes only (see :meth:from_point_normal). A zyx plane on tzyx data holds at every timepoint.

The model is frozen. Moving a plane means assigning a new tuple to visual.clipping_planes. Build the moved plane with item.model_copy(update={"plane": new_plane}) so it keeps its id: the id is what names a plane across replacements of the tuple. Two planes built from scratch have different ids and are not equal, even with the same plane.

Parameters:

Name Type Description Default
id UUID4

Names this plane. Unique within a visual's clipping_planes. Generated when not given.

 required
plane Plane

The plane, in the visual's level-0 data coordinates.

 required
enabled bool

A disabled plane stays in the list and clips nothing. Toggling it costs no shader compile. Default True.

 required
outline PlaneOutline

The line around the plane's cut face: the plane where it crosses the visual's data, inside the visual's other clipping planes. Off by default. It is drawn in a 3D view, while the plane is enabled.

 required

Config:

  • frozen: True

Fields:

from_point_normal classmethod 

from_point_normal(coordinate_system: CoordinateSystem, point: ArrayLike, normal: ArrayLike, axes: Sequence[AxisRef] | None = None, *, enabled: bool = True, outline: PlaneOutline | None = None) -> ClippingPlane

Build the plane through point that keeps the side normal points to.

Parameters:

Name Type Description Default
coordinate_system CoordinateSystem

The visual's level-0 data coordinate system: store.data_coordinate_systems[0].

 required
point ArrayLike

A point on the plane, in data coordinates.

 required
normal ArrayLike

The normal, the same length as point. It points into the kept half-space.

 required
axes Sequence[AxisRef] or None

The axes point and normal are given on, e.g. ("z", "y", "x"). The other axes are not constrained. None means every axis of the system.

 None
enabled bool

Whether the plane clips. Default True.

 True
outline PlaneOutline or None

The line around the plane's cut face. None is no outline.

 None

Returns:

Type Description
ClippingPlane

Render planes

An image or labels visual whose render mode is "plane" draws its data on its render_planes tuple in a 3D view, instead of as a volume. A render plane is in the scene's world space.

cellier.visuals.RenderPlane pydantic-model

Bases: BaseModel

One plane a visual in "plane" render mode draws its data on.

The plane is in the scene's world space, on three named world axes. origin is a point on it and in_plane_axis_0 and in_plane_axis_1 are two orthogonal unit vectors in it; all three are given on axes, in that order. The plane constrains no other world axis: a zyx plane in a tzyx scene holds at every time point.

The plane is drawn where it crosses the visual's data, inside the visual's clipping planes, and within extent_0 and extent_1: the (min, max) distances from origin along the two in-plane axes, in world units. None is unbounded on that side.

The model is frozen. Moving a plane means assigning a new tuple to visual.render_planes. Build the moved plane with plane.model_copy(update={...}) so it keeps its id: the id names a plane across replacements of the tuple. Two planes built from scratch have different ids and are not equal, even with the same pose. (model_copy does not validate: give it unit, orthogonal axes, or use a constructor.)

Parameters:

Name Type Description Default
id UUID4

Names this plane. Unique within a visual's render_planes. Generated when not given.

 required
coordinate_system UUID4

The id of the scene's world coordinate system.

 required
axes tuple of three AxisRef

The world axes the pose is given on, by id or name. The constructors store ids.

 required
origin tuple of three float

A point on the plane.

 required
in_plane_axis_0 tuple of three float

The in-plane frame. Normalised on construction; they must be finite, non-zero and orthogonal.

 required
in_plane_axis_1 tuple of three float

The in-plane frame. Normalised on construction; they must be finite, non-zero and orthogonal.

 required
extent_0 tuple of two (float or None)

(min, max) along each in-plane axis; None is unbounded. A bounded pair needs min < max.

 required
extent_1 tuple of two (float or None)

(min, max) along each in-plane axis; None is unbounded. A bounded pair needs min < max.

 required
enabled bool

A disabled plane stays in the tuple and is not drawn. Default True.

 required
outline PlaneOutline

The line around what is drawn of the plane. Off by default. It is drawn while the plane is: in a 3D view of the plane's axes, with the visual in the "plane" render mode.

 required

Config:

  • frozen: True

Fields:

  • id (UUID4)
  • coordinate_system (UUID4)
  • axes (Axes3)
  • origin (Vector3)
  • in_plane_axis_0 (Vector3)
  • in_plane_axis_1 (Vector3)
  • extent_0 (Extent)
  • extent_1 (Extent)
  • enabled (bool)
  • outline (PlaneOutline)

Validators:

  • _axis_ids_from_text → axes
  • _finite_origin → origin
  • _valid_extent → extent_0, extent_1
  • _validate_frame

normal property 

normal: Vector3

The unit normal, in_plane_axis_0 x in_plane_axis_1, on axes.

Derived, not stored. Which of the two sides it points to changes nothing drawn.

from_point_normal classmethod 

from_point_normal(world: CoordinateSystem, point: ArrayLike, normal: ArrayLike, axes: Sequence[AxisRef] | None = None, up: ArrayLike | None = None, **kwargs: Any) -> RenderPlane

Build the plane through point with the given normal.

The in-plane frame is chosen for the caller. Axis 0 is up projected into the plane; with no up it is the projection of the axis (of axes) least aligned with the normal. Axis 1 completes the frame so that in_plane_axis_0 x in_plane_axis_1 is the normal.

Parameters:

Name Type Description Default
world CoordinateSystem

The scene's world coordinate system.

 required
point ArrayLike

A point on the plane, on axes.

 required
normal ArrayLike

The plane normal, on axes. Any non-zero length.

 required
axes sequence of three AxisRef, or None

The world axes point and normal are given on, e.g. ("z", "y", "x"). None means the system's axes, which must then be three.

 None
up ArrayLike or None

A direction, on axes, whose projection into the plane becomes in_plane_axis_0. It must not be parallel to the normal.

 None
**kwargs Any

extent_0, extent_1, enabled, outline, id.

 {}

Returns:

Type Description
RenderPlane

from_rotation classmethod 

from_rotation(world: CoordinateSystem, origin: ArrayLike, rotation: ArrayLike, axes: Sequence[AxisRef] | None = None, **kwargs: Any) -> RenderPlane

Build the plane at origin whose frame is a rotation.

Parameters:

Name Type Description Default
world CoordinateSystem

The scene's world coordinate system.

 required
origin ArrayLike

A point on the plane, on axes.

 required
rotation ArrayLike

A 3 x 3 rotation matrix whose columns are in_plane_axis_0, in_plane_axis_1 and the normal, on axes; or a quaternion (x, y, z, w) (scalar last) of that rotation, its vector part on axes.

 required
axes sequence of three AxisRef, or None

The world axes the pose is given on. None means the system's axes, which must then be three.

 None
**kwargs Any

extent_0, extent_1, enabled, outline, id.

 {}

Returns:

Type Description
RenderPlane

Raises:

Type Description
ValueError

If rotation is not a rotation: not orthonormal, or a reflection.

Plane outlines

A clipping plane and a render plane each carry an outline: a line round the polygon the plane makes in its visual, in a 3D view.

cellier.visuals.PlaneOutline pydantic-model

Bases: BaseModel

The line along the edge of the polygon a plane makes in its visual.

For a render plane the polygon is what is drawn of it: the plane cut by its extents, by the visual's data box and by the visual's enabled clipping planes. For a clipping plane it is the cut face: the plane cut by the data box and by the visual's other enabled clipping planes.

The model is frozen, as the planes are. An outline is changed the way a plane is moved: plane.model_copy(update={"outline": ...}) in a new tuple, which keeps the plane's id. A change of the outline alone redraws; it does not load data again.

Parameters:

Name Type Description Default
enabled bool

Whether the outline is drawn. Default False. Switching it off keeps the colour and the width.

 required
color tuple of four float

RGBA, each in [0, 1]. Default opaque white.

 required
width float

The line's width in screen pixels. Default 2.0.

 required

Config:

  • frozen: True

Fields:

Validators:

  • _valid_color → color
  • _finite_width → width

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.VisualType module-attribute 

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