Scene API

class viser.SceneApi

Interface for adding 3D primitives to the scene.

Used by both our global server object, for sharing the same GUI elements with all clients, and by individual client handles.

world_axes: FrameHandle

Handle for the world axes, which are created by default.

set_up_direction(direction: Literal[‘+x’, ‘+y’, ‘+z’, ‘-x’, ‘-y’, ‘-z’] | tuple[float, float, float] | ndarray) → None

Set the global up direction of the scene. By default we follow +Z-up (similar to Blender, 3DS Max, ROS, etc), the most common alternative is +Y (OpenGL, Maya, etc).

In practice, the impact of this can improve (1) the ergonomics of camera controls, which will default to the same up direction as the scene, and (2) lighting, because the default lights and environment map are oriented to match the scene’s up direction.

Parameters:

direction (Literal[‘+x’, ‘+y’, ‘+z’, ‘-x’, ‘-y’, ‘-z’] | tuple[float, float, float] | ~numpy.ndarray) – New up direction. Can either be a string (one of +x, +y, +z, -x, -y, -z) or a length-3 direction vector.

Return type:

None

set_global_visibility(visible: bool) → None

Set visibility for all scene nodes. If set to False, all scene nodes will be hidden.

This can be useful when we’ve called SceneApi.set_background_image(), and want to hide everything except for the background.

Parameters:

visible (bool) – Whether or not all scene nodes should be visible.

Return type:

None

add_light_directional(name: str, color: Tuple[int, int, int] = (255, 255, 255), intensity: float = 1.0, wxyz: tuple[float, float, float, float] | ndarray = (1.0, 0.0, 0.0, 0.0), position: tuple[float, float, float] = (0.0, 0.0, 0.0), visible: bool = True) → DirectionalLightHandle

Add a directional light to the scene.

Parameters:

• name (str) – A scene tree name. Names in the format of /parent/child can be used to define a kinematic tree.

• color (Tuple[int, int, int]) – Color of the light.

• intensity (float) – Light’s strength/intensity.

• wxyz (tuple[float, float, float, float] | ndarray) – Quaternion rotation to parent frame from local frame (R_pl).

• position (tuple[float, float, float]) – Translation to parent frame from local frame (t_pl).

• visible (bool) – Whether or not this scene node is initially visible.

Returns:

Handle for manipulating scene node.

Return type:

DirectionalLightHandle

add_light_ambient(name: str, color: Tuple[int, int, int] = (255, 255, 255), intensity: float = 1.0, wxyz: tuple[float, float, float, float] | ndarray = (1.0, 0.0, 0.0, 0.0), position: tuple[float, float, float] | ndarray = (0.0, 0.0, 0.0), visible: bool = True) → AmbientLightHandle

Add an ambient light to the scene.

Parameters:

• name (str) – A scene tree name. Names in the format of /parent/child can be used to define a kinematic tree.

• color (Tuple[int, int, int]) – Color of the light.

• intensity (float) – Light’s strength/intensity.

• wxyz (tuple[float, float, float, float] | ndarray) – Quaternion rotation to parent frame from local frame (R_pl).

• position (tuple[float, float, float] | ndarray) – Translation to parent frame from local frame (t_pl).

• visible (bool) – Whether or not this scene node is initially visible.

Returns:

Handle for manipulating scene node.

Return type:

AmbientLightHandle

add_light_hemisphere(name: str, sky_color: Tuple[int, int, int] = (255, 255, 255), ground_color: Tuple[int, int, int] = (255, 255, 255), intensity: float = 1.0, wxyz: tuple[float, float, float, float] | ndarray = (1.0, 0.0, 0.0, 0.0), position: tuple[float, float, float] = (0.0, 0.0, 0.0), visible: bool = True) → HemisphereLightHandle

Add a hemisphere light to the scene.

Parameters:

• name (str) – A scene tree name. Names in the format of /parent/child can be used to define a kinematic tree.

• sky_color (Tuple[int, int, int]) – The light’s sky color.

• ground_color (Tuple[int, int, int]) – The light’s ground color.

• intensity (float) – Light’s strength/intensity.

• wxyz (tuple[float, float, float, float] | ndarray) – Quaternion rotation to parent frame from local frame (R_pl).

• position (tuple[float, float, float]) – Translation to parent frame from local frame (t_pl).

• visible (bool) – Whether or not this scene node is initially visible.

Returns:

Handle for manipulating scene node.

Return type:

HemisphereLightHandle

add_light_point(name: str, color: Tuple[int, int, int] = (255, 255, 255), intensity: float = 1.0, distance: float = 0.0, decay: float = 2.0, wxyz: tuple[float, float, float, float] | ndarray = (1.0, 0.0, 0.0, 0.0), position: tuple[float, float, float] = (0.0, 0.0, 0.0), visible: bool = True) → PointLightHandle

Add a point light to the scene.

Parameters:

• name (str) – A scene tree name. Names in the format of /parent/child can be used to define a kinematic tree.

• color (Tuple[int, int, int]) – Color of the light.

• intensity (float) – Light’s strength/intensity.

• distance (float) – Maximum distance of light.

• decay (float) – The amount the light dims along the distance of the light.

