vantagekit 0.6.1__py3-none-any.whl

vantagekit/core/targets.py

@@ -0,0 +1,93 @@
+"""Targets the camera can attach to, and selection among them."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable, Hashable, List, Optional, Protocol, Sequence
+
+from .frame import Quat, Vec3, dot, sub
+
+
+@dataclass(frozen=True)
+class Pose:
+    position: Vec3  # stage units, world space
+    orientation: Quat = (1.0, 0.0, 0.0, 0.0)  # (w, x, y, z)
+
+
+class TargetProvider(Protocol):
+    def target_ids(self) -> Sequence[Hashable]:
+        """Targets in cycling order."""
+
+    def target_pose(self, tid: Hashable) -> Optional[Pose]:
+        """World pose of a target, or None if it is not present now."""
+
+
+class CallbackTargets:
+    """A TargetProvider from two callables, for apps that keep poses in their own dicts."""
+
+    def __init__(
+        self,
+        ids: Callable[[], Sequence[Hashable]],
+        pose: Callable[[Hashable], Optional[Pose]],
+    ):
+        self._ids = ids
+        self._pose = pose
+
+    def target_ids(self) -> Sequence[Hashable]:
+        return list(self._ids() or ())
+
+    def target_pose(self, tid: Hashable) -> Optional[Pose]:
+        return self._pose(tid)
+
+
+class TargetCycler:
+    """The selected target. The selection survives targets coming and going; previous and
+    next step through the provider's current list."""
+
+    def __init__(self, provider: TargetProvider, selected: Hashable = None):
+        self.provider = provider
+        self.selected = selected
+
+    def ids(self) -> List[Hashable]:
+        return list(self.provider.target_ids())
+
+    def pose(self) -> Optional[Pose]:
+        if self.selected is None:
+            return None
+        return self.provider.target_pose(self.selected)
+
+    def step(self, direction: int) -> Hashable:
+        ids = self.ids()
+        if not ids:
+            return self.selected
+        if self.selected in ids:
+            i = (ids.index(self.selected) + direction) % len(ids)
+        else:
+            i = 0 if direction >= 0 else len(ids) - 1
+        self.selected = ids[i]
+        return self.selected
+
+    def nearest(self, point: Sequence[float]) -> Hashable:
+        best, best_d = None, None
+        for tid in self.ids():
+            p = self.provider.target_pose(tid)
+            if p is None:
+                continue
+            d = sub(p.position, point)
+            d2 = dot(d, d)
+            if best_d is None or d2 < best_d:
+                best, best_d = tid, d2
+        return best
+
+    def ensure(self, near: Sequence[float] | None = None) -> Hashable:
+        """Keep the selection if it is present; otherwise pick the target nearest to near
+        (or the first one)."""
+        if self.selected is not None and self.provider.target_pose(self.selected) is not None:
+            return self.selected
+        pick = self.nearest(near) if near is not None else None
+        if pick is None:
+            ids = self.ids()
+            pick = ids[0] if ids else None
+        if pick is not None:
+            self.selected = pick
+        return self.selected

vantagekit/kit/__init__.py

@@ -0,0 +1,20 @@
+"""Kit adapters for the vantagekit core: camera rig, input router, native navigation
+handover and Events 2.0 subscriptions. Loaded by Kit as the python module of the
+lhzn.vantagekit extension."""
+
+from .controls import ViewerControls
+from .events import on_stage_opened, on_update
+from .input import InputRouter
+from .native_nav import NativeNavigation
+from .rig import MODES, CameraRig, RigSettings
+
+__all__ = [
+    "CameraRig",
+    "InputRouter",
+    "MODES",
+    "NativeNavigation",
+    "RigSettings",
+    "ViewerControls",
+    "on_stage_opened",
+    "on_update",
+]

vantagekit/kit/controls.py

