warp.render.UsdRenderer#

class warp.render.UsdRenderer(stage, up_axis='Y', fps=60, scaling=1.0)[source]#

USD-based renderer for creating 3D visualizations and animations.

This renderer writes geometric primitives, meshes, and point clouds to Universal Scene Description (USD) files, which can be viewed in USD-compatible applications such as USDView, applications built with the Omniverse Kit SDK, or Blender. It supports time-varying animations by recording geometry at different time codes.

The renderer provides methods to visualize geometric shapes (spheres, boxes, capsules, cylinders, cones), custom meshes, line primitives, and point clouds. All geometry is organized under a root transform that can be scaled uniformly.

Note

Requires USD to be installed. Install usd-core (pip install usd-core) or usd-exchange (pip install usd-exchange) on Linux aarch64 systems where usd-core is not available.

Parameters:

  • stage (str | Usd.Stage) – A USD stage (either a file path or a Usd.Stage object). If a string path is provided, a new USD stage will be created at that location.

  • up_axis (str) – The upfacing axis of the stage. Can be "X", "Y", or "Z".

  • fps (int) – The number of frames per second for animation playback.

  • scaling (float) – Uniform scaling factor applied to all entities in the scene.

__init__(stage, up_axis='Y', fps=60, scaling=1.0)[source]#
Parameters:

Methods

__init__(stage[, up_axis, fps, scaling])

add_shape_instance(name, shape, body, pos, rot)

Instance a previously defined shape.

begin_frame(time)

Set the current time code for subsequent writes.

end_frame()

End the current frame (no-op for USD).

register_body(body_name)

Create a transform prim for a body.

render_arrow(name, pos, rot, base_radius, ...)

Render an arrow composed of a cylinder and a cone.

render_box(name, pos, rot, extents[, ...])

Debug helper to add a box for visualization

render_capsule(name, pos, rot, radius, ...)

Debug helper to add a capsule for visualization

render_cone(name, pos, rot, radius, half_height)

Debug helper to add a cone for visualization

render_cylinder(name, pos, rot, radius, ...)

Debug helper to add a cylinder for visualization

render_ground([size, plane])

Render a ground plane.

render_line_list(name, vertices, indices[, ...])

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

render_line_strip(name, vertices[, color, ...])

Render a line strip as capsules.

render_mesh(name, points, indices[, colors, ...])

Create or update a mesh prim.

render_plane(name, pos, rot, width, length)

Render a plane with the given dimensions.

render_points(name, points, radius[, ...])

Render points as spheres or USD points.

render_ref(name, path, pos, rot, scale[, color])

Reference an external USD asset.

render_sphere(name, pos, rot, radius[, ...])

Debug helper to add a sphere for visualization

save()

Save the USD stage to disk.

update_body_transforms(body_q)

Update body transforms (deprecated).
begin_frame(time)[source]#

Set the current time code for subsequent writes.

Parameters:

time – Time in seconds.

end_frame()[source]#

End the current frame (no-op for USD).

register_body(body_name)[source]#

Create a transform prim for a body.

Parameters:

body_name – Name of the body prim under /root.

add_shape_instance(
name,
shape,
body,
pos,
rot,
scale=(1.0, 1.0, 1.0),
color1=None,
color2=None,
custom_index=-1,
visible=True,
)[source]#

Instance a previously defined shape.

Parameters:

  • name (str) – Name for the instance prim.

  • shape (int) – Shape prim path returned by a render_* method.

  • body – Optional parent body name.

  • pos (tuple) – Position tuple (x, y, z).

  • rot (tuple) – Orientation quaternion (x, y, z, w).

  • scale (tuple) – Scale tuple.

  • color1 – Optional color override (currently unused).

  • color2 – Optional secondary color override (currently unused).

  • custom_index (int) – Optional custom instance index (currently unused).

  • visible (bool) – Whether the instance is visible.

render_plane(
name,
pos,
rot,
width,
length,
color=(1.0, 1.0, 1.0),
color2=None,
parent_body=None,
is_template=False,
u_scaling=1.0,
v_scaling=1.0,
visible=True,
)[source]#

Render a plane with the given dimensions.

Parameters:

  • name (str) – Name of the plane

  • pos (tuple) – Position of the plane

  • rot (tuple) – Rotation of the plane

  • width (float) – Width of the plane

  • length (float) – Length of the plane

  • color (tuple[float, float, float]) – Color of the plane

  • parent_body (str | None) – Name of the parent body

  • is_template (bool) – Whether the plane is a template

  • u_scaling (float)

  • v_scaling (float)

  • visible (bool)

render_ground(size=100.0, plane=None)[source]#

Render a ground plane.

Parameters:

  • size (float) – Half-extent of the plane along each axis.

  • plane – Optional plane equation (nx, ny, nz, d) to orient and offset the plane.

render_sphere(
name,
pos,
rot,
radius,
parent_body=None,
is_template=False,
color=None,
visible=True,
)[source]#

Debug helper to add a sphere for visualization

Parameters:

  • pos (tuple) – The position of the sphere

  • radius (float) – The radius of the sphere

  • name (str) – A name for the USD prim on the stage

  • color (tuple[float, float, float] | None) – The color of the sphere

  • rot (tuple)

  • parent_body (str | None)

  • is_template (bool)

  • visible (bool)

render_capsule(
name,
pos,
rot,
radius,
half_height,
parent_body=None,
is_template=False,
up_axis=1,
color=None,
visible=True,
)[source]#

Debug helper to add a capsule for visualization

Parameters:

  • pos (tuple) – The position of the capsule

  • radius (float) – The radius of the capsule

  • half_height (float) – The half height of the capsule

  • name (str) – A name for the USD prim on the stage

  • color (tuple[float, float, float] | None) – The color of the capsule

  • rot (tuple)

  • parent_body (str | None)

  • is_template (bool)

  • up_axis (int)

  • visible (bool)

