@nakednous/tree 0.0.26 → 0.0.27

package/README.md

@@ -41,6 +41,7 @@ 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
+filter.js — input conditioning: the 1€ filter + absolute→rate differencing
 handle.js — constraint solver + ray primitives for interactive manipulators
 ```
 
@@ -351,14 +352,55 @@ SELF     the helm's OWN evolving pose — body-relative
 
 ```js
 helm.deadzone = 8       // rest-drift floor — |rate| ≤ deadzone reads as 0
+helm.filter = oneEuro({ minCutoff: 1, beta: 0.5 })  // optional input conditioner (filter → deadzone)
+helm.fullScale = 500    // raw full-deflection magnitude a read-out divides by
 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
+helm.home([pose])       // re-home pos + rot (NOT reset — no keyframes); clears pending rate; resets filter
 ```
 
+`filter` is an optional input conditioner (default `null`): when set, `step` runs it over the fed rate before the deadzone — filter then deadzone, the two orthogonal (the 1€ removes zero-mean jitter; the deadzone's exact zero is the only no-creep guarantee, since a low-pass passes DC). `fullScale` (default `500`) is the raw full-deflection magnitude a read-out divides by, so a transport on a different input scale declares its own and its meters read honestly. `activity()` reports the raw fed rate (pre-filter) by design.
+
 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.
 
 ---
 
+### Input conditioning — `oneEuro` · `poseDelta`
+
+Two helpers for the rate stream a helm feeds on — flat, out-first, zero-alloc (`filter.js`).
+
+**`oneEuro({ minCutoff, beta, dCutoff })`** is the [1€ filter](https://gery.casiez.net/1euro/) (Casiez et al., CHI'12): a first-order low-pass whose cutoff rises with signal speed — heavy smoothing at rest, low lag under motion. It returns a stateful carrying function, dispatched on its first argument:
+
+```js
+import { oneEuro } from '@nakednous/tree'
+
+const f = oneEuro({ minCutoff: 1, beta: 0.5 })   // params live-mutable: f.minCutoff, f.beta
+
+// scalar form — returns the filtered number
+const y = f(rawScalar, dt)
+
+// vec form — out-first, zero-alloc after warm-up
+const out = [0, 0, 0]
+f(out, rawVec3, dt)
+
+f.reset()   // drop state — next call re-seeds
+```
+
+It removes zero-mean **jitter**, not a DC **bias**: a low-pass passes a constant offset, so a resting bias survives it and still integrates to drift — pair it with a deadzone (the helm applies filter → deadzone in that order).
+
+**`poseDelta(out, prev, cur, dt)`** differences two absolute poses into the `{ lin, ang }` rate a helm feeds on — the bridge from an absolute transport (a tracked hand, a marker, a played keyframe) to the rate stream.
+
+```js
+import { poseDelta } from '@nakednous/tree'
+
+const rate = { lin: [0, 0, 0], ang: [0, 0, 0] }
+poseDelta(rate, prevPose, curPose, dt)   // prev / cur: { pos:[x,y,z], rot:[x,y,z,w] }
+helm.feed(rate.lin, rate.ang)
+```
+
+The angular half carries a **double-cover guard**: a quaternion and its negation are the same orientation, so a source that returns a canonicalised quaternion makes the stored value jump hemispheres as the true orientation sweeps through `w = 0`. When `dot(prev, cur) < 0`, `poseDelta` flips `cur` into `prev`'s hemisphere before differencing, so the relative rotation always takes the short arc — without it the angular rate spikes toward `2π/dt` at every crossing.
+
+---
+
 ### 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.

package/dist/index.js

@@ -293,6 +293,117 @@ const qToAxisAngle = (q, out) => {
   return out;
 };
 
+/**
+ * @file 1€ input filter — speed-adaptive first-order low-pass for noisy input.
+ * @module tree/filter
+ * @license AGPL-3.0-only
+ *
+ * A jitter conditioner for noisy / absolute input streams (the helm's optional
+ * `filter` slot; sketch-side handle conditioning). It is NOT a deadzone
+ * replacement: a low-pass passes DC, so a constant rest bias survives it and
+ * still integrates to creep — only the deadzone's exact-zero clamp removes that.
+ * The 1€ removes zero-mean jitter; the two are orthogonal and coexist, applied
+ * filter → deadzone (condition the continuous signal first, then gate to zero).
+ *
+ * First-order low-pass whose cutoff rises with the signal's speed: slow (rest)
+ * → low cutoff → heavy smoothing; fast (motion) → high cutoff → low lag. Tuned
+ * by `minCutoff` (Hz, the rest cutoff) and `beta` (how fast the cutoff opens
+ * with speed). Reimplemented from the paper's equations — `tree` is zero-dep, so
+ * the ~one-page primitive is vendored, not depended on (the same call made for
+ * quaternions over gl-matrix).
+ *
+ * Reference: Casiez, G., Roussel, N., & Vogel, D. (2012). 1€ Filter: A Simple
+ * Speed-based Low-pass Filter for Noisy Input in Interactive Systems. CHI '12,
+ * 2527–2530. DOI 10.1145/2207676.2208639 · https://gery.casiez.net/1euro/
+ */
+
+
+/**
+ * Build a stateful 1€ filter as an out-first carrying function.
+ *
+ * The returned `f` carries the previous filtered value and derivative across
+ * calls (one state slot per vector component), and is used in one of two forms:
+ *
+ *   - vec form    `f(out, raw, dt)` — `out`/`raw` are equal-length ArrayLikes;
+ *                 writes the filtered vector into `out` and returns it.
+ *                 Zero-allocation after the first call (state sized to `raw`).
+ *   - scalar form `f(raw, dt)` — `raw` is a number; returns the filtered number.
+ *
+ * The form is chosen by the first argument's type (number ⇒ scalar). `minCutoff`,
+ * `beta`, and `dCutoff` are live-mutable on the returned function (`f.minCutoff`,
+ * `f.beta`, `f.dCutoff`) and read every call, so a panel can tune them against
+ * live noise. `f.reset()` drops the carried state at a discontinuity (a
+ * re-acquired source, a helm `home()`); smear across one and the output lurches.
+ *
+ * @param {Object}  [opts]
+ * @param {number}  [opts.minCutoff=1]  Minimum (rest) cutoff frequency, in Hz.
+ * @param {number}  [opts.beta=0]       Speed coefficient (cutoff = minCutoff +
+ *                                       beta·|filtered derivative|); unitless.
+ * @param {number}  [opts.dCutoff=1]    Derivative cutoff frequency, in Hz.
+ * @returns {Function} A carrying filter `f(out, raw, dt)` / `f(raw, dt)` with a
+ *                      `reset()` method and live `minCutoff` / `beta` / `dCutoff`.
+ */
+function oneEuro(opts) {
+  opts = opts || {};
+
+  // Carried state: previous filtered value + previous filtered derivative.
+  // number (scalar form) | number[] (vec form). primed = state is seeded.
+  let xPrev = null;
+  let dxPrev = null;
+  let primed = false;
+
+  // Low-pass smoothing factor for a sample period `dt` and a cutoff frequency
+  // (the paper's α = 1 / (1 + τ/Te), τ = 1 / (2π·cutoff)).
+  const alpha = (dt, cutoff) => {
+    const tau = 1 / (2 * Math.PI * cutoff);
+    return 1 / (1 + tau / dt);
+  };
+  const smooth = (a, x, xp) => a * x + (1 - a) * xp;
+
+  const scalar = (x, dt) => {
+    if (!primed) { xPrev = x; dxPrev = 0; primed = true; return x; }
+    const dx  = (x - xPrev) / dt;
+    const edx = smooth(alpha(dt, f.dCutoff), dx, dxPrev);
+    const a   = alpha(dt, f.minCutoff + f.beta * Math.abs(edx));
+    const xh  = smooth(a, x, xPrev);
+    xPrev = xh; dxPrev = edx;
+    return xh;
+  };
+
+  const vec = (out, raw, dt) => {
+    const n = raw.length;
+    if (!primed) {
+      if (!Array.isArray(xPrev) || xPrev.length !== n) {
+        xPrev = new Array(n); dxPrev = new Array(n);
+      }
+      for (let i = 0; i < n; i++) { xPrev[i] = raw[i]; dxPrev[i] = 0; out[i] = raw[i]; }
+      primed = true;
+      return out;
+    }
+    for (let i = 0; i < n; i++) {
+      const dx  = (raw[i] - xPrev[i]) / dt;
+      const edx = smooth(alpha(dt, f.dCutoff), dx, dxPrev[i]);
+      const a   = alpha(dt, f.minCutoff + f.beta * Math.abs(edx));
+      const xh  = smooth(a, raw[i], xPrev[i]);
+      xPrev[i] = xh; dxPrev[i] = edx;
+      out[i] = xh;
+    }
+    return out;
+  };
+
+  const f = (out, raw, dt) =>
+    (typeof out === 'number') ? scalar(out, raw) : vec(out, raw, dt);
+
+  f.minCutoff = (opts.minCutoff != null) ? opts.minCutoff : 1;
+  f.beta      = (opts.beta      != null) ? opts.beta      : 0;
+  f.dCutoff   = (opts.dCutoff   != null) ? opts.dCutoff   : 1;
+
+  /** Drop the carried state — call at a discontinuity (re-acquire / home). */
+  f.reset = () => { primed = false; return f; };
+
+  return f;
+}
+
 /**
  * @file Matrix construction from geometric specs and partial decomposition.
  * @module tree/form
@@ -3044,6 +3155,12 @@ function createConstraint(kind, opts) {
  *   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)
  *
+ * Value layer (opt-in, §10): a per-helm `fullScale` keeps the read-outs honest
+ * across input scales; an opt-in `filter` (oneEuro) conditions the fed rates
+ * before the deadzone inside step; `poseDelta` differences two absolute poses
+ * into a feedable rate. With `filter` null and the default `fullScale`, the
+ * clean rate-native path is unchanged.
+ *
  * 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
@@ -3076,6 +3193,23 @@ function createConstraint(kind, opts) {
 
 const _dq = [0, 0, 0, 1];
 
+// Scratch for the optional input filter (helm.filter). The fed rates are packed
+// into one 6-vector, conditioned, and unpacked to lin/ang triples before the
+// deadzone — so a single filter carries one state per helm. Shared across
+// instances (step is synchronous, at most once per helm per frame).
+const _f6raw = [0, 0, 0, 0, 0, 0];
+const _f6out = [0, 0, 0, 0, 0, 0];
+const _fLin  = [0, 0, 0];
+const _fAng  = [0, 0, 0];
+
+/**
+ * Default full-deflection input magnitude — the fed rate a read-out shows as
+ * full (the SpaceNavigator's saturated lane). Private to core: a transport on a
+ * different raw scale sets helm.fullScale and never reads this, so there is no
+ * public HELM_FULL export. Display-only; integration uses profile.sens directly.
+ */
+const HELM_FULL_SCALE = 500;
+
 // 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;
@@ -3128,6 +3262,24 @@ class PoseHelm {
      */
     this.deadzone = 8;
 
+    /**
+     * Full-deflection input magnitude for the read-outs (gizmo overlay + panel
+     * meters): a fed rate of |fullScale| reads as a full bar / arrow. Set by a
+     * transport whose saturated rate differs from the default (a gamepad stick
+     * that saturates at 1 sets fullScale = 1). Display-only — integration uses
+     * profile.sens directly, so this never affects flight. @type {number}
+     */
+    this.fullScale = HELM_FULL_SCALE;
+
+    /**
+     * Optional input conditioner applied to the fed rates BEFORE the deadzone,
+     * inside step — a oneEuro filter, or any f(out, raw, dt) carrying function
+     * with a reset(). null (the default) is the clean rate-native path: the
+     * filter branch is skipped, so a clean device pays nothing. Set for noisy /
+     * absolute sources; home() resets it. @type {?Function}
+     */
+    this.filter = null;
+
     /**
      * 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
@@ -3189,7 +3341,22 @@ class PoseHelm {
    */
   step(out, dt, basis) {
     const p = this.profile, dz = this.deadzone;
-    const lin = this._lin, ang = this._ang;
+    let lin = this._lin, ang = this._ang;
+
+    // Value layer — condition the fed rates BEFORE the deadzone (the filter
+    // narrows the jitter band; the deadzone then gates the residual to exact
+    // zero). The filter carries state, so it is ticked exactly once per step;
+    // activity() reads the raw fed rate and is left unfiltered (the read-out
+    // shows device input, normalized by fullScale). Skipped when filter is null.
+    const filter = this.filter;
+    if (filter) {
+      _f6raw[0] = lin[0]; _f6raw[1] = lin[1]; _f6raw[2] = lin[2];
+      _f6raw[3] = ang[0]; _f6raw[4] = ang[1]; _f6raw[5] = ang[2];
+      filter(_f6out, _f6raw, dt);
+      _fLin[0] = _f6out[0]; _fLin[1] = _f6out[1]; _fLin[2] = _f6out[2];
+      _fAng[0] = _f6out[3]; _fAng[1] = _f6out[4]; _fAng[2] = _f6out[5];
+      lin = _fLin; ang = _fAng;
+    }
 
     // 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
@@ -3288,10 +3455,73 @@ class PoseHelm {
     }
     this._lin[0] = this._lin[1] = this._lin[2] = 0;
     this._ang[0] = this._ang[1] = this._ang[2] = 0;
+    if (this.filter) this.filter.reset();   // drop filter state at the discontinuity
     return this;
   }
 }
 
+// =========================================================================
+// poseDelta — absolute pose → 6-DOF rate
+// =========================================================================
+
+/**
+ * Difference two consecutive absolute poses into a 6-DOF rate the helm can be
+ * fed — the bridge for absolute-pose transports (gesture / landmark / marker /
+ * IMU) into feed(lin, ang). Out-first, zero-allocation.
+ *
+ * Linear rate is (cur.pos − prev.pos) / dt. Angular rate is the world-frame
+ * angular velocity ω carrying prev.rot onto cur.rot over dt: the relative
+ * rotation r = cur · conj(prev) (so cur = r · prev, the world-frame compose the
+ * step integrates), read as axis · angle / dt.
+ *
+ * The double-cover guard is the whole reason to ship this rather than inline it:
+ * a quaternion and its negation are the same orientation, so when
+ * dot(prev.rot, cur.rot) < 0 the two samples sit on opposite hemispheres and a
+ * naive difference takes the long way round — the angular rate spikes at the
+ * crossing. Flipping cur into prev's hemisphere first keeps r the shortest arc.
+ *
+ * Fed through a helm with an identity profile in WORLD, the integrated pose
+ * retraces the source (the round-trip e9 asserts). A 1:1, non-integrated
+ * consumer skips the helm and applyPoses the absolute pose directly.
+ *
+ * @param {{ lin:number[], ang:number[] }} [out]  Destination; omit for a fresh one.
+ * @param {{ pos:ArrayLike<number>, rot:ArrayLike<number> }} prev  Previous pose.
+ * @param {{ pos:ArrayLike<number>, rot:ArrayLike<number> }} cur   Current pose.
+ * @param {number} dt  Elapsed seconds between the two samples.
+ * @returns {{ lin:number[], ang:number[] }} out
+ */
+function poseDelta(out, prev, cur, dt) {
+  out = out || { lin: [0, 0, 0], ang: [0, 0, 0] };
+  const inv = 1 / dt;
+
+  out.lin[0] = (cur.pos[0] - prev.pos[0]) * inv;
+  out.lin[1] = (cur.pos[1] - prev.pos[1]) * inv;
+  out.lin[2] = (cur.pos[2] - prev.pos[2]) * inv;
+
+  const px = prev.rot[0], py = prev.rot[1], pz = prev.rot[2], pw = prev.rot[3];
+  let   cx = cur.rot[0],  cy = cur.rot[1],  cz = cur.rot[2],  cw = cur.rot[3];
+
+  // Double-cover guard: bring cur into prev's hemisphere so r is the short arc.
+  if (px * cx + py * cy + pz * cz + pw * cw < 0) { cx = -cx; cy = -cy; cz = -cz; cw = -cw; }
+
+  // Relative rotation r = cur · conj(prev), conj(prev) = (−px, −py, −pz, pw).
+  const rx = -cw * px + cx * pw - cy * pz + cz * py;
+  const ry = -cw * py + cx * pz + cy * pw - cz * px;
+  const rz = -cw * pz - cx * py + cy * px + cz * pw;
+  const rw =  cw * pw + cx * px + cy * py + cz * pz;   // = dot(prev, cur) ≥ 0 → angle ≤ π
+
+  // Axis · angle of r → ω = axis · angle / dt. Below the threshold the rotation
+  // is negligible (no well-defined axis) and the angular rate is exact zero.
+  const sinHalf = Math.sqrt(rx * rx + ry * ry + rz * rz);
+  if (sinHalf < 1e-8) {
+    out.ang[0] = 0; out.ang[1] = 0; out.ang[2] = 0;
+  } else {
+    const k = (2 * Math.atan2(sinHalf, rw)) * inv / sinHalf;
+    out.ang[0] = rx * k; out.ang[1] = ry * k; out.ang[2] = rz * k;
+  }
+  return out;
+}
+
 /**
  * @file Frustum planes and visibility tests — zero allocations.
  * @module tree/visibility
@@ -3451,5 +3681,5 @@ function boxVisibility(planes, x0, y0, z0, x1, y1, z1) {
   return allIn ? VISIBLE : SEMIVISIBLE;
 }
 
-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 };
+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, oneEuro, pixelRatio, pointVisibility, poseDelta, 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