Scene Handles¶

A handle is created for each object that is added to the scene. These can be used to read and set state, as well as detect clicks.

When a scene node is added to a server (for example, via viser.ViserServer.add_frame()), state is synchronized between all connected clients. When a scene node is added to a client (for example, via viser.ClientHandle.add_frame()), state is local to a specific client.

The most common attributes to read and write here are viser.SceneNodeHandle.wxyz and viser.SceneNodeHandle.position. Each node type also has type-specific attributes that we can read and write. Many of these are lower-level than their equivalent arguments in factory methods like viser.ViserServer.add_frame() or viser.ViserServer.add_image().

class viser.AmbientLightHandle[source]¶

Handle for ambient lights.

property name: str¶: Read-only name of the scene node.

property position: ndarray[tuple[int, ...], dtype[float32]]¶: Position of the scene node. This is equivalent to the t in p_parent = [R | t] p_local. Synchronized to clients automatically when assigned.

remove() → None¶

Remove the node from the scene.

Return type:: None

property visible: bool¶: Whether the scene node is visible or not. Synchronized to clients automatically when assigned.

property wxyz: ndarray[tuple[int, ...], dtype[float32]]¶: Orientation of the scene node. This is the quaternion representation of the R in p_parent = [R | t] p_local. Synchronized to clients automatically when assigned.

color: Tuple[int, int, int]¶: Color of the ambient light.

intensity: float¶: Intensity of the ambient light.

class viser.BatchedAxesHandle[source]¶

Handle for batched coordinate frames.

property name: str¶: Read-only name of the scene node.

on_click(func: Callable[[SceneNodePointerEvent[Self]], NoneOrCoroutine]) → Callable[[SceneNodePointerEvent[Self]], NoneOrCoroutine]¶

Attach a callback for when a scene node is clicked.

The callback can be either a standard function or an async function: - Standard functions (def) will be executed in a threadpool. - Async functions (async def) will be executed in the event loop.

Using async functions can be useful for reducing race conditions.

Parameters:

self (Self)
func (Callable[[SceneNodePointerEvent[Self]], NoneOrCoroutine])

Return type:

Callable[[SceneNodePointerEvent[Self]], NoneOrCoroutine]

property position: ndarray[tuple[int, ...], dtype[float32]]¶: Position of the scene node. This is equivalent to the t in p_parent = [R | t] p_local. Synchronized to clients automatically when assigned.

remove() → None¶

Remove the node from the scene.

Return type:: None

remove_click_callback(callback: Literal['all'] | Callable = 'all') → None¶

Remove click callbacks from scene node.

Parameters:: callback (Literal['all'] | ~typing.Callable) – Either “all” to remove all callbacks, or a specific callback function to remove.
Return type:: None

property visible: bool¶: Whether the scene node is visible or not. Synchronized to clients automatically when assigned.

property wxyz: ndarray[tuple[int, ...], dtype[float32]]¶: Orientation of the scene node. This is the quaternion representation of the R in p_parent = [R | t] p_local. Synchronized to clients automatically when assigned.

batched_wxyzs: npt.NDArray[np.float32]¶: Float array of shape (N,4) representing quaternion rotations.

batched_positions: npt.NDArray[np.float32]¶: Float array of shape (N,3) representing positions. Synchronized

batched_scales: npt.NDArray[np.float32] | None¶: Float array of shape (N,) or (N,3) representing uniform or per-axis (XYZ) scales.

axes_length: float¶: Length of each axis.

axes_radius: float¶: Radius of each axis.

class viser.BatchedGlbHandle[source]¶

Handle for batched GLB objects.

property name: str¶: Read-only name of the scene node.

on_click(func: Callable[[SceneNodePointerEvent[Self]], NoneOrCoroutine]) → Callable[[SceneNodePointerEvent[Self]], NoneOrCoroutine]¶

Attach a callback for when a scene node is clicked.

The callback can be either a standard function or an async function: - Standard functions (def) will be executed in a threadpool. - Async functions (async def) will be executed in the event loop.

Using async functions can be useful for reducing race conditions.

Parameters:

self (Self)
func (Callable[[SceneNodePointerEvent[Self]], NoneOrCoroutine])

Return type:

Callable[[SceneNodePointerEvent[Self]], NoneOrCoroutine]

property position: ndarray[tuple[int, ...], dtype[float32]]¶: Position of the scene node. This is equivalent to the t in p_parent = [R | t] p_local. Synchronized to clients automatically when assigned.

remove() → None¶

Remove the node from the scene.

Return type:: None

remove_click_callback(callback: Literal['all'] | Callable = 'all') → None¶

Remove click callbacks from scene node.

Parameters:: callback (Literal['all'] | ~typing.Callable) – Either “all” to remove all callbacks, or a specific callback function to remove.
Return type:: None

property visible: bool¶: Whether the scene node is visible or not. Synchronized to clients automatically when assigned.

property wxyz: ndarray[tuple[int, ...], dtype[float32]]¶: Orientation of the scene node. This is the quaternion representation of the R in p_parent = [R | t] p_local. Synchronized to clients automatically when assigned.

glb_data: bytes¶: A binary payload containing the GLB data.

cast_shadow: bool¶: Whether or not to cast shadows.

receive_shadow: bool¶: Whether or not to receive shadows.

batched_wxyzs: npt.NDArray[np.float32]¶: Float array of shape (N, 4) representing quaternion rotations.

batched_positions: npt.NDArray[np.float32]¶: Float array of shape (N, 3) representing positions.

batched_scales: npt.NDArray[np.float32] | None¶: Float array of shape (N,) or (N,3) representing uniform or per-axis (XYZ) scales.

lod: Literal['auto', 'off'] | Tuple[Tuple[float, float], ...]¶: LOD settings. Either “auto”, “off”, or a tuple of (distance, ratio) pairs.

class viser.BatchedMeshHandle[source]¶

Handle for batched mesh objects.

property name: str¶: Read-only name of the scene node.

