newton.viewer.ViewerViser#

class newton.viewer.ViewerViser(*, port=8080, paused=False, label=None, verbose=True, share=False, record_to_viser=None, plot_history_size=250)[source]#

Bases: ViewerBase

ViewerViser provides a backend for visualizing Newton simulations using the viser library.

Viser is a Python library for interactive 3D visualization in the browser. This viewer launches a web server and renders simulation geometry via WebGL. It supports both standalone browser viewing and Jupyter notebook integration.

Features:

  • Real-time 3D visualization in any web browser

  • Jupyter notebook integration with inline display

  • Static HTML export for sharing visualizations

  • Interactive camera controls

  • Interactive transform gizmos and live scalar plots

  • Picking forces through click-to-create translation handles

Click a rendered body to create a picking handle at the hit point. Drag the handle to apply a spring force; releasing the handle drops the body. A cyan line connects the moving body anchor to the handle target.

classmethod get_viser_client_dir()#

Return the installed Viser client build for notebook playback.

__init__(*, port=8080, paused=False, label=None, verbose=True, share=False, record_to_viser=None, plot_history_size=250)#

Initialize the ViewerViser backend for Newton using the viser visualization library.

This viewer supports both standalone browser viewing and Jupyter notebook environments. It launches a web server that serves an interactive 3D visualization.

Parameters:

  • port (int) – Port number for the web server. Defaults to 8080.

  • paused (bool) – Whether simulation stepping starts paused.

  • label (str | None) – Optional label for the viser server window title.

  • verbose (bool) – If True, print the server URL when starting. Defaults to True.

  • share (bool) – If True, create a publicly accessible URL via viser’s share feature.

  • record_to_viser (str | None) – Path to record the viewer to a *.viser recording file (e.g. “my_recording.viser”). If None, the viewer will not record to a file.

  • plot_history_size (int) – Maximum number of samples kept per log_scalar() signal for the live time-series plots.

apply_forces(state)#

Apply picking forces for the active viewer layer.

Parameters:

state (State) – Current simulation state belonging to the active layer.

begin_frame(time)#

Begin a new frame.

Parameters:

time (float) – The current simulation time.

clear_all_layers()#

Clear all scenes and restore the default camera for example switching.

clear_model()#

Reset model-dependent state, including scalar plot buffers.

close()#

Close the viewer and clean up resources.

end_frame()#

End the current frame.

If recording is active, inserts a sleep command for playback timing. Updates scalar plots if any data changed since last frame.

hide_loading_splash()#

Remove notifications created by show_loading_splash().

is_paused()#

Check whether simulation stepping is paused.

Returns:

True if paused, False otherwise.

Return type:

bool

is_running()#

Check if the viewer is still running.

Returns:

True if the viewer is running, False otherwise.

Return type:

bool

log_array(name, array)#

Viser viewer does not visualize generic arrays.

Parameters:

  • name (str) – Unique path/name for the array signal.

  • array (wp.array[Any] | ndarray) – Array data to visualize.

log_gaussian(name, gaussian, xform=None, hidden=False)#

Log a newton.Gaussian splat asset using viser’s native Gaussian renderer.

Note: viser’s add_gaussian_splats is marked experimental upstream and its API may change or be removed in a future viser release.

Parameters:

  • name (str) – Unique path/name for the Gaussian splat asset.

  • gaussian (Gaussian | None) – The newton.Gaussian asset to visualize, with centers and per-axis scales in meters [m]. None removes any existing asset at name.

  • xform (transformf | None) – Optional world-space transform applied to the splat asset; its translation component is in meters [m].

  • hidden (bool) – Whether the splat asset should be hidden.

log_geo(name, geo_type, geo_scale, geo_thickness, geo_is_solid, geo_src=None, hidden=False)#

Log a geometry primitive, with plane expansion for infinite planes.

Parameters:

  • name (str) – Unique path/name for the geometry asset.

  • geo_type (int) – Geometry type value from newton.GeoType.

  • geo_scale (tuple[float, ...]) – Geometry scale tuple interpreted by geo_type.

  • geo_thickness (float) – Shell thickness for mesh-like geometry.

  • geo_is_solid (bool) – Whether mesh geometry is treated as solid.

  • geo_src (Mesh | Heightfield | None) – Optional source geometry for mesh-backed types.

  • hidden (bool) – Whether the resulting geometry is hidden.

log_gizmo(name, transform, *, translate=None, rotate=None, snap_to=None)#

Log or update an interactive Viser transform gizmo.

