newton.viewer.ViewerUSD#

class newton.viewer.ViewerUSD(output_path, fps=60, up_axis='Z', num_frames=100, scaling=1.0, points_as_spheres=True)[source]#

Bases: ViewerBase

USD viewer backend for Newton physics simulations.

This backend creates a USD stage and manages mesh prototypes and instanced rendering using PointInstancers. It supports time-sampled transforms for efficient playback and visualization of simulation data.

__init__(output_path, fps=60, up_axis='Z', num_frames=100, scaling=1.0, points_as_spheres=True)#

Initialize the USD viewer backend for Newton physics simulations.

Parameters:

output_path (str) – Path to the output USD file.
fps (int) – Frames per second for time sampling. Default is 60.
up_axis (str) – USD up axis, either ‘Y’ or ‘Z’. Default is ‘Z’.
num_frames (int | None) – Maximum number of frames to record. Default is 100. If None, recording is unlimited.
scaling (float) – Uniform scaling applied to the scene root. Default is 1.0.
points_as_spheres (bool) – When True, log_points() renders points as a PointInstancer of Sphere prototypes scaled by radii, instead of flat Points splats. Default is True.

Raises:

ImportError – If the usd-core package is not installed.

apply_forces(state)#

USD backend does not apply interactive forces.

Parameters:: state (State) – Current simulation state.

begin_frame(time)#

Begin a new frame at the given simulation time.

Parameters:: time (float) – The simulation time for the new frame.

clear_model()#

close()#

Finalize and save the USD stage.

This should be called when all logging is complete to ensure the USD file is written.

end_frame()#

End the current frame.

This method is a placeholder for any end-of-frame logic required by the backend.

is_running()#

Check if the viewer is still running.

Returns:: False if the frame limit is exceeded, True otherwise.
Return type:: bool

log_array(name, array)#

Log array data (not implemented for USD backend).

This method is a placeholder and does not log array data in the USD backend.

Parameters:

name (str) – Unique path/name for the array signal.
array (wp.array[Any] | ndarray) – Array data to visualize.

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

Log a geometry prototype, as a native USD Gprim where one exists.

Spheres, capsules, cylinders, cones, boxes, and ellipsoids become UsdGeom Gprims; other types are tessellated via log_mesh().

Parameters:

name (str) – Unique path/name used to register the geometry.
geo_type (int) – Geometry type value from newton.GeoType.
geo_scale (tuple[float, ...]) – Geometry scale tuple, interpreted per geometry type.
geo_thickness (float) – Shell thickness for non-solid mesh generation.
geo_is_solid (bool) – Whether to render mesh geometry as a solid.
geo_src (Mesh | Heightfield | None) – Source mesh or heightfield for mesh-based geo_type values.
hidden (bool) – Whether the geometry should be hidden.

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.
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) – Array of opacity values.

log_instances_point_instancer(name, mesh, xforms, scales, colors, materials, *, opacities=None)#

Create or update a PointInstancer for mesh instances.

Parameters:

name (str) – Instancer name or Sdf.Path string.
mesh (str) – Mesh prototype name (must be previously logged).
xforms (wp.array[wp.transformf] | None) – Instance transforms as a warp array of wp.transform.
scales (wp.array[wp.vec3f] | ndarray | None) – Instance scales as a warp array of wp.vec3.
colors (wp.array[wp.vec3f] | wp.array[wp.float32] | tuple[float, float, float] | list[float] | ndarray | None) – Instance colors as a warp array of wp.vec3.
materials (wp.array[wp.vec4f] | None) – Instance materials as a warp array of wp.vec4.
opacities (wp.array[wp.float32] | None) – Instance opacities as a warp array of wp.float32.

Raises:

RuntimeError – If the mesh prototype is not found.

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

Debug helper to add a line list as a set of capsules

Parameters:

name (str) – Unique name for the line batch.
starts (wp.array[wp.vec3f] | None) – The vertices of the lines (wp.array)
ends (wp.array[wp.vec3f] | None) – The vertices of the lines (wp.array)
colors (wp.array[wp.vec3f] | wp.array[wp.float32] | tuple[float, float, float] | list[float] | None) – The colors of the lines (wp.array)
width (float) – The width of the lines.
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)#

Create a USD mesh prototype from vertex and index data.

The output is a polygonal mesh with explicit per-vertex normals. Missing normals are generated by averaging adjacent triangle normals, matching the smooth default of the OpenGL viewer. Source subdivision control surfaces are not reconstructed from the triangles.

Texture arrays are cached by object identity; a new array with the same pixels reuses the exported file after decoding and hashing it. Reuse the same array for unchanged frames to avoid that work. Pass a new array or path to replace an image; in-place edits are not detected. A call that omits texture or uvs removes a texture bound by an earlier call, as in ViewerGL, while omitted colors and material values persist. Material bindings are not time-sampled, so a replacement applies to the whole export.

Parameters:

name (str) – Mesh name or Sdf.Path string.
points (wp.array[wp.vec3f]) – Vertex positions as a warp array of wp.vec3.
indices (wp.array[wp.int32] | wp.array[wp.uint32]) – Triangle indices as a warp array of wp.uint32.
normals (wp.array[wp.vec3f] | None) – Vertex normals as a warp array of wp.vec3.
uvs (wp.array[wp.vec2f] | None) – UV coordinates as a warp array of wp.vec2.
texture (ndarray | str | None) – Optional texture path/URL or image array.
hidden (bool) – If True, mesh will be hidden.
backface_culling (bool) – If True, 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 as a USD primitive.

By default, each point is an instance of a UsdGeom.Sphere prototype under a UsdGeom.PointInstancer. Set points_as_spheres=False to write flat UsdGeom.Points splats instead.

Parameters:

name (str) – Unique name for the point primitive.
points (wp.array[wp.vec3f] | None) – Point positions.
radii (wp.array[wp.float32] | float | None) – Point radii or a single shared radius.
colors (wp.array[wp.vec3f] | wp.array[wp.float32] | tuple[float, float, float] | list[float] | None) – Optional per-point colors or a shared RGB triplet.
hidden (bool) – Whether the point primitive is hidden.

Returns:

Sdf.Path of the created/updated primitive.

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

Log scalar value (not implemented for USD backend).

This method is a placeholder and does not log scalar values in the USD backend.

Parameters:

name (str) – Unique path/name for the scalar signal.
value (int | float | bool | number) – Scalar value to visualize.
clear (bool) – Ignored by this backend.
smoothing (int) – Ignored by this backend.

notify_model_changed(flags)#