Viser Server¶

class viser.ViserServer[source]¶

ViserServer is the main class for working with viser. On instantiation, it (a) launches a thread with a web server and (b) provides a high-level API for interactive 3D visualization.

Core API. Clients can connect via a web browser, and will be shown two components: a 3D scene and a 2D GUI panel. Methods belonging to ViserServer.scene can be used to add 3D primitives to the scene. Methods belonging to ViserServer.gui can be used to add 2D GUI elements.

Shared state. Elements added to the server object, for example via a server’s SceneApi.add_point_cloud() or GuiApi.add_button(), will have state that’s shared and synchronized automatically between all connected clients. To show elements that are local to a single client, see ClientHandle.scene and ClientHandle.gui.

Parameters:

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

scene: SceneApi¶: Handle for interacting with the 3D scene.

gui: GuiApi¶: Handle for interacting with the GUI.

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

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], NoneOrCoroutine]) → Callable[[ClientHandle], NoneOrCoroutine][source]¶

Attach a callback to run for newly connected clients.

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:: cb (Callable[[ClientHandle], NoneOrCoroutine])
Return type:: Callable[[ClientHandle], NoneOrCoroutine]

on_client_disconnect(cb: Callable[[ClientHandle], NoneOrCoroutine]) → Callable[[ClientHandle], NoneOrCoroutine][source]¶

Attach a callback to run when clients disconnect.

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:: cb (Callable[[ClientHandle], NoneOrCoroutine])
Return type:: Callable[[ClientHandle], NoneOrCoroutine]

flush() → None[source]¶

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

Return type:: None

atomic() → ContextManager[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:: ContextManager[None]

send_file_download(filename: str, content: bytes, chunk_size: int = 1048576) → None[source]¶

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

get_event_loop() → AbstractEventLoop[source]¶

Get the asyncio event loop used by the Viser background thread. This can be useful for safe concurrent operations.

Return type:: AbstractEventLoop