Python API Reference

The Python API provides a high-level interface to the ovrtx rendering library.

Known Limitations

In the current version, you cannot use the usd-core package from PyPI. If you wish to use OpenUSD in the same process as ovrtx, you must use the same version of OpenUSD as the one used to build ovrtx. This means that you must use OpenUSD v25.11, built as non-monolithic libraries with Python support enabled (the default). You must also use oneTBB v2021.13.0 or later when building OpenUSD.

This limitation will be lifted in a future version of ovrtx.

ovrtx

class ovrtx.Renderer

Bases: object

High-level Pythonic renderer for OVRTX.

Wraps the C library with automatic resource management. Resources are cleaned up automatically when the renderer goes out of scope.

Example

from ovrtx import Renderer, RendererConfig

# Use defaults
renderer = Renderer()

# Or customize
config = RendererConfig(mdl_base_path="custom/mdl/", sync_mode=True)
renderer = Renderer(config=config)

# Resources automatically cleaned up when renderer goes out of scope

__init__(config=None)

Create a new renderer instance.

Parameters:

config (RendererConfig | None) – Optional renderer configuration. If None, uses default configuration.

Raises:

RuntimeError – If the renderer cannot be created.

__del__()

Automatically clean up renderer resources on destruction.

add_usd(usd_file_path, path_prefix=None)

Add a USD file to the renderer (synchronous).

Blocks until the USD file is fully loaded.

Parameters:

• usd_file_path (str) – Path to the USD file to add.

• path_prefix (str | None) – Optional path prefix for the USD stage.

Returns:

USD handle for the loaded stage.

Raises:

RuntimeError – If renderer is invalid, enqueue fails, or loading fails.

Return type:

Any

Example

usd_handle = renderer.add_usd("/path/to/scene.usda")

add_usd_async(usd_file_path, path_prefix=None)

Add a USD file to the renderer (asynchronous).

Returns immediately with an Operation for manual control. Advanced users can use this for custom timeout handling or polling.

Parameters:

• usd_file_path (str) – Path to the USD file to add.

• path_prefix (str | None) – Optional path prefix for the USD stage.

Returns:

Operation that can be polled or waited on with custom timeout.

Raises:

RuntimeError – If renderer is invalid or enqueue fails.

Return type:

Operation[Any]

Example

# Poll with custom timeout
op = renderer.add_usd_async("/path/to/scene.usda")
usd_handle = op.wait(timeout_ns=1_000_000_000)  # 1 second
if usd_handle is None:
    print("Still loading...")
else:
    print(f"Loaded: {usd_handle}")

add_usd_layer(usd_layer_content, path_prefix=None)

Add inline USD layer content to the renderer (synchronous).

Blocks until the USD layer is fully loaded.

Parameters:

• usd_layer_content (str) – USDA content as a Python string. Must set defaultPrim for reference composition to work correctly.

• path_prefix (str | None) – Path where layer is composed. Absolute paths in layer content must match this prefix. Cannot reuse an existing prim path.

Returns:

USD handle for the loaded layer.

Raises:

• RuntimeError – If renderer is invalid, enqueue fails, or loading fails.

• ValueError – If usd_layer_content is empty.

Return type:

Any

Example

renderer.add_usd("/path/to/scene.usda")
renderer.add_usd_layer('''
#usda 1.0
(defaultPrim = "Render")
def Scope "Render" {
    def RenderProduct "Camera" { rel camera = </World/Camera> }
}
''', path_prefix="/Render")

add_usd_layer_async(usd_layer_content, path_prefix=None)

Add inline USD layer content to the renderer (asynchronous).

Returns immediately with an Operation for manual control.

Parameters:

• usd_layer_content (str) – USDA content as a Python string. Must set defaultPrim for reference composition to work correctly.

• path_prefix (str | None) – Path where layer is composed. Absolute paths in layer content must match this prefix. Cannot reuse an existing prim path.

Returns:

Operation that can be polled or waited on with custom timeout.

Raises:

• RuntimeError – If renderer is invalid or enqueue fails.

• ValueError – If usd_layer_content is empty.

Return type:

Operation[Any]

Example

op = renderer.add_usd_layer_async('''
#usda 1.0
(defaultPrim = "Inline")
def Xform "Inline" { ... }
''', path_prefix="/Inline")
op.wait()

