newton.viewer.ViewerGL

class newton.viewer.ViewerGL(width=1920, height=1080, vsync=False, headless=False, plot_history_size=250)

Bases: ViewerBase

OpenGL-based interactive viewer for Newton physics models.

This class provides a graphical interface for visualizing and interacting with Newton models using OpenGL rendering. It supports real-time simulation control, camera navigation, object picking, wind effects, and a rich ImGui-based UI for model introspection and visualization options.

Key Features:

• Real-time 3D rendering of Newton models and simulation states.

• Camera navigation with WASD/QE and mouse controls.

• Object picking and manipulation via mouse.

• Visualization toggles for joints, contacts, particles, springs, etc.

• Wind force controls and visualization.

• Performance statistics overlay (FPS, object counts, etc.).

• Selection panel for introspecting and filtering model attributes.

• Extensible logging of meshes, lines, points, and arrays for custom visualization.

__init__(width=1920, height=1080, vsync=False, headless=False, plot_history_size=250)

Initialize the OpenGL viewer and UI.

Parameters:

• width (int) – Window width in pixels.

• height (int) – Window height in pixels.

• vsync (bool) – Enable vertical sync.

• headless (bool) – Run in headless mode (no window).

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

apply_forces(state)

Apply viewer-driven forces (picking, wind) to the model.

Parameters:

state (State) – The current simulation state.

begin_frame(time)

Begin a new frame (calls parent implementation).

Parameters:

time (float) – Current simulation time.

clear_model()

Reset GL-specific model-dependent state to defaults.

Called from __init__ (via super().__init__ → clear_model) and whenever the current model is discarded.

clear_wireframe_vbo_cache()

close()

Close the viewer and clean up resources.

end_frame()

Finish rendering the current frame and process window events.

This method first updates the renderer which will poll and process window events. It is possible that the user closes the window during this event processing step, which would invalidate the underlying OpenGL context. Trying to issue GL calls after the context has been destroyed results in a crash (access violation). Therefore we check whether an exit was requested and early-out before touching GL if so.

get_frame(target_image=None, render_ui=False)

Retrieve the last rendered frame.

This method uses OpenGL Pixel Buffer Objects (PBO) and CUDA interoperability to transfer pixel data entirely on the GPU, avoiding expensive CPU-GPU transfers.

Parameters:

• target_image (array | None) – Optional pre-allocated Warp array with shape (height, width, 3) and dtype wp.uint8. If None, a new array will be created.

• render_ui (bool) – Whether to render the UI.

Returns:

GPU array containing RGB image data with shape (height, width, 3)

and dtype wp.uint8. Origin is top-left (OpenGL’s bottom-left is flipped).

Return type:

wp.array

is_key_down(key)

Check if a key is currently pressed.

Parameters:

key (str | int) –

Either a string representing a character/key name, or an int representing a pyglet key constant.

String examples: ‘w’, ‘a’, ‘s’, ‘d’, ‘space’, ‘escape’, ‘enter’ Int examples: pyglet.window.key.W, pyglet.window.key.SPACE

Returns:

True if the key is currently pressed, False otherwise.

Return type:

bool

is_paused()

Check if the simulation is paused.

Returns:

True if paused, False otherwise.

Return type:

bool

is_running()

Check if the viewer is still running.

Returns:

True if the window is open, False if closed.

Return type:

bool

log_array(name, array)

Log a numeric array for visualization.

Parameters:

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

• array (wp.array[Any] | np.ndarray | None) – Array data to visualize, or None to remove a previously logged array.

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

Log arrow data for rendering (screen-space quad line + arrowhead per segment).

Arrow size is controlled in screen-space pixels by RendererGL.arrow_scale.

Parameters:

• name (str) – Unique identifier for the arrow batch.

• starts (wp.array[wp.vec3] | None) – Array of arrow start positions (shape: [N, 3]) or None for empty.

• ends (wp.array[wp.vec3] | None) – Array of arrow end positions / arrowhead tips (shape: [N, 3]) or None for empty.

• colors (wp.array[wp.vec3] | wp.array[wp.float32] | tuple[float, float, float] | list[float] | None) – Array of arrow colors (shape: [N, 3]) or tuple/list of RGB or None for empty.