• wxyz (tuple[float, float, float, float] | ndarray) – Quaternion rotation to parent frame from local frame (R_pl).

• position (tuple[float, float, float]) – Translation to parent frame from local frame (t_pl).

• visible (bool) – Whether or not this scene node is initially visible.

Returns:

Handle for manipulating scene node.

Return type:

PointLightHandle

add_light_rectarea(name: str, color: Tuple[int, int, int] = (255, 255, 255), intensity: float = 1.0, width: float = 10.0, height: float = 10.0, wxyz: tuple[float, float, float, float] | ndarray = (1.0, 0.0, 0.0, 0.0), position: tuple[float, float, float] = (0.0, 0.0, 0.0), visible: bool = True) → RectAreaLightHandle

Add a rectangular area light to the scene.

Parameters:

• name (str) – A scene tree name. Names in the format of /parent/child can be used to define a kinematic tree.

• color (Tuple[int, int, int]) – Color of the light.

• intensity (float) – Light’s strength/intensity.

• width (float) – The width of the light.

• height (float) – The height of the light.

• wxyz (tuple[float, float, float, float] | ndarray) – Quaternion rotation to parent frame from local frame (R_pl).

• position (tuple[float, float, float]) – Translation to parent frame from local frame (t_pl).

• visible (bool) – Whether or not this scene node is initially visible.

Returns:

Handle for manipulating scene node.

Return type:

RectAreaLightHandle

add_light_spot(name: str, color: Tuple[int, int, int] = (255, 255, 255), distance: float = 0.0, angle: float = 1.0471975511965976, penumbra: float = 0.0, decay: float = 2.0, intensity: float = 1.0, wxyz: tuple[float, float, float, float] | ndarray = (1.0, 0.0, 0.0, 0.0), position: tuple[float, float, float] = (0.0, 0.0, 0.0), visible: bool = True) → SpotLightHandle

Add a spot light to the scene.

Parameters:

• name (str) – A scene tree name. Names in the format of /parent/child can be used to define a kinematic tree.

• color (Tuple[int, int, int]) – Color of the light.

• distance (float) – Maximum distance of light.

• angle (float) – Maximum extent of the spotlight, in radians, from its direction. Should be no more than Math.PI/2.

• penumbra (float) – Percent of the spotlight cone that is attenuated due to penumbra. Between 0 and 1.

• decay (float) – The amount the light dims along the distance of the light.

• intensity (float) – Light’s strength/intensity.

• wxyz (tuple[float, float, float, float] | ndarray) – Quaternion rotation to parent frame from local frame (R_pl).

• position (tuple[float, float, float]) – Translation to parent frame from local frame (t_pl).

• visible (bool) – Whether or not this scene node is initially visible.

Returns:

Handle for manipulating scene node.

Return type:

SpotLightHandle

set_environment_map(hdri: None | Literal[‘apartment’, ‘city’, ‘dawn’, ‘forest’, ‘lobby’, ‘night’, ‘park’, ‘studio’, ‘sunset’, ‘warehouse’] = 'warehouse', background: bool = False, background_blurriness: float = 0.0, background_intensity: float = 1.0, background_wxyz: tuple[float, float, float, float] | ndarray = (1.0, 0.0, 0.0, 0.0), environment_intensity: float = 1.0, environment_wxyz: tuple[float, float, float, float] | ndarray = (1.0, 0.0, 0.0, 0.0)) → None

Set the environment map for the scene. This will set some lights and background.

Parameters:

• hdri (None | Literal[‘apartment’, ‘city’, ‘dawn’, ‘forest’, ‘lobby’, ‘night’, ‘park’, ‘studio’, ‘sunset’, ‘warehouse’]) – Preset HDRI environment to use.

• background (bool) – Show or hide the environment map in the background.

• background_blurriness (float) – Blur factor of the environment map background (0-1).

• background_intensity (float) – Intensity of the background.

• background_wxyz (tuple[float, float, float, float] | ndarray) – Orientation of the background.

• environment_intensity (float) – Intensity of the environment lighting.

• environment_wxyz (tuple[float, float, float, float] | ndarray) – Orientation of the environment lighting.

Return type:

None

enable_default_lights(enabled: bool = True) → None

Enable/disable the default lights in the scene. If not otherwise specified, default lighting will be enabled.

This does not affect lighting from the environment map. To turn these off, see SceneApi.set_environment_map().

Parameters:

enabled (bool) – True if user wants default lighting. False if user does not want default lighting.

Return type:

None

add_glb(name: str, glb_data: bytes, scale: float = 1.0, wxyz: tuple[float, float, float, float] | ndarray = (1.0, 0.0, 0.0, 0.0), position: tuple[float, float, float] | ndarray = (0.0, 0.0, 0.0), visible: bool = True) → GlbHandle

Add a general 3D asset via binary glTF (GLB).

For glTF files, it’s often simpler to use trimesh.load() with .add_mesh_trimesh(). This will call .add_glb() under the hood.

For glTF features not supported by trimesh, glTF to GLB conversion can also be done programatically with libraries like pygltflib.

Parameters:

• name (str) – A scene tree name. Names in the format of /parent/child can be used to define a kinematic tree.

