@nakednous/tree 0.0.25 → 0.0.26

package/README.md

@@ -1,6 +1,6 @@
 # `@nakednous/tree`
 
-Pure numeric core for animation, coordinate-space mapping, and visibility — **zero dependencies**, runs anywhere.
+Pure numeric core for animation, rate-driven control, coordinate-space mapping, and visibility — **zero dependencies**, runs anywhere.
 
 ---
 
@@ -33,13 +33,14 @@ import * as tree from '@nakednous/tree'
 
 The dependency direction is strict: `@nakednous/tree` never imports from the bridge or the DOM layer. This is what lets the same `PoseTrack` that drives a camera path also animate any object — headless, server-side, or in a future renderer.
 
-Source is organised into five focused modules:
+Source is organised into six focused modules:
 
 ```
 form.js   — you have specs, you want a matrix
 query.js  — you have a matrix, you want information
 quat.js   — quaternion algebra and mat4/mat3 conversions
 track.js  — spline math and keyframe animation state machines
+helm.js   — 6-DOF rate-stream integrator — the Track family's live-input sibling
 handle.js — constraint solver + ray primitives for interactive manipulators
 ```
 
@@ -296,6 +297,68 @@ One-keyframe behaviour: `play()` with exactly one keyframe snaps `eval()` to tha
 
 ---
 
