Client Handles

class viser.ClientHandle

A handle is created for each client that connects to a server. Handles can be used to communicate with just one client, as well as for reading and writing of camera state.

Similar to ViserServer, client handles also expose scene and GUI interfaces at ClientHandle.scene and ClientHandle.gui. If these are used, for example via a client’s SceneApi.add_point_cloud() method, created elements are local to only one specific client.

scene: SceneApi

Handle for interacting with the 3D scene.

gui: GuiApi

Handle for interacting with the GUI.

client_id: int

Unique ID for this client.

camera: CameraHandle

Handle for reading from and manipulating the client’s viewport camera.

flush() → None

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

Return type:

None

atomic() → ContextManager[None]

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:

ContextManager[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

add_notification(title: str, body: str, loading: bool = False, with_close_button: bool = True, auto_close: int | Literal[False] = False, color: Literal[‘dark’, ‘gray’, ‘red’, ‘pink’, ‘grape’, ‘violet’, ‘indigo’, ‘blue’, ‘cyan’, ‘green’, ‘lime’, ‘yellow’, ‘orange’, ‘teal’] | None = None) → NotificationHandle

Add a notification to the client’s interface.

This method creates a new notification that will be displayed at the top left corner of the client’s viewer. Notifications are useful for providing alerts or status updates to users.

Parameters:

• title (str) – Title to display on the notification.

• body (str) – Message to display on the notification body.

• loading (bool) – Whether the notification shows loading icon.

• with_close_button (bool) – Whether the notification can be manually closed.

• auto_close (int | Literal[False]) – Time in ms before the notification automatically closes; otherwise False such that the notification never closes on its own.

• color (Literal[‘dark’, ‘gray’, ‘red’, ‘pink’, ‘grape’, ‘violet’, ‘indigo’, ‘blue’, ‘cyan’, ‘green’, ‘lime’, ‘yellow’, ‘orange’, ‘teal’] | None)

Returns:

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

Return type:

NotificationHandle

class viser.NotificationHandle

Handle for a notification in our visualizer.

remove() → None

Return type:

None

title: str

Title of the notification. Synchronized automatically when assigned.

body: str

Body text of the notification. Synchronized automatically when assigned.

loading: bool

Whether to show a loading indicator. Synchronized automatically when assigned.

with_close_button: bool

Whether to show a close button. Synchronized automatically when assigned.

auto_close: int | Literal[False]

Time in milliseconds after which the notification should auto-close, or False to disable auto-close. Synchronized automatically when assigned.

color: Color | None

Color of the notification. Synchronized automatically when assigned.