on_click(func: Callable[[SceneNodePointerEvent[Self]], NoneOrCoroutine]) → Callable[[SceneNodePointerEvent[Self]], NoneOrCoroutine]¶

Attach a callback for when a scene node is clicked.

The callback can be either a standard function or an async function: - Standard functions (def) will be executed in a threadpool. - Async functions (async def) will be executed in the event loop.

Using async functions can be useful for reducing race conditions.

Parameters:

self (Self)
func (Callable[[SceneNodePointerEvent[Self]], NoneOrCoroutine])

Return type:

Callable[[SceneNodePointerEvent[Self]], NoneOrCoroutine]

property position: ndarray[tuple[int, ...], dtype[float32]]¶: Position of the scene node. This is equivalent to the t in p_parent = [R | t] p_local. Synchronized to clients automatically when assigned.

remove() → None¶

Remove the node from the scene.

Return type:: None

remove_click_callback(callback: Literal['all'] | Callable = 'all') → None¶

Remove click callbacks from scene node.

Parameters:: callback (Literal['all'] | ~typing.Callable) – Either “all” to remove all callbacks, or a specific callback function to remove.
Return type:: None

property visible: bool¶: Whether the scene node is visible or not. Synchronized to clients automatically when assigned.

property wxyz: ndarray[tuple[int, ...], dtype[float32]]¶: Orientation of the scene node. This is the quaternion representation of the R in p_parent = [R | t] p_local. Synchronized to clients automatically when assigned.

vertices: npt.NDArray[np.float32]¶: A numpy array of vertex positions. Should have shape (V, 3).

faces: npt.NDArray[np.uint32]¶: A numpy array of faces, where each face is represented by indices of vertices. Should have shape (F, 3).

batched_colors: npt.NDArray[np.uint8]¶: A numpy array of colors, where each color is represented by RGB integers. Should have shape (N, 3) or (3,).

wireframe: bool¶: Boolean indicating if the mesh should be rendered as a wireframe.

opacity: float | None¶: Opacity of the mesh. None means opaque.

flat_shading: bool¶: Whether to do flat shading.

side: Literal['front', 'back', 'double']¶: Side of the surface to render.

material: Literal['standard', 'toon3', 'toon5']¶: Material type of the mesh.

cast_shadow: bool¶: Whether or not to cast shadows.

receive_shadow: bool¶: Whether or not to receive shadows.

batched_wxyzs: npt.NDArray[np.float32]¶: Float array of shape (N, 4) representing quaternion rotations.

batched_positions: npt.NDArray[np.float32]¶: Float array of shape (N, 3) representing positions.

batched_scales: npt.NDArray[np.float32] | None¶: Float array of shape (N,) or (N,3) representing uniform or per-axis (XYZ) scales.

lod: Literal['auto', 'off'] | Tuple[Tuple[float, float], ...]¶: LOD settings. Either “auto”, “off”, or a tuple of (distance, ratio) pairs.

class viser.BoxHandle[source]¶

Handle for box objects.

property name: str¶: Read-only name of the scene node.

on_click(func: Callable[[SceneNodePointerEvent[Self]], NoneOrCoroutine]) → Callable[[SceneNodePointerEvent[Self]], NoneOrCoroutine]¶

Attach a callback for when a scene node is clicked.

The callback can be either a standard function or an async function: - Standard functions (def) will be executed in a threadpool. - Async functions (async def) will be executed in the event loop.

Using async functions can be useful for reducing race conditions.

Parameters:

self (Self)
func (Callable[[SceneNodePointerEvent[Self]], NoneOrCoroutine])

Return type:

Callable[[SceneNodePointerEvent[Self]], NoneOrCoroutine]

property position: ndarray[tuple[int, ...], dtype[float32]]¶: Position of the scene node. This is equivalent to the t in p_parent = [R | t] p_local. Synchronized to clients automatically when assigned.

remove() → None¶

Remove the node from the scene.

Return type:: None

remove_click_callback(callback: Literal['all'] | Callable = 'all') → None¶

Remove click callbacks from scene node.

Parameters:: callback (Literal['all'] | ~typing.Callable) – Either “all” to remove all callbacks, or a specific callback function to remove.
Return type:: None

property visible: bool¶: Whether the scene node is visible or not. Synchronized to clients automatically when assigned.

property wxyz: ndarray[tuple[int, ...], dtype[float32]]¶: Orientation of the scene node. This is the quaternion representation of the R in p_parent = [R | t] p_local. Synchronized to clients automatically when assigned.

dimensions: Tuple[float, float, float]¶: Dimensions of the box (x, y, z).

color: Tuple[int, int, int]¶: Color of the box as RGB integers.

wireframe: bool¶: Boolean indicating if the box should be rendered as a wireframe.

opacity: float | None¶: Opacity of the box. None means opaque.

flat_shading: bool¶: Whether to do flat shading.

side: Literal['front', 'back', 'double']¶: Side of the surface to render.

material: Literal['standard', 'toon3', 'toon5']¶: Material type of the box.

cast_shadow: bool¶: Whether or not to cast shadows.

receive_shadow: bool | float¶: Whether to receive shadows. If True, receives shadows normally. If False, no shadows. If a float (0-1), shadows are rendered with a fixed opacity regardless of lighting conditions.

class viser.CameraFrustumHandle[source]¶

Handle for camera frustums.

property image: ndarray | None¶: Current content of the image. Synchronized automatically when assigned.

property format: Literal['auto', 'jpeg', 'png']¶: Image format. ‘auto’ will use PNG for RGBA images and JPEG for RGB.

compute_canonical_frustum_size() → tuple[float, float, float][source]¶

Compute the X, Y, and Z dimensions of the frustum if it had .scale=1.0. These dimensions will change whenever .fov or .aspect are changed.

To set the distance between a frustum’s origin and image plane to 1, we can run:

frustum.scale = 1.0 / frustum.compute_canonical_frustum_size()[2]

.scale is a unitless value that scales the X/Y/Z dimensions linearly. It aims to preserve the visual volume of the frustum regardless of the aspect ratio or FOV. This method allows more precise computation and control of the frustum’s dimensions.

