newton.viewer.ViewerBase#

class newton.viewer.ViewerBase[source]#

Bases: ABC

class ShapeInstances(name, static, flags, mesh, device)#

Bases: object

A batch of shape instances.

__init__(name, static, flags, mesh, device)#

Initialize the ShapeInstances.

add(parent, xform, scale, color, material, shape_index, world=-1)#

Add an instance of the geometry to the batch.

Parameters:

  • parent (int) – The parent body index.

  • xform (transformf) – The transform of the instance.

  • scale (vec3f) – The scale of the instance.

  • color (vec3f) – The color of the instance.

  • material (vec4f) – The material of the instance.

  • shape_index (int) – The shape index.

  • world (int) – The world index.

finalize(shape_colors=None)#

Allocates the batch of shape instances as Warp arrays.

Parameters:

shape_colors (wp.array(dtype=wp.vec3) | None) – The colors of the shapes.

update(state, world_offsets)#

Update the world transforms of the shape instances.

Parameters:

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

  • world_offsets (array(ndim=1, dtype=vec3f)) – The world offsets.

colors#

Color (vec3f) per instance.

colors_changed: bool#

Indicates that finalized ShapeInstances.colors changed and should be included in log_instances().

__init__()#

Initialize shared viewer state and rendering caches.

abstractmethod apply_forces(state)#

Apply forces to the state from picking and wind (if available).

Parameters:

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

begin_frame(time)#

Begin a new frame.

Parameters:

time (float) – The current frame time.

clear_model()#

Reset all model-dependent state to defaults.

Called from __init__ to establish initial values and whenever the current model needs to be discarded (e.g. before set_model() or when switching examples).

abstractmethod close()#

Close the viewer.

abstractmethod end_frame()#

End the current frame.

is_key_down(key)#

Default key query API. Concrete viewers can override.

Parameters:

key (str | int) – Key identifier (string or backend-specific code)

Returns:

Always False by default.

Return type:

bool

is_paused()#

Report whether the viewer is currently paused.

Returns:

True when simulation stepping is paused.

Return type:

bool

is_running()#

Report whether the viewer backend should keep running.

Returns:

True while the viewer should continue rendering.

Return type:

bool

abstractmethod log_array(name, array)#

Log a numeric array for backend-specific visualization utilities.

Parameters:

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

  • array (wp.array(dtype=Any) | np.ndarray) – Array data as a Warp array or NumPy array.

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

Log capsules as instances. This is a specialized path for rendering capsules. If the viewer backend does not specialize this path, it will fall back to log_instances().

Parameters:

  • name (str) – Unique path/name for the capsule batch.

  • mesh (str) – Path/name of a mesh previously registered via log_mesh().

  • xforms (wp.array(dtype=wp.transform) | None) – Optional per-capsule transforms as a Warp transform array.

  • scales (wp.array(dtype=wp.vec3) | None) – Optional per-capsule scales as a Warp vec3 array.

  • colors (wp.array(dtype=wp.vec3) | None) – Optional per-capsule colors as a Warp vec3 array.

  • materials (wp.array(dtype=wp.vec4) | None) – Optional per-capsule material parameters as a Warp vec4 array.

  • hidden (bool) – Whether the capsule batch should be hidden.

log_contacts(contacts, state)#

Creates line segments along contact normals for rendering.

Parameters:

  • contacts (Contacts) – The contacts to render.

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

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

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

Each Gaussian is rendered as a sphere positioned at its center, with radius equal to the largest per-axis scale and color derived from the DC spherical-harmonics coefficients.

The default implementation is a no-op. Override in viewer backends that support point-cloud rendering.

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_geo(name, geo_type, geo_scale, geo_thickness, geo_is_solid, geo_src=None, hidden=False)#

Create a primitive mesh and upload it via log_mesh().

Expects mesh generators to return interleaved vertices [x, y, z, nx, ny, nz, u, v] and an index buffer. Slices them into separate arrays and forwards to log_mesh.

Parameters:

  • name (str) – Unique path/name used to register the mesh.

  • 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 newton.Mesh or newton.Heightfield data when required by geo_type.

  • hidden (bool) – Whether the created mesh should be 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_hydro_contact_surface(contact_surface_data, penetrating_only=True)#

Render the hydroelastic contact surface triangles as wireframe lines.

Parameters:
abstractmethod log_instances(name, mesh, xforms, scales, colors, materials, hidden=False)#

Log a batch of mesh instances.

Parameters:

  • name (str) – Unique path/name for the instance batch.

  • mesh (str) – Path/name of a mesh previously registered via log_mesh().

  • xforms (wp.array(dtype=wp.transform) | None) – Optional per-instance transforms as a Warp transform array.

  • scales (wp.array(dtype=wp.vec3) | None) – Optional per-instance scales as a Warp vec3 array.

  • colors (wp.array(dtype=wp.vec3) | None) – Optional per-instance colors as a Warp vec3 array.

  • materials (wp.array(dtype=wp.vec4) | None) – Optional per-instance material parameters as a Warp vec4 array.

  • hidden (bool) – Whether the instance batch should be hidden.

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