Translation arrows and rotation rings are separate, synchronized controls so each operation can honor its own enabled-axis set.

Parameters:

  • name (str) – Unique gizmo path/name.

  • transform (transformf) – Gizmo world transform with translation in meters and a unitless quaternion, mutated in place on interaction.

  • translate (Sequence[Axis] | None) – Axes on which translation handles are shown.

  • rotate (Sequence[Axis] | None) – Axes on which rotation rings are shown.

  • snap_to (transformf | None) – Optional world transform, with translation in meters and a unitless quaternion, applied when dragging ends.

log_image(name, image, *, fullscreen=False)#

Display a selected image stream in a persistent native Viser panel.

Parameters:

  • name (str) – Image stream name.

  • image (wp.array[Any] | ndarray) – Single image or image batch to display.

  • fullscreen (bool) – Accepted for viewer API compatibility and ignored by Viser.

log_instances(name, mesh, xforms, scales, colors, materials, hidden=False, opacities=None)#

Log instanced mesh data to viser using efficient batched rendering.

Uses viser’s add_batched_meshes_simple for GPU-accelerated instanced rendering. Supports in-place updates of transforms for real-time animation.

Parameters:

  • name (str) – Entity path for the instances.

  • mesh (str) – Name of the mesh asset to instance.

  • xforms (wp.array[wp.transformf] | None) – Instance transforms.

  • scales (wp.array[wp.vec3f] | None) – Instance scales.

  • colors (wp.array[wp.vec3f] | None) – Instance colors.

  • materials (wp.array[wp.vec4f] | None) – Instance materials.

  • hidden (bool) – Whether the instances are hidden.

  • opacities (wp.array[wp.float32] | None) – Instance opacities.

log_lines(name, starts, ends, colors, width=0.01, hidden=False)#

Log lines for visualization.

Parameters:

  • name (str) – Name of the line batch.

  • starts (wp.array[wp.vec3f] | None) – Line start points.

  • ends (wp.array[wp.vec3f] | None) – Line end points.

  • colors (wp.array[wp.vec3f] | wp.array[wp.float32] | tuple[float, float, float] | list[float] | None) – Line colors.

  • width (float) – Line width.

  • hidden (bool) – Whether the lines are hidden.

log_mesh(name, points, indices, normals=None, uvs=None, texture=None, hidden=False, backface_culling=True, color=None, roughness=None, metallic=None, dynamic=False, opacity=None)#

Log a mesh to viser for visualization.

Parameters:

  • name (str) – Entity path for the mesh.

  • points (wp.array[wp.vec3f]) – Vertex positions.

  • indices (wp.array[wp.int32] | wp.array[wp.uint32]) – Triangle indices.

  • normals (wp.array[wp.vec3f] | None) – Vertex normals, unused in viser.

  • uvs (wp.array[wp.vec2f] | None) – UV coordinates, used for textures if supported.

  • texture (ndarray | str | None) – Texture path/URL or image array (H, W, C).

  • hidden (bool) – Whether the mesh is hidden.

  • backface_culling (bool) – Whether to enable backface culling.

  • color (tuple[float, float, float] | None) – Optional base color as an RGB tuple with values in [0, 1]. Used when no texture is provided.

  • roughness (float | None) – Surface roughness in [0, 1]. 0 is perfectly smooth, 1 is fully rough.

  • metallic (float | None) – Metallicity in [0, 1]. 0 is dielectric, 1 is metal.

  • dynamic (bool) – Whether mesh topology may change between frames.

  • opacity (float | None) – Optional display opacity in [0, 1].

log_points(name, points, radii=None, colors=None, hidden=False)#

Log points for visualization.

Parameters:

  • name (str) – Name of the point batch.

  • points (wp.array[wp.vec3f] | None) – Point positions (can be a wp.array or a numpy array).

  • radii (wp.array[wp.float32] | float | None) – Point radii (can be a wp.array or a numpy array).

  • colors (wp.array[wp.vec3f] | wp.array[wp.float32] | tuple[float, float, float] | list[float] | None) – Point colors (can be a wp.array or a numpy array).

  • hidden (bool) – Whether the points are hidden.

log_scalar(name, value, *, clear=False, smoothing=1)#

Log a scalar value as a live time-series plot.

Each unique name creates a separate uPlot chart in a “Plots” folder in the GUI sidebar. Values are stored in a rolling buffer of the last plot_history_size samples.