• glb_data (bytes) – A binary payload.

• scale (float) – A scale for resizing the GLB asset.

• wxyz (tuple[float, float, float, float] | ndarray) – Quaternion rotation to parent frame from local frame (R_pl).

• position (tuple[float, float, float] | ndarray) – Translation to parent frame from local frame (t_pl).

• visible (bool) – Whether or not this scene node is initially visible.

Returns:

Handle for manipulating scene node.

Return type:

GlbHandle

add_line_segments(name: str, points: ndarray, colors: ndarray | tuple[float, float, float], line_width: float = 1, wxyz: tuple[float, float, float, float] | ndarray = (1.0, 0.0, 0.0, 0.0), position: tuple[float, float, float] | ndarray = (0.0, 0.0, 0.0), visible: bool = True) → LineSegmentsHandle

Add line segments to the scene.

Parameters:

• name (str) – A scene tree name. Names in the format of /parent/child can be used to define a kinematic tree.

• points (ndarray) – A numpy array of shape (N, 2, 3) defining start/end points for each of N line segments.

• colors (ndarray | tuple[float, float, float]) – Colors of points. Should have shape (N, 2, 3) or be broadcastable to it.

• line_width (float) – Width of the lines.

• wxyz (tuple[float, float, float, float] | ndarray) – Quaternion rotation to parent frame from local frame (R_pl).

• position (tuple[float, float, float] | ndarray) – Translation to parent frame from local frame (t_pl).

• visible (bool) – Whether or not these line segments are initially visible.

Returns:

Handle for manipulating scene node.

Return type:

LineSegmentsHandle

add_spline_catmull_rom(name: str, positions: tuple[tuple[float, float, float], …] | ndarray, curve_type: Literal[‘centripetal’, ‘chordal’, ‘catmullrom’] = 'centripetal', tension: float = 0.5, closed: bool = False, line_width: float = 1, color: Tuple[int, int, int] | Tuple[float, float, float] | ndarray = (20, 20, 20), segments: int | None = None, wxyz: tuple[float, float, float, float] | ndarray = (1.0, 0.0, 0.0, 0.0), position: tuple[float, float, float] | ndarray = (0.0, 0.0, 0.0), visible: bool = True) → SplineCatmullRomHandle

Add a spline to the scene using Catmull-Rom interpolation.

This method creates a spline based on a set of positions and interpolates them using the Catmull-Rom algorithm. This can be used to create smooth curves.

If many splines are needed, it’ll be more efficient to batch them in add_line_segments().

Parameters:

• name (str) – A scene tree name. Names in the format of /parent/child can be used to define a kinematic tree.

• positions (tuple[tuple[float, float, float], …] | ndarray) – A tuple of 3D positions (x, y, z) defining the spline’s path.

• curve_type (Literal[‘centripetal’, ‘chordal’, ‘catmullrom’]) – Type of the curve (‘centripetal’, ‘chordal’, ‘catmullrom’).

• tension (float) – Tension of the curve. Affects the tightness of the curve.

• closed (bool) – Boolean indicating if the spline is closed (forms a loop).

• line_width (float) – Width of the spline line.

• color (Tuple[int, int, int] | Tuple[float, float, float] | ndarray) – Color of the spline as an RGB tuple.

• segments (int | None) – Number of segments to divide the spline into.

• wxyz (tuple[float, float, float, float] | ndarray) – Quaternion rotation to parent frame from local frame (R_pl).

• position (tuple[float, float, float] | ndarray) – Translation to parent frame from local frame (t_pl).

• visible (bool) – Whether or not this scene node is initially visible.

Returns:

Handle for manipulating scene node.

Return type:

SplineCatmullRomHandle

add_spline_cubic_bezier(name: str, positions: tuple[tuple[float, float, float], …] | ndarray, control_points: tuple[tuple[float, float, float], …] | ndarray, line_width: float = 1.0, color: Tuple[int, int, int] | Tuple[float, float, float] | ndarray = (20, 20, 20), segments: int | None = None, wxyz: tuple[float, float, float, float] | ndarray = (1.0, 0.0, 0.0, 0.0), position: tuple[float, float, float] | ndarray = (0.0, 0.0, 0.0), visible: bool = True) → SplineCubicBezierHandle

Add a spline to the scene using Cubic Bezier interpolation.

This method allows for the creation of a cubic Bezier spline based on given positions and control points. It is useful for creating complex, smooth, curving shapes.

If many splines are needed, it’ll be more efficient to batch them in add_line_segments().

Parameters:

• name (str) – A scene tree name. Names in the format of /parent/child can be used to define a kinematic tree.

• positions (tuple[tuple[float, float, float], …] | ndarray) – A tuple of 3D positions (x, y, z) defining the spline’s key points.

• control_points (tuple[tuple[float, float, float], …] | ndarray) – A tuple of control points for Bezier curve shaping.

• line_width (float) – Width of the spline line.

• color (Tuple[int, int, int] | Tuple[float, float, float] | ndarray) – Color of the spline as an RGB tuple.

• segments (int | None) – Number of segments to divide the spline into.

• wxyz (tuple[float, float, float, float] | ndarray) – Quaternion rotation to parent frame from local frame (R_pl).

