/project-setup-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: project-setup-python
description: >
  Setting up a new Python project that uses ovrtx. Use when user asks to create a new
  Python project, set up ovrtx in Python, create a pyproject.toml, or scaffold a Python
  app.
license: LicenseRef-NvidiaProprietary
author: NVIDIA ovrtx
tags:
  - ovrtx
  - python
  - setup
tools:
  - Read
  - Grep
  - Shell
  - Write

Project Setup (Python)

When to Use

Use this skill when the user asks to create a new Python project, set up ovrtx in Python, create a pyproject.toml, or scaffold a Python app.

Inputs

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

• Project language, package manager, build system, and target platform from the user request.
• Whether the project should use packaged ovrtx or the local dev-mode build.
• Repository source snippets and example projects referenced below. Treat these snippets as the API source of truth.

Prerequisites

• Use an ovrtx checkout that contains the referenced examples and docs tests.
• Confirm Python, CMake, compiler, and package-index requirements before giving setup commands.
• Avoid modifying tracked dependency files unless the user explicitly asks for project scaffolding changes.

Instructions

1. Identify the requested project type, platform, package source, and expected run command. 2. Read the minimal example and setup snippets before writing scaffolding. 3. Use the repository's existing Python or CMake conventions instead of inventing a new layout. 4. Include renderer creation and first-frame validation only after the project dependency setup is complete. 5. When changing code, run the narrow example setup or docs test 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

ovrtx and ovstage are distributed as Python packages on PyPI. Use `uv` when you want project and dependency management. This skill scaffolds the current attached-stage workflow with both packages. ovstage remains optional for standalone compatibility code.

Project Structure

my-ovrtx-app/
  pyproject.toml
  main.py

Setup with uv (Recommended)

mkdir my-ovrtx-app && cd my-ovrtx-app
uv init
uv add ovrtx ovstage

This creates a `pyproject.toml` and `uv.lock`. Then add `numpy` (required for array/tensor operations):

uv add numpy

The resulting `pyproject.toml` will look like:

[project]
name = "my-ovrtx-app"
version = "0.1.0"
requires-python = ">=3.10,<3.14"
dependencies = [
    "ovrtx",
    "ovstage",
    "numpy",
]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

Adding optional dependencies

For image output:

uv add pillow

For GPU compute with Warp:

uv add warp-lang

For visualization with rerun:

uv add rerun-sdk

Setup with pip

pip install ovrtx ovstage

Minimal main.py

> **Source:** `examples/python/minimal/main.py` snippet `create-renderer` > > **Source (continued):** `examples/python/minimal/main.py` snippet `add-usd` > > **Source (continued):** `examples/python/minimal/main.py` snippet `step` > > **Source (continued):** `examples/python/minimal/main.py` snippet `read-render-output`

ovrtx and ovstage Load Order

Importing the modules does not load either OpenUSD-dependent runtime. Two flows are supported:

• **Renderer first (the minimal example):** `ovrtx.Renderer()` opens the ovrtx

shared loader, registers schema paths, and loads the ovrtx runtime/OpenUSD. `ovstage.Stage()` then opens the ovstage shared loader and loads the ovstage runtime against that initialized OpenUSD.

• **Stage first:** call `ovrtx.register_schema_paths()` before constructing the

first `ovstage.Stage`. Registration opens only the ovrtx shared loader and publishes discovery paths. Stage construction then loads the ovstage runtime and OpenUSD; later `ovrtx.Renderer()` loads the ovrtx runtime with the paths already fixed.

Treat `ovstage.library_version()` as ovstage initialization for ordering purposes because its version probe creates a temporary native instance. The schema call must precede it in a stage-first process.

Run

uv run main.py --png
# or with pip-installed ovrtx and ovstage:
python main.py --png

A successful run writes `_output/render.png`. The output should match the documented minimal reference image.

Key Dependencies

| Package | Purpose | |---------|---------| | `ovrtx` | Core renderer | | `ovstage` | Runtime scene ownership for attached rendering | | `pillow` | Image I/O (PNG, JPEG) | | `numpy` | Array manipulation, DLPack interop | | `warp-lang` | GPU compute kernels | | `rerun-sdk` | Real-time visualization |

Troubleshooting

• If `uv` is missing (`uv: command not found`), install `uv` before using the recommended setup commands, or translate the dependency steps to an equivalent `pip`/virtualenv workflow. PyPI is still the package source.
• ovrtx supports Python 3.10-3.13. If install resolution fails, no matching wheel is found, or imports fail on another Python version,