/loading-usd

# 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: loading-usd
description: >
  Loading USD scenes into ovstage for rendering from files, URLs, or inline USDA strings. Use
  when user asks to load a USD scene, compose USD content, add cameras or
  RenderProducts to an existing USD layer, add referenced content, or create runtime
  geometry.
license: LicenseRef-NvidiaProprietary
author: NVIDIA ovrtx
tags:
  - ovrtx
  - usd
  - loading
tools:
  - Read
  - Grep

Loading USD

When to Use

Use this skill when the user asks to load a USD scene, compose USD content, add cameras or RenderProducts to an existing USD layer, add referenced content, or create runtime geometry.

Inputs

Resolve inputs in this order: existing repository files and referenced snippets, explicit user request, then broader agent context.

• Target API surface: Python, C/C++, or both.
• Application lifecycle stage: renderer creation, scene loading, stepping, warmup, output readback, or cleanup.
• Repository source snippets referenced below. Treat these snippets as the API source of truth.

Prerequisites

• Use an ovrtx checkout that contains the referenced examples and docs tests.
• Read the relevant `> **Source:**` snippet before writing or explaining API usage.
• For code changes, preserve renderer lifecycle ordering and cleanup semantics for the selected language.

Instructions

1. Identify the requested language and lifecycle stage before choosing an example. 2. Read the referenced snippet that matches the requested stage and language. 3. For Python, create an ovstage, attach it to the renderer, populate it at an ordinal, advance the write floor, and step at that ordinal. Preserve the standalone C lifecycle when maintaining C code. 4. Apply the async, status-query, error-handling, and warmup skills when the workflow crosses those concerns. 5. When changing code, run the narrow example or docs test that owns the snippet whenever practical.

Output Format

• For explanations, cite the relevant API names, source snippets, and caveats.
• For code changes, summarize the files changed, snippets affected, and validation run.

Scripts

This skill has no scripts.

Limitations

• The referenced snippets remain the source of truth; update or add tested snippets before documenting new API usage.

Overview

Before rendering, load USD content into an application-owned ovstage. Python supports three input modes through `ovstage.population`:

1. **File path or URL** -- open an existing `.usd`/`.usda`/`.usdc` file as the root layer. 2. **Inline USDA string** -- open runtime-generated USD content as the root layer. The inline root layer may use USD `subLayers` to compose a base scene and additional authored prims. 3. **USD references** -- compose additional file or string content under a specific path prefix.

There are two common composition patterns:

• **Inline root with `subLayers`** -- build one inline root USDA layer that sublayers the original scene and authors the extra prims, then load it with `ovstage.population.open_usd_from_string()` in Python.
• **Additive references** -- use `ovstage.population.add_usd_reference*()`, apply the USD changes at an ordinal, and advance the write floor.

Python

Open from file or URL

> **Source:** `examples/python/minimal/main.py` snippet `add-usd` > > **Source (local file):** `examples/python/projectors/main.py` snippet `projectors-load-usd`

Open from inline USDA string

Useful for creating RenderProducts, cameras, or runtime geometry without editing the original scene:

> **Source:** `tests/docs/python/test_sensor_configuration.py` snippet `doc-add-render-config-layer`

Compose a base scene plus extra prims

When a USD layer has the scene content but lacks render configuration or sensors, compose a new inline root layer: add `subLayers = [@existing_scene.usda@]`, author the missing Camera / RenderProduct / RenderVar prims in that same inline layer, and populate it with `ovstage.population.open_usd_from_string()`.

> **Source (USDA):** `tests/docs/usd/data/inline_sublayers_camera_renderproduct.usda` snippet `doc-usda-inline-sublayers-camera-renderproduct` > > **Source:** `tests/docs/python/test_sensor_configuration.py` snippet `doc-add-render-config-layer` > > **Source (query check):** `tests/docs/python/test_stage_query.py` snippet `doc-query-inline-sublayer-composition`

Add a USD reference with a path prefix

Use `ovstage.population.add_usd_reference()` or `add_usd_reference_from_string()` after a root stage is open. Call `apply_usd_changes()` at the next ordinal, then advance the write floor.

Compose multiple inputs

Use inline `subLayers` for one composed root stage, or ovstage reference APIs for incremental additions.

Remove USD

Use `ovstage.population.remove_usd(stage, handle)`, then apply the change at a new ordinal and advance the write floor.

C

Open from file or URL

> **Source:** `examples/c/minimal/main.cpp` snippet `load-usd-and-wait`

Poll for completion

Loading is asynchronous in C. Poll until done:

> **Source:** `examples/c/minimal/main.cpp` snippet `load-usd-and-wait`

Or block indefinitely:

> **Source:** `examples/c/minimal/main.cpp` snippet `step-renderer` > > The step snippet demonstrates blocking with `ovrtx_timeout_infinite`.

Add a USD reference with a path prefix

> Use `ovrtx_add_usd_reference_from_file` or `ovrtx_add_usd_reference_from_string` with a path prefix.

Open from inline USDA