render_cylinder(
name,
pos,
rot,
radius,
half_height,
parent_body=None,
is_template=False,
up_axis=1,
color=None,
visible=True,
)[source]#

Debug helper to add a cylinder for visualization

Parameters:

  • pos (tuple) – The position of the cylinder

  • radius (float) – The radius of the cylinder

  • half_height (float) – The half height of the cylinder

  • name (str) – A name for the USD prim on the stage

  • color (tuple[float, float, float] | None) – The color of the cylinder

  • rot (tuple)

  • parent_body (str | None)

  • is_template (bool)

  • up_axis (int)

  • visible (bool)

render_cone(
name,
pos,
rot,
radius,
half_height,
parent_body=None,
is_template=False,
up_axis=1,
color=None,
visible=True,
)[source]#

Debug helper to add a cone for visualization

Parameters:

  • pos (tuple) – The position of the cone

  • radius (float) – The radius of the cone

  • half_height (float) – The half height of the cone

  • name (str) – A name for the USD prim on the stage

  • color (tuple[float, float, float] | None) – The color of the cone

  • rot (tuple)

  • parent_body (str | None)

  • is_template (bool)

  • up_axis (int)

  • visible (bool)

render_box(
name,
pos,
rot,
extents,
parent_body=None,
is_template=False,
color=None,
visible=True,
)[source]#

Debug helper to add a box for visualization

Parameters:

  • pos (tuple) – The position of the box

  • extents (tuple) – The radius of the box

  • name (str) – A name for the USD prim on the stage

  • color (tuple[float, float, float] | None) – The color of the box

  • rot (tuple)

  • parent_body (str | None)

  • is_template (bool)

  • visible (bool)

render_ref(name, path, pos, rot, scale, color=None)[source]#

Reference an external USD asset.

Parameters:

  • name (str) – Name for the reference prim.

  • path (str) – Path to the USD file.

  • pos (tuple) – Position tuple (x, y, z).

  • rot (tuple) – Orientation quaternion (x, y, z, w).

  • scale (tuple) – Scale tuple.

  • color (tuple | None) – Optional display color applied to referenced prims.

render_mesh(
name,
points,
indices,
colors=None,
pos=(0.0, 0.0, 0.0),
rot=(0.0, 0.0, 0.0, 1.0),
scale=(1.0, 1.0, 1.0),
update_topology=False,
parent_body=None,
is_template=False,
smooth_shading=True,
visible=True,
)[source]#

Create or update a mesh prim.

Parameters:

  • name (str) – Name for the mesh prim.

  • points – Vertex positions.

  • indices – Triangle indices.

  • colors – Display colors (constant or per-vertex).

  • pos – Position tuple (x, y, z).

  • rot – Orientation quaternion (x, y, z, w).

  • scale – Scale tuple.

  • update_topology – Whether to update index data.

  • parent_body (str | None) – Optional parent body name.

  • is_template (bool) – Whether to create an instanced template.

  • smooth_shading (bool) – Reserved for future use.

  • visible (bool) – Whether the mesh is visible.

Returns:

The prim path of the mesh or template.

render_arrow(
name,
pos,
rot,
base_radius,
base_height,
cap_radius=None,
cap_height=None,
parent_body=None,
is_template=False,
up_axis=1,
color=None,
visible=True,
)[source]#

Render an arrow composed of a cylinder and a cone.

Parameters:

  • name (str) – Name for the arrow prim.

  • pos (tuple) – Position tuple (x, y, z).

  • rot (tuple) – Orientation quaternion (x, y, z, w).

  • base_radius (float) – Radius of the arrow shaft.

  • base_height (float) – Height of the arrow shaft.

  • cap_radius (float | None) – Radius of the arrow head.

  • cap_height (float | None) – Height of the arrow head.

  • parent_body (str | None) – Optional parent body name.

  • is_template (bool) – Whether to create an instanced template.

  • up_axis (int) – Up-axis index (0=X, 1=Y, 2=Z).

  • color (tuple[float, float, float] | None) – Optional display color.

  • visible (bool) – Whether the arrow is visible.

Returns:

The prim path of the arrow.

render_line_list(
name,
vertices,
indices,
color=None,
radius=0.01,
visible=True,
)[source]#

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

Parameters:

  • vertices – The vertices of the line-strip

  • color (tuple[float, float, float] | None) – The color of the line

  • time – The time to update at

  • name (str)

  • radius (float)

  • visible (bool)

render_line_strip(
name,
vertices,
color=None,
radius=0.01,
visible=True,
)[source]#

Render a line strip as capsules.

Parameters:

  • name (str) – Name for the line strip prim.

  • vertices – Polyline vertices.

  • color (tuple[float, float, float] | None) – Display color for the capsules.

  • radius (float) – Capsule radius.

  • visible (bool) – Whether the line strip is visible.

render_points(
name,
points,
radius,
colors=None,
as_spheres=True,
visible=True,
)[source]#

Render points as spheres or USD points.

Parameters:

  • name (str) – Name for the points prim.

  • points – Point positions.

  • radius – Scalar or per-point radius.

  • colors – Optional display colors.

  • as_spheres (bool) – Whether to render as sphere instances.

  • visible (bool) – Whether the points are visible.

Returns:

The prim path for the points.

update_body_transforms(body_q)[source]#

Update body transforms (deprecated).

Deprecated since version 1.11: This method references non-existent attributes (self.model and self.body_names) and will be removed in a future release.

save()[source]#

Save the USD stage to disk.

Returns:

True if saving succeeded, False otherwise.