Return type:: tuple[float, float, float]

property name: str¶: Read-only name of the scene node.

on_click(func: Callable[[SceneNodePointerEvent[Self]], NoneOrCoroutine]) → Callable[[SceneNodePointerEvent[Self]], NoneOrCoroutine]¶

Attach a callback for when a scene node is clicked.

The callback can be either a standard function or an async function: - Standard functions (def) will be executed in a threadpool. - Async functions (async def) will be executed in the event loop.

Using async functions can be useful for reducing race conditions.

Parameters:

self (Self)
func (Callable[[SceneNodePointerEvent[Self]], NoneOrCoroutine])

Return type:

Callable[[SceneNodePointerEvent[Self]], NoneOrCoroutine]

property position: ndarray[tuple[int, ...], dtype[float32]]¶: Position of the scene node. This is equivalent to the t in p_parent = [R | t] p_local. Synchronized to clients automatically when assigned.

remove() → None¶

Remove the node from the scene.

Return type:: None

remove_click_callback(callback: Literal['all'] | Callable = 'all') → None¶

Remove click callbacks from scene node.

Parameters:: callback (Literal['all'] | ~typing.Callable) – Either “all” to remove all callbacks, or a specific callback function to remove.
Return type:: None

variant: Literal['wireframe', 'filled'] = 'wireframe'¶: Variant of the frustum visualization. ‘wireframe’ shows lines only, ‘filled’ adds semi-transparent faces.

property visible: bool¶: Whether the scene node is visible or not. Synchronized to clients automatically when assigned.

property wxyz: ndarray[tuple[int, ...], dtype[float32]]¶: Orientation of the scene node. This is the quaternion representation of the R in p_parent = [R | t] p_local. Synchronized to clients automatically when assigned.

fov: float¶: Field of view of the camera (in radians).

aspect: float¶: Aspect ratio of the camera (width over height). Synchronized

scale: float¶: Scale factor for the size of the frustum.

line_width: float¶: Width of the frustum lines.

color: Tuple[int, int, int]¶: Color of the frustum as RGB integers.

cast_shadow: bool¶: Whether or not to cast shadows.

receive_shadow: bool | float¶: Whether to receive shadows. If True, receives shadows normally. If False, no shadows. If a float (0-1), shadows are rendered with a fixed opacity regardless of lighting conditions.

class viser.DirectionalLightHandle[source]¶

Handle for directional lights.

property name: str¶: Read-only name of the scene node.

property position: ndarray[tuple[int, ...], dtype[float32]]¶: Position of the scene node. This is equivalent to the t in p_parent = [R | t] p_local. Synchronized to clients automatically when assigned.

remove() → None¶

Remove the node from the scene.

Return type:: None

property visible: bool¶: Whether the scene node is visible or not. Synchronized to clients automatically when assigned.

property wxyz: ndarray[tuple[int, ...], dtype[float32]]¶: Orientation of the scene node. This is the quaternion representation of the R in p_parent = [R | t] p_local. Synchronized to clients automatically when assigned.

color: Tuple[int, int, int]¶: Color of the directional light.

intensity: float¶: Intensity of the directional light.

cast_shadow: bool¶: If set to true mesh will cast a shadow.

class viser.FrameHandle[source]¶

Handle for coordinate frames.

property name: str¶: Read-only name of the scene node.

on_click(func: Callable[[SceneNodePointerEvent[Self]], NoneOrCoroutine]) → Callable[[SceneNodePointerEvent[Self]], NoneOrCoroutine]¶

Attach a callback for when a scene node is clicked.

The callback can be either a standard function or an async function: - Standard functions (def) will be executed in a threadpool. - Async functions (async def) will be executed in the event loop.

Using async functions can be useful for reducing race conditions.

Parameters:

self (Self)
func (Callable[[SceneNodePointerEvent[Self]], NoneOrCoroutine])

Return type:

Callable[[SceneNodePointerEvent[Self]], NoneOrCoroutine]

property position: ndarray[tuple[int, ...], dtype[float32]]¶: Position of the scene node. This is equivalent to the t in p_parent = [R | t] p_local. Synchronized to clients automatically when assigned.

remove() → None¶

Remove the node from the scene.

Return type:: None

remove_click_callback(callback: Literal['all'] | Callable = 'all') → None¶

Remove click callbacks from scene node.

Parameters:: callback (Literal['all'] | ~typing.Callable) – Either “all” to remove all callbacks, or a specific callback function to remove.
Return type:: None

property visible: bool¶: Whether the scene node is visible or not. Synchronized to clients automatically when assigned.

property wxyz: ndarray[tuple[int, ...], dtype[float32]]¶: Orientation of the scene node. This is the quaternion representation of the R in p_parent = [R | t] p_local. Synchronized to clients automatically when assigned.

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¶: Radius of the origin sphere.

origin_color: Tuple[int, int, int]¶: Color of the origin sphere as RGB integers.

class viser.GaussianSplatHandle[source]¶

Handle for Gaussian splatting objects.

Work-in-progress. Gaussian rendering is still under development.

property name: str¶: Read-only name of the scene node.

on_click(func: Callable[[SceneNodePointerEvent[Self]], NoneOrCoroutine]) → Callable[[SceneNodePointerEvent[Self]], NoneOrCoroutine]¶

Attach a callback for when a scene node is clicked.

The callback can be either a standard function or an async function: - Standard functions (def) will be executed in a threadpool. - Async functions (async def) will be executed in the event loop.

Using async functions can be useful for reducing race conditions.

Parameters:

self (Self)
func (Callable[[SceneNodePointerEvent[Self]], NoneOrCoroutine])

Return type:

Callable[[SceneNodePointerEvent[Self]], NoneOrCoroutine]

property position: ndarray[tuple[int, ...], dtype[float32]]¶: Position of the scene node. This is equivalent to the t in p_parent = [R | t] p_local. Synchronized to clients automatically when assigned.

remove() → None¶