• position (tuple[float, float, float] | ndarray) – Translation to parent frame from local frame (t_pl).

• visible (bool) – Whether or not this scene node is initially visible.

Returns:

Handle for manipulating scene node.

Return type:

SplineCubicBezierHandle

add_camera_frustum(name: str, fov: float, aspect: float, scale: float = 0.3, line_width: float = 2.0, color: Tuple[int, int, int] | Tuple[float, float, float] | ndarray = (20, 20, 20), image: ndarray | None = None, format: Literal[‘png’, ‘jpeg’] = 'jpeg', jpeg_quality: int | None = None, wxyz: tuple[float, float, float, float] | ndarray = (1.0, 0.0, 0.0, 0.0), position: tuple[float, float, float] | ndarray = (0.0, 0.0, 0.0), visible: bool = True, *_removed_kwargs) → CameraFrustumHandle

Add a camera frustum to the scene for visualization.

This method adds a frustum representation, typically used to visualize the field of view of a camera. It’s helpful for understanding the perspective and coverage of a camera in the 3D space.

Like all cameras in the viser Python API, frustums follow the OpenCV [+Z forward, +X right, +Y down] convention. fov is vertical in radians; aspect is width over height.

Parameters:

• name (str) – A scene tree name. Names in the format of /parent/child can be used to define a kinematic tree.

• fov (float) – Field of view of the camera (in radians).

• aspect (float) – Aspect ratio of the camera (width over height).

• scale (float) – Scale factor for the size of the frustum.

• line_width (float) – Width of the frustum lines, in screen space. Defaults to 2.0.

• color (Tuple[int, int, int] | Tuple[float, float, float] | ndarray) – Color of the frustum as an RGB tuple.

• image (ndarray | None) – Optional image to be displayed on the frustum.

• format (Literal[‘png’, ‘jpeg’]) – Format of the provided image (‘png’ or ‘jpeg’).

• jpeg_quality (int | None) – Quality of the jpeg image (if jpeg format is used).

• wxyz (tuple[float, float, float, float] | ndarray) – Quaternion rotation to parent frame from local frame (R_pl).

• position (tuple[float, float, float] | ndarray) – Translation to parent frame from local frame (t_pl).

• visible (bool) – Whether or not this scene node is initially visible.

Returns:

Handle for manipulating scene node.

Return type:

CameraFrustumHandle

add_frame(name: str, show_axes: bool = True, axes_length: float = 0.5, axes_radius: float = 0.025, origin_radius: float | None = None, origin_color: Tuple[int, int, int] | Tuple[float, float, float] | ndarray = (236, 236, 0), wxyz: tuple[float, float, float, float] | ndarray = (1.0, 0.0, 0.0, 0.0), position: tuple[float, float, float] | ndarray = (0.0, 0.0, 0.0), visible: bool = True) → FrameHandle

Add a coordinate frame to the scene.

This method is used for adding a visual representation of a coordinate frame, which can help in understanding the orientation and position of objects in 3D space.

For cases where we want to visualize many coordinate frames, like trajectories containing thousands or tens of thousands of frames, batching and calling add_batched_axes() may be a better choice than calling add_frame() in a loop.

Parameters:

• name (str) – A scene tree name. Names in the format of /parent/child can be used to define a kinematic tree.

• show_axes (bool) – Boolean to indicate whether to show the frame as a set of axes + origin sphere.

• axes_length (float) – Length of each axis.

• axes_radius (float) – Radius of each axis.

• origin_radius (float | None) – Radius of the origin sphere. If not set, defaults to 2 * axes_radius.

• wxyz (tuple[float, float, float, float] | ndarray) – Quaternion rotation to parent frame from local frame (R_pl).

• position (tuple[float, float, float] | ndarray) – Translation to parent frame from local frame (t_pl).

• visible (bool) – Whether or not this scene node is initially visible.

• origin_color (Tuple[int, int, int] | Tuple[float, float, float] | ndarray)

Returns:

Handle for manipulating scene node.

Return type:

FrameHandle

add_batched_axes(name: str, batched_wxyzs: tuple[tuple[float, float, float, float], …] | ndarray, batched_positions: tuple[tuple[float, float, float], …] | ndarray, axes_length: float = 0.5, axes_radius: float = 0.025, wxyz: tuple[float, float, float, float] | ndarray = (1.0, 0.0, 0.0, 0.0), position: tuple[float, float, float] | ndarray = (0.0, 0.0, 0.0), visible: bool = True) → BatchedAxesHandle

Visualize batched sets of coordinate frame axes.

The functionality of add_batched_axes() overlaps significantly with add_frame() when show_axes=True. The primary difference is that add_batched_axes() supports multiple axes via the wxyzs_batched (shape Nx4) and positions_batched (shape Nx3) arguments.

Axes that are batched and rendered via a single call to add_batched_axes() are instanced on the client; this will be much faster to render than add_frame() called in a loop.

Parameters:

• name (str) – A scene tree name. Names in the format of /parent/child can be used to define a kinematic tree.

• batched_wxyzs (tuple[tuple[float, float, float, float], …] | ndarray) – Float array of shape (N,4).