+### PoseHelm — 6-DOF rate-driven pose
+
+The rate-stream sibling of the Track family. Where a track produces a pose from keyframes over time, a `PoseHelm` produces one from a live 6-DOF delta stream — a SpaceNavigator, a tracked hand, an agent policy. It holds a profile plus the integrated pose; there is no timeline (no keyframes, no `play` / `seek` / `loop`), and it never learns about a camera — the host hands it a resolved `basis` each step.
+
+```js
+import { PoseHelm } from '@nakednous/tree'
+
+const helm = new PoseHelm()
+const out  = { pos: [0,0,0], rot: [0,0,0,1] }
+
+// a transport feeds raw lane rates — either half may be omitted:
+helm.feed([tx, ty, tz], [rx, ry, rz])
+
+// per-frame — host-driven, zero allocation:
+helm.step(out, dt, basis)   // integrate dt seconds, write the new { pos, rot }
+helm.eval(out)              // read the current pose without integrating
+```
+
+`feed` is the input (as `add` is a track's); `step` + `eval` parallel `tick` + `eval`. `step` is host-driven — the bridge calls it each frame, exactly as a sketch never calls `track.tick()`.
+
+**Profile — sign · sens · lane.** The whole sign / sensitivity / axis-map question is one flat declarative object. Six channels — three translation (Tx Ty Tz), three rotation (Rp pitch, Ry yaw, Rr roll) — each `{ sign, sens, lane }`:
+
+```js
+helm.profile = {
+  Tx: { sign: +1, sens: 0.30,   lane: 0 },   // lane = which fed channel drives +X
+  Ty: { sign: +1, sens: 0.30,   lane: 2 },
+  Tz: { sign: -1, sens: 0.30,   lane: 1 },
+  Rp: { sign: -1, sens: 0.0025, lane: 0 },
+  Ry: { sign: -1, sens: 0.0025, lane: 2 },
+  Rr: { sign: +1, sens: 0.0018, lane: 1 },
+}
+```
+
+- **sign** — per-app direction (camera-fly vs object-grab invert).
+- **sens** — per-axis sensitivity (tame roll without touching the rest).
+- **lane** — input-channel permutation: which fed channel drives this DOF. `T*` lanes index the translation triple, `R*` the rotation triple.
+
+`sens` does all the scaling, so the same raw `feed()` suits any transport — only the profile changes. The default is SpaceNavigator-tuned and meant to be replaced wholesale for a different device. `HELM_CHANNELS` is the frozen order `['Tx','Ty','Tz','Rp','Ry','Rr']`.
+
+**Frame — `from`.** `helm.from` names the space fed rates are interpreted in — a declaration the host reads to resolve the per-step `basis` (the core stays camera-agnostic):
+
+```
+WORLD    world axes — the identity basis (step's basis is null)
+EYE      a viewing camera's frame — screen-relative (default)
+SELF     the helm's OWN evolving pose — body-relative
+<mat4>   an explicit fixed frame
+```
+
+`step` rotates both linear and angular rates through `basis`, then composes the quaternion world-frame — one code path covering body-fly and screen-relative manipulation. `SELF` is body-relative (a per-frame-rebuilt pose matrix); it is a helm `from` value only, not a general mapping space.
+
+**Rest of the surface.**
+
+```js
+helm.deadzone = 8       // rest-drift floor — |rate| ≤ deadzone reads as 0
+helm.activity(out6)     // six effective rates (post deadzone·sign·sens), channel order
+helm.home([pose])       // re-home pos + rot (NOT reset — no keyframes); clears pending rate
+```
+
+The `p5.tree` bridge wraps this into `createCameraHelm` / `createPoseHelm` (transport, camera basis, draw-loop player) plus the `helmRig` gizmo and the `createPanel(helm)` profile editor.
+
+---
+
 ### Coordinate-space mapping
 
 `mapLocation` and `mapDirection` convert points and vectors between any pair of named spaces. All work is done in flat scalar arithmetic — no objects created per call.
@@ -455,6 +518,9 @@ projLeft  projRight  projTop  projBottom
 // Coordinate spaces
 WORLD, EYE, NDC, SCREEN, MODEL, MATRIX
 
+// Helm integrator frame (helm `from` only — body-relative, not a mapping space)
+SELF
+
 // NDC Z convention
 WEBGL   // −1  (z ∈ [−1, 1])
 WEBGPU  //  0  (z ∈ [0, 1])

package/dist/index.js

@@ -12,6 +12,10 @@ const SCREEN = 'SCREEN';
 const MODEL  = 'MODEL';
 const MATRIX = 'MATRIX';
 
+// Integrator frame source (helm `from` only): the construct's own current pose
+// — body-relative; not a general mapDirection space.
+const SELF   = 'SELF';
+
 // NDC Z convention (only difference between backends)
 const WEBGL  = -1;   // z ∈ [−1, 1]
 const WEBGPU =  0;   // z ∈ [0, 1]
@@ -3021,6 +3025,273 @@ function createConstraint(kind, opts) {
   return new Constraint(kind, opts);
 }
 
+/**
+ * @file Source-agnostic 6-DOF pose helm — integrates a live rate stream into a
+ *       { pos, rot } pose. Renderer- and transport-agnostic. Zero dependencies.
+ * @module tree/helm
+ * @license AGPL-3.0-only
+ *
+ * A helm is the rate-stream sibling of the Track family: where a Track produces
+ * a pose from keyframes over time, a helm produces a pose from a live 6-DOF
+ * delta stream (a SpaceNavigator, a tracked hand, an agent policy). It is NOT a
+ * handle — a handle reports a `vec3` solved from a pointer ray; a helm reports a
+ * pose (position + orientation).
+ *
+ * Family placement (peer of PoseTrack, NOT a Track subclass — no timeline):
+ *   feed(translation, rotation)  push the latest raw device rate (input, as Track.add)
+ *   step(out, dt, basis)         integrate the rate by dt into the pose (BRIDGE-DRIVEN,
+ *                                as Track.tick) — writes the new pose into out
+ *   eval(out)                    read the current { pos, rot } (zero-alloc, as Track.eval)
+ *   home(pose?)                  re-home the integrated pose (NOT reset — no keyframes to clear)
+ *
+ * Quaternion algebra is provided by quat.js. Out-first throughout; no allocation
+ * in feed/step/eval. Storage convention (matches the rest of the core): vec3 and
+ * quat state are plain number[] (f64) — the same shape as track.js keyframes and
+ * the frozen basis-vector constants.
+ *
+ * ── Frame discipline (`from` / `basis`) ──────────────────────────────────────
+ * The space the rates are interpreted in is named by `from` (WORLD | EYE | mat4),
+ * a declaration the BRIDGE reads — the core never learns about a camera. The
+ * resolved orientation arrives per-step as `basis`: an eye→world mat4 (or null
+ * for WORLD ≡ the identity basis). Both the linear and angular rates are rotated
+ * through that basis, then the quaternion is composed world-frame. This is the
+ * single code path that covers both manipulation conventions:
+ *
+ *   - camera body-fly  — basis is the driven camera's own eye matrix (which this
+ *                        helm produced last frame ⇒ equals the integrated `q`,
+ *                        zero staleness); rotating a body delta through `q` then
+ *                        world-composing is algebraically a body-frame compose.
+ *   - screen-relative  — basis is the *viewing* camera's eye matrix (an external
+ *                        frame); a push moves the target relative to the screen.
+ *
+ * Per-channel `from` ({ translation, rotation }) is a deferred, non-breaking
+ * extension (one basis suffices today — pose-helm-design.md §8.3).
+ */
+
+
+// =========================================================================
+// Module-level scratch — shared across helm instances (non-reentrant; step
+// is synchronous and called at most once per helm per frame).
+// =========================================================================
+
+const _dq = [0, 0, 0, 1];
+
+// Deadzone gate — |v| > dz keeps v, else 0. Module-level so step allocates no
+// closure. Strictly-greater matches the e7 reference (rest reads exact 0).
+const _dz = (v, dz) => (v > dz || v < -dz) ? v : 0;
+
+/**
+ * Build the canonical default profile. SpaceNavigator-tuned lane permutation
+ * and the eye-frame manipulation feel found in the e7 experiments; it is the
+ * per-app / per-device mapping layer and is meant to be overwritten wholesale
+ * (`helm.profile = { … }`) for a different transport.
+ *
+ *   sign  — per-app direction (camera-fly vs object-grab invert; flip live).
+ *   sens  — per-axis sensitivity (tame roll without touching the rest).
+ *   lane  — input-channel permutation: which fed channel drives this DOF.
+ *           T* lanes index the translation triple; R* lanes the rotation triple.
+ */
+function _defaultProfile() {
+  return {
+    Tx: { sign:  1, sens: 0.30,   lane: 0 },
+    Ty: { sign:  1, sens: 0.30,   lane: 2 },
+    Tz: { sign: -1, sens: 0.30,   lane: 1 },
+    Rp: { sign: -1, sens: 0.0025, lane: 0 },
+    Ry: { sign: -1, sens: 0.0025, lane: 2 },
+    Rr: { sign:  1, sens: 0.0018, lane: 1 },
+  };
+}
+
+/** Channel order — readout / iteration convenience (Tx Ty Tz Rp Ry Rr). */
+const HELM_CHANNELS = Object.freeze(['Tx', 'Ty', 'Tz', 'Rp', 'Ry', 'Rr']);
+
+// =========================================================================
+// PoseHelm
+// =========================================================================
+
+/**
+ * Source-agnostic 6-DOF pose producer. Holds a profile + the integrated pose;
+ * no timeline (no keyframes, no play/seek/loop).
+ */
+class PoseHelm {
+  constructor() {
+    /**
+     * DOF mapping table. Six channels, each `{ sign, sens, lane }`.
+     * Public and mutable — set wholesale to re-map a device or app.
+     * @type {{ Tx:Object, Ty:Object, Tz:Object, Rp:Object, Ry:Object, Rr:Object }}
+     */
+    this.profile = _defaultProfile();
+
+    /**
+     * Rest-drift floor. A fed rate with |value| ≤ deadzone reads as 0. Devices
+     * that rest at exact 0 need only a small floor. @type {number}
+     */
+    this.deadzone = 8;
+
+    /**
+     * The space fed rates are interpreted in: a space constant (WORLD | EYE) or
+     * a mat4 frame. Declarative only — the bridge reads this to resolve the
+     * per-step `basis`; the core stays camera-agnostic. @type {string|ArrayLike<number>}
+     */
+    this.from = 'EYE';
+
+    // Latest fed raw rates (refreshed by feed; persist until the next feed —
+    // the transport is responsible for feeding 0 when motion should stop).
+    this._lin = [0, 0, 0];
+    this._ang = [0, 0, 0];
+
+    // Integrated pose — the source of truth.
+    this._pos = [0, 0, 0];
+    this._q   = [0, 0, 0, 1];
+  }
+
+  /**
+   * Push the latest raw 6-DOF device rate. Either argument may be omitted to
+   * leave that half unchanged (devices report the two halves on separate
+   * frames). The value persists until the next feed. Raw device units — the
+   * profile's `sens` does the scaling, so the same feed() suits any transport.
+   *
+   * @param {ArrayLike<number>} [translation]  [tx, ty, tz] raw lane rates.
+   * @param {ArrayLike<number>} [rotation]     [rx, ry, rz] raw lane rates.
+   * @returns {PoseHelm} this
+   */
+  feed(translation, rotation) {
+    if (translation) {
+      this._lin[0] = translation[0] || 0;
+      this._lin[1] = translation[1] || 0;
+      this._lin[2] = translation[2] || 0;
+    }
+    if (rotation) {
+      this._ang[0] = rotation[0] || 0;
+      this._ang[1] = rotation[1] || 0;
+      this._ang[2] = rotation[2] || 0;
+    }
+    return this;
+  }
+
+  /**
+   * Integrate the latest fed rate by `dt` seconds into the pose, then write the
+   * pose into `out`. Bridge-driven (the player calls it each frame; a sketch
+   * never does, as it never calls track.tick()).
+   *
+   * `basis` is the resolved `from` frame: an eye→world column-major mat4
+   * (16-element ArrayLike), or null/omitted for WORLD (the identity basis). Its
+   * columns supply the right/up/back axes; forward is −col2. Both the linear and
+   * angular rates are rotated through it, then `q` is composed world-frame.
+   *
+   * Zero-allocation. `out` is `{ pos:number[3], rot:number[4] }`; omit it for a
+   * fresh object.
+   *
+   * @param {{ pos:number[], rot:number[] }} [out]
+   * @param {number} dt       Elapsed time in seconds.
+   * @param {ArrayLike<number>} [basis]  Eye→world mat4, or null for WORLD.
+   * @returns {{ pos:number[], rot:number[] }} out
+   */
+  step(out, dt, basis) {
+    const p = this.profile, dz = this.deadzone;
+    const lin = this._lin, ang = this._ang;
+
+    // Basis axes (right / up / forward). No basis ⇒ the identity eye matrix:
+    // right +X, up +Y, forward −Z. Forward is −col2 (an eye→world matrix stores
+    // the camera's BACK in col2), and the identity's col2 is +Z, so forward is
+    // −Z — making step(out, dt, null) identical to step(out, dt, IDENTITY_MAT4),
+    // as the `from` contract ("null ≡ the identity basis") promises.
+    let rX = 1, rY = 0, rZ =  0;
+    let uX = 0, uY = 1, uZ =  0;
+    let fX = 0, fY = 0, fZ = -1;
+    if (basis) {
+      rX =  basis[0]; rY =  basis[1]; rZ =  basis[2];
+      uX =  basis[4]; uY =  basis[5]; uZ =  basis[6];
+      fX = -basis[8]; fY = -basis[9]; fZ = -basis[10];
+    }
+
+    // Angular: three rates → one delta quat, rotated into world, world-composed.
+    const wx = _dz(ang[p.Rp.lane], dz) * p.Rp.sign * p.Rp.sens;
+    const wy = _dz(ang[p.Ry.lane], dz) * p.Ry.sign * p.Ry.sens;
+    const wz = _dz(ang[p.Rr.lane], dz) * p.Rr.sign * p.Rr.sens;
+    const w  = Math.sqrt(wx * wx + wy * wy + wz * wz);
+    if (w > 0) {
+      // Axis in world = basis · (wx,wy,wz); its length is w (basis orthonormal),
+      // so the rotation angle is w·dt. qFromAxisAngle renormalizes the axis.
+      const ax = wx * rX + wy * uX + wz * fX;
+      const ay = wx * rY + wy * uY + wz * fY;
+      const az = wx * rZ + wy * uZ + wz * fZ;
+      qFromAxisAngle(_dq, ax, ay, az, w * dt);
+      qMul(this._q, _dq, this._q);        // delta already in world → world-frame compose
+      qNormalize(this._q);
+    }
+
+    // Linear: three rates rotated into world, integrated by dt.
+    const tx = _dz(lin[p.Tx.lane], dz) * p.Tx.sign * p.Tx.sens;
+    const ty = _dz(lin[p.Ty.lane], dz) * p.Ty.sign * p.Ty.sens;
+    const tz = _dz(lin[p.Tz.lane], dz) * p.Tz.sign * p.Tz.sens;
+    this._pos[0] += (tx * rX + ty * uX + tz * fX) * dt;
+    this._pos[1] += (tx * rY + ty * uY + tz * fY) * dt;
+    this._pos[2] += (tx * rZ + ty * uZ + tz * fZ) * dt;
+
+    return this.eval(out);
+  }
+
+  /**
+   * Read the current pose into `out` (zero-alloc). The shared output contract
+   * that feeds applyPose — mirrors Track.eval.
+   *
+   * @param {{ pos:number[], rot:number[] }} [out]
+   * @returns {{ pos:number[], rot:number[] }} out
+   */
+  eval(out) {
+    out = out || { pos: [0, 0, 0], rot: [0, 0, 0, 1] };
+    out.pos[0] = this._pos[0]; out.pos[1] = this._pos[1]; out.pos[2] = this._pos[2];
+    out.rot[0] = this._q[0];   out.rot[1] = this._q[1];
+    out.rot[2] = this._q[2];   out.rot[3] = this._q[3];
+    return out;
+  }
+
+  /**
+   * Write the six effective channel rates (post deadzone·sign·sens) into `out6`,
+   * in channel order [Tx, Ty, Tz, Rp, Ry, Rr]. The gizmo reads this to light the
+   * DOFs being driven; readouts can show signed magnitudes. Zero-alloc.
+   *
+   * @param {number[]} out6  6-element destination.
+   * @returns {number[]} out6
+   */
+  activity(out6) {
+    const p = this.profile, dz = this.deadzone, lin = this._lin, ang = this._ang;
+    out6[0] = _dz(lin[p.Tx.lane], dz) * p.Tx.sign * p.Tx.sens;
+    out6[1] = _dz(lin[p.Ty.lane], dz) * p.Ty.sign * p.Ty.sens;
+    out6[2] = _dz(lin[p.Tz.lane], dz) * p.Tz.sign * p.Tz.sens;
+    out6[3] = _dz(ang[p.Rp.lane], dz) * p.Rp.sign * p.Rp.sens;
+    out6[4] = _dz(ang[p.Ry.lane], dz) * p.Ry.sign * p.Ry.sens;
+    out6[5] = _dz(ang[p.Rr.lane], dz) * p.Rr.sign * p.Rr.sens;
+    return out6;
+  }
+
+  /**
+   * Re-home the integrated pose. Sets position + orientation to `pose` (or the
+   * identity pose when omitted) and clears any pending rate so the helm rests at
+   * a clean, known state. NOT a reset — there are no keyframes to clear.
+   *
+   * @param {{ pos?:ArrayLike<number>, rot?:ArrayLike<number> }} [pose]
+   * @returns {PoseHelm} this
+   */
+  home(pose) {
+    if (pose && pose.pos) {
+      this._pos[0] = pose.pos[0]; this._pos[1] = pose.pos[1]; this._pos[2] = pose.pos[2];
+    } else {
+      this._pos[0] = 0; this._pos[1] = 0; this._pos[2] = 0;
+    }
+    if (pose && pose.rot) {
+      this._q[0] = pose.rot[0]; this._q[1] = pose.rot[1];
+      this._q[2] = pose.rot[2]; this._q[3] = pose.rot[3];
+    } else {
+      this._q[0] = 0; this._q[1] = 0; this._q[2] = 0; this._q[3] = 1;
+    }
+    this._lin[0] = this._lin[1] = this._lin[2] = 0;
+    this._ang[0] = this._ang[1] = this._ang[2] = 0;
+    return this;
+  }
+}
+
 /**
  * @file Frustum planes and visibility tests — zero allocations.
  * @module tree/visibility
@@ -3180,5 +3451,5 @@ function boxVisibility(planes, x0, y0, z0, x1, y1, z1) {
   return allIn ? VISIBLE : SEMIVISIBLE;
 }
 
-export { AXIS, CameraTrack, Constraint, DIAL, DIRECTION, EYE, INVISIBLE, MATRIX, MODEL, NDC, ORIGIN, PLANE, PLANE_BOTTOM, PLANE_FAR, PLANE_LEFT, PLANE_NEAR, PLANE_RIGHT, PLANE_TOP, POINT, PoseTrack, SCREEN, SEMIVISIBLE, SPHERE, VISIBLE, WEBGL, WEBGPU, WORLD, _i, _j, _k, azElFromDir, boxVisibility, createConstraint, dirFromAzEl, distanceToPlane, frustumPlanes, hermiteVec3, i, j, k, lerpVec3, mapDirection, mapLocation, mat3Direction, mat3NormalFromMat4, mat4Bias, mat4Eye, mat4FromBasis, mat4FromScale, mat4FromTRS, mat4FromTranslation, mat4Invert, mat4Location, mat4MV, mat4Mul, mat4MulDir, mat4MulPoint, mat4Ortho, mat4PV, mat4Persp, mat4Pick, mat4Reflect, mat4ToRotation, mat4ToScale, mat4ToTransform, mat4ToTranslation, mat4View, pixelRatio, pointVisibility, projBottom, projFar, projFov, projHfov, projIsOrtho, projLeft, projNear, projRight, projTop, qConjugate, qCopy, qDot, qFromAxisAngle, qFromLookDir, qFromMat4, qFromRotMat3x3, qFromUnitVectors, qMul, qNegate, qNlerp, qNormalize, qRotateVec3, qSet, qSlerp, qToAxisAngle, qToMat4, rayClosestPointOnAxis, rayPlane, raySphere, sphereVisibility, transformToMat4 };
+export { AXIS, CameraTrack, Constraint, DIAL, DIRECTION, EYE, HELM_CHANNELS, INVISIBLE, MATRIX, MODEL, NDC, ORIGIN, PLANE, PLANE_BOTTOM, PLANE_FAR, PLANE_LEFT, PLANE_NEAR, PLANE_RIGHT, PLANE_TOP, POINT, PoseHelm, PoseTrack, SCREEN, SELF, SEMIVISIBLE, SPHERE, VISIBLE, WEBGL, WEBGPU, WORLD, _i, _j, _k, azElFromDir, boxVisibility, createConstraint, dirFromAzEl, distanceToPlane, frustumPlanes, hermiteVec3, i, j, k, lerpVec3, mapDirection, mapLocation, mat3Direction, mat3NormalFromMat4, mat4Bias, mat4Eye, mat4FromBasis, mat4FromScale, mat4FromTRS, mat4FromTranslation, mat4Invert, mat4Location, mat4MV, mat4Mul, mat4MulDir, mat4MulPoint, mat4Ortho, mat4PV, mat4Persp, mat4Pick, mat4Reflect, mat4ToRotation, mat4ToScale, mat4ToTransform, mat4ToTranslation, mat4View, pixelRatio, pointVisibility, projBottom, projFar, projFov, projHfov, projIsOrtho, projLeft, projNear, projRight, projTop, qConjugate, qCopy, qDot, qFromAxisAngle, qFromLookDir, qFromMat4, qFromRotMat3x3, qFromUnitVectors, qMul, qNegate, qNlerp, qNormalize, qRotateVec3, qSet, qSlerp, qToAxisAngle, qToMat4, rayClosestPointOnAxis, rayPlane, raySphere, sphereVisibility, transformToMat4 };
 //# sourceMappingURL=index.js.map