Viser Server#

The core viser API is designed around viser.ViserServer, which (a) launches a thread with a visualization server and (b) provides a high-level API for communicating with clients.

class viser.ViserServer[source]#

Viser server class. The primary interface for functionality in viser.

Commands on a server object (add_frame, add_gui_*, …) will be sent to all clients, including new clients that connect after a command is called.

Parameters:

host – Host to bind server to.
port – Port to bind server to.
label – Label shown at the top of the GUI panel.

world_axes: FrameHandle#: Handle for manipulating the world frame axes (/WorldAxes), which is instantiated and then hidden by default.

get_host() → str[source]#

Returns the host address of the Viser server.

Returns:: Host address as string.
Return type:: str

get_port() → int[source]#

Returns the port of the Viser server. This could be different from the originally requested one.

Returns:: Port as integer.
Return type:: int

request_share_url(verbose: bool = True) → str | None[source]#

Request a share URL for the Viser server, which allows for public access. On the first call, will block until a connecting with the share URL server is established. Afterwards, the URL will be returned directly.

This is an experimental feature that relies on an external server; it shouldn’t be relied on for critical applications.

Returns:: Share URL as string, or None if connection fails or is closed.
Parameters:: verbose (bool) –
Return type:: str | None

disconnect_share_url() → None[source]#

Disconnect from the share URL server.

Return type:: None

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

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

Parameters:

name (str) – A scene tree name. Names in the format of /parent/child can be used to define a kinematic tree.
wxyz (Tuple[float, float, float, float] | ndarray) – Quaternion rotation to parent frame from local frame (R_pl).
position (Tuple[float, float, float] | ndarray) – Translation to parent frame from local frame (t_pl).
visible (bool) – Whether or not this scene node is initially visible.

Returns:

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

Return type:

Gui3dContainerHandle

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

Visualize batched sets of coordinate frame axes.

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

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

Parameters:

name (str) – A scene tree name. Names in the format of /parent/child can be used to define a kinematic tree.
batched_wxyzs (Tuple[Tuple[float, float, float, float], …] | ndarray) – Float array of shape (N,4).
batched_positions (Tuple[Tuple[float, float, float], …] | ndarray) – Float array of shape (N,3).
axes_length (float) – Length of each axis.
axes_radius (float) – Radius of each axis.
wxyz (Tuple[float, float, float, float] | ndarray) – Quaternion rotation to parent frame from local frame (R_pl). This will be applied to all axes.
position (Tuple[float, float, float] | ndarray) – Translation to parent frame from local frame (t_pl). This will be applied to all axes.
visible (bool) – Whether or not this scene node is initially visible.

Returns:

Handle for manipulating scene node.

Return type:

BatchedAxesHandle

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

Add a box to the scene.

Parameters:

name (str) – A scene tree name. Names in the format of /parent/child can be used to define a kinematic tree.
color (Tuple[int, int, int] | Tuple[float, float, float] | ndarray) – Color of the box as an RGB tuple.
dimensions (Tuple[float, float, float] | ndarray) – Dimensions of the box (x, y, z).
wxyz (Tuple[float, float, float, float] | ndarray) – Quaternion rotation to parent frame from local frame (R_pl).
position (Tuple[float, float, float] | ndarray) – Translation from parent frame to local frame (t_pl).
visible (bool) – Whether or not this box is initially visible.

Returns:

Handle for manipulating scene node.

Return type:

MeshHandle

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

Add a camera frustum to the scene for visualization.

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

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

Parameters:

name (str) – A scene tree name. Names in the format of /parent/child can be used to define a kinematic tree.
fov (float) – Field of view of the camera (in radians).
aspect (float) – Aspect ratio of the camera (width over height).
scale (float) – Scale factor for the size of the frustum.
color (Tuple[int, int, int] | Tuple[float, float, float] | ndarray) – Color of the frustum as an RGB tuple.
image (ndarray | None) – Optional image to be displayed on the frustum.
format (Literal[‘png’, ‘jpeg’]) – Format of the provided image (‘png’ or ‘jpeg’).
jpeg_quality (int | None) – Quality of the jpeg image (if jpeg format is used).
wxyz (Tuple[float, float, float, float] | ndarray) – Quaternion rotation to parent frame from local frame (R_pl).
position (Tuple[float, float, float] | ndarray) – Translation to parent frame from local frame (t_pl).
visible (bool) – Whether or not this scene node is initially visible.

