Omniverse Realtime Viewer

OvWidgets Full Editor

Triggers

Use this skill for complete standalone editor path, omni.ui docking, RTX viewport, stage browser, property inspector, transform manipulators, undo/redo, themes, settings, content browser, layer stack, or full-featured OvGear USD editor/viewer.

Use OvGear (ovwidgets) when the request is for the complete USD editor/viewer: docked panels, editor lifecycle, selection synchronization, undoable edits, and RTX rendering. For a minimal single-window viewer, use the local-viewer skill instead; ovwidgets.app.Application intentionally starts the heavy editor shell.

When customizing editor controls, property editors, toolbar tools, settings, or confirmation dialogs, read viewer-control-patterns and apply its client-agnostic control guidance to omni.ui/ovwidgets primitives.

For ovwidgets package behavior, editor-shell behavior, or widget APIs beyond this summary, read references/dependencies for acquisition guidance and supplemental dependency documentation.

Quick Start

Launch the full editor and optionally open a USD stage after the UI is built:

from ovwidgets.app.application import Application

Application().run(usd_path="path/to/stage.usd")

Equivalent launch paths are the ovwidgets console script and python -m ovwidgets.app. The CLI accepts an optional USD path.

What OvGear Provides

OvGear is a Kit-free standalone omni.ui application rendered through ovrtx. It provides:

• RTX viewport with camera controls, frame loop, HUD, pick gesture plumbing, selection outline, and transform manipulator integration.

• Stage Browser with hierarchy, type badges, visibility controls, filtering, rename, and drag/drop reparenting.

• Property Inspector with type-dispatched attribute editors and multi-selection ambiguity handling.

• Undo/redo command stack for editor mutations.

• Runtime themes and JSON-backed settings.

• Content Browser for local files, bookmarks, recent files, and open-file wiring.

• Layer Stack panel backed by LayerStackAdapter for USD layer inspection and editing.

Key Widgets

• Application (ovwidgets.app.application.Application): use for the full editor. It owns Settings, UndoManager, SelectionBus, global styles, dock layout, shortcuts, frame loop, status bar, content browser, layer panel, property panel, stage browser, and viewport.

• ViewportWidget (ovwidgets.viewport.viewport_widget.ViewportWidget): use when embedding the RTX viewport into an existing omni.ui app. It hosts the rendered image, SceneView camera gestures, toolbar tools, transform gizmos, selection outline, drag/drop, and renderer adapter integration.

• StageWidget (ovwidgets.stage.widget.stage_widget.StageWidget): use for an embeddable prim hierarchy browser inside any active ui.VStack/ui.Frame context. Use StageWindow when you want the dockable window shell.

• PropertyWindow (ovwidgets.property.window.PropertyWindow): use for the USD property inspector. It rebuilds from a PropertyAdapter, dispatches widgets by scheme/type, and should be wired to a stage adapter plus UndoManager for editor behavior.

• ContentBrowserWindow (ovwidgets.content.ContentBrowserWindow): use for file navigation, bookmarks, recent files, and explicit open_file_fn wiring.

• LayerWindow (ovwidgets.layers.LayerWindow): use for the Layers panel. Back it with UsdLayerStackAdapter or another LayerStackAdapter.

Adapter Pattern

Keep UI code behind the ABCs in ovwidgets.common.adapters:

• RendererAdapter: implement this for custom renderers. Required surface: load_stage, render_frame, set_resolution, pick, cancel_pick, pick_rect, set_selection_highlight, and shutdown.

• OvRtxRendererAdapter (ovwidgets.viewport.ovrtx_renderer_adapter): built-in ovrtx renderer adapter. It composes the user stage with an OvGear session layer for camera/render-product data and pushes camera/transform updates into ovrtx.

• StageAdapter: hierarchy, display, visibility, rename, reparent, filtering, change notifications, and undo grouping. UsdStageAdapter is the USD-backed implementation.

• TransformAdapter: local/world transform read/write used by the transform manipulator. UsdTransformAdapter is the USD-backed implementation.

• PropertyAdapter and LayerStackAdapter: use these to back property and layer UI without coupling those panels directly to pxr.

