colight.scene3d

Scene

A 3D scene visual component using WebGPU.

This class creates an interactive 3D scene that can contain multiple types of components:

  • Point clouds
  • Ellipsoids (solid or wireframe fill modes)
  • Cuboids
  • Line segments and beams
  • Meshes (inline vertex/index arrays)
  • Image planes
  • Bounding boxes
  • Groups (nested TRS transforms over any children)

The component supports:

  • Orbit camera control (left mouse drag)
  • Pan camera control (shift + left mouse drag or middle mouse drag)
  • Zoom control (mouse wheel)
  • Component hover highlighting
  • Component click selection
  • Optional FPS display (set controls=['fps'])

PointCloud

Create a point cloud element.

Parameters

  • centers (Optional[ArrayLike]): Nx3 array of point centers or flattened array

  • center (Optional[ArrayLike]): Single point center [x, y, z] (convenience for single-point case)

  • colors (Optional[ArrayLike]): Nx3 array of RGB colors or flattened array (optional)

  • color (Optional[ArrayLike]): Default RGB color [r,g,b] for all points if colors not provided

  • color_by (Optional[ColorBy]): Colormap spec {values, cmap, domain, label, ...} mapping

    scalar values to per-point colors (see ColorBy); adds a legend

  • sizes (Optional[ArrayLike]): N array of point sizes or flattened array (optional)

  • size (Optional[NumberLike]): Default size for all points if sizes not provided

  • alphas (Optional[ArrayLike]): Array of alpha values per point (optional)

  • alpha (Optional[NumberLike]): Default alpha value for all points if alphas not provided

  • layer (Optional[Literal['scene', 'overlay']]): Render layer - "scene" (default) or "overlay" (renders in front, always visible)

  • hover_props (Optional[HoverProps]): Properties to apply on hover (color, alpha, scale)

  • picking_scale (Optional[NumberLike]): Scale factor for picking hit area (values > 1 make clicking easier)

  • **kwargs (Any): Additional arguments like decorations, on_hover, on_click

Ellipsoid

Create an ellipsoid element.

Parameters

  • centers (Optional[ArrayLike]): Nx3 array of ellipsoid centers or flattened array

  • center (Optional[ArrayLike]): Single ellipsoid center [x, y, z] (convenience for single-ellipsoid case)

  • half_sizes (Optional[ArrayLike]): Nx3 array of half_sizes (x,y,z) or flattened array (optional)

  • half_size (Optional[Union[NumberLike, ArrayLike]]): Default half_size (sphere) or [x,y,z] half_sizes (ellipsoid) if half_sizes not provided

  • quaternions (Optional[ArrayLike]): Nx4 array of orientation quaternions [x,y,z,w] (optional)

  • quaternion (Optional[ArrayLike]): Default orientation quaternion [x,y,z,w] if quaternions not provided

  • colors (Optional[ArrayLike]): Nx3 array of RGB colors or flattened array (optional)

  • color (Optional[ArrayLike]): Default RGB color [r,g,b] for all ellipsoids if colors not provided

  • color_by (Optional[ColorBy]): Colormap spec {values, cmap, domain, label, ...} mapping

    scalar values to per-instance colors (see ColorBy); adds a legend

  • alphas (Optional[ArrayLike]): Array of alpha values per ellipsoid (optional)

  • alpha (Optional[NumberLike]): Default alpha value for all ellipsoids if alphas not provided

  • fill_mode (str | None): How the shape is drawn. One of:

    • "Solid": Filled surface with solid color

    • "MajorWireframe": Three axis-aligned ellipse cross-sections

  • layer (Optional[Literal['scene', 'overlay']]): Render layer - "scene" (default) or "overlay" (renders in front, always visible)

  • hover_props (Optional[HoverProps]): Properties to apply on hover (color, alpha, scale)

  • picking_scale (Optional[NumberLike]): Scale factor for picking hit area (values > 1 make clicking easier)

  • **kwargs (Any): Additional arguments like decorations, on_hover, on_click

Cuboid

Create a cuboid element.