• width (float) – Reserved for future use (world-space line width). Currently ignored; pixel dimensions are controlled by RendererGL.arrow_scale.

• hidden (bool) – Whether the arrows are initially hidden.

log_capsules(name, mesh, xforms, scales, colors, materials, hidden=False)

Render capsules using instanced cylinder bodies + instanced sphere end caps.

This specialized path improves batching for varying-length capsules by reusing two prototype meshes (unit cylinder + unit sphere) and applying per-instance transforms/scales.

Parameters:

• name (str) – Unique name for the capsule instancer group.

• mesh (str) – Capsule prototype mesh path from ViewerBase (unused in this backend).

• xforms (wp.array[wp.transform] | None) – Capsule instance transforms (wp.transform), length N.

• scales (wp.array[wp.vec3] | None) – Capsule body instance scales, expected (radius, radius, half_height), length N.

• colors (wp.array[wp.vec3] | None) – Capsule instance colors (wp.vec3), length N or None (no update).

• materials (wp.array[wp.vec4] | None) – Capsule instance materials (wp.vec4), length N or None (no update).

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

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

Log a newton.Gaussian as a point cloud of spheres.

Parameters:

• name (str) – Unique path/name for the Gaussian point cloud.

• gaussian (Gaussian) – The newton.Gaussian asset to visualize.

• xform (transformf | None) – Optional world-space transform applied to all splat centers.

• hidden (bool) – Whether the point cloud should be hidden.

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

Log or update a transform gizmo for the current frame.

Parameters:

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

• transform (transformf) – Gizmo world transform.

• translate (Sequence[Axis] | None) – Axes on which the translation handles are shown. Defaults to all axes when None. Pass an empty sequence to hide all translation handles.

• rotate (Sequence[Axis] | None) – Axes on which the rotation rings are shown. Defaults to all axes when None. Pass an empty sequence to hide all rotation rings.

• snap_to (transformf | None) – Optional world transform to snap to when this gizmo is released by the user.

log_image(name, image)

See log_image().

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

Log a batch of mesh instances for rendering.

Parameters:

• name (str) – Unique name for the instancer.

• mesh (str) – Name of the base mesh.

• xforms (wp.array[wp.transform] | None) – Array of transforms.

• scales (wp.array[wp.vec3] | None) – Array of scales.

• colors (wp.array[wp.vec3] | None) – Array of colors.

• materials (wp.array[wp.vec4] | None) – Array of materials.

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

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

Log line data for rendering.

Lines are drawn as screen-space quads whose pixel width is set by RendererGL.line_width. The width parameter is currently unused and reserved for future world-space width support.

Parameters:

• name (str) – Unique identifier for the line batch.

• starts (wp.array[wp.vec3] | None) – Array of line start positions (shape: [N, 3]) or None for empty.

• ends (wp.array[wp.vec3] | None) – Array of line end positions (shape: [N, 3]) or None for empty.

• colors (wp.array[wp.vec3] | wp.array[wp.float32] | tuple[float, float, float] | list[float] | None) – Array of line colors (shape: [N, 3]) or tuple/list of RGB or None for empty.

• width (float) – Reserved for future use (world-space line width). Currently ignored; pixel width is controlled by RendererGL.line_width.

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

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

Log a mesh for rendering.

Parameters:

• name (str) – Unique name for the mesh.

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

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

• normals (wp.array[wp.vec3] | None) – Vertex normals.

• uvs (wp.array[wp.vec2] | None) – Vertex UVs.

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

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

• backface_culling (bool) – 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.

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

Log a batch of points for rendering as spheres.

Parameters:

• name (str) – Unique name for the point batch.

• points (wp.array[wp.vec3] | None) – Array of point positions.

• radii (wp.array[wp.float32] | float | None) – Array of point radius values.

• colors (wp.array[wp.vec3] | wp.array[wp.float32] | tuple[float, float, float] | list[float] | None) – Array of point colors.

• 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 line plot displayed in an auto-generated “Plots” window. 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 the current simulation state for rendering.