@@ -0,0 +1,202 @@
+"""ViewerControls: the rig, the input router and target selection wired with the default
+actions. Apps add handlers for their own actions and their own binding layers.
+
+    controls = ViewerControls("/World/ViewerCam", CallbackTargets(ids_fn, pose_fn))
+    controls.on("pilot_toggle", my_toggle)
+    ...
+    # once per frame, from the app's update observer:
+    frame = controls.update(dt)
+    ...
+    controls.dispose()
+"""
+
+from __future__ import annotations
+
+import math
+import time
+from typing import Callable, Dict, Iterable, List, Sequence
+
+import carb
+
+from ..core.bindings import DEFAULT_BINDINGS, Binding, BindingState, Frame
+from ..core.targets import TargetCycler, TargetProvider
+from .input import InputRouter
+from .native_nav import NativeNavigation
+from .overlay import NAMES, ViewOverlay
+from .rig import CameraRig, RigSettings
+
+# Orbit input scales: a drag across the whole window turns half a circle; a wheel step
+# changes the range by about 14 percent; full stick deflection turns 90 degrees a second;
+# a full trigger doubles or halves the range in about half a second.
+DRAG_RAD_PER_WINDOW = math.pi
+WHEEL_LOG_STEP = 0.15
+STICK_RAD_PER_S = math.radians(90.0)
+TRIGGER_LOG_PER_S = 1.5
+
+
+class ViewerControls:
+    def __init__(
+        self,
+        camera_path: str,
+        provider: TargetProvider,
+        bindings: Iterable[Binding] | None = None,
+        layers: Sequence[str] = ("camera", "orbit"),
+        settings: RigSettings | None = None,
+        free_gamepad: bool | None = None,
+        order: int = 0,
+        consume: bool = False,
+        name: str = "vantagekit",
+        overlay: bool = True,
+        overlay_extra: Callable[[], str] | None = None,
+    ):
+        """overlay: draw the view badge over the viewport (an app with its own HUD can turn
+        it off and draw view_badge() itself). overlay_extra: returns text the app appends
+        to the badge title (for example "PILOT" while piloting)."""
+        self.name = name
+        self._overlay_on = overlay
+        self._overlay = None
+        self._overlay_retry_t = 0.0
+        self._overlay_extra = overlay_extra
+        self.targets = TargetCycler(provider)
+        self.native = NativeNavigation(free_gamepad=free_gamepad)
+        self.rig = CameraRig(camera_path, self.targets, settings, self.native, name=name)
+        self.state = BindingState(list(bindings) if bindings is not None else DEFAULT_BINDINGS, layers)
+        self.router = InputRouter(self.state, order=order, consume=consume, name=name)
+        self._handlers: Dict[str, Callable[[], None]] = {
+            "attach": self.toggle_attach,
+            "view_next": self.next_view,
+            "target_prev": lambda: self.step_target(-1),
+            "target_next": lambda: self.step_target(1),
+            "home": self.rig.home,
+        }
+        self._mode_listeners: List[Callable[[str], None]] = []
+        self._target_listeners: List[Callable[[object], None]] = []
+
+    # wiring ---------------------------------------------------------------------
+    def on(self, action: str, fn: Callable[[], None]) -> None:
+        """Handle a press action (replaces a default handler of the same name)."""
+        self._handlers[action] = fn
+
+    def on_mode_change(self, fn: Callable[[str], None]) -> None:
+        self._mode_listeners.append(fn)
+
+    def on_target_change(self, fn: Callable[[object], None]) -> None:
+        self._target_listeners.append(fn)
+
+    def set_layer(self, layer: str, on: bool) -> None:
+        self.state.set_layer(layer, on)
+
+    # actions ------------------------------------------------------------------
+    def set_mode(self, mode: str) -> str:
+        before = self.rig.mode
+        after = self.rig.set_mode(mode)
+        self.state.set_layer("orbit", after == "orbit")
+        if after != before:
+            for fn in self._mode_listeners:
+                fn(after)
+        return after
+
+    def toggle_attach(self) -> str:
+        return self.set_mode("free" if self.rig.attached else self.rig.view)
+
+    def next_view(self) -> str:
+        if not self.rig.attached:
+            return self.set_mode(self.rig.view)
+        views = list(self.rig.settings.views)
+        i = views.index(self.rig.mode) if self.rig.mode in views else -1
+        return self.set_mode(views[(i + 1) % len(views)])
+
+    def step_target(self, direction: int):
+        tid = self.rig.step_target(direction)
+        for fn in self._target_listeners:
+            fn(tid)
+        return tid
+
+    def select(self, tid) -> None:
+        self.targets.selected = tid
+        for fn in self._target_listeners:
+            fn(tid)
+
+    # per frame ------------------------------------------------------------------
+    def update(self, dt: float) -> Frame:
+        frame = self.router.poll(dt)
+        for action in frame.pressed:
+            fn = self._handlers.get(action)
+            if fn is not None:
+                try:
+                    fn()
+                except Exception as e:
+                    carb.log_error(f"[{self.name}] action {action} failed: {e}")
+        if self.rig.mode == "orbit":
+            d_yaw = -frame.value("orbit_yaw") * DRAG_RAD_PER_WINDOW
+            # The stick moves the camera the way it is pushed: left takes the camera left
+            # around the target (a positive yaw moves it right on screen), up raises it.
+            # The mouse drags the scene instead, so its signs are the opposite.
+            d_yaw += frame.amount("orbit_yaw_rate", STICK_RAD_PER_S)
+            d_elev = frame.value("orbit_pitch") * DRAG_RAD_PER_WINDOW
+            d_elev += frame.amount("orbit_pitch_rate", STICK_RAD_PER_S)  # stick up: camera up
+            log_r = -frame.value("orbit_range") * WHEEL_LOG_STEP
+            log_r += frame.amount("orbit_range_rate", TRIGGER_LOG_PER_S)
+            if d_yaw or d_elev or log_r:
+                self.rig.orbit_by(d_yaw, d_elev, math.exp(log_r))
+        self.rig.update(dt)
+        self._update_overlay()
+        return frame
+
+    _HINTS = {
+        "free": "K / X: attach",
+        "chase": "T / D-pad down: next view    Home / A: reset view",
+        "pov": "T / D-pad down: next view",
+        "orbit": "Right stick, drag: orbit    Triggers, wheel: distance    "
+        "T / D-pad down: chase from here    Home / A: reset",
+    }
+
+    def view_badge(self) -> tuple:
+        """(mode, title, hint) for the current view, e.g. ("orbit", "ORBIT  101", "Right
+        stick, drag: orbit ..."). The built-in overlay draws it; an app with its own HUD
+        can pass overlay=False and draw this at the top of its panel instead. COLORS in
+        vantagekit.kit.overlay holds the color per mode."""
+        mode = self.rig.mode
+        title = NAMES.get(mode, mode.upper())
+        if self.rig.attached and self.targets.selected is not None:
+            title += f"  {self.targets.selected}"
+        if self._overlay_extra is not None:
+            try:
+                extra = self._overlay_extra()
+            except Exception:
+                extra = ""
+            if extra:
+                title += f"  {extra}"
+        return mode, title, self._HINTS.get(mode, "")
+
+    def _update_overlay(self) -> None:
+        if not self._overlay_on:
+            return
+        if self._overlay is None:
+            # the viewport window may not exist yet at startup: try about once a second
+            now = time.monotonic()
+            if now < self._overlay_retry_t:
+                return
+            self._overlay_retry_t = now + 1.0
+            self._overlay = ViewOverlay(f"{self.name}.view")
+            if not self._overlay.ready:
+                self._overlay = None
+                return
+        self._overlay.show(*self.view_badge())
+
+    def on_stage_opened(self) -> None:
+        self.rig.reset_stage()
+        self.state.set_layer("orbit", False)
+
+    def help_rows(self) -> List[dict]:
+        return self.state.table()
+
+    def dispose(self) -> None:
+        if self._overlay is not None:
+            self._overlay.destroy()
+            self._overlay = None
+        self.router.dispose()
+        self.rig.dispose()
+        self._handlers.clear()
+        self._mode_listeners.clear()
+        self._target_listeners.clear()

