UsdRerunLogger¶

class UsdRerunLogger(stage, path_filter=None, recording_stream=None, save_path=None, application_id=None)[source]¶

Bases: object

Logs USD (Universal Scene Description) stages to Rerun.io for visualization.

This logger traverses a USD stage and logs all transforms and visual geometry (meshes, cubes, spheres, etc.) to a Rerun recording stream. It supports incremental logging, only re-logging transforms that have changed between calls to log_stage().

The recording stream can either be provided directly via recording_stream, or a new recording stream can be created that saves to save_path. If neither is provided, it will try to find it using rr.get_data_recording(). save_path takes precedence over recording_stream.

Parameters:

stage (Stage) – The USD stage to log. This is the root of the scene hierarchy that will be traversed and logged.
path_filter (str | list[str] | None) – Glob pattern(s) to filter which prims are logged. Can be a single pattern string or a list of patterns. Patterns starting with "!" are treated as exclusion patterns. For example, "/World/*" includes only prims under /World, while "!/World/Hidden/*" excludes prims under /World/Hidden. If None, all prims are logged.
recording_stream (RecordingStream | None) – The Rerun recording stream to use. Ignored if save_path is provided.
save_path (Path | str | None) – Path where the Rerun recording will be saved as an .rrd file. If provided, a new recording stream is created that saves to this path.
application_id (str | None) – Application ID for the Rerun recording. Used when creating a new recording stream (either via save_path or when falling back to a new stream). Defaults to "usd_logger" if not provided.

stage¶

The USD stage being logged.

Type:: Usd.Stage

recording_stream¶

The Rerun recording stream used for logging.

Type:: rr.RecordingStream

Notes

Meshes are logged only once (on first encounter) and tracked internally to avoid redundant logging.
Transforms are logged every time log_stage() is called, but only if they have changed since the last call.
Prims with purpose set to guide are skipped, along with their children.
Instance proxies (referenced/instanced prims) are traversed and logged.
When a prim is removed from the stage, it is automatically cleared from the Rerun recording.

Examples

Log a USD stage to the Rerun viewer:

import rerun as rr
from pxr import Usd
from usd_rerun_logger import UsdRerunLogger

rr.init("my_usd_viewer", spawn=True)
stage = Usd.Stage.Open("my_scene.usda")
logger = UsdRerunLogger(stage)
logger.log_stage()

Save the recording to a file:

stage = Usd.Stage.Open("my_scene.usda")
logger = UsdRerunLogger(stage, save_path="recording.rrd")
logger.log_stage()

Filter which prims are logged:

# Log only prims under /World/Robots, but exclude /World/Robots/Debug
logger = UsdRerunLogger(
    stage,
    path_filter=["/World/Robots/*", "!/World/Robots/Debug/*"]
)
logger.log_stage()

Animate a scene by logging at each time step:

rr.init("animated_scene", spawn=True)
stage = Usd.Stage.Open("animated.usda")
logger = UsdRerunLogger(stage)

for frame in range(100):
    # Update USD stage time code
    stage.SetTimeCode(frame)
    # Log current state - only changed transforms are re-logged
    rr.set_time_sequence("frame", frame)
    logger.log_stage()

__init__(stage, path_filter=None, recording_stream=None, save_path=None, application_id=None)[source]¶

Create the USD Rerun logger.

Parameters:

stage (Stage)
path_filter (str | list[str] | None)
recording_stream (RecordingStream | None)
save_path (Path | str | None)
application_id (str | None)

log_stage()[source]¶

Log the current state of the USD stage to Rerun.

Traverses all prims in the stage and logs their transforms and visual geometry. Transforms are only re-logged if they have changed since the last call. Meshes and other visual geometry are logged only once on first encounter.

Prims with purpose set to guide are skipped along with their children. Path filters (if configured) are applied to include/exclude specific prim paths.

When prims are removed from the stage between calls, they are automatically cleared from the Rerun recording.

property recording_stream: RecordingStream¶: The Rerun recording stream used for logging.

property stage: Stage¶: The USD stage being logged.