@woosh/meep-engine 3.60.3 → 3.60.5

package/src/shade/renderer/camera/orbital/OrbitalCameraRig.js

@@ -1,411 +0,0 @@
-import { clamp } from "../../../../core/math/clamp.js";
-import { clamp01 } from "../../../../core/math/clamp01.js";
-import { lerp } from "../../../../core/math/lerp.js";
-import { smoothStep } from "../../../../core/math/smoothStep.js";
-import { NumericInterval } from "../../../../core/math/interval/NumericInterval.js";
-import Vector3 from "../../../../core/geom/Vector3.js";
-import { Transform64 } from "../../../../engine/ecs/transform/Transform64.js";
-import { MomentumAxis } from "./MomentumAxis.js";
-import { createOrbitalCameraConfig } from "./OrbitalCameraConfig.js";
-
-const TAU = Math.PI * 2;
-
-/**
- * The CONTROL CORE of the orbital camera — pure kinematics with no knowledge of
- * the DOM, input devices, or a wall clock. Drive it with intents, advance it
- * with an explicit `dt`, read a {@link Transform} back out. Unit testable with
- * plain numbers (see `OrbitalCameraRig.spec.js`).
- *
- * Feel model: **direct drive + release momentum** (a "throw"), via
- * {@link MomentumAxis}. A drag is bracketed by `engageRotate`/`disengageRotate`
- * (or pan); between them the orbit angles / target follow input 1:1 — no lag.
- * On disengage the recent input velocity is carried forward and decays to a
- * weighty stop. This is the Google-Earth/Cesium feel, not a spring chasing a
- * goal. Set `config.momentumEnabled = false` for an instant stop (precision).
- *
- * Zoom is applied directly (multiplicative, instant) — wheel notches are
- * discrete impulses, so there is nothing to "catch up" and no lag to hide.
- *
- * @author Alex Goldring (orbital rework)
- * @copyright Company Named Limited (c) 2026
- */
-export class OrbitalCameraRig {
-    /**
-     * @param {object} [options]
-     * @param {ReturnType<typeof createOrbitalCameraConfig>} [options.config]
-     * @param {NumericInterval} [options.distanceLimits]
-     * @param {number} [options.movementSpeedScale]
-     */
-    constructor({ config = createOrbitalCameraConfig(), distanceLimits, movementSpeedScale = 1 } = {}) {
-        this.config = config;
-        this.distanceLimits = distanceLimits ?? new NumericInterval(0.1, 1000);
-        this.movementSpeedScale = movementSpeedScale;
-
-        // orbit angles + target, each a direct-drive momentum axis
-        this._phi = new MomentumAxis(Math.PI / 2);
-        this._theta = new MomentumAxis(0);
-        this._tx = new MomentumAxis(0);
-        this._ty = new MomentumAxis(0);
-        this._tz = new MomentumAxis(0);
-
-        // zoom is direct/instant — a plain clamped scalar
-        this.distance = 1;
-
-        // set by direct (non-momentum) edits — dolly / truck — so update() knows
-        // to recompose even though no axis is engaged or coasting
-        this._directDirty = false;
-
-        // programmatic framing glide; null when not animating
-        this._fly = null;
-
-        // scratch — reused, never allocated per frame
-        this._basisTransform = new Transform64();
-        this._scratchTransform = new Transform64();
-        this._scratchTarget = new Vector3();
-    }
-
-    // ─────────────────────────────────────────────────────────────────────────
-    //  Rotate intents
-    // ─────────────────────────────────────────────────────────────────────────
-
-    /** Begin an orbit drag (pointer down). Cancels any coast/fly and takes direct control. */
-    engageRotate() {
-        this._fly = null;
-        this._phi.engage();
-        this._theta.engage();
-    }
-
-    /**
-     * Apply an orbit delta directly (1:1). `dPhi` pitches (clamped to the polar
-     * range), `dTheta` yaws. Radians.
-     * @param {number} dPhi
-     * @param {number} dTheta
-     */
-    rotate(dPhi, dTheta) {
-        this._phi.dragClamped(dPhi, this.config.minPolar, this.config.maxPolar);
-        this._theta.drag(dTheta);
-    }
-
-    /** End the orbit drag (pointer up): throw with the recent input velocity (or stop dead). */
-    disengageRotate() {
-        this._phi.release(this.config.velocityWindow, this.config.momentumEnabled);
-        this._theta.release(this.config.velocityWindow, this.config.momentumEnabled);
-    }
-
-    // ─────────────────────────────────────────────────────────────────────────
-    //  Pan intents
-    // ─────────────────────────────────────────────────────────────────────────
-
-    /** Begin a pan drag (pointer down, pan button). */
-    engagePan() {
-        this._fly = null;
-        this._tx.engage();
-        this._ty.engage();
-        this._tz.engage();
-    }
-
-    /**
-     * Screen-space pan: drag the target in the current view plane, directly (1:1).
-     * `dx`/`dy` are pointer-pixel deltas (sign: last − current, "grab the world").
-     * @param {number} dx pixels
-     * @param {number} dy pixels
-     * @param {number} viewportHeight pixels
-     * @param {number} fov vertical fov, radians
-     */
-    panScreen(dx, dy, viewportHeight, fov) {
-        if (viewportHeight <= 0) {
-            return;
-        }
-
-        const m = this._currentBasisMatrix();
-        const scale = this.distance * Math.tan(fov * 0.5);
-        const kx = (2 * dx * scale) / viewportHeight;
-        const ky = (2 * dy * scale) / viewportHeight;
-
-        // move the target opposite the drag, along camera right (col0) / up (col1)
-        this._tx.drag(-(kx * m[0] + ky * m[4]));
-        this._ty.drag(-(kx * m[1] + ky * m[5]));
-        this._tz.drag(-(kx * m[2] + ky * m[6]));
-
-        // a standalone (non-gesture) pan still needs a recompose; during a real
-        // pan gesture the engaged-axis path already reports the move
-        if (!this._tx.engaged) {
-            this._directDirty = true;
-        }
-    }
-
-    /** End the pan drag: throw the target with the recent velocity (or stop dead). */
-    disengagePan() {
-        const w = this.config.velocityWindow;
-        const m = this.config.momentumEnabled;
-        this._tx.release(w, m);
-        this._ty.release(w, m);
-        this._tz.release(w, m);
-    }
-
-    /** Abort direct control without throwing, retaining the last applied pose. */
-    cancelGesture() {
-        this._phi.settle(this._phi.value);
-        this._theta.settle(this._theta.value);
-        this._tx.settle(this._tx.value);
-        this._ty.settle(this._ty.value);
-        this._tz.settle(this._tz.value);
-        // The last drag may not have reached the facade's next frame yet.
-        this._directDirty = true;
-    }
-
-    // ─────────────────────────────────────────────────────────────────────────
-    //  Zoom + keyboard (direct, no momentum)
-    // ─────────────────────────────────────────────────────────────────────────
-
-    /**
-     * Multiplicative zoom, applied directly. `factor < 1` zooms in, `> 1` out.
-     * Scale-uniform and clamped to {@link distanceLimits}.
-     * @param {number} factor
-     */
-    dolly(factor) {
-        const next = clamp(this.distance * factor, this.distanceLimits.min, this.distanceLimits.max);
-        if (next !== this.distance) {
-            this.distance = next;
-            this._directDirty = true;
-        }
-    }
-
-    /** Set the zoom distance directly (world units), clamped. */
-    setDistance(distance) {
-        this.distance = clamp(distance, this.distanceLimits.min, this.distanceLimits.max);
-        this._directDirty = true;
-    }
-
-    /**
-     * Keyboard fly: move the target in the camera-local XZ plane (directly).
-     * `x` strafe (±1), `z` forward/back (±1); speed scales with
-     * {@link movementSpeedScale} and zoom-out, integrated over `dt`.
-     * @param {number} x
-     * @param {number} z
-     * @param {number} dt seconds
-     */
-    truckLocal(x, z, dt) {
-        const rawLen = Math.hypot(x, z);
-        if (rawLen === 0 || dt <= 0) {
-            return;
-        }
-
-        const zoomScale = lerp(1, 2, clamp01(this.distanceLimits.normalizeValue(this.distance)));
-        const dist = this.movementSpeedScale * zoomScale * dt * rawLen;
-
-        const nx = x / rawLen;
-        const nz = z / rawLen;
-
-        const m = this._currentBasisMatrix();
-        const wx = nx * m[0] + nz * m[8];
-        const wy = nx * m[1] + nz * m[9];
-        const wz = nx * m[2] + nz * m[10];
-
-        this._tx.value += wx * dist;
-        this._ty.value += wy * dist;
-        this._tz.value += wz * dist;
-        this._directDirty = true;
-    }
-
-    // ─────────────────────────────────────────────────────────────────────────
-    //  Framing
-    // ─────────────────────────────────────────────────────────────────────────
-
-    /**
-     * Point the camera at `to` from `from`. Instant by default (snap), or an
-     * eased glide over `config.flyToDuration` when `animate` is true.
-     * @param {Vector3} from eye position
-     * @param {Vector3} to look-at target
-     * @param {object} [opts]
-     * @param {boolean} [opts.animate=false]
-     */
-    frameTo(from, to, { animate = false } = {}) {
-        const { phi, theta, distance } = this._deriveOrbit(from, to);
-
-        if (!animate || this.config.flyToDuration <= 0) {
-            this._phi.settle(phi);
-            this._theta.settle(theta);
-            this._tx.settle(to.x);
-            this._ty.settle(to.y);
-            this._tz.settle(to.z);
-            this.distance = distance;
-            this._fly = null;
-            this._directDirty = true;
-            return;
-        }
-
-        // animated: ease from the current pose to the new one (shortest azimuth)
-        this._fly = {
-            phi0: this._phi.value, theta0: this._theta.value, dist0: this.distance,
-            tx0: this._tx.value, ty0: this._ty.value, tz0: this._tz.value,
-            phi1: phi, theta1: this._shortestAzimuth(theta, this._theta.value), dist1: distance,
-            tx1: to.x, ty1: to.y, tz1: to.z,
-            t: 0,
-        };
-    }
-
-    // ─────────────────────────────────────────────────────────────────────────
-    //  Simulation + output
-    // ─────────────────────────────────────────────────────────────────────────
-
-    /**
-     * Advance one frame. Returns whether the pose changed (so the caller can skip
-     * a redundant transform write when the camera is fully at rest).
-     * @param {number} dt seconds
-     * @returns {boolean}
-     */
-    update(dt) {
-        if (!(dt > 0)) {
-            return false;
-        }
-
-        if (this._fly !== null) {
-            return this._advanceFly(dt);
-        }
-
-        let moved = this._directDirty;
-        this._directDirty = false;
-
-        const hl = this.config.momentumDecayHalfLife;
-        const rotStop = this.config.momentumStopSpeed;
-        const panStop = this.config.momentumStopSpeed * this.distance;
-
-        moved = this._phi.update(dt, hl, rotStop) || moved;
-        // stop a coast at the pole instead of gliding through it
-        if (this._phi.value < this.config.minPolar) {
-            this._phi.value = this.config.minPolar;
-            this._phi.velocity = 0;
-        } else if (this._phi.value > this.config.maxPolar) {
-            this._phi.value = this.config.maxPolar;
-            this._phi.velocity = 0;
-        }
-        moved = this._theta.update(dt, hl, rotStop) || moved;
-        moved = this._tx.update(dt, hl, panStop) || moved;
-        moved = this._ty.update(dt, hl, panStop) || moved;
-        moved = this._tz.update(dt, hl, panStop) || moved;
-
-        // keep azimuth bounded over long sessions (periodic, so visually a no-op)
-        this._theta.value -= TAU * Math.round(this._theta.value / TAU);
-
-        return moved;
-    }
-
-    /**
-     * Write the current pose into `out` (position + look rotation), preserving
-     * its scale. Returns `out`.
-     * @param {Transform} out
-     * @returns {Transform}
-     */
-    composeTransform(out) {
-        this._scratchTransform.copy(out);
-        this._poseToTransform(
-            this._scratchTransform,
-            this._phi.value, this._theta.value, this.distance,
-            this._currentTarget()
-        );
-        out.copy(this._scratchTransform);
-        return out;
-    }
-
-    // ── read-only views ──────────────────────────────────────────────────────
-
-    get phi() { return this._phi.value; }
-    get theta() { return this._theta.value; }
-    /** True when nothing is engaged, coasting, or flying. */
-    get isAtRest() {
-        return (
-            this._fly === null &&
-            !this._phi.engaged && !this._theta.engaged &&
-            !this._tx.engaged && !this._ty.engaged && !this._tz.engaged &&
-            this._phi.velocity === 0 && this._theta.velocity === 0 &&
-            this._tx.velocity === 0 && this._ty.velocity === 0 && this._tz.velocity === 0
-        );
-    }
-
-    /**
-     * Current target. Writes into `out` if given (no allocation), else a shared
-     * scratch vector — copy it if you need to retain it.
-     * @param {Vector3} [out]
-     * @returns {Vector3}
-     */
-    getTarget(out) {
-        const v = out ?? this._scratchTarget;
-        v.set(this._tx.value, this._ty.value, this._tz.value);
-        return v;
-    }
-
-    // ─────────────────────────────────────────────────────────────────────────
-    //  Internals
-    // ─────────────────────────────────────────────────────────────────────────
-
-    _advanceFly(dt) {
-        const f = this._fly;
-        f.t += dt;
-        const u = clamp01(f.t / this.config.flyToDuration);
-        const e = smoothStep(0, 1, u);
-
-        this._phi.settle(lerp(f.phi0, f.phi1, e));
-        this._theta.settle(lerp(f.theta0, f.theta1, e));
-        this._tx.settle(lerp(f.tx0, f.tx1, e));
-        this._ty.settle(lerp(f.ty0, f.ty1, e));
-        this._tz.settle(lerp(f.tz0, f.tz1, e));
-        this.distance = lerp(f.dist0, f.dist1, e);
-
-        if (u >= 1) {
-            this._fly = null;
-        }
-        return true;
-    }
-
-    _deriveOrbit(from, to) {
-        const radius = Vector3.distance(from, to);
-        let phi = 0;
-        let theta = 0;
-        if (radius > 1e-9) {
-            theta = Math.atan2(from.x - to.x, from.z - to.z);
-            phi = Math.acos(clamp((from.y - to.y) / radius, -1, 1));
-        }
-        return {
-            phi: clamp(phi, this.config.minPolar, this.config.maxPolar),
-            theta,
-            distance: clamp(radius, this.distanceLimits.min, this.distanceLimits.max),
-        };
-    }
-
-    _currentTarget() {
-        this._scratchTarget.set(this._tx.value, this._ty.value, this._tz.value);
-        return this._scratchTarget;
-    }
-
-    /** Matrix of the current pose, for deriving the pan/truck view basis. */
-    _currentBasisMatrix() {
-        this._poseToTransform(
-            this._basisTransform,
-            this._phi.value, this._theta.value, this.distance,
-            this._currentTarget()
-        );
-        return this._basisTransform.matrix;
-    }
-
-    _poseToTransform(out, phi, theta, radius, target) {
-        const sinPhiR = Math.sin(phi) * radius;
-        out.setTranslation(
-            target.x + sinPhiR * Math.sin(theta),
-            target.y + Math.cos(phi) * radius,
-            target.z + sinPhiR * Math.cos(theta)
-        );
-        out.lookAt(target);
-
-        // lookAt set the rotation and nothing recomposes on its own, so callers reading the
-        // matrix - _currentBasisMatrix does, immediately - would otherwise get the previous pose
-        out.updateMatrix();
-    }
-
-    /** Representative of `target` angle nearest `current` (shortest arc). */
-    _shortestAzimuth(target, current) {
-        let d = target - current;
-        d = d - TAU * Math.floor((d + Math.PI) / TAU); // wrap to (-π, π]
-        return current + d;
-    }
-}

