Omniverse Spatial Python API and Extension Development#

Note

Applies to: Spatial Extensions, Kit 109.0.3+, CloudXR 6

This section covers the Spatial Extensions system in depth. It is intended for developers who want to build custom XR tools, interact with the XR Python API, create reusable extension bundles, or work directly with XRUsdLayer for real-time USD integration.

If you are looking to set up a Kit XR server and connect a client for the first time, start with the Quick Start or the Server Setup Guide instead.

Documentation#

Architecture and Fundamentals#

  • Core Concepts – XRCore singleton, profile system (VR/AR/TabletAR), system plugins (OpenXR/SimulatedXR), frame scheduling (2-frame pipeline), coordinate systems, and the settings hierarchy

  • API Reference – Complete Python API documentation for XRCore, XRProfile, XRInputDevice, XRUsdLayer, XRSettings, and helper classes

Input and Events#

  • Input & Interaction – Controller and hand tracking device names, poses (raw/filtered/virtual), button and gesture input, event-based input, action maps, raycasting, and input smoothing

  • Event System – Message bus architecture, lifecycle events (xr.enable, xr_display.enable, profile events), frame timing (pre_sync/post_sync), input event generators, tool and GUI events, and custom event patterns

USD Integration#

  • Scene Integration (XRUsdLayer) – XRUsdLayer for real-time XR UI elements in the USD stage, managed objects (assets, beams, teleport arcs, transforms, links), coordinate conversion, visibility and pickability, and group management

Building Extensions#

  • Custom Tools – Tool architecture, base component classes (XRComponentBase, XRToolComponentBase, XRGuiLayerComponentBase), building selection tools, tool registration, and GUI layer examples

  • Custom Bundles – Creating reusable XR bundle extensions, platform-specific bundles, testing, versioning, and distribution

  • Kit App Integration – Integrating XR with the Kit App Template, build and deployment workflows, CI/CD, multi-platform builds, and configuration management

Common Use Cases#

Enable a Profile Programmatically#

import omni.kit.xr.core

xr_core = omni.kit.xr.core.XRCore.get_singleton()
xr_core.request_enable_profile("ar")  # or "vr", "tabletar"

Access Controller Poses#

left_hand = xr_core.get_input_device("/user/hand/left")
pose = left_hand.get_pose("aim")
position = pose.ExtractTranslation()

Listen for Button Presses#

left_hand = xr_core.get_input_device("/user/hand/left")
generator = left_hand.bind_event_generator(
    "trigger", "my_trigger", ["press", "release"]
)

Cast Rays for Selection#

from omni.kit.xr.core import XRRay

def on_hit(ray, result):
    if result.hit:
        print(f"Hit: {result.hit_prim_path}")

ray = XRRay()
ray.origin = origin
ray.direction = direction
ray.max_distance = 10.0
xr_core.submit_raycast_query(ray, on_hit)

See Also#