nvidia-omniverse/ovrtx/update-0-4-to-0-5

Update OVRTX 0.4 to 0.5

Port an existing application with the minimum changes required by the 0.5 public contract. Do not adopt unrelated 0.5 features or rewrite working code.

When to Use

Use this skill when upgrading an existing Python, C, or C++ application from OVRTX 0.4.x to 0.5.x. It also covers authored sensor USD and attached-mode applications that must upgrade from OVStage 0.1.x to the matching 0.2.x release.

Do not use it for applications starting on OVRTX 0.3.x or earlier; apply the corresponding earlier-version migration skill first.

Inputs

Resolve these before editing:

• The exact source and target OVRTX versions and package locations.
• Whether the application uses Python, C/C++, authored USD, or a combination.
• Whether it uses attached OVStage and directly consumes OVStage data.
• The source, build, deployment, and generated-asset files in migration scope.
• Whether 0.4-equivalent rendered output must be preserved.

Prerequisites

• Access to the application's current source, package pins, build configuration,

authored USD, and accepted output baselines when visual compatibility matters.

• Matching OVRTX 0.5.x and OVStage 0.2.x packages from the same release train for

attached mode.

• Read the [0.5.0] migration notes in

`../../CHANGELOG.md` and the installed target headers and Python signatures before changing APIs or data contracts. For attached mode, also consult the release notes for the matching OVStage package.

• Runtime validation requires the GPU, driver, network, and unsandboxed execution

prerequisites documented in `../../AGENTS.md`.

Scope

• Source: OVRTX 0.4.x, including 0.4.1, with optional OVStage 0.1.x.
• Target: OVRTX 0.5.x and, when attached mode is used, the matching OVStage

0.2.x package from the same release train.

• Languages: Python, C, C++, and authored USD used by those applications.
• Preserve application behavior unless the user explicitly wants the new 0.5

defaults.

This skill includes only changes that can require user source, build, deployment, or authored-USD changes. Renderer bug fixes, performance work, tests, CI, packaging reductions, documentation-only work, and optional new features are not migration steps.

Instructions

1. Establish the real baseline. Locate OVRTX and OVStage version pins,

package roots, copied headers/libraries, lock files, and generated USD. Record whether the source is 0.4.0 or 0.4.1 and whether the application is Python, C/C++, or mixed.

1. Update packages together. Pin OVRTX to the requested 0.5 build. If the

app uses attached mode, pin the matching OVStage 0.2 build from the same release train. Do not mix their bundled OpenUSD runtimes.

1. Run the audit searches below before editing. Apply a migration only when

its search matches application code, build/deployment logic, or authored USD. Do not turn every conditional item into a source change.

1. Migrate RenderVar identity first. It affects nearly every output-reading

application and makes later tensor tests address the correct output.

1. Migrate Python tensor handling. Remove ManagedDLTensor dependencies,

consume mappings through DLPack, replace raw DLTensor inputs, and fix device/lifetime assumptions.

1. Migrate removed configuration and outputs. Remove Windows backend

selection and replace GenericModelOutput where used.

1. Migrate sensor assets. Resolve each applied sensor schema version and

update omni:sensor:modelVersion; do not use the deprecation escape hatch as the permanent migration.

1. Fix initialization order. Register OVRTX schema paths before OpenUSD is

loaded and before OVStage performs its first population.

1. Apply OVStage 0.2 data-contract migrations only to code that directly

reads or writes the affected representations. Ordinary OVRTX render-output consumers do not need these edits.

1. Decide whether to preserve 0.4 rendering defaults. Author explicit old

values only when image compatibility is required; otherwise accept and test the new 0.5 defaults.

1. Rebuild C/C++ applications. Do not reuse a 0.4 binary with 0.5 headers or

runtime libraries. Rebuild all translation units that include OVRTX or OVX public headers.

1. Validate representative workflows. Test renderer creation, scene

population, one step, every consumed RenderVar, sensor output parsing, teardown, and Windows Vulkan/CUDA interop when applicable. Compare images or tensors against the application's accepted 0.4 baseline when behavior must remain stable.

Audit Searches and Required Actions

1. RenderVar path identity

Search Python for frame.render_vars, RenderVarOutput.name, MappedRenderVar.name, and dictionaries keyed by AOV/source names such as LdrColor, HdrColor, DepthSD, or PointCloud.

• Index frame.render_vars by the full authored RenderVar prim path, not the

prim name and not sourceName. A unique prim name is insufficient.

• Replace RenderVarOutput.name and MappedRenderVar.name with

render_var_path.

• Use source_name only when code needs the AOV kind; do not use it as output

identity.