For shape instances on CUDA, uses a batched path: 2 kernel launches + 1 D2H copy to a shared pinned buffer, then uploads slices per instancer. Everything else (capsules, SDF, particles, joints, …) uses the standard path.

Parameters:

state (State) – Current simulation state for all rendered bodies/shapes.

log_wireframe_shape(name, vertex_data, world_matrix, hidden=False)

Log a wireframe shape for geometry-shader line rendering.

Parameters:

• name (str) – Unique path/name for the wireframe shape.

• vertex_data (ndarray | None) – (N, 6) float32 interleaved vertex data, or None to keep existing geometry.

• world_matrix (ndarray | None) – 4x4 float32 world matrix, or None to keep current.

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

on_key_press(symbol, modifiers)

Handle key press events for UI and simulation control.

Parameters:

• symbol (int) – Key symbol.

• modifiers (int) – Modifier keys.

on_key_release(symbol, modifiers)

Handle key release events (not used).

Parameters:

• symbol (int) – Released key code.

• modifiers (int) – Active modifier bitmask for this event.

on_mouse_drag(x, y, dx, dy, buttons, modifiers)

Handle mouse drag events for camera and picking.

Parameters:

• x (float) – Mouse X position in window coordinates.

• y (float) – Mouse Y position in window coordinates.

• dx (float) – Mouse delta along X since previous event.

• dy (float) – Mouse delta along Y since previous event.

• buttons (int) – Mouse buttons pressed.

• modifiers (int) – Modifier keys.

on_mouse_motion(x, y, dx, dy)

Handle mouse motion events (not used).

Parameters:

• x (float) – Mouse X position in window coordinates.

• y (float) – Mouse Y position in window coordinates.

• dx (float) – Mouse delta along X since previous event.

• dy (float) – Mouse delta along Y since previous event.

on_mouse_press(x, y, button, modifiers)

Handle mouse press events (object picking).

Parameters:

• x (float) – Mouse X position in window coordinates.

• y (float) – Mouse Y position in window coordinates.

• button (int) – Mouse button pressed.

• modifiers (int) – Modifier keys.

on_mouse_release(x, y, button, modifiers)

Handle mouse release events to stop dragging.

Parameters:

• x (float) – Mouse X position in window coordinates.

• y (float) – Mouse Y position in window coordinates.

• button (int) – Mouse button released.

• modifiers (int) – Modifier keys.

on_mouse_scroll(x, y, scroll_x, scroll_y)

Handle mouse scroll for dolly and FOV adjustment.

Parameters:

• x (float) – Mouse X position in window coordinates.

• y (float) – Mouse Y position in window coordinates.

• scroll_x (float) – Horizontal scroll delta.

• scroll_y (float) – Vertical scroll delta.

on_resize(width, height)

Handle window resize events.

Parameters:

• width (int) – New window width.

• height (int) – New window height.

register_ui_callback(callback, position='side')

Register a UI callback to be rendered during the UI phase.

Parameters:

• callback (Callable[[Any], None]) – Function to be called during UI rendering

• position (Literal['side', 'stats', 'free', 'panel']) – Position where the UI should be rendered. One of: “side” - Side callback (default) “stats” - Stats/metrics area “free” - Free-floating UI elements “panel” - Top-level collapsing headers in left panel

set_camera(pos, pitch, yaw)

Set the camera position, pitch, and yaw.

Parameters:

• pos (vec3f) – The camera position.

• pitch (float) – The camera pitch.

• yaw (float) – The camera yaw.

set_model(model, max_worlds=None)

Set the Newton model to visualize.

Parameters:

• model (Model | None) – The Newton model instance.

• max_worlds (int | None) – Maximum number of worlds to render (None = all).

set_reset_callback(callback)

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

Parameters:

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

set_visible_worlds(worlds)

set_world_offsets(spacing)

Set world offsets and update the picking system.

Parameters:

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

should_step()

Return True if the loop should advance one step.

Consumes a pending single-step request, so call exactly once per frame.

property vsync: bool

Get the current vsync state.

Returns:

True if vsync is enabled, False otherwise.

Return type:

bool