• batched_positions (tuple[tuple[float, float, float], …] | ndarray) – Float array of shape (N,3).

• axes_length (float) – Length of each axis.

• axes_radius (float) – Radius of each axis.

• wxyz (tuple[float, float, float, float] | ndarray) – Quaternion rotation to parent frame from local frame (R_pl). This will be applied to all axes.

• position (tuple[float, float, float] | ndarray) – Translation to parent frame from local frame (t_pl). This will be applied to all axes.

• visible (bool) – Whether or not this scene node is initially visible.

Returns:

Handle for manipulating scene node.

Return type:

BatchedAxesHandle

add_grid(name: str, width: float = 10.0, height: float = 10.0, width_segments: int = 10, height_segments: int = 10, plane: Literal[‘xz’, ‘xy’, ‘yx’, ‘yz’, ‘zx’, ‘zy’] = 'xy', cell_color: Tuple[int, int, int] | Tuple[float, float, float] | ndarray = (200, 200, 200), cell_thickness: float = 1.0, cell_size: float = 0.5, section_color: Tuple[int, int, int] | Tuple[float, float, float] | ndarray = (140, 140, 140), section_thickness: float = 1.0, section_size: float = 1.0, wxyz: tuple[float, float, float, float] | ndarray = (1.0, 0.0, 0.0, 0.0), position: tuple[float, float, float] | ndarray = (0.0, 0.0, 0.0), visible: bool = True) → GridHandle

Add a 2D grid to the scene.

This can be useful as a size, orientation, or ground plane reference.

Parameters:

• name (str) – Name of the grid.

• width (float) – Width of the grid.

• height (float) – Height of the grid.

• width_segments (int) – Number of segments along the width.

• height_segments (int) – Number of segments along the height.

• plane (Literal[‘xz’, ‘xy’, ‘yx’, ‘yz’, ‘zx’, ‘zy’]) – The plane in which the grid is oriented (e.g., ‘xy’, ‘yz’).

• cell_color (Tuple[int, int, int] | Tuple[float, float, float] | ndarray) – Color of the grid cells as an RGB tuple.

• cell_thickness (float) – Thickness of the grid lines.

• cell_size (float) – Size of each cell in the grid.

• section_color (Tuple[int, int, int] | Tuple[float, float, float] | ndarray) – Color of the grid sections as an RGB tuple.

• section_thickness (float) – Thickness of the section lines.

• section_size (float) – Size of each section in the grid.

• wxyz (tuple[float, float, float, float] | ndarray) – Quaternion rotation to parent frame from local frame (R_pl).

• position (tuple[float, float, float] | ndarray) – Translation to parent frame from local frame (t_pl).

• visible (bool) – Whether or not this scene node is initially visible.

Returns:

Handle for manipulating scene node.

Return type:

GridHandle

add_label(name: str, text: str, wxyz: tuple[float, float, float, float] | ndarray = (1.0, 0.0, 0.0, 0.0), position: tuple[float, float, float] | ndarray = (0.0, 0.0, 0.0), visible: bool = True) → LabelHandle

Add a 2D label to the scene.

This method creates a text label in the 3D scene, which can be used to annotate or provide information about specific points or objects.

Parameters:

• name (str) – Name of the label.

• text (str) – Text content of the label.

• wxyz (tuple[float, float, float, float] | ndarray) – Quaternion rotation to parent frame from local frame (R_pl).

• position (tuple[float, float, float] | ndarray) – Translation to parent frame from local frame (t_pl).

• visible (bool) – Whether or not this scene node is initially visible.

Returns:

Handle for manipulating scene node.

Return type:

LabelHandle

add_point_cloud(name: str, points: ndarray, colors: ndarray | tuple[float, float, float], point_size: float = 0.1, point_shape: Literal[‘square’, ‘diamond’, ‘circle’, ‘rounded’, ‘sparkle’] = 'square', wxyz: tuple[float, float, float, float] | ndarray = (1.0, 0.0, 0.0, 0.0), position: tuple[float, float, float] | ndarray = (0.0, 0.0, 0.0), visible: bool = True) → PointCloudHandle

Add a point cloud to the scene.

Parameters:

• name (str) – Name of scene node. Determines location in kinematic tree.

• points (ndarray) – Location of points. Should have shape (N, 3).

• colors (ndarray | tuple[float, float, float]) – Colors of points. Should have shape (N, 3) or (3,).

• point_size (float) – Size of each point.

• point_shape (Literal[‘square’, ‘diamond’, ‘circle’, ‘rounded’, ‘sparkle’]) – Shape to draw each point.

• wxyz (tuple[float, float, float, float] | ndarray) – Quaternion rotation to parent frame from local frame (R_pl).

• position (tuple[float, float, float] | ndarray) – Translation to parent frame from local frame (t_pl).

• visible (bool) – Whether or not this scene node is initially visible.

Returns:

Handle for manipulating scene node.

Return type:

PointCloudHandle