remove_usd(usd_handle)

Remove a previously added USD from the runtime stage.

Parameters:

usd_handle (Any) – Handle returned from add_usd() or add_usd_layer().

Raises:

RuntimeError – If the removal fails.

Return type:

None

remove_usd_async(usd_handle)

Remove a previously added USD (async).

Parameters:

usd_handle (Any) – Handle returned from add_usd() or add_usd_layer().

Returns:

Operation that completes when USD is removed.

Raises:

RuntimeError – If renderer is invalid or enqueue fails.

Return type:

Operation[None]

update_from_usd_time(usd_time)

Update runtime stage to a specific USD time.

Updates all time-sampled attributes in the runtime stage to the provided USD time. Use this for animated USD scenes to evaluate attributes at different times.

Parameters:

usd_time (float) – USD time to update the stage to.

Raises:

RuntimeError – If the update fails.

Return type:

None

clone_usd(source_path, target_paths)

Clone a USD subtree to one or more target paths.

Creates copies of the prim at source_path at each target path.

Parameters:

• source_path (str) – Path to the source prim to clone.

• target_paths (List[str]) – List of target paths for the clones.

Raises:

• RuntimeError – If the clone operation fails.

• ValueError – If target_paths is empty.

Return type:

None

clone_usd_async(source_path, target_paths)

Clone a USD subtree (async).

Parameters:

• source_path (str) – Path to the source prim to clone.

• target_paths (List[str]) – List of target paths for the clones.

Returns:

Operation that completes when cloning is done.

Raises:

• RuntimeError – If renderer is invalid or enqueue fails.

• ValueError – If target_paths is empty.

Return type:

Operation[None]

step(render_products, delta_time)

Step the renderer (synchronous - blocks until complete).

Enqueues a step operation, waits for rendering to complete, and returns results. This is the simple, blocking interface suitable for most use cases.

Parameters:

• render_products (set[str]) – Set of render product paths to step.

• delta_time (float) – Time delta for the simulation step.

Returns:

RenderProductSetOutputs with rendering results.

Raises:

• RuntimeError – If renderer is invalid, enqueue fails, or rendering fails.

• ValueError – If no valid render products provided.

Return type:

RenderProductSetOutputs[Any]

Example

products = renderer.step(render_products={"/Render/..."}, delta_time=0.1)
for product_name, product in products.products.items():
    print(f"Rendered {product_name}")

step_async(render_products, delta_time)

Step the renderer (asynchronous - returns immediately).

Enqueues a step operation and returns result for advanced control. Use this for custom timeout handling or polling.

Parameters:

• render_products (set[str]) – Set of render product paths to step.

• delta_time (float) – Time delta for the simulation step.

Returns:

RendererResult that can be waited on with custom timeouts.

Raises:

• RuntimeError – If renderer is invalid or enqueue fails.

• ValueError – If no valid render products provided.

Return type:

RendererResult[Any]

Example

result = renderer.step_async(render_products={"/Render/..."}, delta_time=0.1)
# Poll without blocking
metadata = result.wait(step_timeout_ns=0)
if metadata is None:
    print("Still rendering...")
else:
    print("Done!")

reset(time=0.0)

Reset sensor simulation history to a specific time.

Clears accumulated rendering history for all render products and sets the simulation start time for future step() calls.

Parameters:

time (float) – Simulation time to reset to (default: 0.0).

Raises:

RuntimeError – If the reset fails.

Return type:

None

reset_async(time=0.0)

Reset sensor simulation history (async).

Parameters:

time (float) – Simulation time to reset to (default: 0.0).

Returns:

Operation that completes when reset is done.

Raises:

RuntimeError – If renderer is invalid or enqueue fails.

Return type:

Operation[None]

reset_stage()

Reset stage to empty state.

Clears all USD content from the runtime stage. After this call, the stage will be empty and new USD content can be loaded.

Raises:

RuntimeError – If the reset fails.

Return type:

None

reset_stage_async()

Reset stage to empty state (async).

Returns:

Operation that completes when stage is cleared.

Raises:

RuntimeError – If renderer is invalid or enqueue fails.

Return type:

Operation[None]

write_attribute(

prim_paths,

attribute_name,

tensor,

semantic=None,

dirty_bits=None,

prim_mode='existing_only',

)

