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, *, plot_history_size=250, ovstage=None, render_settings=None)[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 0.3 attribute interface or the OVStage interface used by OVRTX 0.4 and newer, and present the rendered image in a pyglet / OpenGL window. Debug markers and custom mesh instances can also be added after rendering starts.

__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, *, plot_history_size=250, ovstage=None, render_settings=None)#

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 viewer-loop frames in headless mode before is_running() returns False. None means run indefinitely. Includes rendering-paused frames. 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.

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

  • ovstage (ovstage.Stage | None) – Populated stage to render instead of a scene built from the model; see Rendering an existing USD scene. log_state() writes each body’s world pose to the stage prim whose path is the body’s body_label, keeping the prim’s authored scale; bodies without such a prim are not rendered. If the import re-oriented the stage (up-axis alignment or xform), set_model() infers the model-to-stage transform from the root bodies’ poses, which must still be the imported ones, and applies it to bodies, camera, and debug geometry. The caller owns the stage’s content, lights, and lifetime; the viewer adds its camera, render product, and debug geometry under /__newton_viewer. The viewer generates no geometry for the model’s shapes, cloth, or particles; show_triangles (off by default here) and show_particles draw simulated cloth and particles as debug overlays. set_visible_worlds(), show_collision, and show_visual affect only the debug geometry, environment must stay "default", and layers are not supported. set_model() and end_frame() write above the stage’s current write floor and then advance it, so finish other writes to the stage first. Bound prims keep their last world pose after the viewer releases the stage. Requires OVRTX 0.4 and OVStage 0.2 or newer, and a stage created with GPU hierarchy computation.

  • render_settings (dict[str, tuple[str, Any]] | None) – omni:rtx:* attributes to author on the viewer’s render product as {name: (usd_type_name, value)}, e.g. {"omni:rtx:pt:samplesPerPixel": ("uint", 4)}. The type is a USD type name or its Sdf.ValueTypeNames attribute ("UInt").

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_all_layers()#

Reset the RTX viewer as one complete layered scene.

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 runtime scene and OVRTX renderer, and closes 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.

get_frame(*, output=None, render_ui=False)#

Retrieve the last rendered frame as RGB image data.

Like ViewerGL.get_frame(), this returns a Warp array on the viewer device. Call .numpy() on the result for a NumPy array. Works in headless mode and reads the RTX render output through CPU memory. Call after end_frame(). With asynchronous rendering, capture waits for the render submitted by that call so the image contains the latest logged state. While rendering is paused, capture returns the frozen displayed image without waiting for a pending render. Capturing fullscreen images displayed with log_image(..., fullscreen=True) is not supported; capture resumes after the next scene render.

Parameters:

  • output (wp.array3d[wp.uint8] | None) – Optional pre-allocated Warp array on the viewer device with shape (height, width, 3) and dtype wp.uint8. If None, a new array is created.

  • render_ui (bool) – Whether to include UI overlays. Only False is supported because RTX capture reads the renderer output.

Returns:

RGB image data on the viewer device with shape (height, width, 3) and dtype wp.uint8. The origin is top-left and the dimensions are the fixed render resolution. If supplied, returns output.

Raises:

  • RuntimeError – No rendered frame or color output is available.

  • ValueError – The output shape, dtype, or device is incompatible.

  • NotImplementedError – render_ui is True or the last frame displayed a fullscreen logged image.

Return type:

wp.array3d[wp.uint8]

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_array(name, array)#

Log a numeric array as a live heatmap.

Scalars appear as a single cell, 1-D arrays as a single row, and 2-D arrays as a grid. Higher-dimensional arrays are not supported.

Parameters:

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

  • array (wp.array[Any] | 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 arrows as cylinder shafts with cone heads.

Parameters:

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

  • starts (wp.array[wp.vec3f] | None) – Arrow start positions [m], shape [N, 3], or None for empty.

  • ends (wp.array[wp.vec3f] | None) – Arrow tip positions [m], shape [N, 3], or None for empty.

  • colors (wp.array[wp.vec3f] | wp.array[wp.float32] | tuple[float, float, float] | list[float] | None) – Per-arrow RGB colors, a single RGB triplet, or None for empty.

  • width (float) – Shaft radius [m]. The head radius is twice this value.

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

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_image(name, image, *, fullscreen=False)#

See log_image().

Ignored in headless mode, which has no window to display images in.

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

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[wp.transformf] | None) – Array of transforms.

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

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

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

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

  • opacities (wp.array[wp.float32] | None) – Optional per-instance opacity values.

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[wp.vec3f] | None) – Array of line start positions [m], shape [N, 3], or None for empty.

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

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

  • width (float) – Line radius [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, dynamic=False, opacity=None)#

Log a mesh for rendering.

Parameters:

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

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

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

  • normals (wp.array[wp.vec3f] | None) – Vertex normals. If omitted, generate normals from the current triangle geometry, matching the USD and OpenGL viewers.

  • uvs (wp.array[wp.vec2f] | 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.

  • 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 a batch of points for rendering as spheres.

Parameters:

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

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

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

  • colors (wp.array[wp.vec3f] | wp.array[wp.float32] | 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_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)#

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.

Deprecated since version 1.7: Use get_frame() and an image library instead, for example PIL.Image.fromarray(viewer.get_frame().numpy()).save(path).

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. While rendering is paused, capture returns the frozen image.

Parameters:

path (str) – Output image filename.

Raises:

RuntimeError – No completed image exists, or the renderer has no color output.

set_camera(pos, pitch=None, yaw=None)#

Set the camera position, pitch, and yaw.

Parameters:

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

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

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

set_model(model)#

Set the Newton model to visualize.

Parameters:

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

set_rendering_paused(paused)#

See newton.viewer.ViewerBase.set_rendering_paused().

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