viser: 3D Visualization for Computer Vision and Robotics

Warnings

• breaking When updating properties of `SceneNodeHandles` (e.g., position, orientation), explicit reassignment of the entire property is required, especially when modifying NumPy arrays in-place. Direct in-place modification of array elements might not trigger updates to the client for versions `0.2.10` and later.
  Fix: Instead of `handle.position[0] += 0.1`, use `new_pos = list(handle.position); new_pos[0] += 0.1; handle.position = tuple(new_pos)` (or similar explicit reassignment with `numpy` arrays).
• gotcha Viser enforces strict version compatibility between the Python backend and the web client. If the client (served by the browser) and the Python server versions do not match, the connection will be rejected with a protocol error (code 1002). This is a security and stability feature to prevent mismatched functionality.
  Fix: Ensure that your `viser` Python package version matches the client version it attempts to serve. If manually hosting a client, ensure it's built from a compatible `viser` source.
• gotcha On some Windows systems, users have reported issues where the Viser web client fails to load due to a 'Failed to load module script: Expected a JavaScript module script but the server responded with a MIME type of "text/plain"' error. This is often caused by missing or incorrect `.js` MIME type definitions in the Windows registry.
  Fix: This is an environment-specific issue. Potential workarounds include ensuring the Windows registry correctly associates `.js` files with `text/javascript` MIME type, or trying different web browsers.
• gotcha Viser's API is inherently stateful, and all data transfers between the Python server and the web client occur over a WebSocket connection. This can introduce network overhead, especially for frequent, high-bandwidth updates or complex user interactions requiring round-trip communication. Static web page exports with full interactivity are not directly supported.
  Fix: Optimize your data updates to minimize frequency and size where possible. For purely static scene exports without interactivity, consider using `server.get_scene_serializer().serialize()` to save the scene state to a `.viser` file.

Install

• pip install viser Install core library
• pip install "viser[examples]" Install with example dependencies

Imports

• ViserServer

  from viser import ViserServer

  This is the main class for instantiating the visualization server.

Quickstart

This quickstart code initializes a Viser server, adds a red sphere to the 3D scene, and includes a GUI slider to interactively control the sphere's X-axis position. Access the visualization by navigating to the printed URL in your web browser.

import time
import numpy as np
from viser import ViserServer

# Create a Viser server
server = ViserServer(port=8080, label='My Viser App')
print(f"Viser server started at: http://localhost:{server.get_port()}")

# Add a red sphere to the scene
server.scene.add_sphere(
    name="/my_sphere",
    position=(0.0, 0.0, 0.0),
    radius=0.5,
    color=(1.0, 0.0, 0.0)
)

# Add a simple GUI slider to control sphere's X position
x_position_slider = server.gui.add_slider(
    name="Sphere X Position",
    min=-2.0,
    max=2.0,
    step=0.1,
    initial_value=0.0
)

@x_position_slider.on_update
def _(field):
    current_position = list(server.scene["/my_sphere"].position)
    current_position[0] = field.value
    server.scene["/my_sphere"].position = tuple(current_position)

# Keep the server running indefinitely
server.sleep_forever()