Write scalar attribute data synchronously.

For repeated writes to the same attribute, consider using bind_attribute() followed by binding.write() for better performance.

Parameters:

• prim_paths (List[str]) – List of prim paths to write to.

• attribute_name (str) – Name of the attribute.

• tensor (DLTensor) – Single DLTensor with one element per prim.

• semantic (str | None) – Semantic string (“transform_4x4”, “color_rgba4b”, “color_rgb3f”). If provided, dtype is inferred and validated against tensor’s dtype.

• dirty_bits (bytes | None) – Optional dirty bit array for selective updates.

• prim_mode (str) – Prim mode (“existing_only”, “must_exist”, or “create_new”).

Raises:

• RuntimeError – If renderer is invalid or write fails.

• ValueError – If invalid parameters.

Return type:

None

Example

matrix = Matrix4d()
matrix.SetIdentity()
renderer.write_attribute(
    prim_paths=["/World/Cube"],
    attribute_name="omni:fabric:worldMatrix",
    tensor=matrix.to_dltensor(),
    semantic="transform_4x4"
)

write_array_attribute(

prim_paths,

attribute_name,

tensors,

dirty_bits=None,

prim_mode='existing_only',

)

Write array attribute data synchronously.

Array attributes (e.g., float3[] points) may have variable lengths per prim. Each tensor in the list corresponds to one prim.

Parameters:

• prim_paths (List[str]) – List of prim paths to write to.

• attribute_name (str) – Name of the array attribute.

• tensors (List[DLTensor]) – List of DLTensor, one per prim. Lengths may differ but element dtype must match the USD attribute schema. Must be CPU tensors; for GPU data, copy to CPU first (e.g., arr.numpy()).

• dirty_bits (bytes | None) – Optional dirty bit array for selective updates.

• prim_mode (str) – Prim mode (“existing_only”, “must_exist”, or “create_new”).

Raises:

• RuntimeError – If renderer is invalid or write fails.

• ValueError – If invalid parameters or dtype mismatch.

Return type:

None

Note

Tensor dtype must exactly match the USD attribute’s element type:

• int[] → np.int32

• float3[] → np.float32 with shape (N, 3)

• double3[] → np.float64 with shape (N, 3)

Using the wrong dtype (e.g., numpy’s default float64 for a float3 attribute) will cause an element size mismatch error.

Example

from ovrtx._src.dlpack import DLTensor
# int[] attribute - use int32
face_counts = np.array([4, 4, 4], dtype=np.int32)
renderer.write_array_attribute(
    prim_paths=["/World/Mesh"],
    attribute_name="faceVertexCounts",
    tensors=[DLTensor.from_dlpack(face_counts)]
)
# float3[] attribute - use float32 with shape (N, 3)
points = np.array([[0, 0, 0], [1, 0, 0]], dtype=np.float32)
renderer.write_array_attribute(
    prim_paths=["/World/Mesh"],
    attribute_name="points",
    tensors=[DLTensor.from_dlpack(points)]
)

write_attribute_async(

prim_paths,

attribute_name,

tensor,

semantic=None,

dirty_bits=None,

prim_mode='existing_only',

)

Write scalar attribute data asynchronously.

Parameters:

• prim_paths (List[str]) – List of prim paths to write to.

• attribute_name (str) – Name of the attribute.

• tensor (DLTensor) – Single DLTensor with one element per prim.

• semantic (str | None) – Semantic string (dtype inferred if provided).

• dirty_bits (bytes | None) – Optional dirty bit array for selective updates.

• prim_mode (str) – Prim mode string.

Returns:

Operation for async control (yields None on completion).

Return type:

Operation[None]

write_array_attribute_async(

prim_paths,

attribute_name,

tensors,

dirty_bits=None,

prim_mode='existing_only',

)

Write array attribute data asynchronously.

Parameters:

• prim_paths (List[str]) – List of prim paths to write to.

• attribute_name (str) – Name of the array attribute.

• tensors (List[DLTensor]) – List of DLTensor, one per prim. Element dtype must match the USD attribute schema. Must be CPU tensors; for GPU data, copy to CPU first (e.g., arr.numpy()).

• dirty_bits (bytes | None) – Optional dirty bit array for selective updates.

• prim_mode (str) – Prim mode string.

Returns:

Operation for async control (yields None on completion).

Return type:

Operation[None]

See also

write_array_attribute() for dtype matching requirements.

bind_attribute(

prim_paths,

attribute_name,

semantic=None,

dtype=None,

prim_mode='existing_only',

)

Create a persistent binding for scalar attribute writes.

Creates a binding handle that can be reused for multiple write() calls, avoiding the overhead of recreating the binding descriptor each time.

Parameters:

• prim_paths (List[str]) – List of prim paths.

• attribute_name (str) – Name of the attribute.

• semantic (str | None) – Semantic string (“transform_4x4”, “color_rgba4b”, “color_rgb3f”). If provided, dtype is inferred automatically.

• dtype (DLDataType | None) – DLDataType for the attribute. Required only if semantic is None.

• prim_mode (str) – Prim mode (“existing_only”, “must_exist”, or “create_new”).

Returns:

AttributeBinding[DLTensor] for scalar attribute writes.

Return type:

AttributeBinding[DLTensor]

Example

binding = renderer.bind_attribute(
    prim_paths=["/World/Cube"],
    attribute_name="omni:fabric:worldMatrix",
    semantic="transform_4x4"
)
binding.write(matrix.to_dltensor())
binding.unbind()

bind_attribute_async(

prim_paths,

attribute_name,

semantic=None,

dtype=None,

prim_mode='existing_only',

)

Create a persistent binding for scalar attribute writes (async).

Parameters:

• prim_paths (List[str])

• attribute_name (str)

• semantic (str | None)

• dtype (DLDataType | None)

• prim_mode (str)

Return type:

Operation[AttributeBinding[DLTensor]]

bind_array_attribute(

prim_paths,

attribute_name,

dtype=None,

prim_mode='existing_only',

)

Create a persistent binding for array attribute writes.

Array attributes (e.g., float3[] points) may have variable lengths per prim. The binding locks in the element dtype; subsequent writes can have varying tensor lengths but must use the same element type.

Parameters:

• prim_paths (List[str]) – List of prim paths.

• attribute_name (str) – Name of the array attribute.

• dtype (DLDataType | None) – DLDataType for the attribute elements. Must match the USD attribute schema (e.g., int32 for int[], float32 for float3[]).

• prim_mode (str) – Prim mode (“existing_only”, “must_exist”, or “create_new”).

Returns:

AttributeBinding[List[DLTensor]] for array attribute writes.

Return type:

AttributeBinding[List[DLTensor]]

Note

The dtype specifies the element type, not the array length. Each tensor in subsequent writes can have different lengths, but all must share the same element dtype matching the USD schema.

Example

from ovrtx._src.dlpack import DLDataType
# int[] attribute binding
binding = renderer.bind_array_attribute(
    prim_paths=["/World/Mesh1", "/World/Mesh2"],
    attribute_name="faceVertexCounts",
    dtype=DLDataType.from_str("int32"),
)
binding.write([counts1, counts2])  # Variable lengths OK
binding.unbind()

bind_array_attribute_async(

prim_paths,

attribute_name,

dtype=None,

prim_mode='existing_only',

)

Create a persistent binding for array attribute writes (async).

Parameters:

• prim_paths (List[str])

• attribute_name (str)

• dtype (DLDataType | None)

• prim_mode (str)

Return type:

Operation[AttributeBinding[List[DLTensor]]]

map_attribute(

prim_paths,

attribute_name,

semantic=None,

dtype=None,

device='cpu',

device_id=0,

prim_mode='existing_only',

)

Map attribute buffer for direct zero-copy writes (synchronous, by-name).

Returns an AttributeMapping that provides direct access to RTX’s internal buffer. Write data via the DLPack protocol (NumPy, Warp, etc.), then call unmap_attribute() to apply the changes.

For repeated operations on the same attribute, consider using bind_attribute() followed by binding.map() for better performance.

Note

Array attributes (e.g., float3[] points) are not supported for mapping. They may have variable lengths per prim, which is incompatible with contiguous tensor mapping. Use write_array_attribute() instead.

Parameters:

• prim_paths (List[str]) – List of prim paths.

• attribute_name (str) – Name of the attribute.

• semantic (str | None) – Semantic string (“transform_4x4”, “color_rgba4b”, “color_rgb3f”). If provided, dtype is inferred automatically.