package/src/shade/renderer/camera/orbital/README.md

@@ -1,81 +0,0 @@
-# Orbital camera (momentum)
-
-A drop-in replacement for the legacy orbital camera controller
-that makes orbit/pan **responsive while dragging** and **weighty on release** —
-the "throw" feel of Google Earth / Maps, not a spring.
-
-## Feel model — direct drive + release momentum
-
-The mistake to avoid is a smoothed-target spring (camera chases a goal): it lags
-behind the cursor during a drag (floaty, unresponsive) and just arrives at the
-goal on release (no follow-through). Instead:
-
-- **Position is applied directly.** A drag moves the orbit angle / target 1:1,
-  zero lag — the camera tracks your hand exactly.
-- **Only the velocity is filtered.** Each frame's motion goes into a short
-  time-windowed history; on release the average velocity over the last
-  ~100 ms becomes the throw. Averaging the *velocity* (not the position) gives a
-  clean throw without adding any drag-time lag.
-- **On release it coasts** — `value += velocity·dt` with the velocity decaying
-  exponentially (integrated analytically, so it's exactly frame-rate
-  independent), settling to a weighty stop. Grab it again and it stops dead.
-
-Holding still before releasing yields ~zero velocity, so a deliberate slow drag
-stops precisely while a flick throws — no special click-vs-drag handling. Set
-`momentumEnabled: false` for an instant stop (Maya/CAD precision feel).
-
-Zoom is applied directly/instantly (wheel notches are discrete, nothing to lag).
-
-## Architecture — input and control are separated
-
-```
-events ──▶ OrbitalCameraInput ──intents──▶ OrbitalCameraRig ──pose──▶ Transform
-           (adapter, no kinematics)        (control core, pure)        │
-                                            uses MomentumAxis per DOF   │
-          OrbitalCameraController (facade: devices, dt, external-change contract)
-```
-
-| Layer | File | Responsibility | DOM/clock? |
-|---|---|---|---|
-| **Momentum primitive** | `MomentumAxis.js` | one DOF: direct drive, windowed-velocity release, exponential coast | **No** |
-| **Control core** | `OrbitalCameraRig.js` | orbit/pan/zoom kinematics over momentum axes; `engage*/rotate/panScreen/disengage*/dolly/frameTo`, `update(dt)`, `composeTransform` | **No** |
-| **Input adapter** | `OrbitalCameraInput.js` | bracket gestures (`dragStart`→engage, `drag`→apply, `dragEnd`→release); wheel/keys | devices only |
-| **Facade** | `OrbitalCameraController.js` | device lifecycle, frame `dt`, write the transform, external-change detection | yes |
-| **Config** | `OrbitalCameraConfig.js` | shared feel object + `createPrecisionProfile()` | no |
-
-The rig and `MomentumAxis` are unit-testable with plain numbers (no browser);
-the input adapter is tested by firing synthetic signals at injected fake devices.
-28 specs: direct-drive responsiveness, windowed-velocity throw, frame-rate-
-independent coast, hold-still-no-throw, pole clamp, precision (no-momentum) mode,
-event→intent mapping.
-
-## Import
-
-```js
-import { OrbitalCameraController } from "@woosh/meep-engine/src/shade/renderer/camera/orbital/index.js";
-```
-
-Constructor `(camera, domElement)` and `look` / `from_transform` / `pan` /
-`update` / `flyTo` plus `distanceLimits` / `movement_speed_scale` / `camera` are
-preserved. Pass the frame time to `update()` (`create_frame_loop` already
-provides it): `controller.update(frame_time_s)`.
-
-## Tuning
-
-```js
-import { createPrecisionProfile } from "../../webgpu/renderer/camera/orbital/index.js";
-
-// no inertia, direct control (Maya/CAD)
-new OrbitalCameraController(camera, dom, { momentumEnabled: false });
-
-// heavier / longer glide, or a snappier one
-new OrbitalCameraController(camera, dom, { momentumDecayHalfLife: 0.4 });  // weightier
-new OrbitalCameraController(camera, dom, { momentumDecayHalfLife: 0.12 }); // snappier
-```
-
-Key knobs (see `OrbitalCameraConfig.js`): `momentumDecayHalfLife` (glide length),
-`velocityWindow` (how much recent motion the throw averages), `momentumStopSpeed`
-(when the coast ends), `zoomStep`, `rotateSpeed`/`panSpeed`, `flyToDuration`.
-
-Touch pinch-zoom is wired but inert until meep's `PointerDevice` dispatches
-`on.pinch` (it declares the signal but never fires it).