Returns:

Handle for manipulating scene node.

Return type:

CameraFrustumHandle

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

Add a coordinate frame to the scene.

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

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

Parameters:

name (str) – A scene tree name. Names in the format of /parent/child can be used to define a kinematic tree.
show_axes (bool) – Boolean to indicate whether to show the frame as a set of axes + origin sphere.
axes_length (float) – Length of each axis.
axes_radius (float) – Radius of each axis.
origin_radius (float | None) – Radius of the origin sphere. If not set, defaults to 2 * axes_radius.
wxyz (Tuple[float, float, float, float] | ndarray) – Quaternion rotation to parent frame from local frame (R_pl).
position (Tuple[float, float, float] | ndarray) – Translation to parent frame from local frame (t_pl).
visible (bool) – Whether or not this scene node is initially visible.

Returns:

Handle for manipulating scene node.

Return type:

FrameHandle

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

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

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

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

Parameters:

name (str) – A scene tree name. Names in the format of /parent/child can be used to define a kinematic tree.
glb_data (bytes) – A binary payload.
scale – A scale for resizing the GLB asset.
wxyz (Tuple[float, float, float, float] | ndarray) – Quaternion rotation to parent frame from local frame (R_pl).
position (Tuple[float, float, float] | ndarray) – Translation to parent frame from local frame (t_pl).
visible (bool) – Whether or not this scene node is initially visible.

Returns:

Handle for manipulating scene node.

Return type:

GlbHandle

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

Add a 2D grid to the scene.

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

Parameters:

name (str) – Name of the grid.
width (float) – Width of the grid.
height (float) – Height of the grid.
width_segments (int) – Number of segments along the width.
height_segments (int) – Number of segments along the height.
plane (Literal[‘xz’, ‘xy’, ‘yx’, ‘yz’, ‘zx’, ‘zy’]) – The plane in which the grid is oriented (e.g., ‘xy’, ‘yz’).
cell_color (Tuple[int, int, int] | Tuple[float, float, float] | ndarray) – Color of the grid cells as an RGB tuple.
cell_thickness (float) – Thickness of the grid lines.
cell_size (float) – Size of each cell in the grid.
section_color (Tuple[int, int, int] | Tuple[float, float, float] | ndarray) – Color of the grid sections as an RGB tuple.
section_thickness (float) – Thickness of the section lines.
section_size (float) – Size of each section in the grid.
wxyz (Tuple[float, float, float, float] | ndarray) – Quaternion rotation to parent frame from local frame (R_pl).
position (Tuple[float, float, float] | ndarray) – Translation to parent frame from local frame (t_pl).
visible (bool) – Whether or not this scene node is initially visible.

Returns:

Handle for manipulating scene node.

Return type:

SceneNodeHandle

add_gui_button(label: str, disabled: bool = False, visible: bool = True, hint: str | None = None, color: Literal[‘dark’, ‘gray’, ‘red’, ‘pink’, ‘grape’, ‘violet’, ‘indigo’, ‘blue’, ‘cyan’, ‘green’, ‘lime’, ‘yellow’, ‘orange’, ‘teal’] | None = None, icon: IconName | None = None, order: float | None = None) → GuiButtonHandle#

Add a button to the GUI. The value of this input is set to True every time it is clicked; to detect clicks, we can manually set it back to False.

Parameters:

label (str) – Label to display on the button.
visible (bool) – Whether the button is visible.
disabled (bool) – Whether the button is disabled.
hint (str | None) – Optional hint to display on hover.
color (Literal[‘dark’, ‘gray’, ‘red’, ‘pink’, ‘grape’, ‘violet’, ‘indigo’, ‘blue’, ‘cyan’, ‘green’, ‘lime’, ‘yellow’, ‘orange’, ‘teal’] | None) – Optional color to use for the button.
icon (IconName | None) – Optional icon to display on the button.
order (float | None) – Optional ordering, smallest values will be displayed first.

Returns:

A handle that can be used to interact with the GUI element.

Return type:

GuiButtonHandle

add_gui_button_group(label: str, options: Sequence[TLiteralString] | Sequence[TString], visible: bool = True, disabled: bool = False, hint: str | None = None, order: float | None = None) → GuiButtonGroupHandle[Any]#

Add a button group to the GUI.

Parameters:

label (str) – Label to display on the button group.
options (Sequence[TLiteralString] | Sequence[TString]) – Sequence of options to display as buttons.
visible (bool) – Whether the button group is visible.
disabled (bool) – Whether the button group is disabled.
hint (str | None) – Optional hint to display on hover.
order (float | None) – Optional ordering, smallest values will be displayed first.

Returns:

A handle that can be used to interact with the GUI element.

Return type:

GuiButtonGroupHandle[Any]

add_gui_checkbox(label: str, initial_value: bool, disabled: bool = False, visible: bool = True, hint: str | None = None, order: float | None = None) → GuiInputHandle[bool]#

Add a checkbox to the GUI.

Parameters:

label (str) – Label to display on the checkbox.
initial_value (bool) – Initial value of the checkbox.
disabled (bool) – Whether the checkbox is disabled.
visible (bool) – Whether the checkbox is visible.
hint (str | None) – Optional hint to display on hover.
order (float | None) – Optional ordering, smallest values will be displayed first.

Returns:

A handle that can be used to interact with the GUI element.

Return type:

GuiInputHandle[bool]

add_gui_dropdown(label: str, options: Sequence[TLiteralString] | Sequence[TString], initial_value: TLiteralString | TString | None = None, disabled: bool = False, visible: bool = True, hint: str | None = None, order: float | None = None) → GuiDropdownHandle[Any]#

Add a dropdown to the GUI.

Parameters:

label (str) – Label to display on the dropdown.
options (Sequence[TLiteralString] | Sequence[TString]) – Sequence of options to display in the dropdown.
initial_value (TLiteralString | TString | None) – Initial value of the dropdown.
disabled (bool) – Whether the dropdown is disabled.
visible (bool) – Whether the dropdown is visible.
hint (str | None) – Optional hint to display on hover.
order (float | None) – Optional ordering, smallest values will be displayed first.

Returns:

A handle that can be used to interact with the GUI element.

Return type:

GuiDropdownHandle[Any]

add_gui_folder(label: str, order: float | None = None, expand_by_default: bool = True, visible: bool = True) → GuiFolderHandle#

Add a folder, and return a handle that can be used to populate it.

Parameters:

label (str) – Label to display on the folder.
order (float | None) – Optional ordering, smallest values will be displayed first.
expand_by_default (bool) – Open the folder by default. Set to False to collapse it by default.
visible (bool) – Whether the component is visible.

Returns:

A handle that can be used as a context to populate the folder.

Return type:

GuiFolderHandle

add_gui_markdown(content: str, image_root: Path | None = None, order: float | None = None, visible: bool = True) → GuiMarkdownHandle#

Add markdown to the GUI.

Parameters:

content (str) – Markdown content to display.
image_root (Path | None) – Optional root directory to resolve relative image paths.
order (float | None) – Optional ordering, smallest values will be displayed first.
visible (bool) – Whether the component is visible.

Returns:

A handle that can be used to interact with the GUI element.

Return type:

GuiMarkdownHandle

add_gui_modal(title: str, order: float | None = None) → GuiModalHandle#

Show a modal window, which can be useful for popups and messages, then return a handle that can be used to populate it.

Parameters:

title (str) – Title to display on the modal.
order (float | None) – Optional ordering, smallest values will be displayed first.

Returns:

A handle that can be used as a context to populate the modal.

Return type:

GuiModalHandle

add_gui_multi_slider(label: str, min: IntOrFloat, max: IntOrFloat, step: IntOrFloat, initial_value: Tuple[IntOrFloat, …], min_range: IntOrFloat | None = None, fixed_endpoints: bool = False, marks: Tuple[IntOrFloat | Tuple[IntOrFloat, str], …] | None = None, disabled: bool = False, visible: bool = True, hint: str | None = None, order: float | None = None) → GuiInputHandle[Tuple[IntOrFloat, ...]]#

Add a multi slider to the GUI. Types of the min, max, step, and initial value should match.

Parameters:

label (str) – Label to display on the slider.
min (IntOrFloat) – Minimum value of the slider.
max (IntOrFloat) – Maximum value of the slider.
step (IntOrFloat) – Step size of the slider.
initial_value (Tuple[IntOrFloat, …]) – Initial values of the slider.
min_range (IntOrFloat | None) – Optional minimum difference between two values of the slider.
fixed_endpoints (bool) – Whether the endpoints of the slider are fixed.
marks (Tuple[IntOrFloat | Tuple[IntOrFloat, str], …] | None) – Tuple of marks to display below the slider. Each mark should either be a numerical or a (number, label) tuple, where the label is provided as a string.
disabled (bool) – Whether the slider is disabled.
visible (bool) – Whether the slider is visible.
hint (str | None) – Optional hint to display on hover.
order (float | None) – Optional ordering, smallest values will be displayed first.

