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. Synchronized automatically when assigned.

intensity: float

Intensity of the ambient light. Synchronized automatically when assigned.

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:
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. Synchronized automatically when assigned.

batched_positions: npt.NDArray[np.float32]

Float array of shape (N,3) representing positions. Synchronized automatically when assigned.

batched_scales: npt.NDArray[np.float32] | None

Float array of shape (N,) or (N,3) representing uniform or per-axis (XYZ) scales. Synchronized automatically when assigned.

axes_length: float

Length of each axis. Synchronized automatically when assigned.

axes_radius: float

Radius of each axis. Synchronized automatically when assigned.

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:
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. Synchronized automatically when assigned.

cast_shadow: bool

Whether or not to cast shadows. Synchronized automatically when assigned.

receive_shadow: bool

Whether or not to receive shadows. Synchronized automatically when assigned.

batched_wxyzs: npt.NDArray[np.float32]

Float array of shape (N, 4) representing quaternion rotations. Synchronized automatically when assigned.

batched_positions: npt.NDArray[np.float32]

Float array of shape (N, 3) representing positions. Synchronized automatically when assigned.

batched_scales: npt.NDArray[np.float32] | None

Float array of shape (N,) or (N,3) representing uniform or per-axis (XYZ) scales. Synchronized automatically when assigned.

lod: Literal['auto', 'off'] | Tuple[Tuple[float, float], ...]

LOD settings. Either “auto”, “off”, or a tuple of (distance, ratio) pairs. Synchronized automatically when assigned.

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:
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). Synchronized automatically when assigned.

faces: npt.NDArray[np.uint32]

A numpy array of faces, where each face is represented by indices of vertices. Should have shape (F, 3). Synchronized automatically when assigned.

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,). Synchronized automatically when assigned.

wireframe: bool

Boolean indicating if the mesh should be rendered as a wireframe. Synchronized automatically when assigned.

opacity: float | None

Opacity of the mesh. None means opaque. Synchronized automatically when assigned.

flat_shading: bool

Whether to do flat shading. Synchronized automatically when assigned.

side: Literal['front', 'back', 'double']

Side of the surface to render. Synchronized automatically when assigned.

material: Literal['standard', 'toon3', 'toon5']

Material type of the mesh. Synchronized automatically when assigned.

cast_shadow: bool

Whether or not to cast shadows. Synchronized automatically when assigned.

receive_shadow: bool

Whether or not to receive shadows. Synchronized automatically when assigned.

batched_wxyzs: npt.NDArray[np.float32]

Float array of shape (N, 4) representing quaternion rotations. Synchronized automatically when assigned.

batched_positions: npt.NDArray[np.float32]

Float array of shape (N, 3) representing positions. Synchronized automatically when assigned.

batched_scales: npt.NDArray[np.float32] | None

Float array of shape (N,) or (N,3) representing uniform or per-axis (XYZ) scales. Synchronized automatically when assigned.

lod: Literal['auto', 'off'] | Tuple[Tuple[float, float], ...]

LOD settings. Either “auto”, “off”, or a tuple of (distance, ratio) pairs. Synchronized automatically when assigned.

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:
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). Synchronized automatically when assigned.

color: Tuple[int, int, int]

Color of the box as RGB integers. Synchronized automatically when assigned.

wireframe: bool

Boolean indicating if the box should be rendered as a wireframe. Synchronized automatically when assigned.

opacity: float | None

Opacity of the box. None means opaque. Synchronized automatically when assigned.

flat_shading: bool

Whether to do flat shading. Synchronized automatically when assigned.

side: Literal['front', 'back', 'double']

Side of the surface to render. Synchronized automatically when assigned.

material: Literal['standard', 'toon3', 'toon5']

Material type of the box. Synchronized automatically when assigned.

cast_shadow: bool

Whether or not to cast shadows. Synchronized automatically when assigned.

receive_shadow: bool

Whether or not to receive shadows. Synchronized automatically when assigned.

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:
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. Synchronized 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.

fov: float

Field of view of the camera (in radians). Synchronized automatically when assigned.

aspect: float

Aspect ratio of the camera (width over height). Synchronized automatically when assigned.

scale: float

Scale factor for the size of the frustum. Synchronized automatically when assigned.

line_width: float

Width of the frustum lines. Synchronized automatically when assigned.

color: Tuple[int, int, int]

Color of the frustum as RGB integers. Synchronized automatically when assigned.

cast_shadow: bool

Whether or not to cast shadows. Synchronized automatically when assigned.

receive_shadow: bool

Whether or not to receive shadows. Synchronized automatically when assigned.

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. Synchronized automatically when assigned.

intensity: float

Intensity of the directional light. Synchronized automatically when assigned.

cast_shadow: bool

If set to true mesh will cast a shadow. Synchronized automatically when assigned.

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:
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. Synchronized automatically when assigned.

axes_length: float

Length of each axis. Synchronized automatically when assigned.

axes_radius: float

Radius of each axis. Synchronized automatically when assigned.