Search C/C++ for render_var_name and ovrtx_render_var_output_t.

• Replace ovrtx_render_product_render_var_output_t.render_var_name with

render_var_path.

• Use the new source_name and source_type fields only for classification.
• Treat ovrtx_render_var_output_t.name (the mapped output) as a full

RenderVar prim path, not a source name.

• Recompile because the public result structure layout changed.

Source (Python): `../../examples/python/minimal/main.py` snippet read-render-output.

Source (C lookup): `../../examples/c/minimal/main.cpp` snippet find-output-helper.

2. Python DLPack and mapping objects

Search for ManagedDLTensor, MappedRenderVar.tensor, .numpy(), .to_bytes(), .raw_dltensor, isinstance checks against the old wrapper, direct DLTensor(...) inputs, and comparisons of .device with ovrtx.Device.

• Remove public imports and direct construction of ManagedDLTensor.
• For a single-tensor RenderVar, pass the MappedRenderVar directly to a

DLPack consumer. For composite outputs, select a named RenderVarTensor; use params for named parameters.

• Replace .tensor.numpy() or .numpy() with the consuming library's

from_dlpack. Take a copy through that library when independent storage is required.

• A CPU-only consumer cannot read a CUDA pointer. Map to CPU or use a

CUDA-capable DLPack consumer such as Warp, PyTorch, or CuPy.

• device is now a DLDevice. Update comparisons to inspect its DLPack device

type and device id rather than comparing it with OVRTX's mapping-request Device enum.

• Do not inspect mapping properties after unmap() or context exit. Capture

metadata first, or retain a tensor/param view created while mapped.

• Renderer tensor inputs must implement __dlpack__; raw ctypes DLTensor

structures are no longer accepted by Python write, bind, map, or read- destination paths.

• Deprecated attribute reads with dest= now return the exact destination

object. Remove assumptions that the result is a separate wrapper.

• A supplied read destination must have zero byte offset and C-contiguous

layout.

Source: `../reading-render-output/SKILL.md`.

3. Windows backend selection

Search for use_vulkan, OVRTX_CONFIG_USE_VULKAN, ovrtx_config_entry_use_vulkan, DX12 interop, and backend-dependent deployment branches.

• Remove the retired configuration field/key/helper.
• Treat Windows OVRTX 0.5 as Vulkan-only.
• Port DX12-specific graphics interop to Vulkan or disable that integration.
• Recompile C/C++; passing the retired numeric key returns OVRTX_API_ERROR.

4. Sensor versioning and GenericModelOutput

Search USD generators and assets for OmniSensorGeneric, omni:sensor:modelVersion, dotted versions such as 0.0.0, GenericModelOutput, and imports from the bundled GMO Python extension.

• The applied OmniSensorGeneric*API_N suffix selects schema version N;

unsuffixed schemas select version 1.

• Set omni:sensor:modelVersion to latest or a supported integer string for

that schema. Model versions count from 0 and restart at 0 when the schema version is bumped; the acoustic, IDS, generic lidar and radar models each support only 0 for schema 1 today, so 1 is rejected. Dotted semantic versions such as 0.0.0 are invalid. The [0.5.0] changelog bullets and the modelVersion doc string in the OVRTX 0.5 sensor schema ("has to be 1 or greater") say the value is a positive integer such as 1; that is wrong for these four models, and a newer section above [0.5.0] in the same changelog restates the rule, counting from 0. Follow this bullet, not those. The one 0.5.x model that does not count from 0 is the wave-propagation (WPM) lidar, OmniSensorGenericLidarWpmAPI, which 0.4 did not ship: 0.5.x accepts only 1 for it and later versions renumber it to 0, so author latest there.

• Replace sourceName = "GenericModelOutput" with the composite PointCloud

RenderVar and author the channels the application consumes. Update parsing to read named tensors and params rather than a packed GMO buffer.

This works for lidar and radar only: the idealized depth sensor (IDS) publishes its depth data only as GenericModelOutput and has no PointCloud output, so under OVRTX 0.5 its GenericModelOutput RenderVar is skipped and yields no depth data. Report that gap to the user instead of inventing a replacement. The acoustic model has no PointCloud output in 0.5 either: besides GenericModelOutput it publishes separate TransmitterIds, ReceiverIds, ChannelIds, Amplitudes, TimeOffsetNs, Flags, SignalWayShape and SensorFrameData RenderVars, which no OVRTX 0.5 example or test reads and which later versions remove in favor of a SignalWays composite. Do not rewrite an acoustic GenericModelOutput RenderVar to PointCloud; tell the user which acoustic output needs a replacement rather than inventing one.