Parameters:

  • name (str) – Unique path/name for the scalar signal.

  • value (int | float | bool | number) – Scalar value to record.

  • clear (bool) – If True, discard previously recorded samples for name before logging the new value.

  • smoothing (int) – Number of raw samples to average before committing a point to the plot history. Defaults to 1 (no smoothing).

log_state(state)#

Log simulation state with packed model-shape transfers.

Parameters:

state (State) – Current simulation state.

register_ui_callback(callback, position='side')#

Register an example UI callback using native Viser controls.

The common immediate-mode controls used by Newton examples are mapped to persistent Viser widgets. Viser has one control panel, so callback positions are accepted for API compatibility and rendered together in the Example Options folder.

Supported methods are button, checkbox, radio_button, slider_float, slider_int, input_float, text, separator, begin_disabled, end_disabled, and is_item_active (button hold state). These accept the signatures used by Newton examples, not every ImGui overload. same_line is a layout no-op: controls use the native panel’s vertical layout.

Callbacks run on the simulation thread even though the adapter’s is_available is False: that flag indicates a full ImGui context. Unsupported attributes raise AttributeError. For richer interfaces, use the native GUI API through server.

Parameters:

  • callback (Callable[[Any], None]) – Function receiving the limited control adapter described above.

  • position (Literal['side', 'stats', 'free', 'panel', 'rendering']) – ViewerGL callback position retained for compatibility.

save_recording()#

Save the current recording to a .viser file.

The recording can be played back in a static HTML viewer. See build_static_viewer() for creating the HTML player.

Note

Recording must be enabled by passing record_to_viser to the constructor.

Example

viewer = ViewerViser(record_to_viser="my_simulation.viser")
# ... run simulation ...
viewer.save_recording()
set_camera(pos, pitch=None, yaw=None)#

Set camera position and orientation for connected Viser clients.

The requested view is also cached so that newly connected clients receive the same camera setup as soon as they report camera state.

Parameters:

  • pos (vec3f) – Requested camera position [m].

  • pitch (float | None) – Requested camera pitch angle [deg]. If None, the current pitch is kept.

  • yaw (float | None) – Requested camera yaw angle [deg]. If None, the current yaw is kept.

set_model(model)#

Set the model and initialize interactive picking for it.

Parameters:

model (Model | None) – Model to visualize and interact with.

set_reset_callback(callback)#

Register a callback invoked when the user clicks the native Reset button.

Parameters:

callback (Callable[[], None] | None) – Called with no arguments on reset, or None to remove.

set_visible_worlds(worlds)#

Set visible worlds and keep picking visibility in sync.

Parameters:

worlds (Sequence[int] | None) – World indices to show, or None to show all worlds.

set_world_offsets(spacing)#

Set world offsets and keep picking coordinates in sync.

Parameters:

spacing (tuple[float, float, float] | list[float] | vec3f) – Spacing between worlds along each axis [m].

should_step()#

Apply browser interactions before the simulation advances.

Returns:

Whether the simulation should advance.

Return type:

bool

show_loading_splash(text=None)#

Display a loading notification over each connected Viser canvas.

Parameters:

text (str | None) – Loading message. Defaults to "Loading...".

show_notebook(width='100%', height=400)#

Show the viewer in a Jupyter notebook.

If recording is active, saves the recording and displays using the static HTML viewer with timeline controls. Otherwise, displays the live server in an IFrame.

Parameters:

  • width (int | str) – Width of the embedded player in pixels.

  • height (int | str) – Height of the embedded player in pixels.

Returns:

The display object.

Example

viewer = newton.viewer.ViewerViser(record_to_viser="my_sim.viser")
viewer.set_model(model)
# ... run simulation ...
viewer.show_notebook()  # Saves recording and displays with timeline
property picking_enabled: bool#

Whether rendered bodies can be selected for force picking.

property server: viser.ViserServer#

The Viser server for adding native GUI controls and scene content.

The viewer owns the server and stops it in close(). Viser callbacks run asynchronously; schedule simulation mutations on the simulation thread, for example through a queue consumed before stepping.

property ui: Any#

Return the example-GUI compatibility adapter.

The adapter intentionally reports is_available = False because it is not a full ImGui context, while callbacks passed directly to register_ui_callback() can use buttons, checkboxes, radio buttons, float/int sliders, float inputs, text, separators, disabled scopes, and button hold state. See that method for the complete supported subset. Use server for native Viser widgets beyond this subset.

property url: str#

Get the browser URL of the viser server.

Returns:

Browser URL for the running viser server.

Return type:

str