• dtype (DLDataType | None) – DLDataType for the attribute. Required only if semantic is None.

• device (str) – Device for mapping (“cpu” or “cuda”).

• device_id (int) – Device ID (default 0, typically GPU index for CUDA).

• prim_mode (str) – Prim mode (“existing_only”, “must_exist”, or “create_new”).

Returns:

AttributeMapping with zero-copy access to RTX’s internal buffer. - For Matrix4d: tensor has shape (N, 4, 4) for NumPy-friendly operations - For RGBA color: tensor has shape (N, 4) for RGBA channels - For RGB color: tensor has shape (N, 3) for RGB channels

Raises:

• RuntimeError – If renderer is invalid or mapping fails.

• ValueError – If invalid parameters or dtype mismatch.

Return type:

AttributeMapping

Example

import numpy as np
mapping = renderer.map_attribute(
    prim_paths=["/World/Cube"],
    attribute_name="omni:fabric:worldMatrix",
    semantic="transform_4x4"
)
np.from_dlpack(mapping.tensor)[0] = np.eye(4)
renderer.unmap_attribute(mapping)

Or use as context manager:

with renderer.map_attribute(...) as mapping:
    np.from_dlpack(mapping.tensor)[0] = np.eye(4)

unmap_attribute(mapping, event=None, stream=None)

Unmap attribute and apply written data (synchronous - waits internally).

Applies the data written to the mapped buffer to the stage representation and destroys the mapping. After this call, the mapping is invalid.

For CUDA-mapped attributes, you can provide a CUDA event or stream handle to synchronize with ongoing GPU work before the data is consumed.

Parameters:

• mapping (AttributeMapping) – AttributeMapping from map_attribute()

• event (int | None) – CUDA event handle to wait on before accessing data (from wp.Event.cuda_event). The C library will wait for this event before reading the mapped data.

• stream (int | None) – CUDA stream handle for synchronization (from wp.Stream.cuda_stream). The C library will synchronize on this stream before reading the data.

Raises:

• RuntimeError – If renderer is invalid or unmap fails

• ValueError – If event/stream provided for CPU-mapped attribute

• ValueError – If both event and stream provided (mutually exclusive)

Return type:

None

Note

Data must be fully written to mapping.tensor before calling this. The mapping cannot be used after unmap.

unmap_attribute_async(mapping, event=None, stream=None)

Unmap attribute asynchronously (returns Operation for manual control).

Enqueues unmap operation and returns immediately. Use for advanced async control.

For CUDA-mapped attributes, you can provide a CUDA event or stream handle to synchronize with ongoing GPU work before the data is consumed.

Parameters:

• mapping (AttributeMapping) – AttributeMapping from map_attribute()

• event (int | None) – CUDA event handle to wait on before accessing data (from wp.Event.cuda_event)

• stream (int | None) – CUDA stream handle for synchronization (from wp.Stream.cuda_stream)

Returns:

Operation[None] for async control

Raises:

RuntimeError – If renderer is invalid or unmap fails

Return type:

Operation[None]

Note

After wait() completes, set mapping._unmapped = True manually. Validation of event/stream parameters should be done in the caller (unmap_attribute).

__bool__()

Return True if renderer is valid, False if destroyed.

Return type:

bool

property config: RendererConfig

Get the configuration used to create this renderer.

class ovrtx.RendererResult

Bases: Generic[T]

Result of a renderer step operation.

Provides access to rendering metadata via wait().

Usage:

result = renderer.step_async(...)
metadata = result.wait()  # Block until ready

# Or poll without blocking
metadata = result.wait(step_timeout_ns=0)
if metadata is None:
    print("Not ready yet")

__init__(operation)

Internal: Created by Renderer.step_async().

Parameters:

operation (Operation[T]) – The step operation with renderer-specific handle

property step_complete: bool

Check if step operation has completed.

Useful for diagnosing which stage timed out when wait() returns None.

Returns:

True if step completed (regardless of fetch status), False otherwise.

Example

metadata = result.wait(step_timeout_ns=1000, fetch_timeout_ns=500)
if metadata is None:
    if not result.step_complete:
        print("Step timed out - increase step_timeout_ns")
    else:
        print("Fetch timed out - increase fetch_timeout_ns")

wait(step_timeout_ns=None, fetch_timeout_ns=None)

