Python API Reference#

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

ovrtx#

Version and Constants#

ovrtx.__version__ = '0.4.0'#

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.

ovrtx.OVRTX_LIBRARY_PATH_HINT = None#
ovrtx.OVRTX_RENDER_VAR_PICK_HIT = 'ovrtx_pick_hit'#

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.

ovrtx.OVRTX_PICK_FLAG_GIZMO = 1#

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.__int__(). For floating point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by ‘+’ or ‘-’ and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer literal. >>> int(‘0b100’, base=0) 4

ovrtx.OVRTX_PICK_FLAG_INCLUDE_TRACKED_INFO = 2#

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.__int__(). For floating point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by ‘+’ or ‘-’ and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer literal. >>> int(‘0b100’, base=0) 4

ovrtx.OVRTX_PICK_HIT_MAGIC = 1448105032#

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.__int__(). For floating point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by ‘+’ or ‘-’ and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer literal. >>> int(‘0b100’, base=0) 4

ovrtx.OVRTX_PICK_HIT_VERSION = 1#

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.__int__(). For floating point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by ‘+’ or ‘-’ and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer literal. >>> int(‘0b100’, base=0) 4

USD Schema Path Registration#

ovrtx.register_schema_paths(binary_package_root=None)[source]#

Publish ovrtx’s USD schema/plugin paths to USD’s plugin search env-vars.

Thin wrapper that loads ovrtx-dynamic and invokes the C-side ovrtx_register_schema_paths(). All path-resolution and env-var update logic lives in CRenderApiLibLoader.cpp so every entry point (Python auto-import hook, ovrtx_initialize, ovrtx_create_renderer, explicit ovrtx_register_schema_paths call from a C/C++ host) runs the same code.

See ovrtx.h for the full contract — first-call wins, idempotent for matching effective roots, calls with a different root log a warning to stderr.

Parameters:

binary_package_root (str | None) –

Optional override for the ovrtx binary package root. Forwarded by setting OMNI_USD_PLUGINS_BASE_PATH (the highest-precedence input the C resolver consults), so this is equivalent to passing the same root in OVRTX_CONFIG_BINARY_PACKAGE_ROOT_PATH to a subsequent ovrtx_initialize / ovrtx_create_renderer. When None the C side resolves the root from OMNI_USD_PLUGINS_BASE_PATH (if already set in the env) then from the loader’s own location (GetModuleFileName / dladdr).

Note

Passing a non-None value mutates OMNI_USD_PLUGINS_BASE_PATH in the process env unconditionally — even on the second call, where the C side has already pinned the first-registered root and merely emits a stderr warning. The env-var mutation has no effect on USD’s plug registry (one-shot per process), but it will be observed by anything that consults OMNI_USD_PLUGINS_BASE_PATH later. Pass the same root on every call (or None after the first) if you need the env to stay consistent with the registered root.

Return type:

None

Side effect on os.environ: each call mirrors the post-C-call CRT value of every key in _PXR_PLUGINPATH_ENV_KEYS into os.environ (overwriting any prior Python-side edits to those specific keys, by design — the CRT is the source of truth for what USD sees). See the inline comment below the C call for rationale and platform notes.

ovrtx.usd_pluginpath_env_keys()[source]#

Env-var keys that register_schema_paths() reads or writes.

Output keys (USD’s plug registry reads these — see _PXR_PLUGINPATH_ENV_KEYS) followed by the input overrides the C resolver consults. Tests use this to snapshot/restore env state without hard-coding the list of keys.

Return type:

Tuple[str, …]

Renderer#

class ovrtx.Renderer[source]#

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.

Enum types for method parameters are accessible as class attributes (e.g., Renderer.PrimMode.EXISTING_ONLY) or via top-level imports (e.g., from ovrtx import PrimMode).

Example

from ovrtx import Renderer, RendererConfig

# Use defaults
renderer = Renderer()

# Or customize
config = RendererConfig(sync_mode=True, log_file_path="/path/to/app.log")
renderer = Renderer(config=config)

# Resources automatically cleaned up when renderer goes out of scope

Note

Enums are also available as class attributes for convenience (for example, Renderer.Semantic.NONE). Refer to Enums below for details.

__init__(config=None)[source]#

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.

destroy()[source]#

Explicitly release the renderer’s native resources.

Idempotent: safe to call multiple times. Prefer calling this (e.g. in a fixture finalizer or try/finally) for deterministic teardown: the Python wrapper can be kept alive past its last use by reference cycles, which would otherwise defer native cleanup to a GC pass.

Raises:

RuntimeError – If detaching an attached ovstage or destroying the renderer fails.

Return type:

None

__del__()[source]#

Automatically clean up renderer resources on destruction.

property version: tuple#

Runtime library version as a (major, minor, patch) tuple.

attach_ovstage(stage)[source]#

Attach an externally owned ovstage.Stage to this renderer.

The renderer borrows the Stage’s native instance and retains the Python object until detach or renderer destruction. Do not explicitly destroy the Stage while it is attached.

Parameters:

stage (Any) – A live ovstage.Stage instance.

Raises:

  • RuntimeError – If the renderer is invalid, is already attached, or the native attach fails.

  • TypeError – If stage does not expose a compatible native handle.

  • ValueError – If the Stage has already been destroyed.

Return type:

None

detach_ovstage()[source]#

Detach the attached ovstage and return the renderer to standalone mode.

Return type:

None

update_from_stage(ordinal)[source]#

Update from the attached ovstage through at least ordinal.

In BORROW mode this synchronizes the renderer’s scene state with committed population changes while attribute values remain shared with ovstage. In REPLICATE mode it copies committed Stage data into the renderer-owned stage. Normal calls to step() perform this update automatically in both modes.

Parameters:

ordinal (int)

Return type:

None

update_from_stage_async(ordinal)[source]#

Enqueue an update from the attached ovstage through at least ordinal.

BORROW synchronizes the renderer’s scene state with committed population changes without copying shared attribute values. REPLICATE copies committed Stage data into the renderer-owned stage. step_async() performs this update automatically in both modes.

Parameters:

ordinal (int) – Minimum committed ovstage publication to update through.

Returns:

Operation that completes when the update has been applied.

Raises:

  • RuntimeError – If the renderer is invalid, no Stage is attached, or the update cannot be enqueued.

  • TypeError – If ordinal is not an integer.

  • ValueError – If ordinal is outside the uint64 range.

Return type:

Operation[bool]

open_usd(usd_file_path)[source]#

Deprecated since ovrtx 0.4. Use ovstage.population with an ovstage.Stage, attach it with Renderer.attach_ovstage(), and render with Renderer.step(…, ordinal=…).

Open a USD file as the root layer (synchronous).

Resets the current stage and loads the given file as the root sublayer. Blocks until the USD file is fully loaded.

Args:

usd_file_path: Path to the USD file to open.

Raises:

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

Example:

.. code-block:: python

    renderer.open_usd("/path/to/scene.usda")
Parameters:

usd_file_path (str)

Return type:

None

open_usd_async(usd_file_path)[source]#

Deprecated since ovrtx 0.4. Use ovstage.population with an ovstage.Stage, attach it with Renderer.attach_ovstage(), and render with Renderer.step(…, ordinal=…).

Open a USD file as the root layer (asynchronous).

Resets the current stage and loads the given file as the root sublayer. Returns immediately with an Operation for manual control.

Args:

usd_file_path: Path to the USD file to open.

Returns:

Operation that can be polled or waited on with custom timeout. wait() returns True on success and None on timeout.

Raises:

RuntimeError: If renderer is invalid or enqueue fails.

Example:

.. code-block:: python

    op = renderer.open_usd_async("/path/to/scene.usda")
    op.wait(timeout_ns=1_000_000_000)
Parameters:

usd_file_path (str)

Return type:

Operation[bool]

open_usd_from_string(root_layer_content)[source]#

Deprecated since ovrtx 0.4. Use ovstage.population with an ovstage.Stage, attach it with Renderer.attach_ovstage(), and render with Renderer.step(…, ordinal=…).

Open a USD stage from inline USDA content (synchronous).

Resets the current stage and loads the given content as the root sublayer. Blocks until the layer is fully loaded.

Args:

root_layer_content: USDA content as a Python string.

Raises:

RuntimeError: If renderer is invalid, enqueue fails, or loading fails. ValueError: If root_layer_content is empty.

Example:

.. code-block:: python

    renderer.open_usd_from_string('''
    #usda 1.0
    (defaultPrim = "World")
    def Xform "World" { ... }
    ''')
Parameters:

root_layer_content (str)

Return type:

None

open_usd_from_string_async(root_layer_content)[source]#

Deprecated since ovrtx 0.4. Use ovstage.population with an ovstage.Stage, attach it with Renderer.attach_ovstage(), and render with Renderer.step(…, ordinal=…).

Open a USD stage from inline USDA content (asynchronous).

Resets the current stage and loads the given content as the root sublayer. Returns immediately with an Operation for manual control.

Args:

root_layer_content: USDA content as a Python string.

Returns:

Operation that can be polled or waited on with custom timeout. wait() returns True on success and None on timeout.

Raises:

RuntimeError: If renderer is invalid or enqueue fails. ValueError: If root_layer_content is empty.

Parameters:

root_layer_content (str)

Return type:

Operation[bool]

add_usd_reference(layer_file, prefix_path)[source]#

Deprecated since ovrtx 0.4. Use ovstage.population with an ovstage.Stage, attach it with Renderer.attach_ovstage(), and render with Renderer.step(…, ordinal=…).

Add a USD file as a reference at a prim path (synchronous).

Blocks until the reference is fully loaded.

Args:

layer_file: Path to the USD file to add as a reference. prefix_path: Absolute prim path where the reference will be created.

Returns:

USD handle for the added reference (for use with remove_usd).

Raises:

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

Example:

.. code-block:: python

    handle = renderer.add_usd_reference("/path/to/props.usda", "/World/Props")
Parameters:

  • layer_file (str)

  • prefix_path (str)

Return type:

Any

add_usd_reference_async(layer_file, prefix_path)[source]#

Deprecated since ovrtx 0.4. Use ovstage.population with an ovstage.Stage, attach it with Renderer.attach_ovstage(), and render with Renderer.step(…, ordinal=…).

Add a USD file as a reference at a prim path (asynchronous).

Returns immediately with an Operation for manual control.

Args:

layer_file: Path to the USD file to add as a reference. prefix_path: Absolute prim path where the reference will be created.

Returns:

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

Raises:

RuntimeError: If renderer is invalid or enqueue fails.

Parameters:

  • layer_file (str)

  • prefix_path (str)

Return type:

Operation[Any]

add_usd_reference_from_string(layer_content, prefix_path)[source]#

Deprecated since ovrtx 0.4. Use ovstage.population with an ovstage.Stage, attach it with Renderer.attach_ovstage(), and render with Renderer.step(…, ordinal=…).

Add inline USDA content as a reference at a prim path (synchronous).

Blocks until the reference is fully loaded.

Args:
layer_content: USDA content as a Python string. Must set defaultPrim

for reference composition to work correctly.

prefix_path: Absolute prim path where the reference will be created.

Returns:

USD handle for the added reference (for use with remove_usd).

Raises:

RuntimeError: If renderer is invalid, enqueue fails, or loading fails. ValueError: If layer_content is empty.

Note:

A USD reference is namespace-encapsulated: any relationship or path target that points outside prefix_path is dropped during composition. Keep targets self-contained within the reference layer, for example a RenderProduct whose rel camera points at a Camera defined in the same layer.

Example:

.. code-block:: python

    renderer.open_usd("/path/to/scene.usda")
    renderer.add_usd_reference_from_string('''
    #usda 1.0
    (defaultPrim = "Render")
    def Scope "Render" {
        def Camera "Camera" {}
        def RenderProduct "Product" { rel camera = </Render/Camera> }
    }
    ''', prefix_path="/Render")
Parameters:

  • layer_content (str)

  • prefix_path (str)

Return type:

Any

add_usd_reference_from_string_async(
layer_content,
prefix_path,
)[source]#

Deprecated since ovrtx 0.4. Use ovstage.population with an ovstage.Stage, attach it with Renderer.attach_ovstage(), and render with Renderer.step(…, ordinal=…).

Add inline USDA content as a reference at a prim path (asynchronous).

Returns immediately with an Operation for manual control.

Args:
layer_content: USDA content as a Python string. Must set defaultPrim

for reference composition to work correctly.

prefix_path: Absolute prim path where the reference will be created.

Returns:

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

Raises:

RuntimeError: If renderer is invalid or enqueue fails. ValueError: If layer_content is empty.

Parameters:

  • layer_content (str)

  • prefix_path (str)

Return type:

Operation[Any]

remove_usd(usd_handle)[source]#

Deprecated since ovrtx 0.4. Use ovstage.population with an ovstage.Stage, attach it with Renderer.attach_ovstage(), and render with Renderer.step(…, ordinal=…).

Remove a previously added USD from the runtime stage.

Args:

usd_handle: Handle returned from add_usd_reference() or add_usd_reference_from_string().

Raises:

RuntimeError: If the removal fails.

Parameters:

usd_handle (Any)

Return type:

None

remove_usd_async(usd_handle)[source]#

Deprecated since ovrtx 0.4. Use ovstage.population with an ovstage.Stage, attach it with Renderer.attach_ovstage(), and render with Renderer.step(…, ordinal=…).

Remove a previously added USD (async).

Args:

usd_handle: Handle returned from add_usd_reference() or add_usd_reference_from_string().

Returns:

Operation that completes when USD is removed.

Raises:

RuntimeError: If renderer is invalid or enqueue fails.

Parameters:

usd_handle (Any)

Return type:

Operation[bool]

update_from_usd_time(usd_time)[source]#

Deprecated since ovrtx 0.4. Use ovstage.population with an ovstage.Stage, attach it with Renderer.attach_ovstage(), and render with Renderer.step(…, ordinal=…).

Update runtime stage to a specific USD time (synchronous).

Blocks until all time-sampled attributes are re-evaluated.

Args:
usd_time: Stage time in seconds (not USD timecodes). The runtime

converts to timecodes via the stage’s timeCodesPerSecond metadata.

Raises:

RuntimeError: If the update fails.

Parameters:

usd_time (float)

Return type:

None

update_from_usd_time_async(usd_time)[source]#

Deprecated since ovrtx 0.4. Use ovstage.population with an ovstage.Stage, attach it with Renderer.attach_ovstage(), and render with Renderer.step(…, ordinal=…).

Update runtime stage to a specific USD time (asynchronous).

Returns immediately with an Operation for manual control.

Args:
usd_time: Stage time in seconds (not USD timecodes). The runtime

converts to timecodes via the stage’s timeCodesPerSecond metadata.

Returns:

Operation that completes when the update finishes.

Raises:

RuntimeError: If the enqueue fails.

Parameters:

usd_time (float)

Return type:

Operation[bool]

clone_usd(source_path, target_paths)[source]#

Deprecated since ovrtx 0.4. Use ovstage.Stage.clone() or clone_async(), then advance the write floor.

Clone a USD subtree to one or more target paths.

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

Args:

source_path: Path to the source prim to clone. target_paths: List of target paths for the clones.

Raises:

RuntimeError: If the clone operation fails. ValueError: If target_paths is empty.

Parameters:
Return type:

None

clone_usd_async(source_path, target_paths)[source]#

Deprecated since ovrtx 0.4. Use ovstage.Stage.clone() or clone_async(), then advance the write floor.

Clone a USD subtree (async).

Args:

source_path: Path to the source prim to clone. target_paths: 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.

Parameters:
Return type:

Operation[bool]

step(render_products, delta_time, *, ordinal=None)[source]#

Step the renderer (synchronous - blocks until complete).

Enqueues a step operation, waits for rendering to complete, and returns results. Equivalent to step_async(...).wait().fetch() with infinite timeouts for both the operation wait and the result fetch.

When an ovstage is attached, the step first synchronizes the renderer with committed Stage changes through ordinal. BORROW keeps attribute values shared; REPLICATE copies committed data into the renderer-owned stage.

Parameters:

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

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

  • ordinal (int | None) – Minimum committed publication required from the attached ovstage. Execution may observe that publication or a later one. Required in attached mode and invalid in standalone mode.

Returns:

RenderProductSetOutputs with rendering results.

Raises:

  • RuntimeError – If renderer is invalid, enqueue fails, step fails, fetch fails, or ordinal use does not match attachment state.

  • TypeError – If ordinal is not an integer.

  • ValueError – If no valid render products are provided or ordinal is outside the uint64 range.

Return type:

RenderProductSetOutputs[Any]

step_async(render_products, delta_time, *, ordinal=None)[source]#

Step the renderer (asynchronous - returns immediately).

Enqueues a step operation and returns an Operation. Call .wait() to get a PendingFetch, then .fetch() to retrieve the RenderProductSetOutputs.

When an ovstage is attached, the step first enqueues synchronization with committed Stage changes through ordinal. BORROW keeps attribute values shared; REPLICATE copies committed data into the renderer-owned stage.

Parameters:

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

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

  • ordinal (int | None) – Minimum committed publication required from the attached ovstage. Execution may observe that publication or a later one. Required in attached mode and invalid in standalone mode.

Returns:

Operation[PendingFetch[RenderProductSetOutputs]]

Raises:

  • RuntimeError – If renderer is invalid, enqueue fails, or ordinal use does not match attachment state.

  • TypeError – If ordinal is not an integer.

  • ValueError – If no valid render products are provided or ordinal is outside the uint64 range.

Return type:

Operation[PendingFetch[RenderProductSetOutputs]]

reset(time=0.0)[source]#

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)[source]#

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[bool]

enqueue_pick_query_async(
render_product_path,
left_ndc,
top_ndc,
right_ndc,
bottom_ndc,
*,
flags=0,
)[source]#

Enqueue an NDC viewport pick rectangle for the next step() on this RenderProduct (async).

Results appear on the next step() as the multi-tensor render variable OVRTX_RENDER_VAR_PICK_HIT. If multiple queries target the same RenderProduct before a step, the last one wins.

Parameters:

  • render_product_path (str) – Target RenderProduct path.

  • left_ndc (float) – Pick rectangle in normalized RenderProduct coordinates. Values use [0, 1] top-left-origin NDC: x increases left-to-right and y increases top-to-bottom. The rectangle uses the same convention as the old pixel API: right_ndc and bottom_ndc mark the edge just past the last included pixel. For pixel (x, y) on a width x height RenderProduct, use [x / width, y / height, (x + 1) / width, (y + 1) / height]. Use [0, 0, 1, 1] for the full RenderProduct. Out-of-bounds values are rejected; boundary values may be clamped to the valid range to account for floating-point roundoff.

  • top_ndc (float) – Pick rectangle in normalized RenderProduct coordinates. Values use [0, 1] top-left-origin NDC: x increases left-to-right and y increases top-to-bottom. The rectangle uses the same convention as the old pixel API: right_ndc and bottom_ndc mark the edge just past the last included pixel. For pixel (x, y) on a width x height RenderProduct, use [x / width, y / height, (x + 1) / width, (y + 1) / height]. Use [0, 0, 1, 1] for the full RenderProduct. Out-of-bounds values are rejected; boundary values may be clamped to the valid range to account for floating-point roundoff.

  • right_ndc (float) – Pick rectangle in normalized RenderProduct coordinates. Values use [0, 1] top-left-origin NDC: x increases left-to-right and y increases top-to-bottom. The rectangle uses the same convention as the old pixel API: right_ndc and bottom_ndc mark the edge just past the last included pixel. For pixel (x, y) on a width x height RenderProduct, use [x / width, y / height, (x + 1) / width, (y + 1) / height]. Use [0, 0, 1, 1] for the full RenderProduct. Out-of-bounds values are rejected; boundary values may be clamped to the valid range to account for floating-point roundoff.

  • bottom_ndc (float) – Pick rectangle in normalized RenderProduct coordinates. Values use [0, 1] top-left-origin NDC: x increases left-to-right and y increases top-to-bottom. The rectangle uses the same convention as the old pixel API: right_ndc and bottom_ndc mark the edge just past the last included pixel. For pixel (x, y) on a width x height RenderProduct, use [x / width, y / height, (x + 1) / width, (y + 1) / height]. Use [0, 0, 1, 1] for the full RenderProduct. Out-of-bounds values are rejected; boundary values may be clamped to the valid range to account for floating-point roundoff.

  • flags (int) – Combination of OVRTX_PICK_FLAG_*.

Returns:

Operation that completes once the pick query is registered.

Raises:
Return type:

Operation[bool]

enqueue_pick_query(
render_product_path,
left_ndc,
top_ndc,
right_ndc,
bottom_ndc,
*,
flags=0,
)[source]#

Enqueue an NDC viewport pick rectangle for the next step() on this RenderProduct (blocking).

Equivalent to enqueue_pick_query_async(...).wait(). See enqueue_pick_query_async() for argument details.

Parameters:
Return type:

None

set_selection_group_styles(styles)[source]#

Set per-group outline and fill colors for selection groups (blocking).

Equivalent to set_selection_group_styles_async(styles).wait(). See set_selection_group_styles_async() for argument details.

Parameters:

styles (dict[int, SelectionGroupStyle])

Return type:

None

set_selection_group_styles_async(styles)[source]#

Set per-group outline and fill colors for selection groups (async).

Stream-ordered: takes effect on the next step() after it completes. If multiple writes target the same group id, the last writer wins. Outline thickness and fill mode are configured at renderer creation via RendererConfig.selection_outline_width and RendererConfig.selection_fill_mode.

Parameters:

styles (dict[int, SelectionGroupStyle]) – Mapping from group id (0..255) to a SelectionGroupStyle. Group ids match the per-prim id passed to set_selection_outline_group(). An empty mapping enqueues a no-op.

Returns:

Operation that completes once the styling state has been applied.

Raises:

  • RuntimeError – If renderer is invalid or enqueue fails.

  • ValueError – If any group id is outside 0..255 or any color is not a 4-element RGBA sequence.

Return type:

Operation[bool]

set_selection_outline_group(prim_path_ids, group_ids)[source]#

Set each prim’s selection outline group by path id (blocking).

Equivalent to set_selection_outline_group_async(...).wait(). See set_selection_outline_group_async() for argument details.

Parameters:
Return type:

None

set_selection_outline_group_async(prim_path_ids, group_ids)[source]#

Set each prim’s selection outline group by path id (async).

