vantagekit 0.6.1__py3-none-any.whl

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/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/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/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/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),
+    )

vantagekit/core/smoothing.py

@@ -0,0 +1,126 @@
+"""Frame-rate independent smoothing.
+
+A fixed blend per frame (x += 0.1 * (target - x)) converges twice as fast at 120 fps as at
+60 fps. Here every filter takes the frame's dt and a time constant tau in seconds, with
+
+    alpha = 1 - exp(-dt / tau)
+
+Smoothed3 and SmoothedAngle solve dy/dt = (x - y) / tau exactly with the target moving in
+a straight line between frames (a first-order hold):
+
+    y1 = x1 - v tau + (y0 - x0 + v tau) alpha',  v = (x1 - x0) / dt,  alpha' = exp(-dt / tau)
+
+A plain blend toward the newest target (y += alpha (x1 - y)) treats the target as having
+jumped at the start of the frame. For a target moving at speed v its lag is then
+v dt exp(-dt/tau) / (1 - exp(-dt/tau)), which depends on dt when dt is near tau: with
+tau 0.05 s it lagged 0.034 s at 37 ms frames and 0.028 s at 52 ms, so a chase camera
+behind a boat at 15 m/s jumped by about 8 cm whenever the frame time changed (slop-fest,
+2026-11-09). With the hold the lag is v tau at any frame time, and N frames of dt/N reach
+the same value as one frame of dt for any target that moves in a straight line.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Sequence, Tuple
+
+from .frame import Vec3
+
+
+def exp_alpha(dt: float, tau: float) -> float:
+    """Blend fraction for one step of dt seconds toward the target; 1 when tau <= 0."""
+    if tau <= 0.0:
+        return 1.0
+    if dt <= 0.0:
+        return 0.0
+    return 1.0 - math.exp(-dt / tau)
+
+
+def wrap_angle(a: float) -> float:
+    """a wrapped to (-pi, pi]."""
+    a = math.fmod(a + math.pi, 2.0 * math.pi)
+    if a <= 0.0:
+        a += 2.0 * math.pi
+    return a - math.pi
+
+
+def hold_step(y0: float, x0: float, x1: float, dt: float, tau: float) -> float:
+    """One exact step of dy/dt = (x - y) / tau with x moving linearly from x0 to x1 over dt."""
+    if tau <= 0.0:
+        return x1
+    if dt <= 0.0:
+        return y0
+    v_tau = (x1 - x0) / dt * tau
+    return x1 - v_tau + (y0 - x0 + v_tau) * math.exp(-dt / tau)
+
+
+class Smoothed3:
+    """A 3-vector following its target with time constant tau (seconds); its lag behind a
+    target moving at speed v is v tau whatever the frame times (first-order hold)."""
+
+    def __init__(self, tau: float):
+        self.tau = float(tau)
+        self.value: Vec3 | None = None
+        self._target: Vec3 | None = None
+
+    def snap(self, v: Sequence[float]) -> Vec3:
+        self.value = (float(v[0]), float(v[1]), float(v[2]))
+        self._target = self.value
+        return self.value
+
+    def update(self, target: Sequence[float], dt: float) -> Vec3:
+        if self.value is None or self._target is None:
+            return self.snap(target)
+        x1 = (float(target[0]), float(target[1]), float(target[2]))
+        if dt <= 0.0:
+            return self.value
+        y, x0 = self.value, self._target
+        self.value = tuple(hold_step(y[i], x0[i], x1[i], dt, self.tau) for i in range(3))
+        self._target = x1
+        return self.value
+
+
+class SmoothedAngle:
+    """An angle (radians) following its target along the shorter way around, with the
+    same first-order hold as Smoothed3 (a steady turn lags by its rate times tau)."""
+
+    def __init__(self, tau: float):
+        self.tau = float(tau)
+        self.value: float | None = None
+        self._target: float | None = None
+
+    def snap(self, a: float) -> float:
+        self.value = wrap_angle(float(a))
+        self._target = self.value
+        return self.value
+
+    def update(self, target: float, dt: float) -> float:
+        if self.value is None or self._target is None:
+            return self.snap(target)
+        if dt <= 0.0:
+            return self.value
+        # Work relative to the previous target so wrapping never adds a turn
+        x0 = self._target
+        x1 = x0 + wrap_angle(float(target) - x0)
+        y0 = x0 + wrap_angle(self.value - x0)
+        self.value = wrap_angle(hold_step(y0, x0, x1, dt, self.tau))
+        self._target = wrap_angle(x1)
+        return self.value
+
+
+def spring_step(
+    x: float, v: float, target: float, dt: float, omega: float
+) -> Tuple[float, float]:
+    """One exact step of a critically damped spring; returns (x, v).
+
+    omega (1/s) sets the stiffness: the spring settles in about 4/omega seconds with no
+    overshoot from rest. Exact for any dt, so it does not depend on frame rate.
+    """
+    if dt <= 0.0:
+        return x, v
+    c1 = x - target
+    c2 = v + omega * c1
+    e = math.exp(-omega * dt)
+    x_new = target + (c1 + c2 * dt) * e
+    v_new = (c2 - omega * (c1 + c2 * dt)) * e
+    return x_new, v_new