package/src/shade/renderer/camera/orbital/index.d.ts

@@ -1,6 +0,0 @@
-export { OrbitalCameraController } from "./OrbitalCameraController.js";
-export { OrbitalCameraRig } from "./OrbitalCameraRig.js";
-export { OrbitalCameraInput } from "./OrbitalCameraInput.js";
-export { MomentumAxis } from "./MomentumAxis.js";
-export { ORBITAL_CAMERA_FEEL_DEFAULTS, createOrbitalCameraConfig, createPrecisionProfile } from "./OrbitalCameraConfig.js";
-//# sourceMappingURL=index.d.ts.map

package/src/shade/renderer/camera/orbital/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/camera/orbital/index.js"],"names":[],"mappings":""}

package/src/shade/renderer/camera/orbital/index.js

@@ -1,9 +0,0 @@
-export { OrbitalCameraController } from "./OrbitalCameraController.js";
-export { OrbitalCameraRig } from "./OrbitalCameraRig.js";
-export { OrbitalCameraInput } from "./OrbitalCameraInput.js";
-export { MomentumAxis } from "./MomentumAxis.js";
-export {
-    ORBITAL_CAMERA_FEEL_DEFAULTS,
-    createOrbitalCameraConfig,
-    createPrecisionProfile,
-} from "./OrbitalCameraConfig.js";