add_mesh_skinned(name: str, vertices: ndarray, faces: ndarray, bone_wxyzs: tuple[tuple[float, float, float, float], …] | ndarray, bone_positions: tuple[tuple[float, float, float], …] | ndarray, skin_weights: ndarray, color: Tuple[int, int, int] | Tuple[float, float, float] | ndarray = (90, 200, 255), wireframe: bool = False, opacity: float | None = None, material: Literal[‘standard’, ‘toon3’, ‘toon5’] = 'standard', flat_shading: bool = False, side: Literal[‘front’, ‘back’, ‘double’] = 'front', wxyz: Tuple[float, float, float, float] | ndarray = (1.0, 0.0, 0.0, 0.0), position: Tuple[float, float, float] | ndarray = (0.0, 0.0, 0.0), visible: bool = True) → MeshSkinnedHandle

Add a skinned mesh to the scene, which we can deform using a set of bone transformations.

Parameters:

• name (str) – A scene tree name. Names in the format of /parent/child can be used to define a kinematic tree.

• vertices (ndarray) – A numpy array of vertex positions. Should have shape (V, 3).

• faces (ndarray) – A numpy array of faces, where each face is represented by indices of vertices. Should have shape (F,)

• bone_wxyzs (tuple[tuple[float, float, float, float], …] | ndarray) – Nested tuple or array of initial bone orientations.

• bone_positions (tuple[tuple[float, float, float], …] | ndarray) – Nested tuple or array of initial bone positions.

• skin_weights (ndarray) – A numpy array of skin weights. Should have shape (V, B) where B is the number of bones. Only the top 4 bone weights for each vertex will be used.

• color (Tuple[int, int, int] | Tuple[float, float, float] | ndarray) – Color of the mesh as an RGB tuple.

• wireframe (bool) – Boolean indicating if the mesh should be rendered as a wireframe.

• opacity (float | None) – Opacity of the mesh. None means opaque.

• material (Literal[‘standard’, ‘toon3’, ‘toon5’]) – Material type of the mesh (‘standard’, ‘toon3’, ‘toon5’). This argument is ignored when wireframe=True.

• flat_shading (bool) – Whether to do flat shading. This argument is ignored when wireframe=True.

• side (Literal[‘front’, ‘back’, ‘double’]) – Side of the surface to render (‘front’, ‘back’, ‘double’).

• wxyz (Tuple[float, float, float, float] | ndarray) – Quaternion rotation to parent frame from local frame (R_pl).

• position (Tuple[float, float, float] | ndarray) – Translation from parent frame to local frame (t_pl).

• visible (bool) – Whether or not this mesh is initially visible.

Returns:

Handle for manipulating scene node.

Return type:

MeshSkinnedHandle

add_mesh_simple(name: str, vertices: ndarray, faces: ndarray, color: Tuple[int, int, int] | Tuple[float, float, float] | ndarray = (90, 200, 255), wireframe: bool = False, opacity: float | None = None, material: Literal[‘standard’, ‘toon3’, ‘toon5’] = 'standard', flat_shading: bool = False, side: Literal[‘front’, ‘back’, ‘double’] = 'front', wxyz: tuple[float, float, float, float] | ndarray = (1.0, 0.0, 0.0, 0.0), position: tuple[float, float, float] | ndarray = (0.0, 0.0, 0.0), visible: bool = True) → MeshHandle

Add a mesh to the scene.

Parameters:

• name (str) – A scene tree name. Names in the format of /parent/child can be used to define a kinematic tree.

• vertices (ndarray) – A numpy array of vertex positions. Should have shape (V, 3).

• faces (ndarray) – A numpy array of faces, where each face is represented by indices of vertices. Should have shape (F,)

• color (Tuple[int, int, int] | Tuple[float, float, float] | ndarray) – Color of the mesh as an RGB tuple.

• wireframe (bool) – Boolean indicating if the mesh should be rendered as a wireframe.

• opacity (float | None) – Opacity of the mesh. None means opaque.

• material (Literal[‘standard’, ‘toon3’, ‘toon5’]) – Material type of the mesh (‘standard’, ‘toon3’, ‘toon5’). This argument is ignored when wireframe=True.

• flat_shading (bool) – Whether to do flat shading. This argument is ignored when wireframe=True.

• side (Literal[‘front’, ‘back’, ‘double’]) – Side of the surface to render (‘front’, ‘back’, ‘double’).

• wxyz (tuple[float, float, float, float] | ndarray) – Quaternion rotation to parent frame from local frame (R_pl).

• position (tuple[float, float, float] | ndarray) – Translation from parent frame to local frame (t_pl).

• visible (bool) – Whether or not this mesh is initially visible.

Returns:

Handle for manipulating scene node.

Return type:

MeshHandle

add_mesh_trimesh(name: str, mesh: trimesh.Trimesh, scale: float = 1.0, wxyz: tuple[float, float, float, float] | np.ndarray = (1.0, 0.0, 0.0, 0.0), position: tuple[float, float, float] | np.ndarray = (0.0, 0.0, 0.0), visible: bool = True) → GlbHandle

Add a trimesh mesh to the scene. Internally calls self.add_glb().

Parameters:

• name (str) – A scene tree name. Names in the format of /parent/child can be used to define a kinematic tree.

• mesh (trimesh.Trimesh) – A trimesh mesh object.

• scale (float) – A scale for resizing the mesh.