Log line segments for rendering.

Parameters:

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

  • starts (wp.array(dtype=wp.vec3) | None) – Optional line start points as a Warp vec3 array.

  • ends (wp.array(dtype=wp.vec3) | None) – Optional line end points as a Warp vec3 array.

  • colors (wp.array(dtype=wp.vec3) | wp.array(dtype=wp.float32) | tuple[float, float, float] | list[float] | None) – Per-line colors as a Warp array, or a single RGB triplet.

  • width (float) – Line width in rendered scene units.

  • hidden (bool) – Whether the line batch should be hidden.

abstractmethod log_mesh(name, points, indices, normals=None, uvs=None, texture=None, hidden=False, backface_culling=True)#

Register or update a mesh prototype in the viewer backend.

Parameters:

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

  • points (wp.array(dtype=wp.vec3)) – Vertex positions as a Warp vec3 array.

  • indices (wp.array(dtype=wp.int32) | wp.array(dtype=wp.uint32)) – Triangle index buffer as a Warp integer array.

  • normals (wp.array(dtype=wp.vec3) | None) – Optional vertex normals as a Warp vec3 array.

  • uvs (wp.array(dtype=wp.vec2) | None) – Optional texture coordinates as a Warp vec2 array.

  • texture (np.ndarray | str | None) – Optional texture image array or path.

  • hidden (bool) – Whether the mesh should be hidden.

  • backface_culling (bool) – Whether back-face culling should be enabled.

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

Log a point cloud for rendering.

Parameters:

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

  • points (wp.array(dtype=wp.vec3) | None) – Optional point positions as a Warp vec3 array.

  • radii (wp.array(dtype=wp.float32) | float | None) – Optional per-point radii array or a single radius value.

  • colors (wp.array(dtype=wp.vec3) | wp.array(dtype=wp.float32) | tuple[float, float, float] | list[float] | None) – Optional per-point colors or a single RGB triplet.

  • hidden (bool) – Whether the points should be hidden.

abstractmethod log_scalar(name, value)#

Log a scalar signal for backend-specific visualization utilities.

Parameters:

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

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

log_shapes(name, geo_type, geo_scale, xforms, colors=None, materials=None, geo_thickness=0.0, geo_is_solid=True, geo_src=None, hidden=False)#

Convenience helper to create/cache a mesh of a given geometry and render a batch of instances with the provided transforms/colors/materials.

Parameters:

  • name (str) – Instance path/name (e.g., “/world/spheres”).

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

  • geo_scale (float | tuple[float, ...] | list[float] | np.ndarray) – Geometry scale parameters: - Sphere: float radius - Capsule/Cylinder/Cone: (radius, height) - Plane: (width, length) or float for both - Box: (x_extent, y_extent, z_extent) or float for all

  • xforms (wp.array(dtype=wp.transform)) – wp.array(dtype=wp.transform) of instance transforms

  • colors (wp.array(dtype=wp.vec3) | None) – wp.array(dtype=wp.vec3) or None (broadcasted if length 1)

  • materials (wp.array(dtype=wp.vec4) | None) – wp.array(dtype=wp.vec4) or None (broadcasted if length 1)

  • geo_thickness (float) – Optional thickness used for hashing and solidification.

  • geo_is_solid (bool) – If False, use shell-thickening for mesh-based geometry.

  • geo_src (newton.Mesh | newton.Heightfield | None) – Source geometry to use only when geo_type is newton.GeoType.MESH.

  • hidden (bool) – If True, the shape will not be rendered

log_state(state)#

Update the viewer with the given state of the simulation.

Parameters:

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

set_camera(pos, pitch, yaw)#

Set the camera position and orientation.

Parameters:

  • pos (vec3f) – The position of the camera.

  • pitch (float) – The pitch of the camera.

  • yaw (float) – The yaw of the camera.

set_model(model, max_worlds=None)#

Set the model to be visualized.

Parameters:

  • model (Model | None) – The Newton model to visualize.

  • max_worlds (int | None) – Maximum number of worlds to render (None = all). Useful for performance when training with many environments.

set_world_offsets(spacing)#

Set world offsets for visual separation of multiple worlds.

Parameters:

spacing (tuple[float, float, float] | list[float] | vec3f) – Spacing between worlds along each axis as a tuple, list, or wp.vec3. Example: (5.0, 5.0, 0.0) for 5 units spacing in X and Y.

Raises:

RuntimeError – If model has not been set yet

update_shape_colors(shape_colors)#

Set colors for a set of shapes at runtime. :param shape_colors: mapping from shape index -> color