Remove the node from the scene.

Return type:: None

remove_click_callback(callback: Literal['all'] | Callable = 'all') → None¶

Remove click callbacks from scene node.

Parameters:: callback (Literal['all'] | ~typing.Callable) – Either “all” to remove all callbacks, or a specific callback function to remove.
Return type:: None

property visible: bool¶: Whether the scene node is visible or not. Synchronized to clients automatically when assigned.

property wxyz: ndarray[tuple[int, ...], dtype[float32]]¶: Orientation of the scene node. This is the quaternion representation of the R in p_parent = [R | t] p_local. Synchronized to clients automatically when assigned.

buffer: npt.NDArray[np.uint32]¶

Our buffer will contain: - x as f32 - y as f32 - z as f32 - (unused) - cov1 (f16), cov2 (f16) - cov3 (f16), cov4 (f16) - cov5 (f16), cov6 (f16) - rgba (int32)

Where cov1-6 are the upper-triangular terms of covariance matrices.

class viser.GlbHandle[source]¶

Handle for GLB objects.

property name: str¶: Read-only name of the scene node.

on_click(func: Callable[[SceneNodePointerEvent[Self]], NoneOrCoroutine]) → Callable[[SceneNodePointerEvent[Self]], NoneOrCoroutine]¶

Attach a callback for when a scene node is clicked.

The callback can be either a standard function or an async function: - Standard functions (def) will be executed in a threadpool. - Async functions (async def) will be executed in the event loop.

Using async functions can be useful for reducing race conditions.

Parameters:

self (Self)
func (Callable[[SceneNodePointerEvent[Self]], NoneOrCoroutine])

Return type:

Callable[[SceneNodePointerEvent[Self]], NoneOrCoroutine]

property position: ndarray[tuple[int, ...], dtype[float32]]¶: Position of the scene node. This is equivalent to the t in p_parent = [R | t] p_local. Synchronized to clients automatically when assigned.

remove() → None¶

Remove the node from the scene.

Return type:: None

remove_click_callback(callback: Literal['all'] | Callable = 'all') → None¶

Remove click callbacks from scene node.

Parameters:: callback (Literal['all'] | ~typing.Callable) – Either “all” to remove all callbacks, or a specific callback function to remove.
Return type:: None

property visible: bool¶: Whether the scene node is visible or not. Synchronized to clients automatically when assigned.

property wxyz: ndarray[tuple[int, ...], dtype[float32]]¶: Orientation of the scene node. This is the quaternion representation of the R in p_parent = [R | t] p_local. Synchronized to clients automatically when assigned.

glb_data: bytes¶: A binary payload containing the GLB data.

scale: float¶: A scale for resizing the GLB asset.

cast_shadow: bool¶: Whether or not to cast shadows.

receive_shadow: bool | float¶: Whether to receive shadows. If True, receives shadows normally. If False, no shadows. If a float (0-1), shadows are rendered with a fixed opacity regardless of lighting conditions.

class viser.GridHandle[source]¶

Handle for grid objects.

property name: str¶: Read-only name of the scene node.

property position: ndarray[tuple[int, ...], dtype[float32]]¶: Position of the scene node. This is equivalent to the t in p_parent = [R | t] p_local. Synchronized to clients automatically when assigned.

remove() → None¶

Remove the node from the scene.

Return type:: None

property visible: bool¶: Whether the scene node is visible or not. Synchronized to clients automatically when assigned.

property wxyz: ndarray[tuple[int, ...], dtype[float32]]¶: Orientation of the scene node. This is the quaternion representation of the R in p_parent = [R | t] p_local. Synchronized to clients automatically when assigned.

width: float¶: Width of the grid.

height: float¶: Height of the grid.

plane: Literal['xz', 'xy', 'yx', 'yz', 'zx', 'zy']¶: The plane in which the grid is oriented.

cell_color: Tuple[int, int, int]¶: Color of the grid cells as RGB integers.

cell_thickness: float¶: Thickness of the grid lines.

cell_size: float¶: Size of each cell in the grid.

section_color: Tuple[int, int, int]¶: Color of the grid sections as RGB integers.

section_thickness: float¶: Thickness of the section lines.

section_size: float¶: Size of each section in the grid.

infinite_grid: bool¶: Whether the grid should be infinite. If True, the width and height are ignored.

fade_distance: float¶: Distance at which the grid fades out.

fade_strength: float¶: Strength of the fade effect.

fade_from: Literal['camera', 'origin']¶: Whether the grid should fade based on distance from the camera or the origin.

shadow_opacity: float¶: If true, shadows are casted onto the grid plane. Synchronized

class viser.Gui3dContainerHandle[source]¶

Use as a context to place GUI elements into a 3D GUI container.

property name: str¶: Read-only name of the scene node.

property position: ndarray[tuple[int, ...], dtype[float32]]¶: Position of the scene node. This is equivalent to the t in p_parent = [R | t] p_local. Synchronized to clients automatically when assigned.

property visible: bool¶: Whether the scene node is visible or not. Synchronized to clients automatically when assigned.

property wxyz: ndarray[tuple[int, ...], dtype[float32]]¶: Orientation of the scene node. This is the quaternion representation of the R in p_parent = [R | t] p_local. Synchronized to clients automatically when assigned.

order: float¶: Order value for arranging GUI elements.

container_uuid: str¶: Identifier for the container.

remove() → None[source]¶

Permanently remove this GUI container from the visualizer.

Return type:: None

class viser.HemisphereLightHandle[source]¶

Handle for hemisphere lights.

property name: str¶: Read-only name of the scene node.

property position: ndarray[tuple[int, ...], dtype[float32]]¶: Position of the scene node. This is equivalent to the t in p_parent = [R | t] p_local. Synchronized to clients automatically when assigned.

remove() → None¶

Remove the node from the scene.

Return type:: None

property visible: bool¶: Whether the scene node is visible or not. Synchronized to clients automatically when assigned.