Parameters

  • centers (Optional[ArrayLike]): Nx3 array of cuboid centers or flattened array

  • center (Optional[ArrayLike]): Single cuboid center [x, y, z] (convenience for single-cuboid case)

  • half_sizes (Optional[ArrayLike]): Nx3 array of half sizes (width,height,depth) or flattened array (optional)

  • half_size (Optional[Union[ArrayLike, NumberLike]]): Default half size [w,h,d] for all cuboids if half_sizes not provided

  • quaternions (Optional[ArrayLike]): Nx4 array of orientation quaternions [x,y,z,w] (optional)

  • quaternion (Optional[ArrayLike]): Default orientation quaternion [x,y,z,w] if quaternions not provided

  • colors (Optional[ArrayLike]): Nx3 array of RGB colors or flattened array (optional)

  • color (Optional[ArrayLike]): Default RGB color [r,g,b] for all cuboids if colors not provided

  • color_by (Optional[ColorBy]): Colormap spec {values, cmap, domain, label, ...} mapping

    scalar values to per-instance colors (see ColorBy); adds a legend

  • alphas (Optional[ArrayLike]): Array of alpha values per cuboid (optional)

  • alpha (Optional[NumberLike]): Default alpha value for all cuboids if alphas not provided

  • layer (Optional[Literal['scene', 'overlay']]): Render layer - "scene" (default) or "overlay" (renders in front, always visible)

  • hover_props (Optional[HoverProps]): Properties to apply on hover (color, alpha, scale)

  • picking_scale (Optional[NumberLike]): Scale factor for picking hit area (values > 1 make clicking easier)

  • **kwargs (Any): Additional arguments like decorations, on_hover, on_click

LineBeams

Create a line beams element.

Parameters

  • points (ArrayLike): Array of quadruples [x,y,z,i, x,y,z,i, ...] where points sharing the same i value are connected in sequence

  • color (Optional[ArrayLike]): Default RGB color [r,g,b] for all beams if colors not provided

  • size (Optional[NumberLike]): Default size for all beams if sizes not provided

  • colors (Optional[ArrayLike]): Array of RGB colors per line (optional)

  • color_by (Optional[ColorBy]): Colormap spec {values, cmap, domain, label, ...} mapping

    scalar values to per-line colors (see ColorBy); adds a legend

  • sizes (Optional[ArrayLike]): Per-line radii (thickness), one value per line index (the 4th

    component of each point). Every segment of a line shares its line's

    size; for per-segment thickness use LineSegments with sizes.

  • alpha (Optional[NumberLike]): Default alpha value for all beams if alphas not provided

  • alphas (Optional[ArrayLike]): Array of alpha values per line (optional)

  • layer (Optional[Literal['scene', 'overlay']]): Render layer - "scene" (default) or "overlay" (renders in front, always visible)

  • hover_props (Optional[HoverProps]): Properties to apply on hover (color, alpha, scale)

  • picking_scale (Optional[NumberLike]): Scale factor for picking hit area (values > 1 make clicking easier)

  • **kwargs (Any): Additional arguments like on_hover, on_click

Returns

  • A LineBeams scene component that renders connected beam segments. (SceneComponent)

  • Points are connected in sequence within groups sharing the same i value. (SceneComponent)

LineSegments

Create a line segments element.

Parameters

  • starts (ArrayLike): Nx3 array of segment start positions

  • ends (ArrayLike): Nx3 array of segment end positions

  • color (Optional[ArrayLike]): Default RGB color [r,g,b] for all segments if colors not provided

  • size (Optional[NumberLike]): Default size for all segments if sizes not provided

  • colors (Optional[ArrayLike]): Array of RGB colors per segment (optional)

  • color_by (Optional[ColorBy]): Colormap spec {values, cmap, domain, label, ...} mapping

    scalar values to per-segment colors (see ColorBy); adds a legend

  • sizes (Optional[ArrayLike]): Per-segment radii (thickness), one value per segment. Expands

    identically to per-segment colors — index i styles segment

    i (e.g. structural intensity -> drillhole thickness). Falls back

    to size (a scalar for every segment) then the 0.02 default.

  • alpha (Optional[NumberLike]): Default alpha value for all segments if alphas not provided

  • alphas (Optional[ArrayLike]): Array of alpha values per segment (optional)

  • layer (Optional[Literal['scene', 'overlay']]): Render layer - "scene" (default) or "overlay"

  • hover_props (Optional[HoverProps]): Properties to apply on hover (color, alpha, scale)

  • picking_scale (Optional[NumberLike]): Scale factor for picking hit area (values > 1 make clicking easier)

  • **kwargs (Any): Additional arguments like on_hover, on_click