• wxyz (tuple[float, float, float, float] | np.ndarray) – Quaternion rotation to parent frame from local frame (R_pl).

• position (tuple[float, float, float] | np.ndarray) – Translation to parent frame from local frame (t_pl).

• visible (bool) – Whether or not this scene node is initially visible.

Returns:

Handle for manipulating scene node.

Return type:

GlbHandle

add_gaussian_splats(name: str, centers: ndarray, covariances: ndarray, rgbs: ndarray, opacities: ndarray, wxyz: Tuple[float, float, float, float] | ndarray = (1.0, 0.0, 0.0, 0.0), position: Tuple[float, float, float] | ndarray = (0.0, 0.0, 0.0), visible: bool = True) → GaussianSplatHandle

Add a model to render using Gaussian Splatting.

Experimental. This feature is experimental and still under development. It may be changed or removed.

Parameters:

• name (str) – Scene node name.

• centers (ndarray) – Centers of Gaussians. (N, 3).

• covariances (ndarray) – Second moment for each Gaussian. (N, 3, 3).

• rgbs (ndarray) – Color for each Gaussian. (N, 3).

• opacities (ndarray) – Opacity for each Gaussian. (N, 1).

• wxyz (Tuple[float, float, float, float] | ndarray) – R_parent_local transformation.

• position (Tuple[float, float, float] | ndarray) – t_parent_local transformation.

• visible (bool) – Initial visibility of scene node.

Returns:

Scene node handle.

Return type:

GaussianSplatHandle

add_box(name: str, color: Tuple[int, int, int] | Tuple[float, float, float] | ndarray, dimensions: tuple[float, float, float] | ndarray = (1.0, 1.0, 1.0), wxyz: tuple[float, float, float, float] | ndarray = (1.0, 0.0, 0.0, 0.0), position: tuple[float, float, float] | ndarray = (0.0, 0.0, 0.0), visible: bool = True) → MeshHandle

Add a box to the scene.

Parameters:

• name (str) – A scene tree name. Names in the format of /parent/child can be used to define a kinematic tree.

• color (Tuple[int, int, int] | Tuple[float, float, float] | ndarray) – Color of the box as an RGB tuple.

• dimensions (tuple[float, float, float] | ndarray) – Dimensions of the box (x, y, z).

• wxyz (tuple[float, float, float, float] | ndarray) – Quaternion rotation to parent frame from local frame (R_pl).

• position (tuple[float, float, float] | ndarray) – Translation from parent frame to local frame (t_pl).

• visible (bool) – Whether or not this box is initially visible.

Returns:

Handle for manipulating scene node.

Return type:

MeshHandle

add_icosphere(name: str, radius: float, color: Tuple[int, int, int] | Tuple[float, float, float] | ndarray, subdivisions: int = 3, wxyz: tuple[float, float, float, float] | ndarray = (1.0, 0.0, 0.0, 0.0), position: tuple[float, float, float] | ndarray = (0.0, 0.0, 0.0), visible: bool = True) → MeshHandle

Add an icosphere to the scene.

Parameters:

• name (str) – A scene tree name. Names in the format of /parent/child can be used to define a kinematic tree.

• radius (float) – Radius of the icosphere.

• color (Tuple[int, int, int] | Tuple[float, float, float] | ndarray) – Color of the icosphere as an RGB tuple.

• subdivisions (int) – Number of subdivisions to use when creating the icosphere.

• wxyz (tuple[float, float, float, float] | ndarray) – Quaternion rotation to parent frame from local frame (R_pl).

• position (tuple[float, float, float] | ndarray) – Translation from parent frame to local frame (t_pl).

• visible (bool) – Whether or not this icosphere is initially visible.

Returns:

Handle for manipulating scene node.

Return type:

MeshHandle

set_background_image(image: ndarray, format: Literal[‘png’, ‘jpeg’] = 'jpeg', jpeg_quality: int | None = None, depth: ndarray | None = None) → None

Set a background image for the scene, optionally with depth compositing.

Parameters:

• image (ndarray) – The image to set as the background. Should have shape (H, W, 3).

• format (Literal[‘png’, ‘jpeg’]) – Format to transport and display the image using (‘png’ or ‘jpeg’).

• jpeg_quality (int | None) – Quality of the jpeg image (if jpeg format is used).

• depth (ndarray | None) – Optional depth image to use to composite background with scene elements.

Return type:

None

add_image(name: str, image: ndarray, render_width: float, render_height: float, format: Literal[‘png’, ‘jpeg’] = 'jpeg', jpeg_quality: int | None = None, wxyz: tuple[float, float, float, float] | ndarray = (1.0, 0.0, 0.0, 0.0), position: tuple[float, float, float] | ndarray = (0.0, 0.0, 0.0), visible: bool = True) → ImageHandle

Add a 2D image to the scene.

Parameters:

• name (str) – A scene tree name. Names in the format of /parent/child can be used to define a kinematic tree.

• image (ndarray) – A numpy array representing the image.

• render_width (float) – Width at which the image should be rendered in the scene.

• render_height (float) – Height at which the image should be rendered in the scene.

• format (Literal[‘png’, ‘jpeg’]) – Format to transport and display the image using (‘png’ or ‘jpeg’).