vantagekit/kit/events.py

@@ -0,0 +1,53 @@
+"""App update and stage-opened subscriptions through Events 2.0 (carb.eventdispatcher).
+
+Kit 110 logs deprecation warnings for get_update_event_stream and get_stage_event_stream.
+Both helpers return an observer that unsubscribes when released (set it to None), and fall
+back to the older streams on a Kit without Events 2.0.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+import omni.kit.app
+import omni.usd
+
+
+def _dispatcher():
+    try:
+        import carb.eventdispatcher
+
+        return carb.eventdispatcher.get_eventdispatcher()
+    except Exception:
+        return None
+
+
+def on_update(fn: Callable[[float], None], name: str) -> Any:
+    """Call fn(dt) once per app update."""
+    disp = _dispatcher()
+    if disp is not None and hasattr(omni.kit.app, "GLOBAL_EVENT_UPDATE"):
+        return disp.observe_event(
+            observer_name=name,
+            event_name=omni.kit.app.GLOBAL_EVENT_UPDATE,
+            on_event=lambda e: fn(float(e["dt"])),
+        )
+    stream = omni.kit.app.get_app().get_update_event_stream()
+    return stream.create_subscription_to_pop(lambda e: fn(float(e.payload["dt"])), name=name)
+
+
+def on_stage_opened(fn: Callable[[], None], name: str, usd_context=None) -> Any:
+    """Call fn() each time a stage finishes opening."""
+    ctx = usd_context or omni.usd.get_context()
+    disp = _dispatcher()
+    if disp is not None and hasattr(ctx, "stage_event_name"):
+        return disp.observe_event(
+            observer_name=name,
+            event_name=ctx.stage_event_name(omni.usd.StageEventType.OPENED),
+            on_event=lambda e: fn(),
+        )
+
+    def legacy(e):
+        if e.type == int(omni.usd.StageEventType.OPENED):
+            fn()
+
+    return ctx.get_stage_event_stream().create_subscription_to_pop(legacy, name=name)

vantagekit/kit/input.py

@@ -0,0 +1,152 @@
+"""carb.input adapter: feeds a BindingState from keyboard, mouse and gamepad.
+
+Kit 110 contract (carb/input/InputTypes.h, OnInputEventFn): the callback returns whether
+the event should be processed by subsequent subscribers, so True passes it on and False
+consumes it. The router passes everything on by default and leaves native navigation to
+NativeNavigation; with consume=True it consumes the keys and mouse inputs that an active
+layer binds.
+
+The gamepad is polled once per frame (carb gamepads do not repeat, and polling gives the
+analog levels); gamepad input events are ignored so nothing is counted twice.
+"""
+
+from __future__ import annotations
+
+import carb
+import carb.input
+
+from ..core.bindings import BindingState, Frame
+
+_STICK_AXES = {
+    "LEFT_STICK_X": ("LEFT_STICK_RIGHT", "LEFT_STICK_LEFT"),
+    "LEFT_STICK_Y": ("LEFT_STICK_UP", "LEFT_STICK_DOWN"),
+    "RIGHT_STICK_X": ("RIGHT_STICK_RIGHT", "RIGHT_STICK_LEFT"),
+    "RIGHT_STICK_Y": ("RIGHT_STICK_UP", "RIGHT_STICK_DOWN"),
+}
+
+
+def _mods(flags: int) -> list:
+    out = []
+    ci = carb.input
+    if flags & int(getattr(ci, "KEYBOARD_MODIFIER_FLAG_CONTROL", 0)):
+        out.append("ctrl")
+    if flags & int(getattr(ci, "KEYBOARD_MODIFIER_FLAG_SHIFT", 0)):
+        out.append("shift")
+    if flags & int(getattr(ci, "KEYBOARD_MODIFIER_FLAG_ALT", 0)):
+        out.append("alt")
+    return out
+
+
+class InputRouter:
+    def __init__(self, state: BindingState, order: int = 0, consume: bool = False, name: str = "vantagekit"):
+        self.state = state
+        self.name = name
+        self._consume = consume
+        self._input = carb.input.acquire_input_interface()
+        self._keys = {}
+        for inp in state.inputs("key"):
+            enum = getattr(carb.input.KeyboardInput, inp.split(":", 1)[1], None)
+            if enum is None:
+                carb.log_warn(f"[{name}] unknown key in bindings: {inp}")
+            else:
+                self._keys[enum] = inp
+        self._pad_inputs = {}
+        for inp in state.inputs("pad"):
+            key = inp.split(":", 1)[1]
+            if key in _STICK_AXES:
+                pos, neg = _STICK_AXES[key]
+                self._pad_inputs[inp] = (
+                    getattr(carb.input.GamepadInput, pos),
+                    getattr(carb.input.GamepadInput, neg),
+                )
+            else:
+                enum = getattr(carb.input.GamepadInput, key, None)
+                if enum is None:
+                    carb.log_warn(f"[{name}] unknown gamepad input in bindings: {inp}")
+                else:
+                    self._pad_inputs[inp] = (enum, None)
+        self._pads = []
+        self._drag_from = None
+        # Optional callable: mouse events count only while it returns True. carb input is
+        # app-wide, so a viewer with its own pop-up (a second view with its own orbit) sets
+        # this to ignore drags and the wheel while the pointer is over that pop-up.
+        self.mouse_gate = None
+        self._sub = self._input.subscribe_to_input_events(self._on_event, order=order)
+        self._pad_sub = self._input.subscribe_to_gamepad_connection_events(self._on_pad)
+
+    # events -------------------------------------------------------------------
+    def _on_pad(self, e) -> None:
+        if e.type == carb.input.GamepadConnectionEventType.CREATED:
+            if e.gamepad not in self._pads:
+                self._pads.append(e.gamepad)
+                carb.log_info(f"[{self.name}] gamepad connected: {self._input.get_gamepad_name(e.gamepad)}")
+        elif e.type == carb.input.GamepadConnectionEventType.DESTROYED:
+            if e.gamepad in self._pads:
+                self._pads.remove(e.gamepad)
+                self.state.release_all()
+                carb.log_info(f"[{self.name}] gamepad disconnected")
+
+    def _on_event(self, event) -> bool:
+        dt = event.deviceType
+        if dt == carb.input.DeviceType.KEYBOARD:
+            return self._on_key(event.event)
+        if dt == carb.input.DeviceType.MOUSE:
+            return self._on_mouse(event.event)
+        return True  # gamepad: polled in poll()
+
+    def _on_key(self, e) -> bool:
+        inp = self._keys.get(e.input)
+        if inp is None:
+            return True
+        t = e.type
+        if t == carb.input.KeyboardEventType.KEY_PRESS:
+            self.state.key_down(inp, _mods(int(e.modifiers)))
+        elif t == carb.input.KeyboardEventType.KEY_RELEASE:
+            self.state.key_up(inp)
+        # KEY_REPEAT and CHAR: ignored; a held key fires its press once
+        return not (self._consume and self.state.claims(inp))
+
+    def _on_mouse(self, e) -> bool:
+        if self.mouse_gate is not None and not self.mouse_gate():
+            self._drag_from = None  # a drag that wanders into the pop-up ends there
+            return True
+        t = e.type
+        mt = carb.input.MouseEventType
+        claimed = False
+        if t == mt.LEFT_BUTTON_DOWN:
+            self._drag_from = (e.normalized_coords.x, e.normalized_coords.y)
+            claimed = self.state.claims("mouse:DRAG_X") or self.state.claims("mouse:DRAG_Y")
+        elif t == mt.LEFT_BUTTON_UP:
+            self._drag_from = None
+        elif t == mt.MOVE and self._drag_from is not None:
+            x, y = e.normalized_coords.x, e.normalized_coords.y
+            self.state.add_delta("mouse:DRAG_X", x - self._drag_from[0])
+            self.state.add_delta("mouse:DRAG_Y", y - self._drag_from[1])
+            self._drag_from = (x, y)
+            claimed = self.state.claims("mouse:DRAG_X") or self.state.claims("mouse:DRAG_Y")
+        elif t == mt.SCROLL:
+            self.state.add_delta("mouse:WHEEL", e.scrollDelta.y)
+            claimed = self.state.claims("mouse:WHEEL")
+        return not (self._consume and claimed)
+
+    # per frame ----------------------------------------------------------------
+    def poll(self, dt: float) -> Frame:
+        if self._pads:
+            gp = self._pads[0]
+            get = self._input.get_gamepad_value
+            for inp, (pos, neg) in self._pad_inputs.items():
+                v = float(get(gp, pos))
+                if neg is not None:
+                    v -= float(get(gp, neg))
+                self.state.set_level(inp, v)
+        return self.state.step(dt)
+
+    def dispose(self) -> None:
+        if self._sub is not None:
+            self._input.unsubscribe_to_input_events(self._sub)
+            self._sub = None
+        if self._pad_sub is not None:
+            self._input.unsubscribe_to_gamepad_connection_events(self._pad_sub)
+            self._pad_sub = None
+        self._pads = []
+        self.state.release_all()

vantagekit/kit/native_nav.py

@@ -0,0 +1,84 @@
+"""Hand camera navigation between Kit and the rig, only when the mode changes.
+
+Kit 110 has two independent native controllers:
+
+- Mouse and keyboard navigation (omni.kit.manipulator.camera): at the start of every
+  gesture it reads the camera prim's `omni:kit:cameraLock` attribute and, when it is true,
+  disables tumble, look, pan, zoom and fly for that camera. Locking the rig's camera is a
+  per-camera switch that leaves other viewports and cameras alone.
+- Gamepad navigation: enabled by the persistent setting
+  `/persistent/app/omniverse/gamepadCameraControl`, which the viewport window watches.
+  Isaac Sim's app file sets it false. It is persistent (saved in the user config), so the
+  value found at startup is restored on dispose.
+
+Nothing here runs per frame.
+"""
+
+from __future__ import annotations
+
+import carb
+import carb.settings
+from pxr import Sdf
+
+CAMERA_LOCK_ATTR = "omni:kit:cameraLock"
+GAMEPAD_SETTING = "/persistent/app/omniverse/gamepadCameraControl"
+
+
+class NativeNavigation:
+    """free_gamepad: native gamepad navigation in free mode; None keeps the value found at
+    startup (the app may want it off so the sticks stay with its own controls)."""
+
+    def __init__(self, free_gamepad: bool | None = None):
+        self._settings = carb.settings.get_settings()
+        self._saved_gamepad = self._settings.get(GAMEPAD_SETTING)
+        self._free_gamepad = free_gamepad
+        self._locked: set = set()  # (stage id, path) we locked
+        self._native: bool | None = None
+
+    def _gamepad_value(self, native: bool) -> bool:
+        if not native:
+            return False
+        if self._free_gamepad is not None:
+            return bool(self._free_gamepad)
+        return bool(self._saved_gamepad)
+
+    def set_native(self, native: bool, stage=None, camera_path: str | None = None) -> None:
+        """native=True gives the camera to Kit (free mode); False gives it to the rig."""
+        if self._native == native:
+            return
+        self._native = native
+        want = self._gamepad_value(native)
+        if bool(self._settings.get(GAMEPAD_SETTING)) != want:
+            self._settings.set_bool(GAMEPAD_SETTING, want)
+        if stage is not None and camera_path:
+            self._lock(stage, camera_path, not native)
+
+    def _lock(self, stage, camera_path: str, on: bool) -> None:
+        prim = stage.GetPrimAtPath(camera_path)
+        if not prim or not prim.IsValid():
+            return
+        key = (id(stage), str(camera_path))
+        if on:
+            attr = prim.CreateAttribute(CAMERA_LOCK_ATTR, Sdf.ValueTypeNames.Bool, custom=True)
+            attr.Set(True)
+            self._locked.add(key)
+        elif key in self._locked or prim.GetAttribute(CAMERA_LOCK_ATTR):
+            attr = prim.GetAttribute(CAMERA_LOCK_ATTR)
+            if attr:
+                attr.Set(False)
+            self._locked.discard(key)
+
+    def reset(self) -> None:
+        """Forget the applied state (a new stage was opened); the next set_native applies."""
+        self._native = None
+        self._locked.clear()
+
+    def dispose(self, stage=None, camera_path: str | None = None) -> None:
+        if stage is not None and camera_path:
+            try:
+                self._lock(stage, camera_path, False)
+            except Exception as e:  # stage may be closing
+                carb.log_warn(f"[vantagekit] could not unlock {camera_path}: {e}")
+        if self._saved_gamepad is not None:
+            self._settings.set_bool(GAMEPAD_SETTING, bool(self._saved_gamepad))
+        self._native = None