Returns

  • A LineSegments scene component that renders independent segments. (SceneComponent)

GridHelper

Create an XZ grid helper.

Parameters

  • size (NumberLike): Total size of the grid

  • divisions (int): Number of divisions

  • color (Optional[ArrayLike]): Grid line color [r,g,b]

  • center_color (Optional[ArrayLike]): Center line color [r,g,b]

  • line_width (NumberLike): Width of grid lines

  • layer (Optional[Literal['scene', 'overlay']]): Render layer - "scene" (default) or "overlay"

Returns

  • A GridHelper scene component (Any)

CameraFrustum

Create a camera frustum helper.

Parameters

  • intrinsics (Dict[str, Any]): Camera intrinsics dict with fx, fy, cx, cy, width, height

  • extrinsics (Dict[str, Any]): Camera extrinsics dict with position [x,y,z] and quaternion [x,y,z,w]

  • near (NumberLike): Near plane distance

  • far (NumberLike): Far plane distance

  • color (Optional[ArrayLike]): Frustum line color [r,g,b]

  • line_width (NumberLike): Width of frustum lines

  • layer (Optional[Literal['scene', 'overlay']]): Render layer - "scene" (default) or "overlay"

Returns

  • A CameraFrustum scene component (Any)

ImagePlane

Create a textured image plane.

ImageProjection

Create an image projection (plane + optional frustum lines).

Parameters

  • image (Any): Image data (numpy array, PIL image, etc.)

  • intrinsics (Dict[str, Any]): Camera intrinsics dict with fx, fy, cx, cy, width, height

  • extrinsics (Dict[str, Any]): Camera extrinsics dict with position [x,y,z] and quaternion [x,y,z,w]

  • depth (NumberLike): Distance from camera to image plane

  • color (Optional[ArrayLike]): Tint color for the image [r,g,b]

  • opacity (Optional[NumberLike]): Opacity of the image plane (0-1)

  • show_frustum (bool): Whether to show frustum lines from camera to image

  • frustum_color (Optional[ArrayLike]): Color of frustum lines [r,g,b]

  • line_width (NumberLike): Width of frustum lines

  • image_key (Optional[Union[str, int]]): Key for caching/updating image

  • image_width (Optional[int]): Width if providing flat image data

  • image_height (Optional[int]): Height if providing flat image data

  • layer (Optional[Literal['scene', 'overlay']]): Render layer - "scene" (default) or "overlay"

Returns

  • An ImageProjection scene component (Any)

Group

Create a group component for hierarchical scene composition.

Groups apply a transform (position, rotation, scale) to all their children. At render time, groups are flattened into transformed primitives.

Group-level event handlers receive events bubbled up from any child component. Group-level hover_props apply to ALL children when ANY child is hovered.