property wxyz: ndarray[tuple[int, ...], dtype[float32]]¶: Orientation of the scene node. This is the quaternion representation of the R in p_parent = [R | t] p_local. Synchronized to clients automatically when assigned.

sky_color: Tuple[int, int, int]¶: Sky color of the hemisphere light.

ground_color: Tuple[int, int, int]¶: Ground color of the hemisphere light.

intensity: float¶: Intensity of the hemisphere light.

class viser.IcosphereHandle[source]¶

Handle for icosphere objects.

property name: str¶: Read-only name of the scene node.

on_click(func: Callable[[SceneNodePointerEvent[Self]], NoneOrCoroutine]) → Callable[[SceneNodePointerEvent[Self]], NoneOrCoroutine]¶

Attach a callback for when a scene node is clicked.

The callback can be either a standard function or an async function: - Standard functions (def) will be executed in a threadpool. - Async functions (async def) will be executed in the event loop.

Using async functions can be useful for reducing race conditions.

Parameters:

self (Self)
func (Callable[[SceneNodePointerEvent[Self]], NoneOrCoroutine])

Return type:

Callable[[SceneNodePointerEvent[Self]], NoneOrCoroutine]

property position: ndarray[tuple[int, ...], dtype[float32]]¶: Position of the scene node. This is equivalent to the t in p_parent = [R | t] p_local. Synchronized to clients automatically when assigned.

remove() → None¶

Remove the node from the scene.

Return type:: None

remove_click_callback(callback: Literal['all'] | Callable = 'all') → None¶

Remove click callbacks from scene node.

Parameters:: callback (Literal['all'] | ~typing.Callable) – Either “all” to remove all callbacks, or a specific callback function to remove.
Return type:: None

property visible: bool¶: Whether the scene node is visible or not. Synchronized to clients automatically when assigned.

property wxyz: ndarray[tuple[int, ...], dtype[float32]]¶: Orientation of the scene node. This is the quaternion representation of the R in p_parent = [R | t] p_local. Synchronized to clients automatically when assigned.

radius: float¶: Radius of the icosphere.

subdivisions: int¶: Number of subdivisions to use when creating the icosphere. Synchronized

color: Tuple[int, int, int]¶: Color of the icosphere as RGB integers.

wireframe: bool¶: Boolean indicating if the icosphere should be rendered as a wireframe.

opacity: float | None¶: Opacity of the icosphere. None means opaque.

flat_shading: bool¶: Whether to do flat shading.

side: Literal['front', 'back', 'double']¶: Side of the surface to render.

material: Literal['standard', 'toon3', 'toon5']¶: Material type of the icosphere.

cast_shadow: bool¶: Whether or not to cast shadows.

receive_shadow: bool | float¶: Whether to receive shadows. If True, receives shadows normally. If False, no shadows. If a float (0-1), shadows are rendered with a fixed opacity regardless of lighting conditions.

class viser.ImageHandle[source]¶

Handle for 2D images, rendered in 3D.

property image: ndarray¶: Current content of the image. Synchronized automatically when assigned.

property name: str¶: Read-only name of the scene node.

on_click(func: Callable[[SceneNodePointerEvent[Self]], NoneOrCoroutine]) → Callable[[SceneNodePointerEvent[Self]], NoneOrCoroutine]¶

Attach a callback for when a scene node is clicked.

The callback can be either a standard function or an async function: - Standard functions (def) will be executed in a threadpool. - Async functions (async def) will be executed in the event loop.

Using async functions can be useful for reducing race conditions.

Parameters:

self (Self)
func (Callable[[SceneNodePointerEvent[Self]], NoneOrCoroutine])

Return type:

Callable[[SceneNodePointerEvent[Self]], NoneOrCoroutine]

property position: ndarray[tuple[int, ...], dtype[float32]]¶: Position of the scene node. This is equivalent to the t in p_parent = [R | t] p_local. Synchronized to clients automatically when assigned.

remove() → None¶

Remove the node from the scene.

Return type:: None

remove_click_callback(callback: Literal['all'] | Callable = 'all') → None¶

Remove click callbacks from scene node.

Parameters:: callback (Literal['all'] | ~typing.Callable) – Either “all” to remove all callbacks, or a specific callback function to remove.
Return type:: None

property visible: bool¶: Whether the scene node is visible or not. Synchronized to clients automatically when assigned.

property wxyz: ndarray[tuple[int, ...], dtype[float32]]¶: Orientation of the scene node. This is the quaternion representation of the R in p_parent = [R | t] p_local. Synchronized to clients automatically when assigned.

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.

cast_shadow: bool¶: Whether or not to cast shadows.

receive_shadow: bool | float¶: Whether to receive shadows. If True, receives shadows normally. If False, no shadows. If a float (0-1), shadows are rendered with a fixed opacity regardless of lighting conditions.

property format: Literal['auto', 'jpeg', 'png']¶: Image format. ‘auto’ will use PNG for RGBA images and JPEG for RGB.

class viser.LabelHandle[source]¶

Handle for 2D label objects. Does not support click events.

property name: str¶: Read-only name of the scene node.

property position: ndarray[tuple[int, ...], dtype[float32]]¶: Position of the scene node. This is equivalent to the t in p_parent = [R | t] p_local. Synchronized to clients automatically when assigned.

remove() → None¶

Remove the node from the scene.

Return type:: None

property visible: bool¶: Whether the scene node is visible or not. Synchronized to clients automatically when assigned.

property wxyz: ndarray[tuple[int, ...], dtype[float32]]¶: Orientation of the scene node. This is the quaternion representation of the R in p_parent = [R | t] p_local. Synchronized to clients automatically when assigned.

text: str¶: Text content of the label.

class viser.LineSegmentsHandle[source]¶

Handle for line segments objects.

property name: str¶: Read-only name of the scene node.

property position: ndarray[tuple[int, ...], dtype[float32]]¶: Position of the scene node. This is equivalent to the t in p_parent = [R | t] p_local. Synchronized to clients automatically when assigned.

remove() → None¶

Remove the node from the scene.

Return type:: None

