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_arrows(name, starts, ends, colors, width=0.01, hidden=False)#

Log arrow segments (line + arrowhead) for rendering.

The GL viewer renders these with a dedicated arrow shader that draws a screen-space quad line body plus a triangular arrowhead per segment. Other backends fall back to log_lines().

Parameters:

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

  • starts (wp.array[wp.vec3] | None) – Optional arrow start points as a Warp vec3 array.

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

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

  • width (float) – Reserved for future use (world-space line width). Currently ignored; arrow size is set in screen-space pixels via the renderer (e.g. RendererGL.arrow_scale).

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

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

Render contact normals as arrows.

Each active rigid contact is drawn as an arrow from the contact point along the contact normal. When show_contacts is False the arrow batch is cleared.

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:
log_image(name, image)#

Log an image (or batch of images) for display in the viewer.

Parameters:

  • name (str) – Stable identifier. Subsequent calls with the same name update in place. In ViewerGL, each name gets one dockable window.

  • image (wp.array[Any] | np.ndarray) –

    Image array. Accepted shapes:

    • (H, W) – single grayscale image

    • (H, W, C) – single color image, C in (1, 3, 4)

    • (N, H, W) – batch of N grayscale images

    • (N, H, W, C) – batch of N color images, C in (1, 3, 4)

    Accepted dtypes: uint8 (values in [0, 255]) or float32 (values in [0, 1]). Values outside the range are clipped.

The base implementation is a no-op. Backends that render images (currently only ViewerGL) override this method.

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.

Lines are rendered as screen-space quads whose pixel width is controlled by the renderer (e.g. RendererGL.line_width). The width parameter is currently unused and reserved for future world-space width support.

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) – Reserved for future use (world-space line width). Currently ignored; line width is set in screen-space pixels via the renderer.

  • 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, color=None, roughness=None, metallic=None)#

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.

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

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, *, clear=False, smoothing=1)#

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.

  • 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_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.

should_step()#

Report whether the loop should advance one step.

Returns:

True when the simulation should step forward.

Return type:

bool

update_shape_colors(shape_colors)#

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