newton.viewer.ViewerBase#

class newton.viewer.ViewerBase[source]#

Bases: ABC

class SDFMarginMode(*values)#

Bases: IntEnum

Controls which offset surface is visualized for SDF debug wireframes.

MARGIN = 1#

Wireframe at shape_margin only.

MARGIN_GAP = 2#

Wireframe at shape_margin + shape_gap (outer contact threshold), not gap alone.

OFF = 0#

Do not draw SDF margin debug wireframes.

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[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 (wp.array(dtype=wp.vec3f, ndim=1)) – 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).

clear_wireframe_vbo_cache()#

Clear the shared wireframe VBO cache (overridden by GL viewer).

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[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[wp.transform] | None) – Optional per-capsule transforms as a Warp transform array.

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

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

  • materials (wp.array[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[wp.transform] | None) – Optional per-instance transforms as a Warp transform array.

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

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

  • materials (wp.array[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[wp.vec3] | None) – Optional line start points as a Warp vec3 array.

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

  • colors (wp.array[wp.vec3] | wp.array[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[wp.vec3]) – Vertex positions as a Warp vec3 array.

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

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

  • uvs (wp.array[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[wp.vec3] | None) – Optional point positions as a Warp vec3 array.

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

  • colors (wp.array[wp.vec3] | wp.array[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[wp.transform]) – wp.array[wp.transform] of instance transforms

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

  • materials (wp.array[wp.vec4] | None) – wp.array[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.

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

Log a wireframe shape for rendering via the geometry-shader line pipeline.

Parameters:

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

  • vertex_data (ndarray | None) – (N, 6) float32 array of interleaved [px,py,pz, cr,cg,cb] line-segment vertices (pairs). Pass None to keep existing geometry and only update the transform.

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

  • hidden (bool) – Whether the wireframe shape should be hidden.

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

    Deprecated since version Use: set_visible_worlds() instead.

set_visible_worlds(worlds)#

Set which worlds are rendered.

Only shapes, joints, contacts, and other visualization elements belonging to the specified worlds will be sent to the viewer backend. Call with None to show all worlds (the default).

This method can be called between frames to dynamically change which worlds are visualized without recreating the model.

Parameters:

worlds (Sequence[int] | None) – Sequence of world indices to render, or None for all.

Raises:

RuntimeError – If the model has not been set yet.

set_world_offsets(spacing)#

Set world offsets for visual separation of multiple worlds.

When set_visible_worlds() restricts rendering to a subset, only the visible worlds receive compact grid positions.

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