Wait for step operation and fetch rendering results.

Two-stage operation with independent timeout control:

1. Step operation: Raytracing/GPU work

   • If times out, returns None immediately without attempting fetch

2. Fetch operation: Memory transfer (only if step completed)

   • If times out, returns None

Parameters:

• step_timeout_ns (int | None) – Timeout for step operation. None = infinite (default), 0 = poll, >0 = wait duration

• fetch_timeout_ns (int | None) – Timeout for fetch operation. None = infinite (default), 0 = poll, >0 = wait duration

Returns:

RenderProductSetOutputs if both stages complete, None if either times out.

The returned results auto-destroy their C resources when they go out of scope. Can be used as context manager for explicit control. Returns cached results on subsequent calls (idempotent).

Raises:

RuntimeError – If step or fetch operation failed.

Return type:

RenderProductSetOutputs[T] | None

Examples

# Infinite wait (most common - never returns None)
metadata = result.wait()
assert metadata is not None

# Poll step without blocking (returns immediately)
metadata = result.wait(step_timeout_ns=0)
if metadata is None:
    print("Step not ready yet")  # Fetch never attempted

# Custom timeouts for both stages
metadata = result.wait(
    step_timeout_ns=5_000_000_000,  # 5 seconds for raytracing
    fetch_timeout_ns=100_000_000    # 100ms for memory transfer
)
if metadata is None:
    # Use step_complete property to diagnose which stage timed out
    if not result.step_complete:
        print("Step timed out")
    else:
        print("Fetch timed out (step complete)")

__del__()

Auto-fetch on garbage collection to prevent C resource leaks.

If the step operation completes but results are never fetched, C resources will leak and trigger error logs. This safety net ensures cleanup happens.

class ovrtx.RendererConfig

Bases: object

ovrtx configuration with automatic defaults.

sync_mode: bool | None = None

Enables synchronous rendering mode for debugging purposes.

log_file_path: str | None = None

Set the path to the log file for logging output.

log_level: str | None = None

“verbose”, “info”, “warn”, “error”

Type:

Set the log level for logging output

__init__(

sync_mode=None,

log_file_path=None,

log_level=None,

)

Parameters:

• sync_mode (bool | None)

• log_file_path (str | None)

• log_level (str | None)

Return type:

None

ovrtx.math

Math types for ovrtx (public API).

This module provides math types like Matrix4d for use with ovrtx attribute operations.

class ovrtx.math.Matrix4d

Bases: Structure

4x4 double-precision matrix (compatible with usdrt::GfMatrix4d).

Memory layout: 16 doubles in row-major order (128 bytes). Compatible with C++ usdrt::GfMatrix4d = omni::math::linalg::matrix4<double>.

Example

from ovrtx.math import Matrix4d

# Create identity matrix
m = Matrix4d()
m.SetIdentity()

# Access elements
m[0][0] = 99.0

# Use with write_attribute
renderer.write_attribute_sync(
    prim_paths=["/World/Cube"],
    attribute_name="omni:fabric:worldMatrix",
    data=m,
    semantic="transform_4x4"
)

__init__()

Initialize matrix to identity.

SetIdentity()

Set matrix to identity matrix.

Return type:

None

SetTranslate(x, y, z)

Set matrix to translation matrix.

Parameters:

• x (float) – Translation in X direction

• y (float) – Translation in Y direction

• z (float) – Translation in Z direction

Return type:

None

SetScale(s)

Set matrix to uniform scale matrix.

Parameters:

s (float) – Scale factor

Return type:

None

__getitem__(row)

Access matrix row.

Parameters:

row (int) – Row index (0-3)

Returns:

Row array (supports [row][col] indexing)

__setitem__(row, value)

Set matrix row.

Parameters:

• row (int) – Row index (0-3)

• value – Row data (list or array of 4 doubles)

__repr__()

Pretty print matrix.

Return type:

str

to_dltensor()

Create DLTensor for this matrix (for use with Renderer.write_attribute).

Returns a DLTensor with the format expected by the C library: - shape[0] = 1 (one matrix) - dtype.lanes = 16 (16 doubles per matrix) - dtype.bits = 64 - dtype.code = kDLFloat

Returns:

DLTensor pointing to this matrix’s data

Return type:

DLTensor

v

Structure/Union member