Returns:

A handle that can be used to interact with the GUI element.

Return type:

GuiInputHandle[Tuple[IntOrFloat, …]]

add_gui_number(label: str, initial_value: IntOrFloat, min: IntOrFloat | None = None, max: IntOrFloat | None = None, step: IntOrFloat | None = None, disabled: bool = False, visible: bool = True, hint: str | None = None, order: float | None = None) → GuiInputHandle[IntOrFloat]#

Add a number input to the GUI, with user-specifiable bound and precision parameters.

Parameters:

label (str) – Label to display on the number input.
initial_value (IntOrFloat) – Initial value of the number input.
min (IntOrFloat | None) – Optional minimum value of the number input.
max (IntOrFloat | None) – Optional maximum value of the number input.
step (IntOrFloat | None) – Optional step size of the number input. Computed automatically if not specified.
disabled (bool) – Whether the number input is disabled.
visible (bool) – Whether the number input is visible.
hint (str | None) – Optional hint to display on hover.
order (float | None) – Optional ordering, smallest values will be displayed first.

Returns:

A handle that can be used to interact with the GUI element.

Return type:

GuiInputHandle[IntOrFloat]

add_gui_plotly(figure: go.Figure, aspect: float = 1.0, order: float | None = None, visible: bool = True) → GuiPlotlyHandle#

Add a Plotly figure to the GUI. Requires the plotly package to be installed.

Parameters:

figure (go.Figure) – Plotly figure to display.
aspect (float) – Aspect ratio of the plot in the control panel (width/height).
order (Optional[float]) – Optional ordering, smallest values will be displayed first.
visible (bool) – Whether the component is visible.

Returns:

A handle that can be used to interact with the GUI element.

Return type:

GuiPlotlyHandle

add_gui_rgb(label: str, initial_value: Tuple[int, int, int], disabled: bool = False, visible: bool = True, hint: str | None = None, order: float | None = None) → GuiInputHandle[Tuple[int, int, int]]#

Add an RGB picker to the GUI.

Parameters:

label (str) – Label to display on the RGB picker.
initial_value (Tuple[int, int, int]) – Initial value of the RGB picker.
disabled (bool) – Whether the RGB picker is disabled.
visible (bool) – Whether the RGB picker is visible.
hint (str | None) – Optional hint to display on hover.
order (float | None) – Optional ordering, smallest values will be displayed first.

Returns:

A handle that can be used to interact with the GUI element.

Return type:

GuiInputHandle[Tuple[int, int, int]]

add_gui_rgba(label: str, initial_value: Tuple[int, int, int, int], disabled: bool = False, visible: bool = True, hint: str | None = None, order: float | None = None) → GuiInputHandle[Tuple[int, int, int, int]]#

Add an RGBA picker to the GUI.

Parameters:

label (str) – Label to display on the RGBA picker.
initial_value (Tuple[int, int, int, int]) – Initial value of the RGBA picker.
disabled (bool) – Whether the RGBA picker is disabled.
visible (bool) – Whether the RGBA picker is visible.
hint (str | None) – Optional hint to display on hover.
order (float | None) – Optional ordering, smallest values will be displayed first.

Returns:

A handle that can be used to interact with the GUI element.

Return type:

GuiInputHandle[Tuple[int, int, int, int]]

add_gui_slider(label: str, min: IntOrFloat, max: IntOrFloat, step: IntOrFloat, initial_value: IntOrFloat, marks: Tuple[IntOrFloat | Tuple[IntOrFloat, str], …] | None = None, disabled: bool = False, visible: bool = True, hint: str | None = None, order: float | None = None) → GuiInputHandle[IntOrFloat]#

Add a slider to the GUI. Types of the min, max, step, and initial value should match.

Parameters:

label (str) – Label to display on the slider.
min (IntOrFloat) – Minimum value of the slider.
max (IntOrFloat) – Maximum value of the slider.
step (IntOrFloat) – Step size of the slider.
initial_value (IntOrFloat) – Initial value of the slider.
marks (Tuple[IntOrFloat | Tuple[IntOrFloat, str], …] | None) – Tuple of marks to display below the slider. Each mark should either be a numerical or a (number, label) tuple, where the label is provided as a string.
disabled (bool) – Whether the slider is disabled.
visible (bool) – Whether the slider is visible.
hint (str | None) – Optional hint to display on hover.
order (float | None) – Optional ordering, smallest values will be displayed first.