Application.open_file() wires the standard USD path: it preconstructs OvRtxRendererAdapter, opens the USD stage, creates UsdStageAdapter, UsdPropertyAdapter, UsdTransformAdapter, and UsdLayerStackAdapter, then hands those adapters to the panels.

Embedding Widgets Without Application

When embedding individual widgets, initialize and run omni.ui yourself, create the selection/undo/settings services you need, and pass adapters explicitly.

Stage browser only:

import omni.ui as ui

from ovwidgets.common.selection import SelectionBus
from ovwidgets.stage.usd_stage_adapter import UsdStageAdapter
from ovwidgets.stage.widget.stage_widget import StageWidget

selection_bus = SelectionBus()
adapter = UsdStageAdapter(stage)

with ui.VStack():
    widget = StageWidget(adapter, selection_bus)

Viewport with the built-in renderer:

from pxr import Usd  # import pxr before ovrtx is imported lazily

from ovwidgets.viewport.ovrtx_renderer_adapter import OvRtxRendererAdapter
from ovwidgets.viewport.viewport_widget import ViewportWidget

renderer = OvRtxRendererAdapter()  # construct before Usd.Stage.Open(...)
stage = Usd.Stage.Open("path/to/stage.usd")
renderer.load_stage(stage)

viewport = ViewportWidget(renderer=renderer)

For dockable panel shells, use StageWindow, PropertyWindow, ContentBrowserWindow, and LayerWindow; they are late-bound and expose set_adapter/setup methods so callers can construct the UI before the USD stage is loaded.

Environment Requirements

• Python version must match the selected ovrtx/ovui package set. Read references/dependencies for the current supported Python version and artifact set.

• ovrtx, omni.ui, and omni.ui_scene importable in the active environment.

• NVIDIA GPU and driver with a Vulkan ICD.

• A real DISPLAY for desktop use, or headless Vulkan:

export OMNIUI_HEADLESS=1
export OMNIUI_BACKEND=vulkan

Use the custom USD runtime paths expected by the OvGear build:

export OVRTX_SKIP_USD_CHECK=1
export PYTHONPATH="$HOME/dev/usd-build/install/lib/python:$PYTHONPATH"
export LD_LIBRARY_PATH="$HOME/dev/usd-build/install/lib:$LD_LIBRARY_PATH"

Set OMNIUI_HEADLESS and OMNIUI_BACKEND before importing omni.ui. Set OVRTX_SKIP_USD_CHECK before constructing the renderer.

Read references/dependencies for the current ovui PyPI package guidance and supplemental dependency documentation. Install ovui, ovui-data-adapters, and ovwidgets from the same package set. Stale data adapters can make even lightweight imports such as ovwidgets.viewport.image_bridge.ImageBridge fail if ovwidgets.viewport.__init__ eagerly imports ViewportWidget.

Gotchas

• Import pxr before ovrtx, but construct OvRtxRendererAdapter before the first Usd.Stage.Open(...). This primes the ovrtx MDL cache while avoiding duplicate USD debug-symbol registration. Application.open_file() already enforces this; embedders must do it manually.

• Do not import ovrtx directly before pxr. Let OvRtxRendererAdapter import it lazily after pxr is available.

• Use ui.Window(..., fill_app_window=True) for full-app overlay/status windows that must resize with the application window.

• Application is a singleton. A second Application() in the same process asserts; reuse the instance pattern or start a new process.

• omni.ui.Frame builds lazily on the first render frame. State needed by attach_stage, set_adapter, or selection callbacks should exist in __init__; only actual UI widget construction belongs in frame build methods.

• For custom sliders, toggles, menus, and property-editor controls, follow viewer-control-patterns: label controls visibly, keep state in adapters or app models, clamp before backend writes, and show effective values when renderer support adjusts the requested value.

• ovrtx availability depends on GPU/driver/runtime setup. If renderer construction fails, keep the stage/property/layer adapters usable and surface the viewport failure separately.

• If install fails with missing pyproject.toml under ovui-data-adapters, use a package set that includes matching package metadata.

• If ovwidgets install reports Multiple top-level packages discovered, use a compatible package set with explicit packaging metadata.