newton.viewer.ViewerRTX#

class newton.viewer.ViewerRTX(width=1280, height=720, vsync=False, headless=False, paused=False, fps=60, up_axis='Z', num_frames=None, scaling=1.0, environment='default', async_rendering=True)[source]#

Bases: ViewerUSD

Real-time ray-traced viewer using NVIDIA OVRTX.

Builds a USD scene during the first simulation frame using the ViewerUSD base class, serializes it to disk, then creates an OVRTX renderer for real-time path-traced rendering. Subsequent frames update rigid-body transforms (and deforming-mesh vertices) via the OVRTX attribute API and present the rendered image in a pyglet / OpenGL window.

__init__(width=1280, height=720, vsync=False, headless=False, paused=False, fps=60, up_axis='Z', num_frames=None, scaling=1.0, environment='default', async_rendering=True)#

Initialize the OVRTX-backed real-time ray-tracing viewer.

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).

  • paused (bool) – Start the viewer in paused mode.

  • fps (int) – Stage frames-per-second metadata used by OVRTX.

  • up_axis (Literal['X', 'Y', 'Z']) – Scene up axis ("X", "Y" or "Z").

  • num_frames (int | None) – Number of frames to render in headless mode before is_running() returns False. None means run indefinitely. Ignored when a window is visible.

  • scaling (float) – Uniform world-scale applied at the /root xform.

  • environment (Literal['default', 'studio', 'none']) – Lighting preset; one of ENVIRONMENTS.

  • async_rendering (bool) – Submit OVRTX render work asynchronously and present the previous frame while the next one is still in flight.

activate(layer_id)#
add_background_usd(path)#

Add a reference to a background USD (e.g. Gaussian splat scan).

Must be called before the first frame (during the build phase).

Parameters:

path (str) – Absolute or relative path to a USD file.

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.

Parameters:

time (float) – Current simulation time [s].

clear_model()#

Reset RTX-specific model-dependent state to defaults.

Called when the current model is discarded (e.g. before set_model(), or when switching examples). Drops example-registered UI callbacks, releases the picking and wind helpers, and drains the async rendering pipeline before releasing the renderer.

close()#

Close the viewer and release rendering resources.

Waits for any in-flight asynchronous render, releases the OVRTX renderer, transform bindings, and the underlying pyglet window.

end_frame()#

Finish rendering the current frame.

On the first call, the RTX renderer is initialized from the USD stage built up during the build phase; subsequent calls update transforms and dispatch the next ray-traced render.

hide_loading_splash()#

Remove the splash set by show_loading_splash().

is_key_down(key)#

Check whether 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.

Returns:

True if the key is currently held down.

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.

In headless mode the viewer stops once num_frames is reached. In windowed mode the viewer keeps running until the user closes the window, ignoring num_frames so the window does not disappear unexpectedly.

Returns:

True while the viewer should continue rendering.

Return type:

bool

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

Log a gizmo GUI element for the given name and transform.

Parameters:

  • name (str) – The name of the gizmo.

  • transform (transformf) – The transform of the gizmo.

  • 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_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 previously registered via log_mesh().

  • xforms (wp.array(dtype=wp.transformf, ndim=1) | None) – Array of transforms.

  • scales (wp.array(dtype=wp.vec3f, ndim=1) | None) – Array of scales.

  • colors (wp.array(dtype=wp.vec3f, ndim=1) | None) – Array of colors.

  • materials (wp.array(dtype=wp.vec4f, ndim=1) | None) – Array of materials.

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

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

Log line segments for rendering.

Parameters:

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

  • starts (wp.array(dtype=wp.vec3f, ndim=1) | None) – Array of line start positions [m], shape [N, 3], or None for empty.

  • ends (wp.array(dtype=wp.vec3f, ndim=1) | None) – Array of line end positions [m], shape [N, 3], or None for empty.

  • colors (wp.array(dtype=wp.vec3f, ndim=1) | wp.array(dtype=wp.float32, ndim=1) | tuple[float, float, float] | list[float] | None) – Array of per-line RGB colors, a single RGB triplet, or None for empty.

  • width (float) – Line width [m].

  • 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(dtype=wp.vec3f, ndim=1)) – Vertex positions [m].

  • indices (wp.array(dtype=wp.int32, ndim=1) | wp.array(dtype=wp.uint32, ndim=1)) – Triangle indices.

  • normals (wp.array(dtype=wp.vec3f, ndim=1) | None) – Vertex normals.

  • uvs (wp.array(dtype=wp.vec2f, ndim=1) | None) – Vertex UVs.

  • texture (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(dtype=wp.vec3f, ndim=1) | None) – Array of point positions [m].

  • radii (wp.array(dtype=wp.float32, ndim=1) | float | None) – Per-point radii [m] or a single radius value.

  • colors (wp.array(dtype=wp.vec3f, ndim=1) | wp.array(dtype=wp.float32, ndim=1) | tuple[float, float, float] | list[float] | None) – Array of point colors, a single RGB triplet, or None.

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

log_state(state)#

Update the viewer with the given state of the simulation.

Parameters:

state (State) – The current state of the simulation.

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', 'rendering']) – 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 “rendering” - Extra items inside the Rendering Options section

save_screenshot(path)#

Save the last rendered frame to an image file.

The file format is inferred from the extension (e.g. .png, .jpg). Call this after at least one completed frame has been rendered (e.g. after the simulation loop). Works in headless mode.

set_camera(pos, pitch, yaw)#

Set the camera position, pitch, and yaw.

Parameters:

  • pos (vec3f) – Camera position [m].

  • pitch (float) – Camera pitch [deg].

  • yaw (float) – Camera yaw [deg].

set_model(model)#

Set the Newton model to visualize.

Parameters:

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

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_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 [m].

should_step()#

Return True if the loop should advance one step.

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

show_loading_splash(text=None)#

Display a centered Newton’s-cradle loading splash with optional sub-label.

Parameters:

text (str | None) – Optional sub-label drawn below the cradle.

ENVIRONMENTS = ('default', 'studio', 'none')#
property ui: Any | None#

Return the underlying UI object, or None if the GUI has not been created yet.

property vsync: bool#

Get the current vsync state.

Returns:

True if vsync is enabled, False otherwise.

Return type:

bool