Omniverse Realtime Viewer

ovui Local Project Structure

Pattern, Not Fixed File Layout

A local Omniverse Realtime Viewer is one desktop app process where ovrtx owns rendering and the local UI presents already-rendered frames. The file tree below is a worked layout, not a requirement. Reorganize modules to match the host repo as long as one UI/render owner serializes renderer mutation, viewer-owned USD state stays out of user files, viewport input is mapped through the visible image rectangle, and scene/query/settings code remains below the UI widget layer.

Global Rules

• Before writing any code, read references/dependencies for current runtime acquisition, environment contracts, and verification steps.

• NEVER use WebGL, Three.js, Babylon.js, or any client-side 3D renderer. All USD rendering is done by ovrtx in-process. The desktop window displays ovrtx-rendered frames via ovui, not a browser canvas. If local validation cannot run because the GPU/runtime environment is absent, scaffold the ovrtx code anyway and document the GPU requirement.

• For deployment work, read references/cloud-deployment and use the supported paths documented there, such as OKAS 1 or Brev.

• Keep the local Omniverse Realtime Viewer as one desktop application process. Use ovui for the native window and UI, ovrtx for rendering, and optional pxr/OpenUSD queries for hierarchy, bounds, properties, and variants.

• Do not add ovstream, WebRTC, a browser frontend, or React unless the user explicitly changes the delivery target to a streaming Omniverse Realtime Viewer.

• Do not start a full editor shell for the lightweight local Omniverse Realtime Viewer. Use focused local UI companion utilities only when they solve a narrow problem, such as an image bridge.

• Make one UI/render loop the sole owner of renderer.step(), open_usd(), open_usd_from_string(), reference add/remove APIs, reset_stage(), native pick queries, selection outline writes, and live write_attribute() calls. UI callbacks update local state or enqueue work for that loop.

• Set OVRTX_SKIP_USD_CHECK=1 before ovrtx work. Keep import order disciplined for the chosen local path.

• Never modify the user USD file when adding viewer camera, render products, render vars, settings, selection metadata, inline session data, or runtime selection outline attributes.

• Do not inject viewer lights unless the user requested viewer-controlled lighting. User stages usually own their lighting.

• Always account for letterboxing when converting ovui mouse coordinates to render-image pixels for picking, overlays, and camera controls.

1. Create The Project Skeleton

Create a single desktop app package. Use this structure unless the host repo already has an equivalent convention:

local-usd-viewer/
  .gitignore
  README.md
  requirements.txt or pyproject.toml
  local_app/
    __init__.py
    __main__.py
    app.py
    config.py
    runtime.py
    renderer_runtime.py
    scene_loader.py
    viewport.py
    input_controller.py
    camera_controller.py
    selection_controller.py
    scene_manager.py
    render_settings.py
    stage_queries.py
    settings_store.py
    widgets/
      toolbar.py
      scene_picker.py
      stage_tree.py
      prim_info_panel.py
      render_settings_panel.py
      status_bar.py
  assets/
    samples/
  data/
    viewer-settings.json

Do this:

• Create the skeleton files above directly in the generated app.

• Add a project .gitignore that excludes local virtual environments, caches, frontend artifacts, logs, and Python bytecode, at minimum: .venv/, .cache/, node_modules/, dist/, __pycache__/, *.log, and logs/.

• Keep renderer, USD, camera, selection, hierarchy, and settings state inside local_app/.

• Put sample USD files under assets/samples/ or accept an absolute configured asset root. Do not hard-code developer machine paths.

• Persist cross-scene viewer settings under data/viewer-settings.json or a user-configurable settings path.

• Keep UI widgets thin. They should render app state and call local runtime actions; they should not own renderer state directly.

Critical contracts:

• local_app/__main__.py is the process entry point only. It parses config, constructs runtime objects, initializes ovui, enters the app loop, and shuts down cleanly.

• local_app/runtime.py owns high-level state, command dispatch, loading state, current scene, current selection, and lifecycle coordination.

• local_app/renderer_runtime.py owns the ovrtx renderer, render product path, frame stepping, frame extraction, and live attribute writes.

• local_app/scene_loader.py owns viewer camera/render-product/render-var injection and never mutates user USD files.

• local_app/viewport.py owns the ImageBridge, displayed image widget, overlay hit surface, viewport size, and letterbox math.

• local_app/input_controller.py owns ovui mouse/keyboard callbacks and translates them to camera, picking, and context-menu actions.

• local_app/stage_queries.py owns hierarchy, properties, variants, bounds, and descendant mesh expansion.

Decision points:

• If the user asks for the quickest local demo, build one process with a fixed render resolution and a small built-in scene picker.

• If the user asks for a native desktop app with Rust/Tauri and React UI, stop using this recipe and read references/tauri-local-viewer.

• If the user asks for full editor docking, property inspectors, transform gizmos, or editor workflows, switch to the dedicated full-editor skill before choosing the shell.

• If the user asks for S3, MinIO, or cloud asset browsing, keep asset discovery behind scene_manager.py; see references/cloud-assets for the full contract.

Common failure modes:

• Starting from a full editor application when the user asked for a simple viewer adds heavyweight editor behavior and obscures the core viewport.

• Putting renderer ownership inside individual widgets makes scene switching and shutdown hard to serialize.

• Returning raw local filesystem paths in UI labels exposes implementation details and makes asset roots harder to change.

Read for depth: see references/local-viewer, references/ovrtx-rendering, references/stage-loading, and references/usd-viewer-app for the full local shell and renderer contracts.