Extension: omni.kit.scene_view.xr_utils-1.0.2

Documentation Generated: Jul 18, 2026

Overview#

omni.kit.scene_view.xr_utils places omni.ui widgets in 3D space — typically for XR HUDs, controller tooltips, and prim-anchored labels. A UiContainer owns the scene view, the manipulator that hosts the UI, and the stack of transforms that positions it in the world.

The three classes you reach for most often are:

  • UiContainer — the entry point. Owns the scene view, the manipulator hierarchy, and visibility.

  • WidgetComponent — wraps any omni.ui.Widget subclass and gives it physical size, rendering resolution, and update policy.

  • SpatialSource — describes where the UI lives. Compose multiple sources as a list for combined transforms.

When to reach for it#

You need to…

Reach for

Show a 2D window with no relation to the scene

omni.ui directly

Draw low-level shapes (lines, arcs, points) in 3D

omni.ui.scene raw

Place an interactive omni.ui.Widget panel in 3D for XR

this extension

Author an XR tool or GUI layer that uses a 3D panel

omni.kit.scene_view.xr (with this extension for the panel itself)

Architecture#

A UiContainer constructs three things on the caller’s behalf:

  1. A SceneViewManager that hosts the underlying omni.ui.scene.SceneView instance.

  2. A hierarchy of omni.ui.scene.Transform nodes — one per SpatialSource in the space_stack — that positions the UI in world space.

  3. A TransformableManipulator that draws the supplied component(s) and dispatches gestures.

                      UiContainer
                           │
       ┌───────────────────┼───────────────────────────┐
       │                   │                           │
SceneViewManager   SpatialSource stack       TransformableManipulator
       │            (applied L→R)                      │
       ▼                   │                  ┌────────┴────────┐
 omni.ui.scene             ▼                  │                 │
 .SceneView         (Transforms)         WidgetComponent   [other components]
                                              │
                                              ▼
                                       your omni.ui.Widget

SpatialSource and the manipulator hierarchy are orthogonal: sources own the placement of the UI in world space; the manipulator owns the contents and any gestures attached to them. The components page covers each axis in detail; see Spatial Sources and WidgetComponent.

Lifecycle rules#

For UI that comes and goes, keep the UiContainer alive and toggle visibility with show() and hide() rather than recreating the container.

panel = UiContainer(...)   # construct once

panel.hide()   # UI stays in memory, just not rendered
panel.show()   # visible again

panel = None   # drop when the UI is no longer needed

The container must be kept reachable from somewhere your extension owns — drop the last reference and the UI disappears.

Coordinate conventions#

  • Stage units. Widths, heights, and translation offsets in this extension are in the units of the active USD stage, which is centimetres by default. A width=40 panel is 40 cm wide.

  • Forward axis. A SpatialSource with a negative Z translation places the panel “in front of” the world origin in a default Y-up, Z-forward stage. In XR, combine with SpatialSource.new_look_at_camera_source to keep the panel facing the headset.

  • Pixel density. WidgetComponent separates how large the panel is in world space (width, height) from how many pixels the omni.ui tree renders into (resolution_scale, unit_to_pixel_scale). See WidgetComponent for the worked sizing math.

Stability#

Stable surface, covered by the worked examples and dedicated pages:

  • UiContainer, WidgetComponent, SpatialSource (and its factory methods).

  • SceneViewAttachMode for picking where the scene view mounts.

Experimental surface — exported in __all__ and rendered in the auto-generated Python API reference. These APIs are not final and are subject to change in future versions of this extension:

  • TransformableManipulator / TransformableManipulatorModel, the ComposableManipulator extension point.

  • The gesture handlers (TranslationGestureHandler, RotationGestureHandler, ScaleGestureHandler, Resize2DGestureHandler) and their paired *HandleComponent classes.

  • PreventGestureOverlap.

These are documented at reference depth in Advanced Manipulators.

Out of scope for this extension: XR tool / GUI layer base classes (XRToolComponentBase, XRGuiLayerComponentBase) live in omni.kit.scene_view.xr and the wider omni.kit.xr.* stack; use this extension to build the UI those bases render.

Where to go next#

  • Spatial Sources — every factory, composition rules, and edge cases.

  • WidgetComponent — sizing model, update policies, omni.ui interop.

  • Advanced Manipulators — manipulator and gesture surface, experimental.

  • Migration — moving from the deprecated SceneWidgetManipulator.

  • Examples — three annotated walkthroughs you can drop into the script editor.