property visible: bool¶: Whether the scene node is visible or not. Synchronized to clients automatically when assigned.

property wxyz: ndarray[tuple[int, ...], dtype[float32]]¶: Orientation of the scene node. This is the quaternion representation of the R in p_parent = [R | t] p_local. Synchronized to clients automatically when assigned.

points: npt.NDArray[np.float32]¶: A numpy array of shape (N, 2, 3) containing a batched set of line segments.

line_width: float¶: Width of the lines.

colors: npt.NDArray[np.uint8]¶: Numpy array of shape (N, 2, 3) containing a color for each point.

class viser.MeshHandle[source]¶

Handle for mesh objects.

property name: str¶: Read-only name of the scene node.

on_click(func: Callable[[SceneNodePointerEvent[Self]], NoneOrCoroutine]) → Callable[[SceneNodePointerEvent[Self]], NoneOrCoroutine]¶

Attach a callback for when a scene node is clicked.

The callback can be either a standard function or an async function: - Standard functions (def) will be executed in a threadpool. - Async functions (async def) will be executed in the event loop.

Using async functions can be useful for reducing race conditions.

Parameters:

self (Self)
func (Callable[[SceneNodePointerEvent[Self]], NoneOrCoroutine])

Return type:

Callable[[SceneNodePointerEvent[Self]], NoneOrCoroutine]

property position: ndarray[tuple[int, ...], dtype[float32]]¶: Position of the scene node. This is equivalent to the t in p_parent = [R | t] p_local. Synchronized to clients automatically when assigned.

remove() → None¶

Remove the node from the scene.

Return type:: None

remove_click_callback(callback: Literal['all'] | Callable = 'all') → None¶

Remove click callbacks from scene node.

Parameters:: callback (Literal['all'] | ~typing.Callable) – Either “all” to remove all callbacks, or a specific callback function to remove.
Return type:: None

property visible: bool¶: Whether the scene node is visible or not. Synchronized to clients automatically when assigned.

property wxyz: ndarray[tuple[int, ...], dtype[float32]]¶: Orientation of the scene node. This is the quaternion representation of the R in p_parent = [R | t] p_local. Synchronized to clients automatically when assigned.

vertices: npt.NDArray[np.float32]¶: A numpy array of vertex positions. Should have shape (V, 3).

faces: npt.NDArray[np.uint32]¶: A numpy array of faces, where each face is represented by indices of vertices. Should have shape (F, 3).

color: Tuple[int, int, int]¶: Color of the mesh as RGB integers.

wireframe: bool¶: Boolean indicating if the mesh should be rendered as a wireframe.

opacity: float | None¶: Opacity of the mesh. None means opaque.

flat_shading: bool¶: Whether to do flat shading.

side: Literal['front', 'back', 'double']¶: Side of the surface to render.

material: Literal['standard', 'toon3', 'toon5']¶: Material type of the mesh.

cast_shadow: bool¶: Whether or not to cast shadows.

receive_shadow: bool | float¶: Whether to receive shadows. If True, receives shadows normally. If False, no shadows. If a float (0-1), shadows are rendered with a fixed opacity regardless of lighting conditions.

class viser.MeshSkinnedBoneHandle[source]¶

Handle for reading and writing the poses of bones in a skinned mesh.

property wxyz: ndarray[tuple[int, ...], dtype[float32]]¶: Orientation of the bone. This is the quaternion representation of the R in p_parent = [R | t] p_local. Synchronized to clients automatically when assigned.

property position: ndarray[tuple[int, ...], dtype[float32]]¶: Position of the bone. This is equivalent to the t in p_parent = [R | t] p_local. Synchronized to clients automatically when assigned.

class viser.MeshSkinnedHandle[source]¶

Handle for skinned mesh objects.

property name: str¶: Read-only name of the scene node.

on_click(func: Callable[[SceneNodePointerEvent[Self]], NoneOrCoroutine]) → Callable[[SceneNodePointerEvent[Self]], NoneOrCoroutine]¶

Attach a callback for when a scene node is clicked.

The callback can be either a standard function or an async function: - Standard functions (def) will be executed in a threadpool. - Async functions (async def) will be executed in the event loop.

Using async functions can be useful for reducing race conditions.

Parameters:

self (Self)
func (Callable[[SceneNodePointerEvent[Self]], NoneOrCoroutine])

Return type:

Callable[[SceneNodePointerEvent[Self]], NoneOrCoroutine]

property position: ndarray[tuple[int, ...], dtype[float32]]¶: Position of the scene node. This is equivalent to the t in p_parent = [R | t] p_local. Synchronized to clients automatically when assigned.

remove() → None¶

Remove the node from the scene.

Return type:: None

remove_click_callback(callback: Literal['all'] | Callable = 'all') → None¶

Remove click callbacks from scene node.

Parameters:: callback (Literal['all'] | ~typing.Callable) – Either “all” to remove all callbacks, or a specific callback function to remove.
Return type:: None

property visible: bool¶: Whether the scene node is visible or not. Synchronized to clients automatically when assigned.

property wxyz: ndarray[tuple[int, ...], dtype[float32]]¶: Orientation of the scene node. This is the quaternion representation of the R in p_parent = [R | t] p_local. Synchronized to clients automatically when assigned.

bone_wxyzs: npt.NDArray[np.float32]¶: Array of quaternions representing bone orientations (B, 4). Synchronized

bone_positions: npt.NDArray[np.float32]¶: Array of positions representing bone positions (B, 3). Synchronized

skin_indices: npt.NDArray[np.uint16]¶: Array of skin indices. Should have shape (V, 4). Synchronized

skin_weights: npt.NDArray[np.float32]¶: Array of skin weights. Should have shape (V, 4). Synchronized

cast_shadow: bool¶: Whether or not to cast shadows.

receive_shadow: bool | float¶: Whether to receive shadows. If True, receives shadows normally. If False, no shadows. If a float (0-1), shadows are rendered with a fixed opacity regardless of lighting conditions.

vertices: npt.NDArray[np.float32]¶: A numpy array of vertex positions. Should have shape (V, 3).