origin_radius: float

Radius of the origin sphere. Synchronized automatically when assigned.

origin_color: Tuple[int, int, int]

Color of the origin sphere as RGB integers. Synchronized automatically when assigned.

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:
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:
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. Synchronized automatically when assigned.

scale: float

A scale for resizing the GLB asset. Synchronized automatically when assigned.

cast_shadow: bool

Whether or not to cast shadows. Synchronized automatically when assigned.

receive_shadow: bool

Whether or not to receive shadows. Synchronized automatically when assigned.

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. Synchronized automatically when assigned.

height: float

Height of the grid. Synchronized automatically when assigned.

width_segments: int

Number of segments along the width. Synchronized automatically when assigned.

height_segments: int

Number of segments along the height. Synchronized automatically when assigned.

plane: Literal['xz', 'xy', 'yx', 'yz', 'zx', 'zy']

The plane in which the grid is oriented. Synchronized automatically when assigned.

cell_color: Tuple[int, int, int]

Color of the grid cells as RGB integers. Synchronized automatically when assigned.

cell_thickness: float

Thickness of the grid lines. Synchronized automatically when assigned.

cell_size: float

Size of each cell in the grid. Synchronized automatically when assigned.

section_color: Tuple[int, int, int]

Color of the grid sections as RGB integers. Synchronized automatically when assigned.

section_thickness: float

Thickness of the section lines. Synchronized automatically when assigned.

section_size: float

Size of each section in the grid. Synchronized automatically when assigned.

shadow_opacity: float

If true, shadows are casted onto the grid plane. Synchronized automatically when assigned.

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. Synchronized automatically when assigned.

container_uuid: str

Identifier for the container. Synchronized automatically when assigned.

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. Synchronized automatically when assigned.

ground_color: Tuple[int, int, int]

Ground color of the hemisphere light. Synchronized automatically when assigned.

intensity: float

Intensity of the hemisphere light. Synchronized automatically when assigned.

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:
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. Synchronized automatically when assigned.

subdivisions: int

Number of subdivisions to use when creating the icosphere. Synchronized automatically when assigned.

color: Tuple[int, int, int]

Color of the icosphere as RGB integers. Synchronized automatically when assigned.

wireframe: bool

Boolean indicating if the icosphere should be rendered as a wireframe. Synchronized automatically when assigned.

opacity: float | None

Opacity of the icosphere. None means opaque. Synchronized automatically when assigned.

flat_shading: bool

Whether to do flat shading. Synchronized automatically when assigned.

side: Literal['front', 'back', 'double']

Side of the surface to render. Synchronized automatically when assigned.

material: Literal['standard', 'toon3', 'toon5']

Material type of the icosphere. Synchronized automatically when assigned.

cast_shadow: bool

Whether or not to cast shadows. Synchronized automatically when assigned.

receive_shadow: bool

Whether or not to receive shadows. Synchronized automatically when assigned.

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:
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. Synchronized automatically when assigned.

render_height: float

Height at which the image should be rendered in the scene. Synchronized automatically when assigned.

cast_shadow: bool

Whether or not to cast shadows. Synchronized automatically when assigned.

receive_shadow: bool

Whether or not to receive shadows. Synchronized automatically when assigned.

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. Synchronized automatically when assigned.

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. Synchronized automatically when assigned.

line_width: float

Width of the lines. Synchronized automatically when assigned.

colors: npt.NDArray[np.uint8]

Numpy array of shape (N, 2, 3) containing a color for each point. Synchronized automatically when assigned.

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:
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). Synchronized automatically when assigned.

faces: npt.NDArray[np.uint32]

A numpy array of faces, where each face is represented by indices of vertices. Should have shape (F, 3). Synchronized automatically when assigned.

color: Tuple[int, int, int]

Color of the mesh as RGB integers. Synchronized automatically when assigned.

wireframe: bool

Boolean indicating if the mesh should be rendered as a wireframe. Synchronized automatically when assigned.

opacity: float | None

Opacity of the mesh. None means opaque. Synchronized automatically when assigned.

flat_shading: bool

Whether to do flat shading. Synchronized automatically when assigned.

side: Literal['front', 'back', 'double']

Side of the surface to render. Synchronized automatically when assigned.

material: Literal['standard', 'toon3', 'toon5']

Material type of the mesh. Synchronized automatically when assigned.

cast_shadow: bool

Whether or not to cast shadows. Synchronized automatically when assigned.

receive_shadow: bool

Whether or not to receive shadows. Synchronized automatically when assigned.

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:
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 automatically when assigned.

bone_positions: npt.NDArray[np.float32]

Array of positions representing bone positions (B, 3). Synchronized automatically when assigned.

skin_indices: npt.NDArray[np.uint16]

Array of skin indices. Should have shape (V, 4). Synchronized automatically when assigned.

skin_weights: npt.NDArray[np.float32]

Array of skin weights. Should have shape (V, 4). Synchronized automatically when assigned.

cast_shadow: bool