Returns:

A handle that can be used to interact with the GUI element.

Return type:

GuiInputHandle[IntOrFloat]

add_gui_tab_group(order: float | None = None, visible: bool = True) → GuiTabGroupHandle#

Add a tab group.

Parameters:

order (float | None) – Optional ordering, smallest values will be displayed first.
visible (bool) – Whether the component is visible.

Returns:

A handle that can be used as a context to populate the tab group.

Return type:

GuiTabGroupHandle

add_gui_text(label: str, initial_value: str, disabled: bool = False, visible: bool = True, hint: str | None = None, order: float | None = None) → GuiInputHandle[str]#

Add a text input to the GUI.

Parameters:

label (str) – Label to display on the text input.
initial_value (str) – Initial value of the text input.
disabled (bool) – Whether the text input is disabled.
visible (bool) – Whether the text input is visible.
hint (str | None) – Optional hint to display on hover.
order (float | None) – Optional ordering, smallest values will be displayed first.

Returns:

A handle that can be used to interact with the GUI element.

Return type:

GuiInputHandle[str]

add_gui_upload_button(label: str, disabled: bool = False, visible: bool = True, hint: str | None = None, color: Literal[‘dark’, ‘gray’, ‘red’, ‘pink’, ‘grape’, ‘violet’, ‘indigo’, ‘blue’, ‘cyan’, ‘green’, ‘lime’, ‘yellow’, ‘orange’, ‘teal’] | None = None, icon: IconName | None = None, mime_type: str = '*/*', order: float | None = None) → GuiUploadButtonHandle#

Add a button to the GUI. The value of this input is set to True every time it is clicked; to detect clicks, we can manually set it back to False.

Parameters:

label (str) – Label to display on the button.
visible (bool) – Whether the button is visible.
disabled (bool) – Whether the button is disabled.
hint (str | None) – Optional hint to display on hover.
color (Literal[‘dark’, ‘gray’, ‘red’, ‘pink’, ‘grape’, ‘violet’, ‘indigo’, ‘blue’, ‘cyan’, ‘green’, ‘lime’, ‘yellow’, ‘orange’, ‘teal’] | None) – Optional color to use for the button.
icon (IconName | None) – Optional icon to display on the button.
mime_type (str) – Optional MIME type to filter the files that can be uploaded.
order (float | None) – Optional ordering, smallest values will be displayed first.

Returns:

A handle that can be used to interact with the GUI element.

Return type:

GuiUploadButtonHandle

Add a length-2 vector input to the GUI.

Parameters:

label (str) – Label to display on the vector input.
initial_value (Tuple[float, float] | ndarray) – Initial value of the vector input.
min (Tuple[float, float] | ndarray | None) – Optional minimum value of the vector input.
max (Tuple[float, float] | ndarray | None) – Optional maximum value of the vector input.
step (float | None) – Optional step size of the vector input. Computed automatically if not
disabled (bool) – Whether the vector input is disabled.
visible (bool) – Whether the vector input is visible.
hint (str | None) – Optional hint to display on hover.
order (float | None) – Optional ordering, smallest values will be displayed first.

Returns:

A handle that can be used to interact with the GUI element.

Return type:

GuiInputHandle[Tuple[float, float]]

Add a length-3 vector input to the GUI.

Parameters:

label (str) – Label to display on the vector input.
initial_value (Tuple[float, float, float] | ndarray) – Initial value of the vector input.
min (Tuple[float, float, float] | ndarray | None) – Optional minimum value of the vector input.
max (Tuple[float, float, float] | ndarray | None) – Optional maximum value of the vector input.
step (float | None) – Optional step size of the vector input. Computed automatically if not
disabled (bool) – Whether the vector input is disabled.
visible (bool) – Whether the vector input is visible.
hint (str | None) – Optional hint to display on hover.
order (float | None) – Optional ordering, smallest values will be displayed first.

Returns:

A handle that can be used to interact with the GUI element.

Return type:

GuiInputHandle[Tuple[float, float, float]]

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

Add an icosphere to the scene.

Parameters:

name (str) – A scene tree name. Names in the format of /parent/child can be used to define a kinematic tree.
radius (float) – Radius of the icosphere.
color (Tuple[int, int, int] | Tuple[float, float, float] | ndarray) – Color of the icosphere as an RGB tuple.
subdivisions (int) – Number of subdivisions to use when creating the icosphere.
wxyz (Tuple[float, float, float, float] | ndarray) – Quaternion rotation to parent frame from local frame (R_pl).
position (Tuple[float, float, float] | ndarray) – Translation from parent frame to local frame (t_pl).
visible (bool) – Whether or not this icosphere is initially visible.

Returns:

Handle for manipulating scene node.

Return type:

MeshHandle

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

Add a 2D image to the scene.

Parameters:

name (str) – A scene tree name. Names in the format of /parent/child can be used to define a kinematic tree.
image (ndarray) – A numpy array representing the image.
render_width (float) – Width at which the image should be rendered in the scene.
render_height (float) – Height at which the image should be rendered in the scene.
format (Literal[‘png’, ‘jpeg’]) – Format to transport and display the image using (‘png’ or ‘jpeg’).
jpeg_quality (int | None) – Quality of the jpeg image (if jpeg format is used).
wxyz (Tuple[float, float, float, float] | ndarray) – Quaternion rotation to parent frame from local frame (R_pl).
position (Tuple[float, float, float] | ndarray) – Translation from parent frame to local frame (t_pl).
visible (bool) – Whether or not this image is initially visible.

Returns:

Handle for manipulating scene node.

Return type:

ImageHandle

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

Add a 2D label to the scene.

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

Parameters:

name (str) – Name of the label.
text (str) – Text content of the label.
wxyz (Tuple[float, float, float, float] | ndarray) – Quaternion rotation to parent frame from local frame (R_pl).
position (Tuple[float, float, float] | ndarray) – Translation to parent frame from local frame (t_pl).
visible (bool) – Whether or not this scene node is initially visible.

Returns:

Handle for manipulating scene node.

Return type:

LabelHandle

add_mesh(*args, **kwargs) → MeshHandle#

Deprecated alias for add_mesh_simple().

Return type:: MeshHandle

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

Add a mesh to the scene.

Parameters:

name (str) – A scene tree name. Names in the format of /parent/child can be used to define a kinematic tree.
vertices (ndarray) – A numpy array of vertex positions. Should have shape (V, 3).
faces (ndarray) – A numpy array of faces, where each face is represented by indices of vertices. Should have shape (F,)
color (Tuple[int, int, int] | Tuple[float, float, float] | ndarray) – Color of the mesh as an RGB tuple.
wireframe (bool) – Boolean indicating if the mesh should be rendered as a wireframe.
opacity (float | None) – Opacity of the mesh. None means opaque.
material (Literal[‘standard’, ‘toon3’, ‘toon5’]) – Material type of the mesh (‘standard’, ‘toon3’, ‘toon5’). This argument is ignored when wireframe=True.
flat_shading (bool) – Whether to do flat shading. This argument is ignored when wireframe=True.
side (Literal[‘front’, ‘back’, ‘double’]) – Side of the surface to render (‘front’, ‘back’, ‘double’).
wxyz (Tuple[float, float, float, float] | ndarray) – Quaternion rotation to parent frame from local frame (R_pl).
position (Tuple[float, float, float] | ndarray) – Translation from parent frame to local frame (t_pl).
visible (bool) – Whether or not this mesh is initially visible.

Returns:

Handle for manipulating scene node.

Return type:

MeshHandle

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

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

Parameters:

name (str) – A scene tree name. Names in the format of /parent/child can be used to define a kinematic tree.
mesh (trimesh.Trimesh) – A trimesh mesh object.
scale (float) – A scale for resizing the mesh.
wxyz (Tuple[float, float, float, float] | onp.ndarray) – Quaternion rotation to parent frame from local frame (R_pl).
position (Tuple[float, float, float] | onp.ndarray) – Translation to parent frame from local frame (t_pl).
visible (bool) – Whether or not this scene node is initially visible.

Returns:

Handle for manipulating scene node.

Return type:

GlbHandle

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

Add a point cloud to the scene.

Parameters:

name (str) – Name of scene node. Determines location in kinematic tree.
points (ndarray) – Location of points. Should have shape (N, 3).
colors (ndarray | Tuple[float, float, float]) – Colors of points. Should have shape (N, 3) or (3,).
point_size (float) – Size of each point.
point_shape (Literal[‘square’, ‘diamond’, ‘circle’, ‘rounded’, ‘sparkle’]) – Shape to draw each point.
wxyz (Tuple[float, float, float, float] | ndarray) – Quaternion rotation to parent frame from local frame (R_pl).
position (Tuple[float, float, float] | ndarray) – Translation to parent frame from local frame (t_pl).
visible (bool) – Whether or not this scene node is initially visible.

Returns:

Handle for manipulating scene node.

Return type:

PointCloudHandle

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

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

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

Parameters:

name (str) – A scene tree name. Names in the format of /parent/child can be used to define a kinematic tree.
positions (Tuple[Tuple[float, float, float], …] | ndarray) – A tuple of 3D positions (x, y, z) defining the spline’s path.
curve_type (Literal[‘centripetal’, ‘chordal’, ‘catmullrom’]) – Type of the curve (‘centripetal’, ‘chordal’, ‘catmullrom’).
tension (float) – Tension of the curve. Affects the tightness of the curve.
closed (bool) – Boolean indicating if the spline is closed (forms a loop).
line_width (float) – Width of the spline line.
color (Tuple[int, int, int] | Tuple[float, float, float] | ndarray) – Color of the spline as an RGB tuple.
segments (int | None) – Number of segments to divide the spline into.
wxyz (Tuple[float, float, float, float] | ndarray) – Quaternion rotation to parent frame from local frame (R_pl).
position (Tuple[float, float, float] | ndarray) – Translation to parent frame from local frame (t_pl).
visible (bool) – Whether or not this scene node is initially visible.

Returns:

Handle for manipulating scene node.

Return type:

SceneNodeHandle

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

Add a spline to the scene using Cubic Bezier interpolation.

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

Parameters:

name (str) – A scene tree name. Names in the format of /parent/child can be used to define a kinematic tree.
positions (Tuple[Tuple[float, float, float], …] | ndarray) – A tuple of 3D positions (x, y, z) defining the spline’s key points.
control_points (Tuple[Tuple[float, float, float], …] | ndarray) – A tuple of control points for Bezier curve shaping.
line_width (float) – Width of the spline line.
color (Tuple[int, int, int] | Tuple[float, float, float] | ndarray) – Color of the spline as an RGB tuple.
segments (int | None) – Number of segments to divide the spline into.
wxyz (Tuple[float, float, float, float] | ndarray) – Quaternion rotation to parent frame from local frame (R_pl).
position (Tuple[float, float, float] | ndarray) – Translation to parent frame from local frame (t_pl).
visible (bool) – Whether or not this scene node is initially visible.

Returns:

Handle for manipulating scene node.

Return type:

SceneNodeHandle

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

Add a transform gizmo for interacting with the scene.

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

Parameters:

name (str) – A scene tree name. Names in the format of /parent/child can be used to define a kinematic tree.
scale (float) – Scale of the transform controls.
line_width (float) – Width of the lines used in the gizmo.
fixed (bool) – Boolean indicating if the gizmo should be fixed in position.
auto_transform (bool) – Whether the transform should be applied automatically.
active_axes (Tuple[bool, bool, bool]) – Tuple of booleans indicating active axes.
disable_axes (bool) – Boolean to disable axes interaction.
disable_sliders (bool) – Boolean to disable slider interaction.
disable_rotations (bool) – Boolean to disable rotation interaction.
translation_limits (Tuple[Tuple[float, float], Tuple[float, float], Tuple[float, float]]) – Limits for translation.
rotation_limits (Tuple[Tuple[float, float], Tuple[float, float], Tuple[float, float]]) – Limits for rotation.
depth_test (bool) – Boolean indicating if depth testing should be used when rendering.
opacity (float) – Opacity of the gizmo.
wxyz (Tuple[float, float, float, float] | ndarray) – Quaternion rotation to parent frame from local frame (R_pl).
position (Tuple[float, float, float] | ndarray) – Translation from parent frame to local frame (t_pl).
visible (bool) – Whether or not this gizmo is initially visible.

Returns:

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

Return type:

TransformControlsHandle

configure_theme(*, titlebar_content: TitlebarConfig | None = None, control_layout: Literal[‘floating’, ‘collapsible’, ‘fixed’] = 'floating', control_width: Literal[‘small’, ‘medium’, ‘large’] = 'medium', dark_mode: bool = False, show_logo: bool = True, show_share_button: bool = True, brand_color: Tuple[int, int, int] | None = None) → None#