faces: npt.NDArray[np.uint32]¶: A numpy array of faces, where each face is represented by indices of vertices. Should have shape (F, 3).

color: Tuple[int, int, int]¶: Color of the mesh as RGB integers.

wireframe: bool¶: Boolean indicating if the mesh should be rendered as a wireframe.

opacity: float | None¶: Opacity of the mesh. None means opaque.

flat_shading: bool¶: Whether to do flat shading.

side: Literal['front', 'back', 'double']¶: Side of the surface to render.

material: Literal['standard', 'toon3', 'toon5']¶: Material type of the mesh.

class viser.PointCloudHandle[source]¶

Handle for point clouds. Does not support click events.

property name: str¶: Read-only name of the scene node.

property position: ndarray[tuple[int, ...], dtype[float32]]¶: Position of the scene node. This is equivalent to the t in p_parent = [R | t] p_local. Synchronized to clients automatically when assigned.

remove() → None¶

Remove the node from the scene.

Return type:: None

property visible: bool¶: Whether the scene node is visible or not. Synchronized to clients automatically when assigned.

property wxyz: ndarray[tuple[int, ...], dtype[float32]]¶: Orientation of the scene node. This is the quaternion representation of the R in p_parent = [R | t] p_local. Synchronized to clients automatically when assigned.

points: npt.NDArray[np.float16] | npt.NDArray[np.float32]¶: Location of points. Should have shape (N, 3). Synchronized

colors: npt.NDArray[np.uint8]¶: Colors of points. Should have shape (N, 3) or (3,). Synchronized

point_size: float¶: Size of each point.

point_shape: Literal['square', 'diamond', 'circle', 'rounded', 'sparkle']¶: Shape to draw each point.

precision: Literal['float16', 'float32']¶: Precision of the point cloud. Assignments to points are automatically casted based on the current precision value. Updates to points should therefore happen after updates to precision.

class viser.PointLightHandle[source]¶

Handle for point lights.

property name: str¶: Read-only name of the scene node.

property position: ndarray[tuple[int, ...], dtype[float32]]¶: Position of the scene node. This is equivalent to the t in p_parent = [R | t] p_local. Synchronized to clients automatically when assigned.

remove() → None¶

Remove the node from the scene.

Return type:: None

property visible: bool¶: Whether the scene node is visible or not. Synchronized to clients automatically when assigned.

property wxyz: ndarray[tuple[int, ...], dtype[float32]]¶: Orientation of the scene node. This is the quaternion representation of the R in p_parent = [R | t] p_local. Synchronized to clients automatically when assigned.

color: Tuple[int, int, int]¶: Color of the point light.

intensity: float¶: Intensity of the point light.

distance: float¶: Distance of the point light.

decay: float¶: Decay of the point light.

cast_shadow: bool¶: If set to true mesh will cast a shadow.

class viser.RectAreaLightHandle[source]¶

Handle for rectangular area lights.

property name: str¶: Read-only name of the scene node.

property position: ndarray[tuple[int, ...], dtype[float32]]¶: Position of the scene node. This is equivalent to the t in p_parent = [R | t] p_local. Synchronized to clients automatically when assigned.

remove() → None¶

Remove the node from the scene.

Return type:: None

property visible: bool¶: Whether the scene node is visible or not. Synchronized to clients automatically when assigned.

property wxyz: ndarray[tuple[int, ...], dtype[float32]]¶: Orientation of the scene node. This is the quaternion representation of the R in p_parent = [R | t] p_local. Synchronized to clients automatically when assigned.

color: Tuple[int, int, int]¶: Color of the rectangular area light.

intensity: float¶: Intensity of the rectangular area light.

width: float¶: Width of the rectangular area light.

height: float¶: Height of the rectangular area light.

class viser.SceneNodeHandle[source]¶

Handle base class for interacting with scene nodes.

property name: str¶: Read-only name of the scene node.

property wxyz: ndarray[tuple[int, ...], dtype[float32]]¶: Orientation of the scene node. This is the quaternion representation of the R in p_parent = [R | t] p_local. Synchronized to clients automatically when assigned.

property position: ndarray[tuple[int, ...], dtype[float32]]¶: Position of the scene node. This is equivalent to the t in p_parent = [R | t] p_local. Synchronized to clients automatically when assigned.

property visible: bool¶: Whether the scene node is visible or not. Synchronized to clients automatically when assigned.

remove() → None[source]¶

Remove the node from the scene.

Return type:: None

class viser.SplineCatmullRomHandle[source]¶

Handle for Catmull-Rom splines.

property positions: tuple[tuple[float, float, float], ...]¶

use ‘points’ instead.

Deprecated since version 1.0.0: “The ‘positions’ tuple property is deprecated. Use the ‘points’ numpy array instead.”,

Type:: Get the spline positions. Deprecated

property name: str¶: Read-only name of the scene node.

property position: ndarray[tuple[int, ...], dtype[float32]]¶: Position of the scene node. This is equivalent to the t in p_parent = [R | t] p_local. Synchronized to clients automatically when assigned.

remove() → None¶

Remove the node from the scene.

Return type:: None

property visible: bool¶: Whether the scene node is visible or not. Synchronized to clients automatically when assigned.

property wxyz: ndarray[tuple[int, ...], dtype[float32]]¶: Orientation of the scene node. This is the quaternion representation of the R in p_parent = [R | t] p_local. Synchronized to clients automatically when assigned.

points: npt.NDArray[np.float32]¶: Array with shape (N, 3) defining the spline’s path. Synchronized

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]¶: Color of the spline as RGB integers.

segments: int | None¶: Number of segments to divide the spline into.

class viser.SplineCubicBezierHandle[source]¶

Handle for cubic Bezier splines.

property positions: tuple[tuple[float, float, float], ...]¶

use ‘points’ instead.

Deprecated since version 1.0.0: The ‘positions’ tuple property is deprecated. Use the ‘points’ numpy array instead.

Type:: Get the spline positions. Deprecated