Whether or not to cast shadows. Synchronized automatically when assigned.

receive_shadow: bool

Whether or not to receive shadows. Synchronized automatically when assigned.

vertices: npt.NDArray[np.float32]

A numpy array of vertex positions. Should have shape (V, 3). Synchronized automatically when assigned.

faces: npt.NDArray[np.uint32]

A numpy array of faces, where each face is represented by indices of vertices. Should have shape (F, 3). Synchronized automatically when assigned.

color: Tuple[int, int, int]

Color of the mesh as RGB integers. Synchronized automatically when assigned.

wireframe: bool

Boolean indicating if the mesh should be rendered as a wireframe. Synchronized automatically when assigned.

opacity: float | None

Opacity of the mesh. None means opaque. Synchronized automatically when assigned.

flat_shading: bool

Whether to do flat shading. Synchronized automatically when assigned.

side: Literal['front', 'back', 'double']

Side of the surface to render. Synchronized automatically when assigned.

material: Literal['standard', 'toon3', 'toon5']

Material type of the mesh. Synchronized automatically when assigned.

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 automatically when assigned.

colors: npt.NDArray[np.uint8]

Colors of points. Should have shape (N, 3) or (3,). Synchronized automatically when assigned.

point_size: float

Size of each point. Synchronized automatically when assigned.

point_shape: Literal['square', 'diamond', 'circle', 'rounded', 'sparkle']

Shape to draw each point. Synchronized automatically when assigned.

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. Synchronized automatically when assigned.

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. Synchronized automatically when assigned.

intensity: float

Intensity of the point light. Synchronized automatically when assigned.

distance: float

Distance of the point light. Synchronized automatically when assigned.

decay: float

Decay of the point light. Synchronized automatically when assigned.

cast_shadow: bool

If set to true mesh will cast a shadow. Synchronized automatically when assigned.

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. Synchronized automatically when assigned.

intensity: float

Intensity of the rectangular area light. Synchronized automatically when assigned.

width: float

Width of the rectangular area light. Synchronized automatically when assigned.

height: float

Height of the rectangular area light. Synchronized automatically when assigned.

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 automatically when assigned.

curve_type: Literal['centripetal', 'chordal', 'catmullrom']

Type of the curve (‘centripetal’, ‘chordal’, ‘catmullrom’). Synchronized automatically when assigned.

tension: float

Tension of the curve. Affects the tightness of the curve. Synchronized automatically when assigned.

closed: bool

Boolean indicating if the spline is closed (forms a loop). Synchronized automatically when assigned.

line_width: float

Width of the spline line. Synchronized automatically when assigned.

color: Tuple[int, int, int]

Color of the spline as RGB integers. Synchronized automatically when assigned.

segments: int | None

Number of segments to divide the spline into. Synchronized automatically when assigned.

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 automatically when assigned.

control_points: npt.NDArray[np.float32]

Array of shape (2*N-2, 3) defining control points for Bezier curve shaping. Synchronized automatically when assigned.

line_width: float

Width of the spline line. Synchronized automatically when assigned.

color: Tuple[int, int, int]

Color of the spline as RGB integers. Synchronized automatically when assigned.

segments: int | None

Number of segments to divide the spline into. Synchronized automatically when assigned.

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. Synchronized automatically when assigned.

intensity: float

Intensity of the spot light. Synchronized automatically when assigned.

distance: float

Distance of the spot light. Synchronized automatically when assigned.

angle: float

Angle of the spot light. Synchronized automatically when assigned.

penumbra: float

Penumbra of the spot light. Synchronized automatically when assigned.

decay: float

Decay of the spot light. Synchronized automatically when assigned.

cast_shadow: bool

If set to true mesh will cast a shadow. Synchronized automatically when assigned.

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. Synchronized automatically when assigned.

line_width: float

Width of the lines used in the gizmo. Synchronized automatically when assigned.

fixed: bool

Boolean indicating if the gizmo should be fixed in position. Synchronized automatically when assigned.

active_axes: Tuple[bool, bool, bool]

Tuple of booleans indicating active axes. Synchronized automatically when assigned.

disable_axes: bool

Tuple of booleans indicating if axes are disabled. These are used for translation in the X, Y, or Z directions. Synchronized automatically when assigned.

disable_sliders: bool

Tuple of booleans indicating if sliders are disabled. These are used for translation on the XY, YZ, or XZ planes. Synchronized automatically when assigned.

disable_rotations: bool

Tuple of booleans indicating if rotations are disabled. These are used for rotation around the X, Y, or Z axes. Synchronized automatically when assigned.

translation_limits: Tuple[Tuple[float, float], Tuple[float, float], Tuple[float, float]]

Limits for translation. Synchronized automatically when assigned.

rotation_limits: Tuple[Tuple[float, float], Tuple[float, float], Tuple[float, float]]

Limits for rotation. Synchronized automatically when assigned.

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. Synchronized automatically when assigned.

opacity: float

Opacity of the gizmo. Synchronized automatically when assigned.

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