Stream-ordered: takes effect on the next step() after it completes. Pass group 0 to clear a prim’s selection outline. A scalar group id applies to every path; a list must have one group id per path. Duplicate path ids are allowed; the last occurrence wins.

Parameters:

  • prim_path_ids (list[int]) – Path ids from this renderer’s pick-hit primPath tensor or own path dictionary.

  • group_ids (int | list[int]) – Group id or parallel list of group ids, each in 0..255.

Returns:

Operation that completes once the renderer selection state has been applied.

Raises:

  • RuntimeError – If renderer is invalid or enqueue fails.

  • ValueError – If any group id is outside 0..255 or list lengths differ.

Return type:

Operation[bool]

set_selection_outline_group_strings(prim_paths, group_ids)[source]#

Set each prim’s selection outline group by string path (blocking).

Duplicate paths are allowed; the last occurrence wins.

Parameters:
Return type:

None

set_selection_outline_group_strings_async(
prim_paths,
group_ids,
)[source]#

Set each prim’s selection outline group by string path (async).

Duplicate paths are allowed; the last occurrence wins.

Parameters:
Return type:

Operation[bool]

set_pickable(prim_path_ids, pickable)[source]#

Set viewport pickability for prims by path id (blocking).

Equivalent to set_pickable_async(...).wait(). See set_pickable_async() for argument details.

Parameters:
Return type:

None

set_pickable_async(prim_path_ids, pickable)[source]#

Set viewport pickability for prims by path id (async).

Stream-ordered: takes effect on the next step() after it completes. A scalar value applies to every path; a list must have one value per path.

Parameters:

  • prim_path_ids (list[int]) – Path ids from this renderer’s pick-hit primPath tensor or own path dictionary.

  • pickable (bool | list[bool]) – Pickability value or parallel list of values.

Returns:

Operation that completes once the renderer pickability state has been applied.

Raises:
Return type:

Operation[bool]

set_pickable_strings(prim_paths, pickable)[source]#

Set viewport pickability for prims by string path (blocking).

Parameters:
Return type:

None

set_pickable_strings_async(prim_paths, pickable)[source]#

Set viewport pickability for prims by string path (async).

Parameters:
Return type:

Operation[bool]

reset_stage()[source]#

Deprecated since ovrtx 0.4. Use ovstage.population with an ovstage.Stage, attach it with Renderer.attach_ovstage(), and render with Renderer.step(…, ordinal=…).

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()[source]#

Deprecated since ovrtx 0.4. Use ovstage.population with an ovstage.Stage, attach it with Renderer.attach_ovstage(), and render with Renderer.step(…, ordinal=…).

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[bool]

query_prims(
require_all=None,
require_any=None,
exclude=None,
attribute_filter_mode=AttributeFilterMode.NONE,
attribute_names=None,
)[source]#

Deprecated since ovrtx 0.4. Use ovstage.Stage.query() or query_from_path_list() instead.

Query prims from the runtime stage (synchronous).

Finds prims matching the specified filters and returns a dict mapping prim paths to their AttributeInfo descriptors. Equivalent to query_prims_async(...).wait().fetch() with infinite timeouts for both the operation wait and the result fetch.

Filter logic: A prim is included when it matches every filter in require_all and at least one filter in require_any and none of the filters in exclude. Omitted lists impose no constraint (i.e. require_all=None means no mandatory filters). Each filter is a (kind, name) tuple where kind selects the match type:

Attribute reporting: attribute_filter_mode controls how much attribute metadata is included per prim in the result:

  • AttributeFilterMode.NONE — no attribute descriptors; the per-prim dicts are empty. Use this for lightweight prim counting or path discovery.

  • ALL — every attribute on each prim is reported as an AttributeInfo.

  • SPECIFIC — only the attributes named in attribute_names are reported.

Args:

require_all: AND filters — prim must match all of them. require_any: OR filters — prim must match at least one. exclude: NOT filters — prim must match none of them. attribute_filter_mode: Attribute reporting level. attribute_names: Attribute names to report when mode is

Returns:

dict[str, dict[str, AttributeInfo]] (dict-like, context manager).

Raises:

RuntimeError: If query fails.

Parameters:
Return type:

dict[str, dict[str, AttributeInfo]]

query_prims_async(
require_all=None,
require_any=None,
exclude=None,
attribute_filter_mode=AttributeFilterMode.NONE,
attribute_names=None,
)[source]#

Deprecated since ovrtx 0.4. Use ovstage.Stage.query() or query_from_path_list() instead.

Query prims from the runtime stage (non-blocking).

Enqueues the query and returns an Operation. Call .wait() to get a PendingFetch, then .fetch() to retrieve the dict[str, dict[str, AttributeInfo]].

Args:
require_all: Filters the prim must match (AND). Each tuple is

(FilterKind.PRIM_TYPE, "Mesh") or (FilterKind.HAS_ATTRIBUTE, "radius").

require_any: Filters the prim must match at least one of (OR). exclude: Filters the prim must not match (NOT). attribute_filter_mode: Which attributes to report per group

attribute_names: Attribute names to report when mode is

SPECIFIC.

Returns:

Operation[PendingFetch[dict[str, dict[str, AttributeInfo]]]]

Raises:

RuntimeError: If enqueue fails.

Parameters:
Return type:

Operation[PendingFetch[dict[str, dict[str, AttributeInfo]]]]

resolve_prim_path_id(prim_path_id)[source]#

Resolve an ovrtx prim-path id to a USD prim path string.

Pick-hit records store path-dictionary ids rather than strings. Use this helper to turn a hit record’s prim_path field into a path such as "/World/Cube".

Parameters:

prim_path_id (int)

Return type:

str

read_attribute(
attribute_name,
prim_paths,
prim_mode=PrimMode.EXISTING_ONLY,
dest=None,
cuda_stream=None,
cuda_event=None,
)[source]#

Deprecated since ovrtx 0.4. Use ovstage.Stage.read_attributes() and fetch read groups from ovstage instead.

Read a scalar attribute (synchronous, one value per prim).

Returns a DLPack-compatible tensor for use with NumPy, Warp, PyTorch, or any from_dlpack() consumer:

tensor = renderer.read_attribute("radius", ["/World/Sphere"])
arr = np.from_dlpack(tensor)

When dest is provided, data is written directly into the caller’s tensor (supports GPU tensors for zero-copy reads). The return value wraps the same memory as dest — both are usable.

Equivalent to read_attribute_async(...).wait().fetch().

Args:

attribute_name: Name of the attribute (e.g. "radius"). prim_paths: USD prim paths to read from. prim_mode: Prim binding mode (default:

dest: Optional pre-allocated DLPack-compatible tensor. When

provided, data is written directly into it. Accepts any object with __dlpack__().

cuda_stream: Optional CUDA stream handle (int) on which you coordinate

work with dest. ovrtx waits on this stream before writing and signals on it when done, and forwards it to the DLPack producer of dest so any prior work on a different stream is synchronized automatically. If omitted, the caller must ensure dest’s state is fully settled before calling.

cuda_event: Optional CUDA event handle (int). Sets the

access sync wait event (waited on before writing to dest).

Returns:

ManagedDLTensor

Raises:

RuntimeError: If the read fails. TypeError: If dest does not support the DLPack protocol.

Parameters:
Return type:

ManagedDLTensor

read_attribute_async(
attribute_name,
prim_paths,
prim_mode=PrimMode.EXISTING_ONLY,
dest=None,
cuda_stream=None,
cuda_event=None,
)[source]#

Deprecated since ovrtx 0.4. Use ovstage.Stage.read_attributes() and fetch read groups from ovstage instead.

Read a scalar attribute (non-blocking, one value per prim).

Enqueues the read and returns an Operation. Call .wait() then .fetch() to retrieve the tensor:

op = renderer.read_attribute_async("radius", ["/World/Sphere"])
pending = op.wait(timeout_ns=5_000_000_000)    # None on timeout
tensor = pending.fetch(timeout_ns=100_000_000)  # None on timeout
arr = np.from_dlpack(tensor)

When dest is provided, data is written directly into the caller’s tensor (supports GPU tensors for zero-copy reads). The fetched tensor wraps the same memory as dest — both are usable.

Args:

attribute_name: Name of the attribute (e.g. "radius"). prim_paths: USD prim paths to read from. prim_mode: Prim binding mode (default:

dest: Optional pre-allocated DLPack-compatible tensor. When

provided, data is written directly into it. Accepts any object with __dlpack__().

cuda_stream: Optional CUDA stream handle (int) on which you coordinate

work with dest. ovrtx waits on this stream before writing and signals on it when done, and forwards it to the DLPack producer of dest so any prior work on a different stream is synchronized automatically. If omitted, the caller must ensure dest’s state is fully settled before calling.

cuda_event: Optional CUDA event handle (int). Sets the

access sync wait event (waited on before writing to dest).

Returns:

Operation[PendingFetch[ManagedDLTensor]]

Raises:

RuntimeError: If enqueue fails. TypeError: If dest does not support the DLPack protocol.

Parameters:
Return type:

Operation[PendingFetch[ManagedDLTensor]]

read_array_attribute(
attribute_name,
prim_paths,
prim_mode=PrimMode.EXISTING_ONLY,
)[source]#

Deprecated since ovrtx 0.4. Use ovstage.Stage.read_attributes() and fetch read groups from ovstage instead.

Read an array attribute (synchronous, variable-length per prim).

Returns a dict mapping prim paths to DLPack-compatible tensors, for use with NumPy, Warp, PyTorch, or any from_dlpack() consumer. Iteration order matches prim_paths:

tensors = renderer.read_array_attribute("points", prim_paths)
for path, tensor in tensors.items():
    arr = np.from_dlpack(tensor)

Equivalent to read_array_attribute_async(...).wait().fetch().

Args:

attribute_name: Name of the attribute (e.g. "points"). prim_paths: USD prim paths to read from. prim_mode: Prim binding mode (default:

Returns:

dict[str, ManagedDLTensor]

Raises:

RuntimeError: If the read fails.

Parameters:
Return type:

dict[str, ManagedDLTensor]

read_array_attribute_async(
attribute_name,
prim_paths,
prim_mode=PrimMode.EXISTING_ONLY,
)[source]#

Deprecated since ovrtx 0.4. Use ovstage.Stage.read_attributes() and fetch read groups from ovstage instead.

Read an array attribute (non-blocking, variable-length per prim).

Enqueues the read and returns an Operation. Call .wait() then .fetch() to retrieve the tensor dict:

op = renderer.read_array_attribute_async("points", prim_paths)
pending = op.wait(timeout_ns=5_000_000_000)    # None on timeout
tensors = pending.fetch(timeout_ns=100_000_000) # None on timeout
for path, tensor in tensors.items():
    arr = np.from_dlpack(tensor)
Args:

attribute_name: Name of the attribute (e.g. "points"). prim_paths: USD prim paths to read from. prim_mode: Prim binding mode (default:

Returns:

Operation[PendingFetch[dict[str, ManagedDLTensor]]]

Raises:

RuntimeError: If enqueue fails.

Parameters:
Return type:

Operation[PendingFetch[dict[str, ManagedDLTensor]]]

write_attribute(
prim_paths,
attribute_name,
tensor,
semantic=Semantic.NONE,
dirty_bits=None,
prim_mode=PrimMode.EXISTING_ONLY,
data_access=DataAccess.SYNC,
cuda_stream=None,
cuda_event=None,
)[source]#

Deprecated since ovrtx 0.4. Use ovstage.Stage.write_attribute() with an ordinal and reusable query instead.

Write scalar attribute data synchronously.

Pass data directly — the element type and component count are inferred automatically from the input:

  • Tensor input (NumPy, Warp, or any __dlpack__-compatible object): the element type is derived from the array’s dtype and shape. For example, a float32 array with shape (N, 3) is interpreted as a 3-component float attribute.

  • String input (list[str]): automatically written as a token string attribute. One string per prim.

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

Args:

prim_paths: List of prim paths to write to. attribute_name: Name of the attribute. tensor: A NumPy array, Warp array, or any __dlpack__-compatible

object. One element per prim. For token strings, pass a list[str] instead.

semantic: Optional attribute semantic (e.g.,

Semantic.XFORM_MAT4x4). When omitted (default), the element type is inferred from the input data.

dirty_bits: Optional dirty bit array for selective updates. prim_mode: Prim binding mode (e.g., PrimMode.EXISTING_ONLY). data_access: Data access mode. DataAccess.SYNC (default) copies

input data immediately so the caller’s buffer can be reused after this call returns. DataAccess.ASYNC references the caller’s buffer until the operation completes (zero-copy). Not allowed with string data.

cuda_stream: Optional CUDA stream handle (int) on which the input

tensor’s data is (or will be) ready. ovrtx synchronizes its read of the tensor against this stream and forwards it to the DLPack producer (e.g. Warp) so any pending work on a different stream is bridged automatically. If omitted, the caller must ensure the tensor’s state is fully settled before calling.

cuda_event: CUDA event handle (int) for GPU synchronization.

Raises:

RuntimeError: If renderer is invalid or write fails. ValueError: If invalid parameters. TypeError: If tensor type is not supported, or if string data is

not a list[str].

Example:

.. code-block:: python

    import numpy as np

    # Tensor writes — just pass the array
    points = np.random.randn(N, 3).astype(np.float32)
    renderer.write_attribute(prim_paths, "points", points)

    matrices = np.tile(np.eye(4, dtype=np.float64), (N, 1, 1))
    renderer.write_attribute(prim_paths, "xformOp:transform", matrices)

    # Token strings — auto-detected from list[str]
    renderer.write_attribute(prim_paths, "displayName", ["Cube", "Sphere"])
Parameters:
Return type:

None

write_array_attribute(
prim_paths,
attribute_name,
tensors,
semantic=Semantic.NONE,
is_token=False,
dirty_bits=None,
prim_mode=PrimMode.EXISTING_ONLY,
data_access=DataAccess.SYNC,
cuda_stream=None,
cuda_event=None,
)[source]#

Deprecated since ovrtx 0.4. Use ovstage.Stage.write_attribute() with an ordinal and reusable query instead.

Write array attribute data synchronously.

Pass data directly — the element type and component count are inferred automatically from the input:

  • Tensor input: Each tensor corresponds to one prim. The element type is derived from the array’s dtype and shape. Lengths may differ per prim.

  • String input (list[list[str]]): defaults to path/relationship arrays. Set is_token=True for token arrays such as custom label or category attributes.

Args:

prim_paths: List of prim paths to write to. attribute_name: Name of the array attribute. tensors: List of tensors (NumPy arrays, Warp arrays, or any

__dlpack__-compatible object), one per prim. Lengths may differ but element dtype must match the USD attribute schema. For string arrays, pass list[list[str]] instead.

semantic: Optional attribute semantic (e.g.,

Semantic.PATH_STRING). When omitted (default), the element type is inferred from the input data.

is_token: When passing list[list[str]] data, set True to write

token arrays instead of path/relationship arrays. Ignored for tensor data. Default False.

dirty_bits: Optional dirty bit array for selective updates. prim_mode: Prim binding mode (e.g., PrimMode.EXISTING_ONLY). data_access: Data access mode. DataAccess.SYNC (default) copies input

data immediately. DataAccess.ASYNC references the caller’s buffer until the operation completes (zero-copy). Not allowed with string data.

cuda_stream: Optional CUDA stream handle (int) on which the input

tensor’s data is (or will be) ready. ovrtx synchronizes its read of the tensor against this stream and forwards it to the DLPack producer (e.g. Warp) so any pending work on a different stream is bridged automatically. If omitted, the caller must ensure the tensor’s state is fully settled before calling.

cuda_event: CUDA event handle (int) for GPU synchronization.

Raises:

RuntimeError: If renderer is invalid or write fails. ValueError: If invalid parameters or dtype mismatch. TypeError: If any tensor type is not supported, or if string data

is not list[str].

Note:

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

  • int[] becomes np.int32

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

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

Example:

.. code-block:: python

    import numpy as np

    # Tensor array write
    face_counts = np.array([4, 4, 4], dtype=np.int32)
    renderer.write_array_attribute(["/World/Mesh"], "faceVertexCounts", [face_counts])

    # Relationship arrays — default for list[list[str]]
    renderer.write_array_attribute(["/World/Mesh"], "material:binding",
        [["path1", "path2"]])

    # Token arrays — explicit is_token override
    renderer.write_array_attribute(["/World/Mesh"], "omni:docTokens",
        [["sensor", "validated"]], is_token=True, prim_mode=ovrtx.PrimMode.CREATE_NEW)
Parameters:
Return type:

None

write_attribute_async(
prim_paths,
attribute_name,
tensor,
semantic=Semantic.NONE,
dirty_bits=None,
prim_mode=PrimMode.EXISTING_ONLY,
data_access=DataAccess.SYNC,
cuda_stream=None,
cuda_event=None,
)[source]#

Deprecated since ovrtx 0.4. Use ovstage.Stage.write_attribute() with an ordinal and reusable query instead.

Write scalar attribute data asynchronously.

See write_attribute() for full documentation and examples.

Returns:

Operation for async control (yields None on completion).

Parameters:
Return type:

Operation[bool]

write_array_attribute_async(
prim_paths,
attribute_name,
tensors,
semantic=Semantic.NONE,
is_token=False,
dirty_bits=None,
prim_mode=PrimMode.EXISTING_ONLY,
data_access=DataAccess.SYNC,
cuda_stream=None,
cuda_event=None,
)[source]#

Deprecated since ovrtx 0.4. Use ovstage.Stage.write_attribute() with an ordinal and reusable query instead.

Write array attribute data asynchronously.

See write_array_attribute() for full documentation and examples.

Returns:

Operation for async control (yields None on completion).

Parameters:
Return type:

Operation[bool]

bind_attribute(
prim_paths,
attribute_name,
dtype=None,
shape=None,
semantic=Semantic.NONE,
prim_mode=PrimMode.EXISTING_ONLY,
flags=<BindingFlag.NONE: 0>,
)[source]#

Deprecated since ovrtx 0.4. Use a reusable ovstage query with ovstage.Stage read, write, or map operations instead.

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.

Specify the attribute type using dtype and optionally shape:

  • Tensor types: dtype="float32", shape=(3,) for point3f, dtype="float64", shape=(4, 4) for matrix4d, etc.

  • String types: dtype="token" or dtype="path".

  • Scalars: dtype="int32" (no shape needed).

Args:

prim_paths: List of prim paths. attribute_name: Name of the attribute. dtype: Element type. Accepts string names ("float32",

"float64", "int32", "token", "path"), NumPy dtypes (np.float32, np.dtype("float64")), any dtype object with .kind/.itemsize attributes (CuPy, JAX), Python built-ins (float, int), or a DLDataType object.

shape: Element shape tuple (e.g. (3,) for 3-component vectors,

(4, 4) for matrices). Mandatory for multi-component types when using numpy dtypes or string names. Omit for scalars. Ignored for string types and DLDataType.

semantic: Optional attribute semantic (e.g.,

Semantic.XFORM_MAT4x4). Alternative to dtype/shape for specifying the attribute type.

prim_mode: Prim binding mode (e.g., PrimMode.EXISTING_ONLY). flags: Binding optimization hint. BindingFlag.OPTIMIZE tells

the runtime to optimize for frequent high-volume writes through this binding. Default: BindingFlag.NONE.

Returns:

AttributeBinding[DLTensor] for scalar attribute writes.

Example:

.. code-block:: python

            # String form — no imports needed for dtype specification:
            binding = renderer.bind_attribute(
                ["/World/Cube"], "xformOp:transform",
                dtype="float64", shape=(4, 4))

            # NumPy dtype objects also work:
            import numpy as np
            binding = renderer.bind_attribute(
                ["/World/Cube"], "visibility", dtype=np.int32)
Parameters:
Return type:

AttributeBinding[DLTensor]

bind_attribute_async(
prim_paths,
attribute_name,
dtype=None,
shape=None,
semantic=Semantic.NONE,
prim_mode=PrimMode.EXISTING_ONLY,
flags=<BindingFlag.NONE: 0>,
)[source]#

Deprecated since ovrtx 0.4. Use a reusable ovstage query with ovstage.Stage read, write, or map operations instead.

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

See bind_attribute() for full documentation and examples.

Parameters:
Return type:

Operation[AttributeBinding[DLTensor]]

bind_array_attribute(
prim_paths,
attribute_name,
dtype=None,
shape=None,
prim_mode=PrimMode.EXISTING_ONLY,
flags=<BindingFlag.NONE: 0>,
)[source]#

Deprecated since ovrtx 0.4. Use a reusable ovstage query with ovstage.Stage read, write, or map operations instead.

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.

Args:

prim_paths: List of prim paths. attribute_name: Name of the array attribute. dtype: Element type. Accepts string names ("float32",

"float64", "int32", "token", "path"), NumPy dtypes (np.float32, np.dtype("float64")), any dtype object with .kind/.itemsize attributes (CuPy, JAX), Python built-ins (float, int), or a DLDataType object.

shape: Element shape tuple (e.g. (3,) for float3[]).

Mandatory for multi-component types when using numpy dtypes or string names. Ignored for string types and DLDataType.

prim_mode: Prim binding mode (e.g., PrimMode.CREATE_NEW). flags: Binding optimization hint. BindingFlag.OPTIMIZE tells

the runtime to optimize for frequent high-volume writes through this binding. Default: BindingFlag.NONE.

Returns:

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

Example:

.. code-block:: python

            # String form — no imports needed for dtype specification:
            binding = renderer.bind_array_attribute(
                ["/World/Mesh"], "faceVertexCounts", dtype="int32")

            binding = renderer.bind_array_attribute(
                ["/World/Mesh"], "points", dtype="float32", shape=(3,))

            # NumPy dtype objects also work:
            import numpy as np
            binding = renderer.bind_array_attribute(
                ["/World/Mesh"], "normals", dtype=np.float32, shape=(3,))
Parameters:
Return type:

AttributeBinding[List[DLTensor]]

bind_array_attribute_async(
prim_paths,
attribute_name,
dtype=None,
shape=None,
prim_mode=PrimMode.EXISTING_ONLY,
flags=<BindingFlag.NONE: 0>,
)[source]#

Deprecated since ovrtx 0.4. Use a reusable ovstage query with ovstage.Stage read, write, or map operations instead.

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

See bind_array_attribute() for full documentation and examples.

Parameters:
Return type:

Operation[AttributeBinding[List[DLTensor]]]

map_attribute(
prim_paths,
attribute_name,
dtype=None,
shape=None,
semantic=Semantic.NONE,
device=Device.CPU,
device_id=0,
prim_mode=PrimMode.EXISTING_ONLY,
)[source]#

Deprecated since ovrtx 0.4. Use ovstage.Stage.map_attribute() with an ordinal and reusable query instead.

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

Returns an AttributeMapping that provides access to an internal buffer. Write data using NumPy, Warp, or any __dlpack__-compatible library, then call unmap_attribute() to apply the changes.

When dtype/shape are provided, the returned tensor is automatically shaped to match. For example, dtype="float32", shape=(3,) returns a tensor with shape (N, 3) and float32 dtype, ready for direct NumPy/Warp consumption.

Note:

Only scalar attributes (one value per prim) are supported at this time. Variable-length array attributes (e.g., point3f[] points, int[] faceVertexCounts) cannot be mapped because each prim may have a different number of elements. Use write_array_attribute() for array attributes — it accepts per-prim tensors of varying length.

Args:

prim_paths: List of prim paths. attribute_name: Name of the attribute. dtype: Element type. Accepts string names ("float32",

"float64", "int32", "token", "path"), NumPy dtypes (np.float32, np.dtype("float64")), any dtype object with .kind/.itemsize attributes (CuPy, JAX), Python built-ins (float, int), or a DLDataType object.

shape: Element shape tuple (e.g. (3,) for 3-component vectors,

(4, 4) for matrices). When provided, the mapped tensor is reshaped to (N, *shape). Ignored for DLDataType.

semantic: Optional attribute semantic (e.g.,

Semantic.XFORM_MAT4x4). Alternative to dtype/shape for specifying the attribute type.

device: Device for mapping (Device.CPU or Device.CUDA). device_id: Device ID (default 0, typically GPU index for CUDA). prim_mode: Prim binding mode (e.g., PrimMode.EXISTING_ONLY).

Returns:

AttributeMapping with access to the internal buffer. When shape was provided, the tensor has dimensions (N, *shape) with a scalar element dtype, ready for NumPy/Warp consumption.

Raises:

RuntimeError: If renderer is invalid or mapping fails. ValueError: If invalid parameters or dtype mismatch.

Example:

.. code-block:: python

    import numpy as np

            # String form — no imports needed for dtype specification:
            mapping = renderer.map_attribute(
                ["/World/Cube"], "xformOp:transform",
                dtype="float64", shape=(4, 4))
            np.from_dlpack(mapping.tensor)[0] = np.eye(4)
            renderer.unmap_attribute(mapping)

            # NumPy dtype objects also work:
            with renderer.map_attribute(["/World/Cube"], "points",
                    dtype=np.float32, shape=(3,)) as mapping:
                np.from_dlpack(mapping.tensor)[:] = new_points
Parameters:
Return type:

AttributeMapping

unmap_attribute(mapping, event=None, stream=None)[source]#

Deprecated since ovrtx 0.4. Use ovstage.Map.unmap() or ovstage.Stage.unmap_attribute() instead.

Commit written data to stage and free the C buffer.

Delegates to mapping.unmap() — a synchronous blocking call. Data is committed to the stage when this method returns.

Args:

mapping: AttributeMapping from map_attribute() event: CUDA event handle to wait on before committing. stream: CUDA stream handle to synchronize before committing.

Raises:

ValueError: If event/stream provided for CPU-mapped attribute. ValueError: If both event and stream provided (mutually exclusive).

Parameters:
Return type:

None

unmap_attribute_async(mapping, event=None, stream=None)[source]#

Deprecated since ovrtx 0.4. Use ovstage.Map.unmap() or ovstage.Stage.unmap_attribute() instead.

Enqueue attribute unmap and return an Operation for caller-managed wait.

Delegates to mapping.unmap_async(). The mapping is marked as unmapped immediately — __del__ becomes a no-op.

Args:

mapping: AttributeMapping from map_attribute() event: CUDA event handle to wait on before committing. stream: CUDA stream handle to synchronize before committing.

Returns:

Operation[bool] for async control

Raises:

RuntimeError: If renderer is invalid or mapping already unmapped. ValueError: If event/stream provided for CPU-mapped attribute. ValueError: If both event and stream provided (mutually exclusive).

Parameters:
Return type:

Operation[bool]

__bool__()[source]#

Return True if renderer is valid, False if destroyed.

Return type:

bool

property config: RendererConfig#

Get the configuration used to create this renderer.

Configuration#

class ovrtx.RendererConfig[source]#

ovrtx renderer configuration.

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

enable_profiling: bool | None = None#

Enable internal profiling. Adds overhead when enabled.

read_gpu_transforms: bool | None = None#

Use GPU world transform propagation during rendering.

keep_system_alive: bool | None = None#

Keep the renderer system alive after all instances are destroyed so the next create reuses it.

When omitted (None), the native layer defaults to enabled.

active_cuda_gpus: str | None = None#

Comma-separated CUDA device indices to use for rendering (e.g., “0,1,2”).

use_vulkan: bool | None = None#

Select Vulkan rendering backend. On Linux Vulkan is always used. On Windows, set True to force Vulkan instead of the default DX12.

selection_outline_enabled: bool | None = None#

Enable the selection-outline post-process pass. Defaults to False when unset. Init-time only; toggling requires recreating the renderer.

selection_outline_width: int | None = None#

Selection outline width in pixels. Valid range is 0..15 (the underlying RTX outline pipeline cap); out-of-range values are clamped by the renderer. Init-time only; changing requires recreating the renderer. Default: 2.

selection_fill_mode: SelectionFillMode | None = None#

Selection-outline fill (interior) mode. Accepts a SelectionFillMode member or the equivalent int value (0..3). Out-of-range values are clamped by the renderer.

Init-time only; changing requires recreating the renderer. Default: SelectionFillMode.GLOBAL.

enable_geometry_streaming: bool | None = None#

Geometry streaming opt-in config entry.

enable_geometry_streaming_lod: bool | None = None#

Geometry streaming LOD opt-in config entry.

__init__(
sync_mode=None,
log_file_path=None,
log_level=None,
enable_profiling=None,
read_gpu_transforms=None,
keep_system_alive=None,
active_cuda_gpus=None,
use_vulkan=None,
selection_outline_enabled=None,
selection_outline_width=None,
selection_fill_mode=None,
enable_geometry_streaming=None,
enable_geometry_streaming_lod=None,
enable_spg=None,
motion_bvh=None,
)#
Parameters:

  • sync_mode (bool | None)

  • log_file_path (str | None)

  • log_level (str | None)

  • enable_profiling (bool | None)

  • read_gpu_transforms (bool | None)

  • keep_system_alive (bool | None)

  • active_cuda_gpus (str | None)

  • use_vulkan (bool | None)

  • selection_outline_enabled (bool | None)

  • selection_outline_width (int | None)

  • selection_fill_mode (SelectionFillMode | None)

  • enable_geometry_streaming (bool | None)

  • enable_geometry_streaming_lod (bool | None)

  • enable_spg (bool | None)

  • motion_bvh (MotionBvh | None)

Return type:

None

enable_spg: bool | None = None#

Set to False to disable Sensor Processing Graphs (SPG), enabled by default. This is a global setting, applying to all active renderer instances.

motion_bvh: MotionBvh | None = None#

Motion BVH mode for sensor pipelines (lidar, radar, acoustic).

Accepts a MotionBvh member, the equivalent int value (0..2), or the strings "disable", "enable", or "auto".

When None (default), motion BVH is disabled and no config entry is sent. Sensor workflows should pass MotionBvh.AUTO or MotionBvh.ENABLE. Init-time only; changing requires recreating the renderer.

class ovrtx.SelectionGroupStyle[source]#

Per-group visual styling for the selection-outline pass.

Used as the value side of the dict passed to Renderer.set_selection_group_styles(). RGBA components are floats in [0, 1].

Group ids (the dict keys) are uint8 (0..255) and match the per-prim group id assigned through the renderer selection-outline group API.

Note

Outline thickness and the fill/interior mode are global init-time settings — see RendererConfig.selection_outline_width and RendererConfig.selection_fill_mode. Outline dashing is not supported by the underlying renderer.

__init__(outline_color, fill_color)#
Parameters:
Return type:

None

outline_color: tuple[float, float, float, float]#

Outline edge color (RGBA, [0, 1]).

fill_color: tuple[float, float, float, float]#

Interior fill color (RGBA, [0, 1]). Used when the global fill mode selects per-group fill modes (2 or 3).

Async Operations#

class ovrtx.Operation[source]#

Represents an enqueued async operation.

None return means timeout; errors raise RuntimeError. Void operations (no payload) return True on success.

For simple operations (add_usd_reference, reset_stage), wait() returns the result directly:

op = renderer.add_usd_reference_async(path, "/World/Props")
handle = op.wait()                           # infinite wait
handle = op.wait(timeout_ns=0)               # poll, None = not ready
handle = op.wait(timeout_ns=5_000_000_000)   # 5s, None = timed out

For void operations (Operation[bool]), wait() returns True on success, None on timeout:

op = renderer.reset_stage_async()
if op.wait(timeout_ns=0):                    # True when complete
    print("reset done")
else:
    print("still running (or timed out)")

Fetchable operations (step, query, read) have a two-phase lifecycle:

  1. Operation wait — wait() blocks until the enqueued GPU/CPU work completes (or times out). Returns a PendingFetch on success, None on timeout.

  2. Fetch — PendingFetch.fetch() retrieves the computed data (or times out). Returns the final result on success (QueryResult, ReadResult, etc.), None on timeout.

Each phase has independent timeout control:

op = renderer.step_async(...)
pending = op.wait(timeout_ns=5_000_000_000)   # None = timed out
result = pending.fetch(timeout_ns=100_000_000) # None = timed out
__init__(
renderer,
op_id,
handle=None,
operation_name='',
fetch_fn=None,
cleanup_fn=None,
)[source]#
Parameters:
property op_id: int#

The operation ID.

wait(timeout_ns=None)[source]#

Wait for operation to complete.

Parameters:

timeout_ns (int | None) – Timeout in nanoseconds. None (default) = infinite wait, 0 = non-blocking poll, >0 = wait for specified duration.

Returns:

PendingFetch for fetchable operations (step, query, read), the operation’s result value for simple operations (e.g. a USD handle from add_usd_reference), True for void operations (no payload), or None on timeout.

Raises:

RuntimeError – If operation failed.

Return type:

T | None

Note

None always indicates timeout — success always returns a non-None value. Void operations return True on success so callers can distinguish completion from timeout with a simple truthiness check.

Examples:

# Fetchable operation (step, query, read) — wait returns PendingFetch
op = renderer.step_async(...)
pending = op.wait()           # PendingFetch[RenderProductSetOutputs]
result = pending.fetch()      # RenderProductSetOutputs

# Simple operation (add_usd_reference) — wait returns handle directly
op = renderer.add_usd_reference_async(path, "/World/Props")
handle = op.wait()            # USD handle (no fetch phase)

# Void operation (reset_stage, write_attribute, ...) — wait returns True
op = renderer.reset_stage_async()
assert op.wait() is True

# Polling with timeout
pending = op.wait(timeout_ns=0)
if pending is None:
    print("Not ready yet")
query_status()[source]#

Query the current progress of this operation.

Returns a point-in-time snapshot. The returned OperationStatus is a plain dataclass with no C resources attached.

Return type:

OperationStatus

__del__()[source]#

Warn and block if operation was never waited on.

class ovrtx.PendingFetch[source]#

Phase 2 of a fetchable operation’s lifecycle (see Operation).

Returned by Operation.wait() after the enqueued work completes. Call fetch() to retrieve the final result (e.g. QueryResult, ReadResult, RenderProductSetOutputs).

The fetch is stream-ordered — it may block waiting for prior GPU work in the stream to drain, independently of the operation wait timeout.

If garbage-collected without fetch(), forces a blocking fetch with a ResourceWarning to prevent C resource leaks.

__init__(fetch_fn)[source]#
Parameters:

fetch_fn (Callable[[int | None], T | None])

fetch(timeout_ns=None)[source]#

Fetch the result data.

Idempotent — subsequent calls return the cached result.

Parameters:

timeout_ns (int | None) – Fetch timeout in nanoseconds. None = infinite (default).

Returns:

The final result, or None on timeout.

Return type:

T | None

class ovrtx.OperationStatus[source]#

Snapshot of an operation’s progress.

Returned by Operation.query_status(). Fields are copied from the C ovrtx_op_status_t struct and the C resources are released immediately, so this object has no special lifecycle requirements.

__init__(state, progress, counters)#
Parameters:
Return type:

None

state: EventStatus#

PENDING, COMPLETED, or FAILURE.

progress: float#

Fraction complete in [0.0, 1.0]. Negative means indeterminate.

counters: list[OperationCounter]#

Per-resource counters (may be empty).

class ovrtx.OperationCounter[source]#

Named resource counter from an operation progress query.

__init__(name, current, total)#
Parameters:
Return type:

None

name: str#

Counter name (e.g. "systems"). Assigned by the C runtime.

current: int#

Current value. Monotonically increases toward total.

total: int#

Target value. 0 means the total is unknown.

Render Outputs#

class ovrtx.RenderProductSetOutputs[source]#

Dict-like container for rendering results from a step operation.

Acts as a dictionary mapping render product paths to ProductOutput instances.

Example:

# Dict-like iteration
products = renderer.step(...)
for product_name, product in products.items():
    for frame in product.frames:
        for var_name, render_var in frame.render_vars.items():
            mapping = render_var.map()
            # Process mapping.tensor...

# Dict-like indexing
product = products["/Render/Product0"]

# Membership test
if "/Render/Product0" in products:
    ...
__init__(destroy_fn, products)[source]#

Internal: Created by Renderer._fetch_results().

Parameters:

  • destroy_fn (Callable[[], None]) – Callable that releases C step result resources.

  • products (dict[str, ProductOutput[T]]) – Parsed product outputs keyed by render product name

__getitem__(key)[source]#

Get product by render product path.

Parameters:

key (str)

Return type:

ProductOutput[T]

__iter__()[source]#

Iterate over render product paths.

__len__()[source]#

Number of render products.

Return type:

int

__contains__(key)[source]#

Check if render product path exists.

Parameters:

key (str)

Return type:

bool

keys()[source]#

Get all render product paths.

values()[source]#

Get all ProductOutput instances.

items()[source]#

Get all (path, ProductOutput) pairs.

__del__()[source]#

Auto-cleanup on garbage collection.

Releases the step result handle. The lifetime of render variable mappings and any DLPack views derived from them is independent of this call — they are released when their own unmap fires (via the mapping’s own deleter chain).

class ovrtx.ProductOutput[source]#

Single render product with multiple frames.

name: str#
frames: list[FrameOutput[T]]#
__init__(name, frames)#
Parameters:
Return type:

None

class ovrtx.FrameOutput[source]#

Single frame with multiple render variables.

start_time: float#

Sensor simulation time at frame start, in seconds.

Accumulated from delta_time values passed to Renderer.step(). Epoch is 0.0 at renderer creation and after reset_stage(); set to time after reset(time=...).

end_time: float#

Sensor simulation time at frame end, in seconds (start_time + delta_time).

render_vars: dict[str, RenderVarOutput[T]]#
progression: int = 0#

Path-tracing sample accumulation progress for this render product frame.

Increases with each time an output is rendered to in a call to Renderer.step(). Resets after Renderer.reset(), or when internal conditions invalidate the current accumulation state (ex: scene changes, camera movement, etc.)

converged: bool = False#

True when the path tracer has reached the omni:rtx:pt:samplesPerPixel stop criterion.

Once True, additional Renderer.step() calls will not result in additional sample accumulation until Renderer.reset() is called or the scene changes. Always False for non-PT render modes.

__init__(
start_time,
end_time,
render_vars,
progression=0,
converged=False,
)#
Parameters:
Return type:

None

class ovrtx.RenderVarOutput[source]#

Single render variable output, fetched as part of a RenderProductSetOutputs.

Use map() to obtain a MappedRenderVar exposing the render variable’s tensors and params via DLPack.

Example:

with render_var.map(device=Device.CUDA) as rv:
    arr = wp.from_dlpack(rv)            # single-tensor render variable
    wp.launch(my_kernel, inputs=[arr])
__init__(name, handle, renderer)[source]#

Internal: created by Renderer._fetch_results().

Parameters:
map(device=Device.CPU, sync_stream=None)[source]#

Map this render variable output and return a MappedRenderVar.

Use either the context-manager form (with ... as rv:) or the direct form (rv = ...; rv.unmap()); they are equivalent. See MappedRenderVar for the full usage surface.

Parameters:

  • device (Device) – Target device (Device.CPU or Device.CUDA).

  • sync_stream (int | None) – Optional CUDA stream handle. When provided, the stream waits for render completion before subsequent work runs on it. Default: 1 for CUDA (default stream), 0 for CPU.

Returns:

A MappedRenderVar exposing the render variable’s tensors, params, and description fields.

Raises:

RuntimeError – If mapping fails or this output is already mapped (call MappedRenderVar.unmap() on the prior mapping first).

Return type:

MappedRenderVar

class ovrtx.MappedRenderVar[source]#

One mapped render variable: named tensors, named params, and the render variable’s description fields (name, type, doc, version).

Returned by RenderVarOutput.map(). A render variable that carries a single tensor exposes it via the DLPack protocol on the mapping itself (np.from_dlpack(rv)); one with multiple tensors exposes them via a dict protocol (rv["tensor_name"]). Param values are reached via params.

Lifetime. Use either the context-manager form or a direct unmap() call to signal that you are done. The underlying buffer stays valid for as long as anything you derived from it is still in use — a NumPy or Warp array, a DLPack capsule, a tensor or param obtained from this mapping. You do not need to manage that explicitly.

After unmap() (or __exit__) has run, requesting a new tensor or param from this mapping raises RuntimeError. Tensors and params obtained earlier — and any arrays already minted from them — remain readable.

GPU mappings. The producer’s CUDA work may still be in flight when map() returns. Reading tensor data before wait_event has fired is a race — the access sees uninitialized or stale memory. Use exactly one of the patterns below to enforce ordering:

  1. Auto-barrier on a stream you’ll use — pass sync_stream=your_stream to map() and then queue your downstream kernel on your_stream. ovrtx inserts cudaStreamWaitEvent(your_stream, wait_event) for you, so the kernel observes the barrier; the data is not valid for any access on a different stream or on the CPU under this pattern.

  2. Explicit stream-ordered wait — call wait_on() (your_stream) and then queue your downstream kernel on your_stream. Same effect as (1); use this when the consumer stream is chosen after map() time, or when no sync_stream was passed.

  3. Explicit CPU-block — call wait(). The calling thread blocks until wait_event fires; after it returns, the data is valid for any subsequent access (CPU read, fresh kernel launch on any stream, etc.).

CPU mappings (device=Device.CPU) are always valid on map return; wait() and wait_on() are silent no-ops in that case (wait_event is None).

Usage:

# Context-manager form.
with render_var.map(device=Device.CUDA) as rv:
    arr = wp.from_dlpack(rv)            # single-tensor render variable
do_work(arr)                            # consumer view still valid

# Multi-tensor render variable: dict access by tensor name.
with render_var.map(device=Device.CPU) as rv:
    coords = np.from_dlpack(rv["Coordinates"])
    frame_id = int(np.from_dlpack(rv.params["frameId"]))

# Direct map / unmap.
rv = render_var.map(device=Device.CUDA)
arr = wp.from_dlpack(rv)
rv.unmap(stream=cuda_stream)            # release with a sync hint
do_work(arr)
__init__(
*,
renderer,
map_handle,
device,
name,
type,
doc,
version,
tensors,
params,
wait_event=None,
)[source]#

Internal: constructed by Renderer._map_output() after decoding the C struct.

tensors and params are lists of (name: str, doc: str, dl: DLTensor) triples — the C-side ovx_string_t fields decoded to Python str and the DLTensor structs copied by value (their inner pointers still reference C-side memory tied to map_handle).

wait_event is the producer-done CUDA event handle for GPU mappings, or None for CPU mappings (and any GPU mapping where every tensor is CPU- resident — the C side already CPU-blocked + copied).

Parameters:
property device: Device#

Device this render variable’s tensors are mapped to (params are always CPU).

property params: dict[str, RenderVarParam]#

{name: RenderVarParam} dict for this render variable’s params (always CPU).

Each access returns a new dict of new RenderVarParam instances over the same underlying data — no copy of the param buffers is performed (the data itself is shared).

Raises:

RuntimeError – If accessed after unmap().

property tensor: ManagedDLTensor#

Deprecated. Returns the sole tensor of a single-tensor render variable as a ManagedDLTensor.

Emits DeprecationWarning. Raises if this render variable carries multiple tensors or none.

Prefer np.from_dlpack(rv) for a single-tensor render variable and rv["<name>"] when there are multiple tensors. The returned ManagedDLTensor preserves the historical signature of this accessor — its .numpy(), .to_bytes(), .data, .shape, .dtype, etc. continue to work as before, and the underlying buffer’s lifetime is tied to this mapping for as long as any view you minted from it is alive.

__dlpack_device__()[source]#

Return (device_type, device_id) for the sole tensor.

Only valid on a single-tensor render variable; raises if the render variable carries multiple tensors or none.

Return type:

tuple[int, int]

__dlpack__(
*,
stream=None,
max_version=None,
dl_device=None,
copy=None,
)[source]#

Mint a DLPack capsule for the sole tensor.

Only valid on a single-tensor render variable; raises if the render variable carries multiple tensors or none. For multi-tensor render variables, use rv["<tensor_name>"]; for a render variable with only params, use rv.params.

Parameters:
Return type:

Any

__getitem__(key)[source]#

Return the RenderVarTensor for the named tensor.

Each call returns a new RenderVarTensor over the same underlying data — accessing a name twice does not copy or duplicate the buffer (no identity guarantee across calls; the data itself is shared).

Raises:
Parameters:

key (str)

Return type:

RenderVarTensor

__iter__()[source]#

Iterate tensor names in declaration order.

__len__()[source]#

Number of tensors in this render variable.

Return type:

int

keys()[source]#

Tensor names.

values()[source]#

Iterator of RenderVarTensor in declaration order.

items()[source]#

Iterator of (name, RenderVarTensor) pairs in declaration order.

property wait_event: int | None#

Producer-done CUDA event handle, or None if no wait is needed.

None for CPU mappings and for any GPU mapping whose tensors all landed on the CPU (the C side already CPU-blocked + copied). For GPU-resident tensors, this is the event the consumer must observe before reading — see the class docstring for the three usage patterns.

wait()[source]#

Block the calling thread until wait_event has fired.

Silent no-op when wait_event is None. After this returns, the data is valid for any subsequent access.

Return type:

None

wait_on(stream)[source]#

Insert a wait barrier into stream against wait_event.

Silent no-op when wait_event is None. Does not CPU-block. Any kernel queued on stream after this call observes the producer as done.

Parameters:

stream (int) – CUDA stream handle (integer). May be on any device — the runtime handles cross-context bookkeeping.

Return type:

None

unmap(event=None, stream=None)[source]#

Release interest in this mapping. Idempotent.

Subsequent attempts to mint new views on this mapping (rv["X"], np.from_dlpack(rv)) raise RuntimeError. Views minted earlier remain readable, and the buffer stays alive while any of them are still referenced. The originating RenderVarOutput is immediately remappable.

Parameters:

  • event (int | None) – Optional CUDA event handle to wait on before the buffer is eventually released. Mutually exclusive with stream. Not accepted for CPU-mapped outputs.

  • stream (int | None) – Optional CUDA stream handle to synchronize before the buffer is eventually released. Mutually exclusive with event. Not accepted for CPU-mapped outputs.

Raises:

ValueError – If event or stream is provided for a CPU-mapped output, or if both are provided together.

Return type:

None

Note

First call wins — subsequent calls are no-ops, and any sync hint recorded by the first call is preserved. __exit__ of a with block is equivalent to calling unmap() with no sync args.

__del__()[source]#

Release the underlying buffer when the last reference is dropped.

Idempotent: if cleanup already ran (e.g. the renderer was torn down and force-released this mapping first), this is a no-op. Skips the underlying C call when the renderer has already been destroyed, so a mapping outliving its renderer collects cleanly. As a fallback for instances dropped without an explicit unmap() or __exit__, also resets the originating output’s re-map gate so the same RenderVarOutput can be mapped again.

Return type:

None

class ovrtx.RenderVarTensor[source]#

One named tensor from a mapped render variable.

Returned by rv["<name>"]. Implements the DLPack protocol so consumers can do np.from_dlpack(rv["Coordinates"]) directly. Exposes the tensor’s name, doc, shape, dtype, device, and ndim.

Safe to keep around past the originating with block or a MappedRenderVar.unmap() call — the underlying buffer remains valid until both this object and any arrays minted from it have been dropped.

__init__(parent, record)[source]#

Internal: constructed by MappedRenderVar.__getitem__().

Parameters:
property name: str#

Tensor name, e.g. "Coordinates", "Intensity".

property doc: str#

Human-readable description of the tensor (may be empty).

property shape: tuple#

Tensor shape as a tuple of ints (read from the live DLTensor).

property dtype: DLDataType#

DLPack data type descriptor.

property device#

DLPack device descriptor.

property ndim: int#

Tensor rank.

class ovrtx.RenderVarParam[source]#

One named param value from a mapped render variable. Always CPU-resident.

Returned by rv.params["<name>"]. Implements the DLPack protocol so consumers can do np.from_dlpack(rv.params["frameId"]) directly. Exposes the param’s name, doc, shape, dtype, device, and ndim.

Safe to keep around past the originating with block or a MappedRenderVar.unmap() call — same lifetime contract as RenderVarTensor.

__init__(parent, record)[source]#

Internal: constructed by MappedRenderVar.params.

Parameters:
property name: str#

Param name, e.g. "frameId", "timestampNs".

property doc: str#

Human-readable description of the param (may be empty).

property shape: tuple#

Param shape as a tuple of ints (scalar params have shape ()).

property dtype: DLDataType#

DLPack data type descriptor.

property device#

DLPack device descriptor (always CPU for params).

property ndim: int#

Param rank.

class ovrtx.ManagedDLTensor[source]#

Managed DLPack tensor wrapper with protocol version support.

Obtained from AttributeMapping.tensor (for attribute maps). Pass the instance to np.from_dlpack() / wp.from_dlpack() / torch.from_dlpack() for zero-copy array access, or call numpy() / to_bytes() directly.

Supports both DLPack 0.x and 1.0 protocols. When a consumer (e.g. NumPy 2.1+) requests a versioned capsule via __dlpack__(max_version=...), this returns a DLManagedTensorVersioned with proper read-only/writeable flags.

__init__(
dl_tensor,
manager_ctx,
deleter_callback=None,
readonly=True,
)[source]#
Parameters:

  • dl_tensor (DLTensor)

  • manager_ctx (Any)

  • deleter_callback (Callable | None)

  • readonly (bool)

property shape: tuple[int, ...]#

Shape as Python tuple.

property ndim: int#

Number of dimensions.

property dtype#

Data type descriptor.

property data: int#

Data pointer address.

property device#

Device info.

property raw_dltensor: DLTensor#

Access underlying DLTensor (advanced use).

to_bytes()[source]#

Get pixel data as bytes (creates copy).

Return type:

bytes

numpy()[source]#

Get NumPy array view of this tensor.

Returns:

NumPy ndarray view of the tensor data (zero-copy).

Return type:

numpy.ndarray

Note

Writeability is controlled by the readonly flag passed to the ManagedDLTensor constructor, which sets the DLPack 1.0 DLPACK_FLAG_BITMASK_READ_ONLY flag in the versioned capsule.

NumPy 2.1+ behavior: Calls __dlpack__(max_version=(1, 0)), receives versioned capsule with flags, and respects DLPACK_FLAG_BITMASK_READ_ONLY — the returned array is writeable only when the flag is not set.

NumPy <2.1 behavior: Calls __dlpack__() without max_version, receives legacy (unversioned) capsule, and always marks external buffers as read-only regardless of flags.

__dlpack_device__()[source]#

Return (device_type, device_id) tuple.

Return type:

tuple[int, int]

__dlpack__(
*,
stream=None,
max_version=None,
dl_device=None,
copy=None,
)[source]#

Create DLPack capsule for tensor exchange.

Parameters:

  • stream (int | None) – CUDA stream hint from consumer. Accepted but ignored - caller is responsible for synchronization before accessing the data. Per DLPack: None=legacy, -1=no sync needed, 1=null stream, positive=actual stream handle.

  • max_version (tuple[int, int] | None) – Maximum DLPack version supported by consumer, e.g. (1, 0)

  • dl_device (tuple[int, int] | None) – Target device (not supported, must match tensor device)

  • copy (bool | None) – Whether to copy data (not supported, must be None or False)

Returns:

PyCapsule containing DLManagedTensor or DLManagedTensorVersioned

Return type:

Any

__del__()[source]#

Call cleanup callback on destruction.

Attribute Bindings and Mappings#

class ovrtx.AttributeBinding[source]#

Persistent attribute binding for efficient repeated writes or maps.

Created by Renderer.bind_attribute() or Renderer.bind_array_attribute(). Reuse for multiple write operations to avoid recreating the binding descriptor.

write() accepts NumPy arrays, Warp arrays, or any __dlpack__-compatible object. For string bindings, pass list[str] (scalar) or list[list[str]] (array).

Example (scalar):
import numpy as np

binding = renderer.bind_attribute(
    ["/World/Cube"], "xformOp:transform",
    dtype="float64", shape=(4, 4))
binding.write(np.eye(4, dtype=np.float64).reshape(1, 4, 4))
binding.unbind()
Example (array):
import numpy as np

binding = renderer.bind_array_attribute(
    ["/World/Mesh1", "/World/Mesh2"], "faceVertexCounts",
    dtype="int32")
binding.write([np.array([4, 4], dtype=np.int32), np.array([3, 3, 3], dtype=np.int32)])
binding.unbind()
__init__(
handle,
semantic,
dtype,
renderer,
is_array=False,
shape=None,
)[source]#

Initialize attribute binding (internal use - created by Renderer.bind_attribute).

Parameters:

  • handle (int) – Raw C binding handle value

  • semantic (int) – Semantic constant (OVRTX_SEMANTIC_*)

  • dtype (DLDataType) – Expected DLDataType for tensors used with this binding

  • renderer (Renderer) – Renderer instance that created this binding

  • is_array (bool) – True if this binding is for array attributes

  • shape (Optional[tuple]) – Optional element shape from the dtype/shape API, stored for map output reshaping

property handle: int#

Raw C binding handle value.

property semantic: int#

Semantic constant (OVRTX_SEMANTIC_*) for tensor reshaping.

property dtype: DLDataType#

Expected DLDataType for tensors used with this binding.

property is_array: bool#

True if this binding is for array attributes.

property shape: tuple | None#

Element shape from the dtype/shape API, or None if not specified.

write(
data,
dirty_bits=None,
data_access=DataAccess.SYNC,
cuda_stream=None,
cuda_event=None,
)[source]#

Deprecated since ovrtx 0.4. Use ovstage.Stage.write_attribute() with a reusable ovstage query instead.

Write attribute data using this binding (synchronous).

Args:
data: Data to write. Accepts NumPy arrays, Warp arrays, or any

__dlpack__-compatible object. For scalar bindings (bind_attribute): a single tensor. For array bindings (bind_array_attribute): a list of tensors, one per prim. For string bindings: a list[str] (scalar) or list[list[str]] (array).

dirty_bits: Optional dirty bit array for selective updates. data_access: Data access mode. DataAccess.SYNC (default) copies

input data immediately so the caller’s buffer can be reused after this call returns. DataAccess.ASYNC references the caller’s buffer until the operation completes (zero-copy). Not allowed with string bindings.

cuda_stream: Optional CUDA stream handle (int) on which the input

tensor’s data is (or will be) ready. ovrtx synchronizes its read of the tensor against this stream and forwards it to the DLPack producer (e.g. Warp) so any pending work on a different stream is bridged automatically. If omitted, the caller must ensure the tensor’s state is fully settled before calling.

cuda_event: CUDA event handle (int) for GPU synchronization.

Raises:

RuntimeError: If called after unbind().

Parameters:

  • data (_BindingTensorT)

  • dirty_bits (bytes | None)

  • data_access (DataAccess)

  • cuda_stream (int | None)

  • cuda_event (int | None)

Return type:

None

write_async(
data,
dirty_bits=None,
data_access=DataAccess.SYNC,
cuda_stream=None,
cuda_event=None,
)[source]#

Deprecated since ovrtx 0.4. Use ovstage.Stage.write_attribute() with a reusable ovstage query instead.

Write attribute data using this binding (asynchronous).

Args:
data: Data to write. Accepts NumPy arrays, Warp arrays, or any

__dlpack__-compatible object. For scalar bindings (bind_attribute): a single tensor. For array bindings (bind_array_attribute): a list of tensors, one per prim. For string bindings: a list[str] (scalar) or list[list[str]] (array).

dirty_bits: Optional dirty bit array for selective updates. data_access: Data access mode. DataAccess.SYNC (default) copies

input data immediately; DataAccess.ASYNC references the caller’s buffer until the operation completes (zero-copy). Not allowed with string bindings.

cuda_stream: Optional CUDA stream handle (int) on which the input

tensor’s data is (or will be) ready. ovrtx synchronizes its read of the tensor against this stream and forwards it to the DLPack producer (e.g. Warp) so any pending work on a different stream is bridged automatically. If omitted, the caller must ensure the tensor’s state is fully settled before calling.

cuda_event: Optional CUDA event handle (int) for GPU sync.

Returns:

Operation for async control (yields None on completion).

Raises:

RuntimeError: If called after unbind().

Parameters:

  • data (_BindingTensorT)

  • dirty_bits (bytes | None)

  • data_access (DataAccess)

  • cuda_stream (int | None)

  • cuda_event (int | None)

Return type:

Operation[bool]

map(device=Device.CPU, device_id=0)[source]#

Deprecated since ovrtx 0.4. Use ovstage.Stage.map_attribute() with a reusable ovstage query instead.

Map attribute buffer for direct memory access using this binding.

Convenience wrapper: delegates to Renderer._map_attribute_by_binding().

Args:

device: Device type (Device.CPU or Device.CUDA). device_id: Device ID (default 0).

Returns:

AttributeMapping for direct buffer access.

Raises:

RuntimeError: If called after unbind().

Parameters:
Return type:

AttributeMapping

unbind()[source]#

Deprecated since ovrtx 0.4. Release the reusable ovstage query with Query.release() instead.

Release this binding.

Convenience wrapper: delegates to Renderer._unbind_attribute().

Return type:

None

__del__()[source]#

Auto-unbind on garbage collection if not already unbound.

class ovrtx.AttributeMapping[source]#

High-level wrapper for mapped attribute buffer.

Provides access to an internal buffer for direct writes using NumPy, Warp, or any __dlpack__-compatible library. unmap() and __exit__ commit data to the stage synchronously. If the mapping is dropped without unmap() or a context manager, __del__ commits and frees the buffer as a safety-net fallback.

Usage:
import numpy as np

mapping = renderer.map_attribute(
    ["/World/Cube"], "xformOp:transform",
    dtype=np.float64, shape=(4, 4))

# Write data via NumPy, Warp, etc.
array = np.from_dlpack(mapping.tensor)
array[:] = source_matrix_data

# Unmap to apply changes
mapping.unmap()
Or use as context manager:
with renderer.map_attribute(...) as mapping:
    np.from_dlpack(mapping.tensor)[:] = source_data
# Automatically unmapped on exit
__init__(
mapping,
renderer,
dltensor,
binding_desc=None,
device=Device.CPU,
)[source]#

Initialize attribute mapping (internal use - created by Renderer.map_attribute).

Parameters:

  • mapping (Any) – C structure ovrtx_attribute_mapping_t containing map_handle and tensor data.

  • renderer (Renderer) – Renderer instance (needed for unmap).

  • dltensor (DLTensor) – Reshaped tensor view (provided by renderer, shaped per dtype/shape).

  • binding_desc (Any | None) – Optional binding descriptor (for write_attribute calls).

  • device (Device) – Device type (Device.CPU or Device.CUDA).

property tensor: ManagedDLTensor#

Access the mapped buffer as a tensor for NumPy, Warp, etc.

When the mapping was created with shape=, the tensor dimensions match (N, *shape) with a scalar element dtype. For Semantic.XFORM_MAT4x4 bindings, the tensor is reshaped to (N, 4, 4) for direct matrix operations.

Use np.from_dlpack(mapping.tensor) or equivalent to obtain a writable array view.

Returns:

ManagedDLTensor ready for consumption by array libraries.

Raises:

RuntimeError – If accessed after unmap().

property map_handle: int#

Get the map handle for unmap operation.

Returns:

Map handle value (uint64)

property binding_desc: Any | None#

Get the binding descriptor used for map_attribute (if available).

This can be used for write_attribute calls if needed.

Returns:

ovrtx_binding_desc_t or None

property device: Device#

Get the device type this attribute is mapped to.

unmap(event=None, stream=None)[source]#

Deprecated since ovrtx 0.4. Use ovstage.Map.unmap() or ovstage.Stage.unmap_attribute() instead.

Commit written data to stage and free the C buffer.

Enqueues the C unmap and waits for completion. Data is visible on the stage when this method returns.

Args:

event: CUDA event handle to wait on before C unmap. stream: CUDA stream handle to synchronize before C unmap.

Raises:

ValueError: If event/stream provided for CPU-mapped attribute. ValueError: If both event and stream provided (mutually exclusive).

Parameters:

  • event (int | None)

  • stream (int | None)

Return type:

None

unmap_async(event=None, stream=None)[source]#

Deprecated since ovrtx 0.4. Use ovstage.Map.unmap() or ovstage.Stage.unmap_attribute() instead.

Enqueue attribute unmap and return an Operation for caller-managed wait.

The mapping is marked as unmapped immediately — __del__ becomes a no-op. Call .wait() on the returned Operation to block until data is committed to the stage.

Args:

event: CUDA event handle to wait on before committing. stream: CUDA stream handle to synchronize before committing.

Returns:

Operation[bool] for async control.

Raises:

RuntimeError: If mapping already unmapped. ValueError: If event/stream provided for CPU-mapped attribute. ValueError: If both event and stream provided (mutually exclusive).

Parameters:

  • event (int | None)

  • stream (int | None)

Return type:

Operation[bool]

__enter__()[source]#

Context manager entry — returns self.

Return type:

AttributeMapping

__exit__(exc_type, exc_val, exc_tb)[source]#

Context manager exit — commits data and frees buffer.

__del__()[source]#

Safety fallback — enqueue C unmap if not already done.

Uses fire-and-forget (no op.wait()) because blocking C calls can deadlock inside finalizers. The enqueued operation completes when the renderer processes its next operation.

class ovrtx.AttributeInfo[source]#

Descriptor for an attribute discovered by Renderer.query_prims().

Carries the resolved attribute name, element data type, and semantic. Returned inside QueryResult dict values.

__init__(name, dtype, is_array, semantic)#
Parameters:
Return type:

None

name: str#

Resolved attribute name (e.g. "radius", "points").

dtype: DLDataType#

Element data type (code, bits, lanes).

is_array: bool#

True if the attribute is variable-length per prim.

semantic: Semantic#

Interpretation hint (NONE, TOKEN_ID, PATH_ID, TAG, etc.).

Enums#

class ovrtx.Semantic[source]#

Attribute semantic type for write, bind, and map operations.

Specifies the interpretation of attribute data. For write methods, the semantic can often be omitted — the element type is inferred from the input data. For bind/map methods, dtype/shape is the recommended alternative for standard tensor types.

The C API defines two additional packed-struct transform semantics (XFORM_POS3d_ROT4f_SCALE3f = 2, XFORM_POS3d_ROT3x3f = 3) that are intentionally omitted here. Their heterogeneous layouts (mixed float32/float64 fields) have no natural NumPy or Warp representation, so they cannot be used without manual byte packing.

NONE = 0#
XFORM_MAT4x4 = 1#
PATH_STRING = 4#
TOKEN_STRING = 5#
TOKEN_ID = 6#
PATH_ID = 7#
TAG = 8#
__new__(value)#
class ovrtx.PrimMode[source]#

Prim binding mode controlling how prim paths are resolved.

EXISTING_ONLY matches only prims that already exist on the stage. MUST_EXIST raises an error if the prim is not found. CREATE_NEW creates the prim if it does not exist.

EXISTING_ONLY = 0#
MUST_EXIST = 1#
CREATE_NEW = 2#
__new__(value)#
class ovrtx.DataAccess[source]#

Data access mode for attribute write operations.

SYNC copies input data immediately so the caller’s buffer can be reused right away. ASYNC references the caller’s buffer until the operation completes (zero-copy).

ASYNC = 0#
SYNC = 1#
__new__(value)#
class ovrtx.Device[source]#

Device type for attribute mapping and render output mapping.

Controls where mapped tensor data resides. DEFAULT lets the runtime pick the most efficient format; CPU forces a synchronous copy to host memory; CUDA returns raw device pointers; and CUDA_ARRAY returns a CUDA array handle (zero-copy for images).

DEFAULT = 0#
CPU = 1#
CUDA = 2#
CUDA_ARRAY = 3#
__new__(value)#
class ovrtx.BindingFlag[source]#

Binding optimization hint flags (bitmask).

Flags can be combined with |: BindingFlag.OPTIMIZE | future_flag.

NONE = 0#
OPTIMIZE = 1#
__new__(value)#
class ovrtx.EventStatus[source]#

Operation event status.

Indicates whether an asynchronous operation is still running, has completed successfully, or has failed.

PENDING = 0#
COMPLETED = 1#
FAILURE = 2#
__new__(value)#
class ovrtx.SelectionFillMode[source]#

Selection-outline interior (fill) mode.

Controls how the interior of selection-outlined prims is filled, parallel to the underlying RTX shader’s OutlineMode. Set globally at renderer creation via RendererConfig.selection_fill_mode (which maps to OVRTX_CONFIG_SELECTION_FILL_MODE); changing it requires recreating the renderer.

EDGE_ONLY = 0#

No interior fill — only the outline edge is drawn.

GLOBAL = 1#

Interior is filled with a single global intersection color shared across all groups.

GROUP_OUTLINE_COLOR = 2#

Interior is filled with each group’s outline color.

GROUP_FILL_COLOR = 3#

Interior is filled with each group’s dedicated fill/shade color.

__new__(value)#
class ovrtx.AttributeFilterMode[source]#

Controls which attributes are reported per prim group in query results.

NONE returns only prim grouping (lightweight prim counting). ALL returns every attribute descriptor on each group. SPECIFIC returns only a named subset (pass names via attribute_names).

NONE = 0#
ALL = 1#
SPECIFIC = 2#
__new__(value)#
class ovrtx.FilterKind[source]#

Kind of prim filter criterion for query_prims.

Each filter matches prims by a single criterion (type name or attribute existence). Combine multiple filters via require_all, require_any, and exclude lists.

PRIM_TYPE = 0#
HAS_ATTRIBUTE = 1#
__new__(value)#
class ovrtx.DLDataType[source]#

Descriptor of data type for elements of DLTensor.

TYPE_MAP = {'bfloat16': (4, 16, 1), 'float16': (2, 16, 1), 'float32': (2, 32, 1), 'float32x4': (2, 32, 4), 'float64': (2, 64, 1), 'int16': (0, 16, 1), 'int32': (0, 32, 1), 'int64': (0, 64, 1), 'int8': (0, 8, 1), 'uint16': (1, 16, 1), 'uint32': (1, 32, 1), 'uint64': (1, 64, 1), 'uint8': (1, 8, 1), 'uint8x4': (1, 8, 4)}#
classmethod from_str(type_name, lanes=None)[source]#

Create DLDataType from string name with optional lanes override.

Parameters:

  • type_name (str) – Type name like “int32”, “float32”, “uint8x4”.

  • lanes (int | None) – Optional lanes override for vector types. If provided, overrides the default lanes from TYPE_MAP.

Returns:

DLDataType instance.

Raises:

ValueError – If type_name is not recognized.

Return type:

DLDataType

Example

>>> DLDataType.from_str("int32")           # int32, lanes=1
>>> DLDataType.from_str("float32", lanes=3)  # float3 for points
>>> DLDataType.from_str("float64", lanes=3)  # double3 for points
bits#

Structure/Union member

code#

Structure/Union member

lanes#

Structure/Union member

On this page