Configures the visual appearance of the viser front-end.

Parameters:

titlebar_content (TitlebarConfig | None) – Optional configuration for the title bar.
control_layout (Literal[‘floating’, ‘collapsible’, ‘fixed’]) – The layout of control elements, options are “floating”, “collapsible”, or “fixed”.
control_width (Literal[‘small’, ‘medium’, ‘large’]) – The width of control elements, options are “small”, “medium”, or “large”.
dark_mode (bool) – A boolean indicating if dark mode should be enabled.
show_logo (bool) – A boolean indicating if the logo should be displayed.
show_share_button (bool) – A boolean indicating if the share button should be displayed.
brand_color (Tuple[int, int, int] | None) – An optional tuple of integers (RGB) representing the brand color.

Return type:

None

gui_folder(label: str) → GuiFolderHandle#

Deprecated.

Parameters:: label (str) –
Return type:: GuiFolderHandle

on_scene_click(func: Callable[[ScenePointerEvent], None]) → Callable[[ScenePointerEvent], None]#

Deprecated. Use on_scene_pointer instead.

Registers a callback for scene click events. (event_type == “click”)

Parameters:: func (Callable[[ScenePointerEvent], None]) – The callback function to add.
Return type:: Callable[[ScenePointerEvent], None]

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

Add a callback for scene pointer events.

Parameters:: event_type (Literal[‘click’, ‘rect-select’]) – event to listen to.
Return type:: Callable[[Callable[[ScenePointerEvent], None]], Callable[[ScenePointerEvent], None]]

on_scene_pointer_removed(func: Callable[[], None]) → Callable[[], None]#

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

Parameters:: func (Callable[[], None]) – Callback for when scene pointer events are removed.
Return type:: Callable[[], None]

remove_scene_pointer_callback() → None#

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

Return type:: None

reset_scene() → None#

Reset the scene.

Return type:: None

send_file_download(filename: str, content: bytes, chunk_size: int = 1048576) → None#

Send a file for a client or clients to download.

Parameters:

filename (str) – Name of the file to send. Used to infer MIME type.
content (bytes) – Content of the file.
chunk_size (int) – Number of bytes to send at a time.

Return type:

None

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

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

Parameters:

image (ndarray) – The image to set as the background. Should have shape (H, W, 3).
format (Literal[‘png’, ‘jpeg’]) – Format to transport and display the image using (‘png’ or ‘jpeg’).
jpeg_quality (int | None) – Quality of the jpeg image (if jpeg format is used).
depth (ndarray | None) – Optional depth image to use to composite background with scene elements.

Return type:

None

set_global_scene_node_visibility(visible: bool) → None#

Set global scene node visibility. If visible is set to False, all scene nodes will be hidden.

Parameters:: visible (bool) – Whether or not all scene nodes should be visible.
Return type:: None

set_gui_panel_label(label: str | None) → None#

Set the main label that appears in the GUI panel.

Parameters:: label (str | None) – The new label.
Return type:: None

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

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

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

stop() → None[source]#

Stop the Viser server and associated threads and tunnels.

Return type:: None

get_clients() → Dict[int, ClientHandle][source]#

Creates and returns a copy of the mapping from connected client IDs to handles.

Returns:: Dictionary of clients.
Return type:: Dict[int, ClientHandle]

on_client_connect(cb: Callable[[ClientHandle], None]) → Callable[[ClientHandle], None][source]#

Attach a callback to run for newly connected clients.

Parameters:: cb (Callable[[ClientHandle], None]) –
Return type:: Callable[[ClientHandle], None]

on_client_disconnect(cb: Callable[[ClientHandle], None]) → Callable[[ClientHandle], None][source]#

Attach a callback to run when clients disconnect.

Parameters:: cb (Callable[[ClientHandle], None]) –
Return type:: Callable[[ClientHandle], None]

atomic() → Generator[None, None, None][source]#

Returns a context where: all outgoing messages are grouped and applied by clients atomically.

This should be treated as a soft constraint that’s helpful for things like animations, or when we want position and orientation updates to happen synchronously.

Returns:: Context manager.
Return type:: Generator[None, None, None]

flush() → None[source]#

Flush the outgoing message buffer. Any buffered messages will immediately be sent. (by default they are windowed)

Return type:: None