Advanced Manipulators#

Warning

The classes on this page are part of the public surface (__all__) and are marked experimental. This API is not final and is subject to change in future versions of this extension. Code written against these classes may need adjustment to keep working as the API evolves. The auto-generated Python API reference is the source of truth for current signatures.

The classes below come into play when you need to build custom 3D handles, add gesture-driven transformations, or manage gesture overlap between multiple interactive components. The stable, higher-level entry points are UiContainer, WidgetComponent, and SpatialSource.

TransformableManipulator / TransformableManipulatorModel#

The manipulator that every UiContainer creates internally is a TransformableManipulator. It exposes translation, rotation, and scale as separate model items plus a combined 4x4 matrix, so callers can drive the placement of the UI programmatically:

from carb import Float3

container.manipulator.translation = Float3(50.0, 100.0, -30.0)
container.manipulator.rotation_degrees = Float3(0.0, 45.0, 0.0)
container.manipulator.scale = Float3(1.5, 1.5, 1.5)

Setting the matrix property bypasses the decomposition and writes directly to the combined matrix item. TransformableManipulatorModel is the underlying model class and the place to attach _item_changed callbacks if you need to observe transform updates from elsewhere in your extension.

ComposableManipulator and ManipulatorComponent#

ComposableManipulator is a wrapper around omni.ui.scene.Manipulator that owns a list of ManipulatorComponent instances and rebuilds them on demand. TransformableManipulator is itself a ComposableManipulator, which is why you can manipulator.add_component(...) on it.

To build a custom component, subclass ManipulatorComponent and implement _do_build. Components receive a weak reference to their owning manipulator so they can read its model and gesture manager during the build pass. Area2DComponent is the 2D-rectangle base most components inherit from (including WidgetComponent itself); extending it gives you width / height / origin / child-placement out of the box.

Built-in handle components#

These components draw gizmo geometry hooked up to the corresponding gesture handlers below. They all subclass Area2DComponent, so they live in 2D and must be parented under a TransformableManipulator.

TranslationHandleComponent — rectangle hit-surface paired with TranslationGestureHandler.
RotationHandleComponent — same for RotationGestureHandler.
ScaleHandleComponent — same for ScaleGestureHandler.
Resize2DHandleComponent — same for Resize2DGestureHandler; takes an additional target argument identifying the Area2DComponent whose width and height should change.

Gesture handlers#

Each gesture handler is an omni.ui.scene.DragGesture subclass that updates a specific item on a TransformableManipulatorModel in response to drag input (controller or mouse).

TranslationGestureHandler — raycast-based drag that moves the manipulator in world space along the hit ray’s plane.
RotationGestureHandler — yaw rotation in the stage’s horizontal plane (currently hard-coded to Y-up).
ScaleGestureHandler — uniform scale clamped to [0.5, 3.0].
Resize2DGestureHandler — drags the corners of a 2D target component, changing its width / height.

The handlers are paired with the corresponding *HandleComponent in normal use; build the handle, which builds the rectangle, which wires the handler into the rectangle’s gestures list.

PreventGestureOverlap#

PreventGestureOverlap is an omni.ui.scene.GestureManager subclass that blocks a new gesture from starting while another gesture on the same manipulator is active (state BEGAN or CHANGED). Every TransformableManipulator installs one of these by default, which is why dragging the translation handle does not accidentally also start a rotation drag.

If you build your own composable manipulator and want the same behaviour, pass PreventGestureOverlap() as the gesture_manager constructor argument.

SceneViewManager / SceneViewAttachMode#

SceneViewManager is the internal helper that hosts the omni.ui.scene.SceneView instance for a UiContainer. Most callers never construct one directly — UiContainer does it for you. The one knob you may want is SceneViewAttachMode, exposed on UiContainer.__init__ as the attach_mode argument:

ATTACH_TO_MAIN_VIEWPORT — default; the view is mounted in the main viewport’s frame stack.
DO_NOT_ATTACH_TO_MAIN_VIEWPORT — the view is created standalone. Most XR tool interaction still works, but custom gesture subclasses and gesture managers are known to behave unreliably in this mode.