/update-0_2-0_3

# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: LicenseRef-NvidiaProprietary
#
# NVIDIA CORPORATION, its affiliates and licensors retain all intellectual
# property and proprietary rights in and to this material, related
# documentation and any modifications thereto. Any use, reproduction,
# disclosure or distribution of this material and related documentation
# without an express license agreement from NVIDIA CORPORATION or
# its affiliates is strictly prohibited.
name: update-0_2-0_3
description: >
  Upgrade skill to migrate an existing ovrtx codebase from 0.2.0 to 0.3.0. Use
  when the user asks to "upgrade from 0.2 to 0.3", migrate ovrtx API usage,
  update 0.2 projects to 0.3, or fix code after moving from ovrtx 0.2.x to 0.3.x.
license: LicenseRef-NvidiaProprietary
author: NVIDIA ovrtx
tags:
  - ovrtx
  - upgrade
  - migration
tools:
  - Read
  - Grep
  - Edit

Update 0.2 to 0.3

When to Use

Use this skill when the user asks to upgrade an existing ovrtx project from 0.2.0 or 0.2.x to 0.3.0 or 0.3.x, especially with the prompt "upgrade from 0.2 to 0.3".

Do not use this for brand-new examples unless the user explicitly wants migration guidance. For new code, prefer the topic skills that describe current 0.3 usage directly.

Inputs

Resolve inputs in this order: the user's repository, its dependency files, then source code and docs.

• Target language: Python, C/C++, or both.
• Dependency manager and package pin location.
• Whether USD loading is root-stage loading or additive removable content.
• Whether async render calls, render output mapping, logging callbacks, or partial-frame behavior are present.
• Existing tests/examples the user expects to keep working.

Prerequisites

• Inspect `CHANGELOG.md` 0.3.0 before editing; it is the release-level source of truth.
• Read current 0.3 snippets before rewriting API usage. Do not infer exact call shapes from memory.
• Preserve user code structure where practical. This is an API migration, not a broad refactor.
• If a project mixes ovrtx with another OpenUSD subsystem, account for schema-path registration before USD initializes.

Instructions

1. Find version pins first. Search package and lock files for `ovrtx==0.2`, `ovrtx~=0.2`, or equivalent C package references. Update to the user's requested 0.3 build; in this repo's examples the packaged Python pin is `ovrtx==0.3.0`. 2. Scan for 0.2-only Python symbols: `RendererResult`, `add_usd`, `add_usd_layer`, `add_usd_async`, `add_usd_layer_async`, `output_partial_frames`, `step_async`, and `MappedRenderVar.tensor`. 3. Scan for 0.2-only C symbols: `ovrtx_add_usd`, `ovrtx_usd_input_t`, `ovrtx_rendered_output_t`, `ovrtx_map_rendered_output`, `ovrtx_unmap_rendered_output`, `ovrtx_rendered_output_handle_t`, `ovrtx_rendered_output_map_handle_t`, `OVRTX_CONFIG_OUTPUT_PARTIAL_FRAMES`, `ovrtx_release_errors`, `ovrtx_flush_op_log`, and old renderer-scoped `ovrtx_set_log_callback` calls. 4. Rewrite USD loading by intent:

• Single scene/root layer: use `open_usd*`.
• Runtime inline root layer, often with `subLayers`: use `open_usd_from_string*`.
• Additive removable content under a new prim path: use `add_usd_reference*` and keep the returned handle for `remove_usd`.

5. Rewrite Python async rendering. `Renderer.step()` still returns fetched outputs. `Renderer.step_async()` now returns `Operation[PendingFetch[RenderProductSetOutputs]]`; call `wait()` for the pending fetch and then `fetch()` for outputs. 6. Rewrite render output mapping. In Python, use DLPack directly on a single-tensor mapping or named tensor/param access for composite outputs. In C, map to `ovrtx_render_var_output_t`, read `tensors[]` and `params[]`, then unmap with `ovrtx_unmap_render_var_output`. 7. Remove global partial-frame config. If 0.2 code explicitly disabled partial frames, author `bool omni:sensor:Core:accumulateOutputs = true` on the affected camera prim instead. If 0.2 code omitted the setting or used the default partial-frame behavior, remove the config without replacement. 8. Rewrite C wait/error handling. Read `ovrtx_op_wait_result_t.error_op_ids`, fetch strings with `ovrtx_get_last_op_error()`, copy or print them before the next wait on the same thread, and remove `ovrtx_release_errors`. 9. Rewrite C logging. The callback is process-global, no longer receives an op id, uses carb-style severity values, and flushing is `ovrtx_flush_log(timeout)`. 10. Validate with the narrowest runnable project tests or examples. For Python projects, run the user's normal test command or at least import and exercise the migrated code path. For C/C++ projects, rebuild so removed symbols are caught at compile time.

Output Format

• Start with the concrete files changed and the 0.2 symbols removed.
• Call out any behavior choices that could not be migrated mechanically, especially partial-frame semantics and root-vs-reference USD loading.
• Include the validation commands run and any remaining manual checks.

Scripts

This skill has no scripts. Use repository search and targeted edits directly.

Limitations

• This skill covers public API migration from 0.2.0 to 0.3.0. It does not attempt to adopt new optional 0.3 features such as lidar, radar, picking, selection outlines, stage queries, or attribute reads unless the existing code needs them.
• Some USD loading calls require intent. A 0.2 `add_usd(..., path_prefix=None)` usually becomes root-stage `open_usd()`, while prefixed additive content usually becomes `add_usd_reference()`.
• `MappedRenderVar.tensor` still works for single-tensor Python render variables in 0.3 but emits `DeprecationWarning`; migrate it instead of suppressing the warning.
• Partial-frame migration may require editing USD content rather than application config.

Migration Details

Python dependency and renderer config

Update the ovrtx dependency pin, remove `RendererResult` imports, and remove