/update-0_3-0_4-python

# 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_3-0_4-python
description: >
  Upgrade skill to migrate an existing Python ovrtx codebase from 0.3.x to 0.4.x by
  moving scene population, cloning, queries, attribute reads, writes, mappings,
  and persistent binding workflows to ovstage while keeping rendering in ovrtx.
  Use when the user asks to upgrade from ovrtx 0.3 to 0.4, remove ovrtx 0.4
  deprecation warnings, or adopt ovstage interop in an existing ovrtx project.
license: LicenseRef-NvidiaProprietary
author: NVIDIA ovrtx
tags:
  - ovrtx
  - upgrade
  - "0.4"
  - ovstage
  - python

tools:
  - Read
  - Grep
  - Edit

Update 0.3 to 0.4 + ovstage 0.1 (Python API)

Version Scope

| | Version | What changes | |---|---|---| | Source | ovrtx 0.3.x | Standalone stage ownership through deprecated `Renderer.open_usd*`, `Renderer.write_attribute*`, `Renderer.query_prims*`, `Renderer.clone_usd*`, `Renderer.bind_attribute*`, and `Renderer.map_attribute` scene APIs, with `Renderer.step()` rendering the renderer-owned stage. | | Target ovrtx | ovrtx 0.4.x | Attach APIs (`Renderer.attach_ovstage`, `Renderer.detach_ovstage`, `Renderer.update_from_stage`, and `Renderer.step(..., ordinal=...)`); `DeprecationWarning` on renderer-owned scene APIs in [`renderer.py`](../../python/ovrtx/_src/renderer.py). | | New dependency | ovstage 0.1.x | Scene data plane (`ovstage.Stage`), population bridge (`ovstage.population.open_usd*` and reference/reset/time helpers), ordinal-keyed writes (`Stage.write_attribute`, `Stage.write_attributes`, `Stage.advance_write_floor`). |

When to Use

Use this skill to migrate an existing ovrtx 0.3.x application to the ovrtx 0.4 scene-ownership model, especially when Python emits `DeprecationWarning` for renderer scene APIs.

For a new application, prefer the current ovstage and ovrtx topic skills directly.

Do **not** use this skill for:

• 0.2 -> 0.3 (see [`update-0_2-0_3`](../../skills/update-0_2-0_3/SKILL.md)).
• C or C++ application ports; switch to `skills/update-0_3-0_4-c/SKILL.md`.

Inputs

Resolve inputs in this order: the user's Python dependency files, current application code, tests, then the installed ovstage and ovrtx Python packages.

• Current ovrtx and ovstage dependency pins.
• Scene sources: USD file, inline USDA, removable references, or direct data-plane writes.
• Current uses of clone, query, read, write, persistent bindings, and map/unmap.
• Whether the app does **one-shot** scene loading (open a USD file once, then step) or **incremental** scene edits (references, resets, attribute writes, time samples).
• Whether the app uses picking, selection outlines, render-output APIs, or the renderer's path dictionary; these stay on ovrtx and change independently.
• The application's frame ordinal owner and existing simulation/update loop.

Prerequisites

• Read [`../update-0_3-0_4-common/Reference.md`](../update-0_3-0_4-common/Reference.md) for language-agnostic ownership, ordering, path-dictionary, transform, exposure, and async-boundary guidance.
• Read `CHANGELOG.md` 0.4.0 and `docs/core/ovstage_integration.rst` before editing.
• Consult the public Python documentation shipped with the installed ovstage version for exact API signatures.
• Preserve application structure where practical; this is an ownership/API migration, not a broad refactor.
• Treat the installed Python package signatures as authoritative when documentation differs.

Architecture

User app code       +----------------------------------------+
------------------->|  ovstage.Stage  (owns scene data)     |
                    |  ovstage.population.open_usd*         |
                    |  Stage.write_attribute / clone        |
                    |  Stage.advance_write_floor(ordinal)   |
                    +------------------+---------------------+
                                       | Renderer.attach_ovstage(stage)
                                       v
                    +----------------------------------------+
                    |  ovrtx.Renderer  (owns rendering)     |
                    |  Renderer.step(..., ordinal=ordinal)  |
                    |  picking / selection / render outputs |
                    +----------------------------------------+

Python `Renderer.step(..., ordinal=ordinal)` performs the attached-stage update before rendering, so a separate `Renderer.update_from_stage(...)` call is usually unnecessary unless the application explicitly needs to update the renderer before a step.

Deprecated Python API Mapping

Every `@deprecated(...)` renderer scene method in [`renderer.py`](../../python/ovrtx/_src/renderer.py) should move to ovstage. The deprecation text in the installed Python package is the primary source of truth; this table groups the Python method families by workflow.

| ovrtx 0.3 Python API deprecated in 0.4 | 0.4 + ovstage 0.1 replacement | |---|---| | `Renderer.open_usd()` / `open_usd_async()` | `ovstage.population.open_usd(stage, path, ordinal=...)` / `open_usd_async(...)`; then attach and call `Renderer.step(..., ordinal=...)`. | | `Renderer.open_usd_from_string()` / `open_usd_from_string_async()` | `ovstage.population.open_usd_from_string(stage, usda, ordinal=...)` / `open_usd_from_string_async(...)`; then attach and call `Renderer.step(..., ordinal=...)`. | | `Renderer.add_usd_reference()` / `add_usd_reference_async()` | `ovstage.population.add_usd_reference(stage, ref_file_path, target_path)` / `add_usd_r