property name: str¶: Read-only name of the scene node.

property position: ndarray[tuple[int, ...], dtype[float32]]¶: Position of the scene node. This is equivalent to the t in p_parent = [R | t] p_local. Synchronized to clients automatically when assigned.

remove() → None¶

Remove the node from the scene.

Return type:: None

property visible: bool¶: Whether the scene node is visible or not. Synchronized to clients automatically when assigned.

property wxyz: ndarray[tuple[int, ...], dtype[float32]]¶: Orientation of the scene node. This is the quaternion representation of the R in p_parent = [R | t] p_local. Synchronized to clients automatically when assigned.

points: npt.NDArray[np.float32]¶: Array of shape (N, 3) defining the spline’s key points. Synchronized

control_points: npt.NDArray[np.float32]¶: Array of shape (2*N-2, 3) defining control points for Bezier curve shaping.

line_width: float¶: Width of the spline line.

color: Tuple[int, int, int]¶: Color of the spline as RGB integers.

segments: int | None¶: Number of segments to divide the spline into.

class viser.SpotLightHandle[source]¶

Handle for spot lights.

property name: str¶: Read-only name of the scene node.

property position: ndarray[tuple[int, ...], dtype[float32]]¶: Position of the scene node. This is equivalent to the t in p_parent = [R | t] p_local. Synchronized to clients automatically when assigned.

remove() → None¶

Remove the node from the scene.

Return type:: None

property visible: bool¶: Whether the scene node is visible or not. Synchronized to clients automatically when assigned.

property wxyz: ndarray[tuple[int, ...], dtype[float32]]¶: Orientation of the scene node. This is the quaternion representation of the R in p_parent = [R | t] p_local. Synchronized to clients automatically when assigned.

color: Tuple[int, int, int]¶: Color of the spot light.

intensity: float¶: Intensity of the spot light.

distance: float¶: Distance of the spot light.

angle: float¶: Angle of the spot light.

penumbra: float¶: Penumbra of the spot light.

decay: float¶: Decay of the spot light.

cast_shadow: bool¶: If set to true mesh will cast a shadow.

class viser.TransformControlsHandle[source]¶

Handle for interacting with transform control gizmos.

property name: str¶: Read-only name of the scene node.

property position: ndarray[tuple[int, ...], dtype[float32]]¶: Position of the scene node. This is equivalent to the t in p_parent = [R | t] p_local. Synchronized to clients automatically when assigned.

property visible: bool¶: Whether the scene node is visible or not. Synchronized to clients automatically when assigned.

property wxyz: ndarray[tuple[int, ...], dtype[float32]]¶: Orientation of the scene node. This is the quaternion representation of the R in p_parent = [R | t] p_local. Synchronized to clients automatically when assigned.

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.

active_axes: Tuple[bool, bool, bool]¶: Tuple of booleans indicating active axes.

disable_axes: bool¶: Tuple of booleans indicating if axes are disabled. These are used for translation in the X, Y, or Z directions.

disable_sliders: bool¶: Tuple of booleans indicating if sliders are disabled. These are used for translation on the XY, YZ, or XZ planes.

disable_rotations: bool¶: Tuple of booleans indicating if rotations are disabled. These are used for rotation around the X, Y, or Z axes.

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. Setting to False can be used to render the gizmo even when occluded by other objects.

opacity: float¶: Opacity of the gizmo.

property update_timestamp: float¶

on_update(func: Callable[[TransformControlsEvent], NoneOrCoroutine]) → Callable[[TransformControlsEvent], NoneOrCoroutine][source]¶

Attach a callback for when the gizmo is moved.

The callback can be either a standard function or an async function: - Standard functions (def) will be executed in a threadpool. - Async functions (async def) will be executed in the event loop.

Using async functions can be useful for reducing race conditions.

Parameters:: func (Callable[[TransformControlsEvent], NoneOrCoroutine])
Return type:: Callable[[TransformControlsEvent], NoneOrCoroutine]

remove_update_callback(callback: Literal['all'] | Callable = 'all') → None[source]¶

Remove update callbacks from the transform controls.

Parameters:: callback (Literal['all'] | ~typing.Callable) – Either “all” to remove all callbacks, or a specific callback function to remove.
Return type:: None

on_drag_start(func: Callable[[TransformControlsEvent], NoneOrCoroutine]) → Callable[[TransformControlsEvent], NoneOrCoroutine][source]¶

Attach a callback for when dragging starts (“mouse down”).

The callback can be either a standard function or an async function: - Standard functions (def) will be executed in a threadpool. - Async functions (async def) will be executed in the event loop.

Using async functions can be useful for reducing race conditions.

Parameters:: func (Callable[[TransformControlsEvent], NoneOrCoroutine])
Return type:: Callable[[TransformControlsEvent], NoneOrCoroutine]

on_drag_end(func: Callable[[TransformControlsEvent], NoneOrCoroutine]) → Callable[[TransformControlsEvent], NoneOrCoroutine][source]¶

Attach a callback for when dragging end (“mouse up”).

The callback can be either a standard function or an async function: - Standard functions (def) will be executed in a threadpool. - Async functions (async def) will be executed in the event loop.

Using async functions can be useful for reducing race conditions.

Parameters:: func (Callable[[TransformControlsEvent], NoneOrCoroutine])
Return type:: Callable[[TransformControlsEvent], NoneOrCoroutine]

remove_drag_start_callback(callback: Literal['all'] | Callable = 'all') → None[source]¶

Remove drag start callbacks from the transform controls.

Parameters:: callback (Literal['all'] | ~typing.Callable) – Either “all” to remove all callbacks, or a specific callback function to remove.
Return type:: None

remove_drag_end_callback(callback: Literal['all'] | Callable = 'all') → None[source]¶

Remove drag end callbacks from the transform controls.

Parameters:: callback (Literal['all'] | ~typing.Callable) – Either “all” to remove all callbacks, or a specific callback function to remove.
Return type:: None

remove() → None[source]¶

Remove the node from the scene.

Return type:: None