• jpeg_quality (int | None) – Quality of the jpeg image (if jpeg format is used).

• wxyz (tuple[float, float, float, float] | ndarray) – Quaternion rotation to parent frame from local frame (R_pl).

• position (tuple[float, float, float] | ndarray) – Translation from parent frame to local frame (t_pl).

• visible (bool) – Whether or not this image is initially visible.

Returns:

Handle for manipulating scene node.

Return type:

ImageHandle

add_transform_controls(name: str, scale: float = 1.0, line_width: float = 2.5, fixed: bool = False, auto_transform: bool = True, active_axes: tuple[bool, bool, bool] = (True, True, True), disable_axes: bool = False, disable_sliders: bool = False, disable_rotations: bool = False, translation_limits: tuple[tuple[float, float], tuple[float, float], tuple[float, float]] = ((-1000.0, 1000.0), (-1000.0, 1000.0), (-1000.0, 1000.0)), rotation_limits: tuple[tuple[float, float], tuple[float, float], tuple[float, float]] = ((-1000.0, 1000.0), (-1000.0, 1000.0), (-1000.0, 1000.0)), depth_test: bool = True, opacity: float = 1.0, wxyz: tuple[float, float, float, float] | ndarray = (1.0, 0.0, 0.0, 0.0), position: tuple[float, float, float] | ndarray = (0.0, 0.0, 0.0), visible: bool = True) → TransformControlsHandle

Add a transform gizmo for interacting with the scene.

This method adds a transform control (gizmo) to the scene, allowing for interactive manipulation of objects in terms of their position, rotation, and scale.

Parameters:

• name (str) – A scene tree name. Names in the format of /parent/child can be used to define a kinematic tree.

• scale (float) – Scale of the transform controls.

• line_width (float) – Width of the lines used in the gizmo.

• fixed (bool) – Boolean indicating if the gizmo should be fixed in position.

• auto_transform (bool) – Whether the transform should be applied automatically.

• active_axes (tuple[bool, bool, bool]) – tuple of booleans indicating active axes.

• disable_axes (bool) – Boolean to disable axes interaction.

• disable_sliders (bool) – Boolean to disable slider interaction.

• disable_rotations (bool) – Boolean to disable rotation interaction.

• translation_limits (tuple[tuple[float, float], tuple[float, float], tuple[float, float]]) – Limits for translation.

• rotation_limits (tuple[tuple[float, float], tuple[float, float], tuple[float, float]]) – Limits for rotation.

• depth_test (bool) – Boolean indicating if depth testing should be used when rendering.

• opacity (float) – Opacity of the gizmo.

• wxyz (tuple[float, float, float, float] | ndarray) – Quaternion rotation to parent frame from local frame (R_pl).

• position (tuple[float, float, float] | ndarray) – Translation from parent frame to local frame (t_pl).

• visible (bool) – Whether or not this gizmo is initially visible.

Returns:

Handle for manipulating (and reading state of) scene node.

Return type:

TransformControlsHandle

reset() → None

Reset the scene.

Return type:

None

on_pointer_event(event_type: Literal[‘click’, ‘rect-select’]) → Callable[[Callable[[ScenePointerEvent], None]], Callable[[ScenePointerEvent], None]]

Add a callback for scene pointer events.

Parameters:

event_type (Literal[‘click’, ‘rect-select’]) – event to listen to.

Return type:

Callable[[Callable[[ScenePointerEvent], None]], Callable[[ScenePointerEvent], None]]

on_pointer_callback_removed(func: Callable[[], NoneOrCoroutine]) → Callable[[], NoneOrCoroutine]

Add a callback to run automatically when the callback for a scene pointer event is removed. This will be triggered exactly once, either manually (via remove_pointer_callback()) or automatically (if the scene pointer event is overridden with another call to on_pointer_event()).

Parameters:

func (Callable[[], NoneOrCoroutine]) – Callback for when scene pointer events are removed.

Return type:

Callable[[], NoneOrCoroutine]

remove_pointer_callback() → None

Remove the currently attached scene pointer event. This will trigger any callback attached to .on_scene_pointer_removed().

Return type:

None

add_3d_gui_container(name: str, wxyz: tuple[float, float, float, float] | ndarray = (1.0, 0.0, 0.0, 0.0), position: tuple[float, float, float] | ndarray = (0.0, 0.0, 0.0), visible: bool = True) → Gui3dContainerHandle

Add a 3D gui container to the scene. The returned container handle can be used as a context to place GUI elements into the 3D scene.

Parameters:

• name (str) – A scene tree name. Names in the format of /parent/child can be used to define a kinematic tree.

• wxyz (tuple[float, float, float, float] | ndarray) – Quaternion rotation to parent frame from local frame (R_pl).

• position (tuple[float, float, float] | ndarray) – Translation to parent frame from local frame (t_pl).

• visible (bool) – Whether or not this scene node is initially visible.

Returns:

Handle for manipulating scene node. Can be used as a context to place GUI elements inside of the container.

Return type:

Gui3dContainerHandle

remove_by_name(name: str) → None

Helper to call .remove() on the scene node handles of the name element or any of its children.

Parameters:

name (str)

Return type:

None