A named Group with no children is meaningful: its composed transform still gets a palette slot, so geometry elsewhere in the scene can reference it by name (see Mesh's transform_refs). That is how a control structure can have more named transforms than it has directly-attached components.

Parameters

  • children (Optional[list]): List of child components (can include nested groups).

    Optional — a named, childless Group is a pure named transform.

  • position (Optional[ArrayLike]): Position offset [x, y, z] in parent space

  • quaternion (Optional[ArrayLike]): Rotation as quaternion [x, y, z, w]

  • scale (Optional[Union[NumberLike, ArrayLike]]): Scale factor (uniform number or [x, y, z] per-axis)

  • name (Optional[str]): Optional name for identifying this group in pick info

  • child_defaults (Optional[Dict[str, Any]]): Props to apply to children (child values take precedence)

  • child_overrides (Optional[Dict[str, Any]]): Props to apply to children (group values take precedence)

  • hover_props (Optional[HoverProps]): Props to apply to ALL children when ANY child is hovered

  • on_hover (Optional[Any]): Handler called when any child is hovered (bubbles up)

  • on_click (Optional[Any]): Handler called when any child is clicked (bubbles up)

  • on_drag (Optional[Any]): Handler called when any child is dragged (bubbles up)

  • on_drag_start (Optional[Any]): Handler called when drag starts on any child

  • on_drag_end (Optional[Any]): Handler called when drag ends on any child

  • drag_constraint (Optional[DragConstraint]): Constraint for drag operations (applies to all children)

Returns

  • A Group scene component (SceneComponent)

Mesh

Create a mesh component with inline geometry.

Supports flexible vertex formats with optional normals, per-vertex colors, UVs, and textures.

Updating geometry across renders is efficient: when a geometry's identity is stable (same geometry_key, or same structure when no key is given), new vertex data is written into the existing GPU buffers instead of rebuilding shaders and pipelines — buffers grow only when the data doesn't fit. So continuously updating positions (deformation, simulation output, per-frame state) is cheap and does not leak GPU memory, and auto-computed lit normals track position changes. Updates must ship fresh arrays (Python-driven updates always do); in-place mutation of the same array object is not observed, so a caller that mutates in place must bump geometry_key.

Per-vertex weighted transform references (transform_refs + transform_indices + transform_weights, all three together) position each vertex by a weighted combination of named Group transforms instead of rigidly by one — a bending tube, a fault-dragged surface. Positions blend linearly over the referenced transforms, normals rotate through the renormalized blended rotation, and picking sees the deformed surface. Weight-only edits rewrite a small storage buffer, never the vertex buffer, and driving a referenced Group's transform (e.g. via Plot.channel or $state) animates the deformation with zero geometry re-upload. All referenced transforms apply to the same vertex coordinates, so vertices are authored in one frame; a rotation about a pivot is expressed as translate → rotate → translate-back, which nested Groups compose.

Parameters

  • positions (ArrayLike): Nx3 array of vertex positions (required)

  • normals (Optional[ArrayLike]): Nx3 array of vertex normals (optional, auto-computed for lit shading)

  • vertex_colors (Optional[ArrayLike]): Nx3 (RGB) or Nx4 (RGBA) array of per-vertex colors (optional)

  • uvs (Optional[ArrayLike]): Nx2 array of texture coordinates (required for textured meshes)

  • indices (Optional[ArrayLike]): Array of triangle indices (optional for non-indexed meshes)

  • transform_refs (Optional[List[str]]): Names of the Groups whose transforms position this

    mesh's vertices. Supplied together with transform_indices and

    transform_weights. **When present, the per-vertex blend REPLACES

    this mesh's own component-level group transform entirely**: the

    referenced transforms are already composed through Group nesting,

    so the mesh may sit anywhere in the hierarchy but only the Groups

    it names move its vertices. Vertices must therefore be authored in

    the frame those transforms expect. A name with no matching Group

    in the scene is a loud compile error, never a silent identity

    transform.

  • transform_indices (Optional[ArrayLike]): (N, K) integer array of local slots into

    transform_refs, one row per vertex, K references per vertex

    (1..8). N must equal the vertex count.

  • transform_weights (Optional[ArrayLike]): (N, K) float array of weights matching

    transform_indices. Weights must be non-negative and each row must

    have at least one non-zero value; rows are normalized to sum to 1

    (with a warning when they are off by more than 1e-3).

  • texture (Optional[Any]): Image for texturing (numpy array, PIL Image, etc). Requires uvs.

  • texture_key (Optional[Union[str, int]]): Optional key to force texture reupload when image data changes

  • centers (Optional[ArrayLike]): Nx3 array of mesh instance centers

  • center (Optional[ArrayLike]): Single mesh instance center [x, y, z] (convenience for single-instance case)

  • colors (Optional[ArrayLike]): Nx3 array of per-instance RGB colors (optional, multiplied with texture)

  • color (Optional[ArrayLike]): Default RGB color [r,g,b] for all instances if colors not provided

  • scales (Optional[ArrayLike]): Nx3 array of per-instance scales (optional)

  • scale (Optional[Union[NumberLike, ArrayLike]]): Default scale for all instances if scales not provided

  • quaternions (Optional[ArrayLike]): Nx4 array of orientation quaternions [w,x,y,z] (optional)

  • quaternion (Optional[ArrayLike]): Default orientation quaternion [w,x,y,z] if quaternions not provided

  • shading (Optional[Literal['lit', 'unlit']]): "lit" (default) or "unlit"

  • cull_mode (Optional[Literal['none', 'front', 'back']]): "back" (default), "front", or "none"

  • geometry_key (Optional[Union[str, int]]): Names this geometry's identity across updates. A stable

    key means "this is the same geometry": the renderer keeps its

    shaders/pipelines and writes new vertex data into the existing GPU

    buffers (growing them only when the data doesn't fit); a changed

    key forces a clean rebuild. Distinct geometries must be given

    distinct keys — two components sharing a key declare themselves the

    same geometry and share GPU buffers. When omitted, identity is

    derived from the geometry's structure (vertex count, index shape,

    vertex format): same-structure updates reuse pipelines and rewrite

    buffer contents, and topology changes rebuild automatically.

  • layer (Optional[Literal['scene', 'overlay']]): Render layer - "scene" (default) or "overlay"

  • **kwargs (Any): Additional arguments like decorations, onHover, onClick

Returns

  • A Mesh scene component using inline geometry. (SceneComponent)

CustomPrimitive

Create a custom primitive instance.

Parameters

  • type_name (str): Name of the mesh type (must match a Mesh definition)

  • centers (Optional[ArrayLike]): Nx3 array of centers

  • center (Optional[ArrayLike]): Single center [x, y, z] (convenience for single-instance case)

  • layer (Optional[Literal['scene', 'overlay']]): "scene" or "overlay"

  • **kwargs (Any): Additional properties (colors, scales, quaternions, etc.)

Returns

  • SceneComponent for the custom primitive (SceneComponent)

deco

Create a decoration for scene components.

Parameters

  • indexes (Union[int, np.integer, ArrayLike]): Single index or list of indices to decorate

  • color (Optional[ArrayLike]): Optional RGB color override [r,g,b]

  • alpha (Optional[NumberLike]): Optional opacity value (0-1)

  • scale (Optional[NumberLike]): Optional scale factor

  • outline (Optional[bool]): Optional flag to enable outline effect

  • outline_color (Optional[ArrayLike]): Optional outline RGB color [r,g,b]

  • outline_width (Optional[NumberLike]): Optional outline width in pixels

Returns

  • Dictionary containing decoration settings (Decoration)

Colormaps & legends

ColorBy

Colormap-driven coloring for instanced primitives.

values is required; everything else has defaults. Colors are computed in Python via :mod:colight.colormaps; the colormap spec (cmap, domain, label, ...) travels with the component so the scene can render a legend and colight inspect / screenshot --json can report what the colors encode.

Legend

A standalone colormap legend, usable anywhere in a layout.

Scenes render legends automatically for components with color_by; this class renders the same legend UI outside a scene (e.g. next to a plot, or in a layout row).

Hover props

HoverProps

Properties to apply automatically when an instance is hovered.

Drag constraints

DragConstraint

Configuration for drag operations on scene components.

drag_axis

Create an axis constraint for dragging.

Constrains drag movement to a single axis line.

Parameters

  • direction (ArrayLike): Axis direction vector [x, y, z]

  • point (Optional[ArrayLike]): Optional origin point for the axis. If not provided,

    uses the instance center at drag start.

Returns

  • DragConstraint configuration (DragConstraint)

drag_plane

Create a plane constraint for dragging.

Constrains drag movement to a plane.

Parameters

  • normal (ArrayLike): Plane normal vector [x, y, z]

  • point (Optional[ArrayLike]): Optional point on the plane. If not provided,

    uses the instance center at drag start.

Returns

  • DragConstraint configuration (DragConstraint)

DRAG_AXIS_X

DRAG_AXIS_Y

DRAG_AXIS_Z

DRAG_PLANE_XY

DRAG_PLANE_XZ

DRAG_PLANE_YZ

DRAG_SURFACE

DRAG_SCREEN

DRAG_FREE

Gizmo (prototype)

TranslateGizmo

Create a translate gizmo for interactive object translation.

The gizmo consists of axis arrows, plane handles, and a center sphere that allow dragging objects along constrained axes or planes.

Hover highlighting is automatic via hoverProps - no state management needed.

NOTE: This is a prototype API and may change. Screen-space sizing is not yet implemented - use the scale parameter to adjust gizmo size manually.

Parameters

  • position (ArrayLike): World position [x, y, z] of the gizmo center

  • on_drag (Optional[Any]): Callback fired during drag. Receives DragInfo with delta.position.

    Use info.delta.position to get the world-space translation.

  • axes (Optional[tuple[str, ...]]): Which axis handles to show. Default: ("x", "y", "z")

  • planes (Optional[tuple[str, ...]]): Which plane handles to show. Default: ("xy", "xz", "yz")

  • show_center (bool): Show center sphere for free drag. Default: True

  • scale (float): Scale factor for gizmo size. Default: 1.0

Returns

  • A Scene containing the gizmo components (Scene)

GIZMO_COLORS