vantagekit 0.6.1__tar.gz

vantagekit-0.6.1/.gitignore

@@ -0,0 +1,5 @@
+node_modules/
+.DS_Store
+__pycache__/
+.pytest_cache/
+dist/

vantagekit-0.6.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Long Horizon Observatory
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vantagekit-0.6.1/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.5
+Name: vantagekit
+Version: 0.6.1
+Summary: Camera and input controls for viewers of terrain, ocean and vessel scenes: orbit, chase and point-of-view camera math, frame-rate independent smoothing, and bindings as data, with Omniverse Kit adapters.
+Project-URL: Demo, https://lhzn-io.github.io/vantagekit/demo/
+Project-URL: Issues, https://github.com/lhzn-io/vantagekit/issues
+Project-URL: Source, https://github.com/lhzn-io/vantagekit
+Author-email: Long Horizon Observatory <dfry@lhzn.io>
+License: MIT License
+        
+        Copyright (c) 2026 Long Horizon Observatory
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: camera,gamepad,input,navigation,omniverse,viewer
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Graphics :: 3D Rendering
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# vantagekit (Python)
+
+Camera and input controls for viewers of terrain, ocean and vessel scenes. This package is the
+Python half of [vantagekit](https://github.com/lhzn-io/vantagekit), whose JavaScript modules give
+three.js and MapLibre GL JS viewers the same navigation in the browser
+([live demo](https://lhzn-io.github.io/vantagekit/demo/)).
+
+```bash
+pip install vantagekit
+```
+
+## vantagekit.core
+
+Standard library only, so it runs anywhere Python 3.10 or later does: in tests, in tools, or in a
+viewer built on any renderer.
+
+- **Stage frames** for Y-up and Z-up scenes in any unit (`UpFrame`), with headings and yaw from
+  orientations.
+- **Camera math** for orbit, chase and point-of-view cameras around a moving target (`orbit_eye`,
+  `look_at_matrix`). Every distance is in metres and every time constant in seconds.
+- **Smoothing** that does not depend on frame rate (`Smoothed3`, `SmoothedAngle`, `exp_alpha`):
+  the filter is solved exactly for a target moving steadily between frames, so the lag behind a
+  moving target is its speed times the time constant at any frame time.
+- **Bindings as data** (`Binding`, `DEFAULT_BINDINGS`): press, hold, axis and delta kinds, exact
+  modifiers, and ordered layers, so an app layer can take the sticks from the camera while it is on.
+- **Target selection** (`CallbackTargets`, `Pose`).
+
+```python
+from vantagekit.core import SmoothedAngle, UpFrame, orbit_eye
+```
+
+## vantagekit.kit
+
+Adapters for Omniverse Kit 109 and 110 (Isaac Sim 6): a camera rig with free, chase,
+point-of-view and orbit modes, a handover to Kit's own navigation, a keyboard, mouse and gamepad
+input router, and a view badge. These import `carb` and `omni` and so work only inside Kit. A Kit
+app usually loads them as the `lhzn.vantagekit` extension from the repository's `kit/exts` folder;
+see the [main README](https://github.com/lhzn-io/vantagekit#omniverse-kit).
+
+## Versions
+
+The package version follows the repository's release tags, so `vantagekit==0.6.1` matches the
+JavaScript modules served from `@v0.6.1`. MIT licence, Long Horizon Observatory.

vantagekit-0.6.1/kit/README.md

@@ -0,0 +1,43 @@
+# vantagekit (Python)
+
+Camera and input controls for viewers of terrain, ocean and vessel scenes. This package is the
+Python half of [vantagekit](https://github.com/lhzn-io/vantagekit), whose JavaScript modules give
+three.js and MapLibre GL JS viewers the same navigation in the browser
+([live demo](https://lhzn-io.github.io/vantagekit/demo/)).
+
+```bash
+pip install vantagekit
+```
+
+## vantagekit.core
+
+Standard library only, so it runs anywhere Python 3.10 or later does: in tests, in tools, or in a
+viewer built on any renderer.
+
+- **Stage frames** for Y-up and Z-up scenes in any unit (`UpFrame`), with headings and yaw from
+  orientations.
+- **Camera math** for orbit, chase and point-of-view cameras around a moving target (`orbit_eye`,
+  `look_at_matrix`). Every distance is in metres and every time constant in seconds.
+- **Smoothing** that does not depend on frame rate (`Smoothed3`, `SmoothedAngle`, `exp_alpha`):
+  the filter is solved exactly for a target moving steadily between frames, so the lag behind a
+  moving target is its speed times the time constant at any frame time.
+- **Bindings as data** (`Binding`, `DEFAULT_BINDINGS`): press, hold, axis and delta kinds, exact
+  modifiers, and ordered layers, so an app layer can take the sticks from the camera while it is on.
+- **Target selection** (`CallbackTargets`, `Pose`).
+
+```python
+from vantagekit.core import SmoothedAngle, UpFrame, orbit_eye
+```
+
+## vantagekit.kit
+
+Adapters for Omniverse Kit 109 and 110 (Isaac Sim 6): a camera rig with free, chase,
+point-of-view and orbit modes, a handover to Kit's own navigation, a keyboard, mouse and gamepad
+input router, and a view badge. These import `carb` and `omni` and so work only inside Kit. A Kit
+app usually loads them as the `lhzn.vantagekit` extension from the repository's `kit/exts` folder;
+see the [main README](https://github.com/lhzn-io/vantagekit#omniverse-kit).
+
+## Versions
+
+The package version follows the repository's release tags, so `vantagekit==0.6.1` matches the
+JavaScript modules served from `@v0.6.1`. MIT licence, Long Horizon Observatory.

vantagekit-0.6.1/kit/exts/lhzn.vantagekit/vantagekit/__init__.py

@@ -0,0 +1,7 @@
+"""vantagekit for Omniverse Kit viewers.
+
+vantagekit.core is pure Python (tested without Kit); vantagekit.kit wraps it for Kit.
+This file imports neither, so importing the core never pulls in Kit.
+"""
+
+__version__ = "0.6.1"

vantagekit-0.6.1/kit/exts/lhzn.vantagekit/vantagekit/core/__init__.py

@@ -0,0 +1,32 @@
+"""vantagekit core for Kit viewers: frames, smoothing, camera math, bindings and targets.
+
+Standard library only; nothing here imports Kit, so it is tested with plain pytest.
+"""
+
+from .bindings import DEFAULT_BINDINGS, Binding, BindingState, Frame
+from .frame import UpFrame
+from .rig_math import chase_view, look_at_matrix, orbit_eye, orbit_from_eye, pov_view
+from .smoothing import Smoothed3, SmoothedAngle, exp_alpha, spring_step, wrap_angle
+from .targets import CallbackTargets, Pose, TargetCycler, TargetProvider
+
+__all__ = [
+    "Binding",
+    "BindingState",
+    "CallbackTargets",
+    "DEFAULT_BINDINGS",
+    "Frame",
+    "Pose",
+    "Smoothed3",
+    "SmoothedAngle",
+    "TargetCycler",
+    "TargetProvider",
+    "UpFrame",
+    "chase_view",
+    "exp_alpha",
+    "look_at_matrix",
+    "orbit_eye",
+    "orbit_from_eye",
+    "pov_view",
+    "spring_step",
+    "wrap_angle",
+]

vantagekit-0.6.1/kit/exts/lhzn.vantagekit/vantagekit/core/bindings.py

@@ -0,0 +1,232 @@
+"""Bindings as data, and the state machine that turns raw input into actions.
+
+Inputs are device-qualified names:
+
+    key:K  key:LEFT_BRACKET                  keyboard (carb.input.KeyboardInput names)
+    pad:X  pad:DPAD_DOWN                     gamepad buttons (carb.input.GamepadInput names)
+    pad:LEFT_STICK_Y  pad:RIGHT_STICK_X      gamepad axes (up minus down, right minus left)
+    pad:LEFT_TRIGGER  pad:RIGHT_TRIGGER      gamepad triggers, 0 to 1
+    mouse:WHEEL  mouse:DRAG_X  mouse:DRAG_Y  mouse deltas (drag with the left button held)
+
+Kinds:
+
+    press  fires once on the down edge; repeats and releases never fire it; its modifiers
+           must match the held modifiers exactly
+    hold   held or not this frame; the consumer integrates with dt
+    axis   a polled level in [-1, 1] (or [0, 1]) with a deadzone
+    delta  summed between frames (wheel steps, drag distance in normalized window units)
+
+Layers are named and ordered (later is higher). An input belongs to the highest active
+layer that binds it, so an app layer can take the sticks from the camera while it is on.
+
+Pure Python: the Kit adapter (kit/input.py) feeds key_down, key_up, set_level and
+add_delta, then calls step(dt) once per frame.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Dict, FrozenSet, Iterable, List, Sequence, Set
+
+KINDS = ("press", "hold", "axis", "delta")
+MODIFIERS = ("ctrl", "shift", "alt")
+
+
+@dataclass(frozen=True)
+class Binding:
+    action: str
+    input: str
+    kind: str = "press"
+    mods: FrozenSet[str] = frozenset()
+    layer: str = "camera"
+    scale: float = 1.0
+    deadzone: float = 0.1
+    label: str = ""
+
+    def __post_init__(self):
+        if self.kind not in KINDS:
+            raise ValueError(f"{self.action}: kind must be one of {KINDS}, not {self.kind!r}")
+        if ":" not in self.input:
+            raise ValueError(f"{self.action}: input {self.input!r} needs a device prefix")
+        bad = set(self.mods) - set(MODIFIERS)
+        if bad:
+            raise ValueError(f"{self.action}: unknown modifiers {sorted(bad)}")
+        object.__setattr__(self, "mods", frozenset(self.mods))
+
+    @property
+    def device(self) -> str:
+        return self.input.split(":", 1)[0]
+
+    @property
+    def name(self) -> str:
+        return self.input.split(":", 1)[1]
+
+
+@dataclass
+class Frame:
+    """What one step saw: fired presses in order, held actions, and axis and delta values."""
+
+    dt: float = 0.0
+    pressed: List[str] = field(default_factory=list)
+    held: Set[str] = field(default_factory=set)
+    values: Dict[str, float] = field(default_factory=dict)
+
+    def value(self, action: str) -> float:
+        return self.values.get(action, 0.0)
+
+    def amount(self, action: str, rate: float) -> float:
+        """How far a rate-driven action moves this frame: rate * dt when held, or scaled by
+        its axis value. Delta actions are already per frame and are returned as they are."""
+        if action in self.held:
+            return rate * self.dt
+        return self.values.get(action, 0.0) * rate * self.dt
+
+
+class BindingState:
+    def __init__(self, bindings: Iterable[Binding], layers: Sequence[str] = ("camera",)):
+        self.bindings: List[Binding] = list(bindings)
+        self.layer_order: List[str] = list(layers)
+        for b in self.bindings:
+            if b.layer not in self.layer_order:
+                self.layer_order.append(b.layer)
+        self.active: Set[str] = {"camera"} & set(self.layer_order)
+        self._down: Set[str] = set()
+        self._levels: Dict[str, float] = {}
+        self._deltas: Dict[str, float] = {}
+        self._mods: FrozenSet[str] = frozenset()
+        self._pending: List[str] = []
+
+    # layers ------------------------------------------------------------------
+    def set_layer(self, layer: str, on: bool) -> None:
+        if layer not in self.layer_order:
+            self.layer_order.append(layer)
+        if on:
+            self.active.add(layer)
+        else:
+            self.active.discard(layer)
+
+    def owner(self, inp: str) -> str | None:
+        """The highest active layer that binds inp, or None."""
+        best = None
+        best_rank = -1
+        for b in self.bindings:
+            if b.input == inp and b.layer in self.active:
+                rank = self.layer_order.index(b.layer)
+                if rank > best_rank:
+                    best, best_rank = b.layer, rank
+        return best
+
+    def _live(self, inp: str) -> List[Binding]:
+        layer = self.owner(inp)
+        return [b for b in self.bindings if b.input == inp and b.layer == layer]
+
+    def claims(self, inp: str) -> bool:
+        return self.owner(inp) is not None
+
+    def inputs(self, device: str | None = None) -> List[str]:
+        seen = []
+        for b in self.bindings:
+            if (device is None or b.device == device) and b.input not in seen:
+                seen.append(b.input)
+        return seen
+
+    # raw input ----------------------------------------------------------------
+    def set_mods(self, mods: Iterable[str]) -> None:
+        self._mods = frozenset(m for m in mods if m in MODIFIERS)
+
+    def key_down(self, inp: str, mods: Iterable[str] | None = None) -> None:
+        """A key or button went down. A repeat (already down) does nothing."""
+        if mods is not None:
+            self.set_mods(mods)
+        if inp in self._down:
+            return
+        self._down.add(inp)
+        for b in self._live(inp):
+            # Keyboard modifiers do not apply to gamepad buttons
+            if b.kind == "press" and (b.device == "pad" or b.mods == self._mods):
+                self._pending.append(b.action)
+
+    def key_up(self, inp: str) -> None:
+        self._down.discard(inp)
+
+    def set_level(self, inp: str, value: float, threshold: float = 0.5) -> None:
+        """A polled value (pad button or axis). Buttons cross threshold to go down or up."""
+        value = float(value)
+        self._levels[inp] = value
+        if abs(value) >= threshold:
+            self.key_down(inp)
+        elif inp in self._down:
+            self.key_up(inp)
+
+    def add_delta(self, inp: str, d: float) -> None:
+        self._deltas[inp] = self._deltas.get(inp, 0.0) + float(d)
+
+    def release_all(self) -> None:
+        """Forget held inputs (focus lost, gamepad removed)."""
+        self._down.clear()
+        self._levels.clear()
+        self._deltas.clear()
+
+    def is_down(self, inp: str) -> bool:
+        return inp in self._down
+
+    # per frame ----------------------------------------------------------------
+    def step(self, dt: float) -> Frame:
+        f = Frame(dt=float(dt), pressed=list(self._pending))
+        self._pending.clear()
+        for b in self.bindings:
+            if b.layer not in self.active or self.owner(b.input) != b.layer:
+                continue
+            if b.kind == "hold":
+                if b.input in self._down and b.mods <= self._mods:
+                    f.held.add(b.action)
+            elif b.kind == "axis":
+                v = self._levels.get(b.input, 0.0)
+                if abs(v) > b.deadzone:
+                    f.values[b.action] = f.values.get(b.action, 0.0) + v * b.scale
+            elif b.kind == "delta":
+                v = self._deltas.get(b.input, 0.0)
+                if v:
+                    f.values[b.action] = f.values.get(b.action, 0.0) + v * b.scale
+        for k in {b.action for b in self.bindings if b.kind == "axis"} & f.values.keys():
+            f.values[k] = max(-1.0, min(1.0, f.values[k]))
+        self._deltas.clear()
+        return f
+
+    def table(self) -> List[dict]:
+        """The bindings as rows for a help panel."""
+        return [
+            {
+                "action": b.action,
+                "input": ("+".join(sorted(b.mods)) + "+" if b.mods else "") + b.input,
+                "kind": b.kind,
+                "layer": b.layer,
+                "label": b.label,
+            }
+            for b in self.bindings
+        ]
+
+
+def _b(*args, **kw) -> Binding:
+    return Binding(*args, **kw)
+
+
+DEFAULT_BINDINGS: List[Binding] = [
+    _b("attach", "key:K", label="attach the camera to the selected target, or free it"),
+    _b("attach", "pad:X"),
+    _b("view_next", "key:T", label="next attached view: chase, point of view, orbit"),
+    _b("view_next", "pad:DPAD_DOWN"),
+    _b("target_prev", "key:LEFT_BRACKET", label="previous target"),
+    _b("target_prev", "pad:LEFT_SHOULDER"),
+    _b("target_next", "key:RIGHT_BRACKET", label="next target"),
+    _b("target_next", "pad:RIGHT_SHOULDER"),
+    _b("home", "key:HOME", label="home view"),
+    _b("home", "pad:A"),
+    _b("orbit_yaw", "mouse:DRAG_X", "delta", layer="orbit", label="orbit around the target"),
+    _b("orbit_pitch", "mouse:DRAG_Y", "delta", layer="orbit"),
+    _b("orbit_yaw_rate", "pad:RIGHT_STICK_X", "axis", layer="orbit"),
+    _b("orbit_pitch_rate", "pad:RIGHT_STICK_Y", "axis", layer="orbit"),
+    _b("orbit_range", "mouse:WHEEL", "delta", layer="orbit", label="orbit distance"),
+    _b("orbit_range_rate", "pad:RIGHT_TRIGGER", "axis", layer="orbit", scale=-1.0),
+    _b("orbit_range_rate", "pad:LEFT_TRIGGER", "axis", layer="orbit"),
+]

vantagekit-0.6.1/kit/exts/lhzn.vantagekit/vantagekit/core/frame.py

@@ -0,0 +1,123 @@
+"""Stage frame: up axis, horizontal basis, units and quaternion helpers.
+
+Pure Python (standard library only), so it is unit-tested without Kit.
+
+Conventions
+-----------
+Y up: up = +Y, h1 = +Z, h2 = +X; a target's forward axis defaults to +Z.
+Z up: up = +Z, h1 = +X, h2 = +Y; a target's forward axis defaults to +X.
+Yaw is measured from h1 toward h2 (h2 = up x h1), so a positive yaw turns
+counterclockwise seen from above in both frames. Quaternions are (w, x, y, z).
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Sequence, Tuple
+
+Vec3 = Tuple[float, float, float]
+Quat = Tuple[float, float, float, float]  # (w, x, y, z)
+
+
+def add(a: Sequence[float], b: Sequence[float]) -> Vec3:
+    return (a[0] + b[0], a[1] + b[1], a[2] + b[2])
+
+
+def sub(a: Sequence[float], b: Sequence[float]) -> Vec3:
+    return (a[0] - b[0], a[1] - b[1], a[2] - b[2])
+
+
+def scale(a: Sequence[float], s: float) -> Vec3:
+    return (a[0] * s, a[1] * s, a[2] * s)
+
+
+def dot(a: Sequence[float], b: Sequence[float]) -> float:
+    return a[0] * b[0] + a[1] * b[1] + a[2] * b[2]
+
+
+def cross(a: Sequence[float], b: Sequence[float]) -> Vec3:
+    return (
+        a[1] * b[2] - a[2] * b[1],
+        a[2] * b[0] - a[0] * b[2],
+        a[0] * b[1] - a[1] * b[0],
+    )
+
+
+def length(a: Sequence[float]) -> float:
+    return math.sqrt(dot(a, a))
+
+
+def normalize(a: Sequence[float]) -> Vec3:
+    n = length(a)
+    if n < 1e-12:
+        return (0.0, 0.0, 0.0)
+    return (a[0] / n, a[1] / n, a[2] / n)
+
+
+def quat_rotate(q: Sequence[float], v: Sequence[float]) -> Vec3:
+    """Rotate v by the unit quaternion q = (w, x, y, z)."""
+    w, x, y, z = q
+    n = math.sqrt(w * w + x * x + y * y + z * z)
+    if n < 1e-12:
+        return (float(v[0]), float(v[1]), float(v[2]))
+    w, x, y, z = w / n, x / n, y / n, z / n
+    u = (x, y, z)
+    t = scale(cross(u, v), 2.0)
+    return add(add(v, scale(t, w)), cross(u, t))
+
+
+def quat_from_axis_angle(axis: Sequence[float], angle: float) -> Quat:
+    ax = normalize(axis)
+    s = math.sin(angle / 2.0)
+    return (math.cos(angle / 2.0), ax[0] * s, ax[1] * s, ax[2] * s)
+
+
+_AXES = {
+    "Y": ((0.0, 1.0, 0.0), (0.0, 0.0, 1.0)),
+    "Z": ((0.0, 0.0, 1.0), (1.0, 0.0, 0.0)),
+}
+
+
+class UpFrame:
+    """The stage's up axis and units, and a target's body forward axis.
+
+    meters_per_unit is UsdGeom.GetStageMetersPerUnit(stage); all rig tuning is in
+    meters and converted with to_units().
+    """
+
+    def __init__(
+        self,
+        up: str = "Y",
+        meters_per_unit: float = 1.0,
+        body_forward: Sequence[float] | None = None,
+    ):
+        up = str(up).upper()
+        if up not in _AXES:
+            raise ValueError(f"up axis must be 'Y' or 'Z', not {up!r}")
+        self.axis = up
+        self.up, self.h1 = _AXES[up]
+        self.h2 = cross(self.up, self.h1)
+        self.meters_per_unit = float(meters_per_unit) if meters_per_unit else 1.0
+        self.body_forward = normalize(body_forward) if body_forward else self.h1
+
+    def to_units(self, meters: float) -> float:
+        return meters / self.meters_per_unit
+
+    def horizontal(self, v: Sequence[float]) -> Vec3:
+        """v with its up component removed."""
+        return sub(v, scale(self.up, dot(v, self.up)))
+
+    def yaw_of(self, v: Sequence[float]) -> float | None:
+        """Yaw (radians, from h1 toward h2) of v's horizontal part; None if v is vertical."""
+        h = self.horizontal(v)
+        if length(h) < 1e-9:
+            return None
+        return math.atan2(dot(h, self.h2), dot(h, self.h1))
+
+    def heading_dir(self, yaw: float) -> Vec3:
+        """Horizontal unit vector at the given yaw."""
+        return add(scale(self.h1, math.cos(yaw)), scale(self.h2, math.sin(yaw)))
+
+    def heading(self, q: Sequence[float]) -> float | None:
+        """Yaw of a target's body forward axis rotated by q; None if it points straight up or down."""
+        return self.yaw_of(quat_rotate(q, self.body_forward))

vantagekit-0.6.1/kit/exts/lhzn.vantagekit/vantagekit/core/rig_math.py

@@ -0,0 +1,129 @@
+"""Camera placement around a target: orbit, chase and point of view.
+
+Positions are in stage units; distances passed in are already converted from meters with
+UpFrame.to_units(). Every function returns plain tuples; the Kit layer turns them into
+Gf types.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Sequence, Tuple
+
+from .frame import UpFrame, Vec3, add, cross, dot, length, normalize, quat_rotate, scale, sub
+
+Matrix4 = Tuple[Tuple[float, float, float, float], ...]
+
+
+def orbit_eye(
+    target: Sequence[float], yaw: float, elevation: float, distance: float, frame: UpFrame
+) -> Vec3:
+    """Eye at the given yaw and elevation (radians) and distance from target."""
+    c = math.cos(elevation)
+    d = add(scale(frame.heading_dir(yaw), c), scale(frame.up, math.sin(elevation)))
+    return add(target, scale(d, distance))
+
+
+def orbit_from_eye(
+    target: Sequence[float], eye: Sequence[float], frame: UpFrame
+) -> Tuple[float, float, float]:
+    """(yaw, elevation, distance) that put the eye where it is now; the inverse of orbit_eye."""
+    d = sub(eye, target)
+    dist = length(d)
+    if dist < 1e-9:
+        return 0.0, 0.0, 0.0
+    yaw = frame.yaw_of(d)
+    elev = math.asin(max(-1.0, min(1.0, dot(d, frame.up) / dist)))
+    return (yaw if yaw is not None else 0.0), elev, dist
+
+
+def chase_view(
+    target: Sequence[float],
+    heading: float,
+    back: float,
+    up: float,
+    look_up: float,
+    look_ahead: float,
+    frame: UpFrame,
+) -> Tuple[Vec3, Vec3, Vec3]:
+    """(eye, look point, up vector) behind the target along its horizontal heading.
+
+    The camera's up is the stage up, so the horizon stays level whatever the target's
+    pitch and roll.
+    """
+    fwd = frame.heading_dir(heading)
+    eye = add(add(target, scale(fwd, -back)), scale(frame.up, up))
+    look = add(add(target, scale(fwd, look_ahead)), scale(frame.up, look_up))
+    return eye, look, frame.up
+
+
+def chase_perspective(back: float, up: float, look_up: float) -> Tuple[float, float, float]:
+    """The chase_view placement as a heading-relative orbit around the pivot
+    (target + look_up along up): (yaw relative to heading, elevation, distance).
+
+    Chase and orbit then share one parameterization, so a perspective chosen in orbit
+    can be kept for chase: chase_orbit_view with these values gives chase_view's camera
+    (with look_ahead 0).
+    """
+    rise = up - look_up
+    return math.pi, math.atan2(rise, back), math.hypot(back, rise)
+
+
+def chase_orbit_view(
+    target: Sequence[float],
+    heading: float,
+    yaw_rel: float,
+    elevation: float,
+    distance: float,
+    look_up: float,
+    frame: UpFrame,
+) -> Tuple[Vec3, Vec3, Vec3]:
+    """(eye, look point, up vector) on an orbit around target + look_up that turns with
+    the target's heading; the horizon stays level."""
+    pivot = add(target, scale(frame.up, look_up))
+    eye = orbit_eye(pivot, heading + yaw_rel, elevation, distance, frame)
+    return eye, pivot, frame.up
+
+
+def pov_view(
+    target: Sequence[float],
+    q: Sequence[float],
+    forward: float,
+    up: float,
+    right: float,
+    frame: UpFrame,
+) -> Tuple[Vec3, Vec3, Vec3]:
+    """(eye, look point, up vector) fixed in the target's body frame, full attitude.
+
+    The body frame at rest is (body_forward, stage up, body_forward x up); the offsets are
+    along those axes.
+    """
+    f0 = frame.body_forward
+    u0 = frame.up
+    r0 = normalize(cross(f0, u0))
+    f = quat_rotate(q, f0)
+    u = quat_rotate(q, u0)
+    r = quat_rotate(q, r0)
+    eye = add(add(add(target, scale(f, forward)), scale(u, up)), scale(r, right))
+    return eye, add(eye, f), u
+
+
+def look_at_matrix(eye: Sequence[float], look: Sequence[float], up: Sequence[float]) -> Matrix4:
+    """Camera-to-world matrix, row-major with the translation in the last row.
+
+    The same layout as Gf.Matrix4d().SetLookAt(eye, look, up).GetInverse(): the camera
+    looks along its -Z with +Y up.
+    """
+    f = normalize(sub(look, eye))
+    r = cross(f, up)
+    if length(r) < 1e-9:  # looking along up: pick any perpendicular
+        alt = (1.0, 0.0, 0.0) if abs(f[0]) < 0.9 else (0.0, 0.0, 1.0)
+        r = cross(f, alt)
+    r = normalize(r)
+    u = cross(r, f)
+    return (
+        (r[0], r[1], r[2], 0.0),
+        (u[0], u[1], u[2], 0.0),
+        (-f[0], -f[1], -f[2], 0.0),
+        (float(eye[0]), float(eye[1]), float(eye[2]), 1.0),
+    )