@nakednous/tree 0.0.15 → 0.0.17

package/README.md

@@ -82,10 +82,10 @@ Playback features: signed `rate` (negative reverses), `loop`, `bounce`, `seek(t)
 `add()` accepts flexible specs. Top-level forms:
 
 ```js
-track.add({ pos, rot, scl })                      // explicit TRS — rot accepts any form below
-track.add({ pos, rot, scl, tanIn, tanOut })        // with Hermite tangents (vec3, optional)
-track.add({ mMatrix: mat4 })                       // decompose a column-major model matrix into TRS
-track.add([ spec, spec, ... ])                     // bulk
+track.add({ pos, rot, scl })                 // explicit TRS — rot accepts any form below
+track.add({ pos, rot, scl, tanIn, tanOut })  // with Hermite tangents (vec3, optional)
+track.add({ mat4Model: mat4 })               // decompose a column-major model matrix into TRS
+track.add([ spec, spec, ... ])               // bulk
 ```
 
 `tanIn` is the incoming position tangent at this keyframe; `tanOut` is the outgoing tangent. When only one is given, the other mirrors it. When neither is given, centripetal Catmull-Rom tangents are auto-computed from neighboring keyframes.
@@ -100,16 +100,16 @@ track.add({ pos:[300,0,0] })                                    // auto tangents
 `rot` sub-forms — all normalised internally:
 
 ```js
-rot: [x,y,z,w]                                   // raw quaternion
-rot: { axis:[x,y,z], angle }                      // axis-angle
-rot: { dir:[x,y,z], up?:[x,y,z] }                // look direction (−Z forward)
-rot: { euler:[rx,ry,rz], order?:'YXZ' }           // intrinsic Euler angles (radians)
-                                                   // orders: YXZ (default), XYZ, ZYX,
-                                                   //         ZXY, XZY, YZX
-                                                   // extrinsic ABC = intrinsic CBA
-rot: { from:[x,y,z], to:[x,y,z] }                // shortest-arc between directions
-rot: { mat3: Float32Array|Array }                 // column-major 3×3 rotation matrix
-rot: { eMatrix: mat4 }                            // rotation block of an eye matrix
+rot: [x,y,z,w]                           // raw quaternion
+rot: { axis:[x,y,z], angle }             // axis-angle
+rot: { dir:[x,y,z], up?:[x,y,z] }        // look direction (−Z forward)
+rot: { euler:[rx,ry,rz], order?:'YXZ' }  // intrinsic Euler angles (radians)
+                                         // orders: YXZ (default), XYZ, ZYX,
+                                         //         ZXY, XZY, YZX
+                                         // extrinsic ABC = intrinsic CBA
+rot: { from:[x,y,z], to:[x,y,z] }        // shortest-arc between directions
+rot: { mat3: Float32Array|Array }        // column-major 3×3 rotation matrix
+rot: { mat4Eye: mat4 }                   // rotation block of an eye matrix
 ```
 
 ---
@@ -160,7 +160,7 @@ track.add({ eye, center?, up?, fov?, halfHeight?,
 track.add([ spec, spec, ... ])     // bulk
 ```
 
-For matrix-based capture use `PoseTrack.add({ mMatrix: eMatrix })` for full-fidelity TRS including roll, or `cam.capturePose()` (p5.tree bridge) for lookat-style capture.
+For matrix-based capture use `track.add({ mat4Model: mat4Eye })` for full-fidelity TRS including roll, or `cam.capturePose()` (p5.tree bridge) for lookat-style capture.
 
 `fov` and `halfHeight` are lerped between keyframes only when both adjacent keyframes carry a non-null value for that field. Mixed or null entries pass `null` through — the bridge leaves the projection unchanged.
 
@@ -284,6 +284,8 @@ pointVisibility(planes, px, py, pz)
 
 Three-state result: `VISIBLE` (fully inside), `SEMIVISIBLE` (intersecting), `INVISIBLE` (fully outside).
 
+**Sign contract:** `top > 0`, `bottom < 0`, `right > 0`, `left < 0` for standard y-up camera.
+
 ---
 
 ### Quaternion and matrix math
@@ -323,6 +325,10 @@ mat4Ortho            — orthographic projection (ndcZMin, ndcYSign)
 mat4Frustum          — off-centre perspective  (ndcZMin, ndcYSign)
 mat4Bias             — NDC→texture/UV remap [0,1] for shadow mapping
 mat4Reflect          — reflection across a plane
+```
+
+**Mat4 decomposition** (`query.js`):
+```
 mat4ToTranslation    — extract translation (col 3)
 mat4ToScale          — extract scale (column lengths)
 mat4ToRotation       — extract rotation as unit quaternion

package/dist/index.js

@@ -346,7 +346,7 @@ function mat4Eye(out, ex,ey,ez, cx,cy,cz, ux,uy,uz) {
  *
  * @param {Float32Array|number[]} out  16-element destination.
  * @param {number} tx,ty,tz      Translation.
- * @param {number} qx,qy,qz,qw  Rotation quaternion [x,y,z,w].
+ * @param {number} qx,qy,qz,qw   Rotation quaternion [x,y,z,w].
  * @param {number} sx,sy,sz      Scale.
  */
 function mat4FromTRS(out, tx,ty,tz, qx,qy,qz,qw, sx,sy,sz) {
@@ -503,49 +503,6 @@ function mat4Reflect(out, nx,ny,nz,d) {
   return out;
 }
 
-// =========================================================================
-// Partial decomposition  (mat4To___ mirrors mat4From___)
-// =========================================================================
-
-/**
- * Extract translation from a column-major mat4 (column 3).
- * @param {Float32Array|number[]} out3  3-element destination.
- * @param {Float32Array|number[]} m     16-element source.
- */
-function mat4ToTranslation(out3, m) {
-  out3[0]=m[12]; out3[1]=m[13]; out3[2]=m[14];
-  return out3;
-}
-
-/**
- * Extract scale from a column-major mat4 (column lengths of the rotation block).
- * Assumes no shear.
- * @param {Float32Array|number[]} out3  3-element destination.
- * @param {Float32Array|number[]} m     16-element source.
- */
-function mat4ToScale(out3, m) {
-  out3[0]=Math.sqrt(m[0]*m[0]+m[1]*m[1]+m[2]*m[2]);
-  out3[1]=Math.sqrt(m[4]*m[4]+m[5]*m[5]+m[6]*m[6]);
-  out3[2]=Math.sqrt(m[8]*m[8]+m[9]*m[9]+m[10]*m[10]);
-  return out3;
-}
-
-/**
- * Extract rotation as a unit quaternion from a column-major mat4.
- * Scale is factored out from each column. Assumes no shear.
- * @param {number[]} out4  4-element [x,y,z,w] destination.
- * @param {Float32Array|number[]} m  16-element source.
- */
-function mat4ToRotation(out4, m) {
-  const sx=Math.sqrt(m[0]*m[0]+m[1]*m[1]+m[2]*m[2])||1;
-  const sy=Math.sqrt(m[4]*m[4]+m[5]*m[5]+m[6]*m[6])||1;
-  const sz=Math.sqrt(m[8]*m[8]+m[9]*m[9]+m[10]*m[10])||1;
-  return qFromRotMat3x3(out4,
-    m[0]/sx, m[4]/sy, m[8]/sz,
-    m[1]/sx, m[5]/sy, m[9]/sz,
-    m[2]/sx, m[6]/sy, m[10]/sz);
-}
-
 /**
  * @file Matrix arithmetic, space-transform dispatch, and projection queries.
  * @module tree/query
@@ -763,10 +720,30 @@ function mat4MV(out, model, view) { return mat4Mul(out, view, model); }
 
 /**
  * Location transform between frames: out = inv(to) · from.
+ * Assumes both matrices are affine (bottom row [0,0,0,1]).
  * @returns {ArrayLike<number>|null} out, or null if `to` is singular.
  */
 function mat4Location(out, from, to) {
-  return mat4Invert(out, to) && mat4Mul(out, out, from);
+  // Same as: return mat4Invert(out, to) && mat4Mul(out, out, from);
+  const a00=to[0],a01=to[1],a02=to[2],
+        a10=to[4],a11=to[5],a12=to[6],
+        a20=to[8],a21=to[9],a22=to[10];
+  const b01=a22*a11-a12*a21, b11=a12*a20-a22*a10, b21=a21*a10-a11*a20;
+  let det=a00*b01+a01*b11+a02*b21;
+  if (Math.abs(det) < 1e-12) return null;
+  det=1/det;
+  const i00=b01*det,             i01=(a02*a21-a22*a01)*det, i02=(a12*a01-a02*a11)*det;
+  const i10=b11*det,             i11=(a22*a00-a02*a20)*det, i12=(a02*a10-a12*a00)*det;
+  const i20=b21*det,             i21=(a01*a20-a21*a00)*det, i22=(a11*a00-a01*a10)*det;
+  const f00=from[0],f01=from[1],f02=from[2],
+        f10=from[4],f11=from[5],f12=from[6],
+        f20=from[8],f21=from[9],f22=from[10];
+  out[0]=i00*f00+i01*f01+i02*f02; out[1]=i10*f00+i11*f01+i12*f02; out[2]=i20*f00+i21*f01+i22*f02; out[3]=0;
+  out[4]=i00*f10+i01*f11+i02*f12; out[5]=i10*f10+i11*f11+i12*f12; out[6]=i20*f10+i21*f11+i22*f12; out[7]=0;
+  out[8]=i00*f20+i01*f21+i02*f22; out[9]=i10*f20+i11*f21+i12*f22; out[10]=i20*f20+i21*f21+i22*f22; out[11]=0;
+  const dx=from[12]-to[12], dy=from[13]-to[13], dz=from[14]-to[14];
+  out[12]=i00*dx+i01*dy+i02*dz; out[13]=i10*dx+i11*dy+i12*dz; out[14]=i20*dx+i21*dy+i22*dz; out[15]=1;
+  return out;
 }
 
 /**
@@ -1149,6 +1126,49 @@ function mat4Pick(proj, px, py, vp) {
   }
 }
 
+// =========================================================================
+// Decomposition
+// =========================================================================
+
+/**
+ * Extract translation from a column-major mat4 (column 3).
+ * @param {Float32Array|number[]} out3  3-element destination.
+ * @param {Float32Array|number[]} m     16-element source.
+ */
+function mat4ToTranslation(out3, m) {
+  out3[0]=m[12]; out3[1]=m[13]; out3[2]=m[14];
+  return out3;
+}
+
+/**
+ * Extract scale from a column-major mat4 (column lengths of the rotation block).
+ * Assumes no shear.
+ * @param {Float32Array|number[]} out3  3-element destination.
+ * @param {Float32Array|number[]} m     16-element source.
+ */
+function mat4ToScale(out3, m) {
+  out3[0]=Math.sqrt(m[0]*m[0]+m[1]*m[1]+m[2]*m[2]);
+  out3[1]=Math.sqrt(m[4]*m[4]+m[5]*m[5]+m[6]*m[6]);
+  out3[2]=Math.sqrt(m[8]*m[8]+m[9]*m[9]+m[10]*m[10]);
+  return out3;
+}
+
+/**
+ * Extract rotation as a unit quaternion from a column-major mat4.
+ * Scale is factored out from each column. Assumes no shear.
+ * @param {number[]} out4  4-element [x,y,z,w] destination.
+ * @param {Float32Array|number[]} m  16-element source.
+ */
+function mat4ToRotation(out4, m) {
+  const sx=Math.sqrt(m[0]*m[0]+m[1]*m[1]+m[2]*m[2])||1;
+  const sy=Math.sqrt(m[4]*m[4]+m[5]*m[5]+m[6]*m[6])||1;
+  const sz=Math.sqrt(m[8]*m[8]+m[9]*m[9]+m[10]*m[10])||1;
+  return qFromRotMat3x3(out4,
+    m[0]/sx, m[4]/sy, m[8]/sz,
+    m[1]/sx, m[5]/sy, m[9]/sz,
+    m[2]/sx, m[6]/sy, m[10]/sz);
+}
+
 /**
  * @file Spline math and keyframe animation state machines.
  * @module tree/track
@@ -1357,11 +1377,11 @@ const _EULER_ORDERS = new Set(['XYZ','XZY','YXZ','YZX','ZXY','ZYX']);
  *
  *   [x,y,z,w]                        — raw quaternion array
  *   { axis:[x,y,z], angle }          — axis-angle
- *   { dir:[x,y,z], up?:[x,y,z] }    — forward direction (−Z) with optional up
- *   { eMatrix: mat4 }                — rotation block of an eye matrix
+ *   { dir:[x,y,z], up?:[x,y,z] }     — forward direction (−Z) with optional up
+ *   { mat4Eye: mat4 }                — rotation block of an eye matrix
  *   { mat3: mat3 }                   — column-major 3×3 rotation matrix
  *   { euler:[rx,ry,rz], order? }     — intrinsic Euler (default order: YXZ)
- *   { from:[x,y,z], to:[x,y,z] }    — shortest-arc rotation
+ *   { from:[x,y,z], to:[x,y,z] }     — shortest-arc rotation
  *
  * @param {*} v
  * @returns {number[]|null}  [x,y,z,w] or null if unparseable.
@@ -1388,10 +1408,10 @@ function _parseQuat(v) {
     return qFromLookDir([0,0,0,1], d, u);
   }
 
-  // { eMatrix }
-  if (v.eMatrix != null) {
-    const m = (ArrayBuffer.isView(v.eMatrix) || Array.isArray(v.eMatrix))
-      ? v.eMatrix : (v.eMatrix.mat4 ?? null);
+  // { mat4Eye }
+  if (v.mat4Eye != null) {
+    const m = (ArrayBuffer.isView(v.mat4Eye) || Array.isArray(v.mat4Eye))
+      ? v.mat4Eye : (v.mat4Eye.mat4 ?? null);
     if (!m || m.length < 16) return null;
     return qFromRotMat3x3([0,0,0,1], m[0],m[4],m[8], m[1],m[5],m[9], m[2],m[6],m[10]);
   }
@@ -1449,7 +1469,7 @@ function _parseQuat(v) {
  *
  * Accepted forms:
  *
- *   { mMatrix }
+ *   { mat4Model }
  *     Decompose a column-major mat4 into TRS via mat4ToTransform.
  *     Float32Array(16), plain Array, or { mat4 } wrapper.
  *
@@ -1465,10 +1485,10 @@ function _parseQuat(v) {
 function _parseSpec(spec) {
   if (!spec || typeof spec !== 'object') return null;
 
-  // { mMatrix } — full TRS decomposition from model matrix
-  if (spec.mMatrix != null) {
-    const m = (ArrayBuffer.isView(spec.mMatrix) || Array.isArray(spec.mMatrix))
-      ? spec.mMatrix : (spec.mMatrix.mat4 ?? null);
+  // { mat4Model } — full TRS decomposition from model matrix
+  if (spec.mat4Model != null) {
+    const m = (ArrayBuffer.isView(spec.mat4Model) || Array.isArray(spec.mat4Model))
+      ? spec.mat4Model : (spec.mat4Model.mat4 ?? null);
     if (!m || m.length < 16) return null;
     const kf = mat4ToTransform({ pos:[0,0,0], rot:[0,0,0,1], scl:[1,1,1] }, m);
     kf.tanIn = null; kf.tanOut = null;
@@ -1505,7 +1525,7 @@ function _sameTransform(a, b) {
  *     When absent, centripetal Catmull-Rom tangents are auto-computed at eval time.
  *
  *   Removed forms (task 2):
- *     { vMatrix } and { eMatrix } — use PoseTrack.add({ mMatrix: eMatrix }) for
+ *     { mat4View } and { mat4Eye } — use PoseTrack.add({ mat4Model: mat4Eye }) for
  *     full-fidelity capture including roll, or cam.capturePose() for lookat-style.
  *
  * @param {Object} spec
@@ -2004,7 +2024,7 @@ class PoseTrack extends Track {
  *   { eye, center?, up?, fov?, halfHeight?,
  *     eyeTanIn?, eyeTanOut?, centerTanIn?, centerTanOut? }
  *
- * To capture a matrix-based pose, use PoseTrack.add({ mMatrix: eMatrix })
+ * To capture a matrix-based pose, use PoseTrack.add({ mat4Model: mat4Eye })
  * for full-fidelity including roll, or cam.capturePose() for lookat-style.
  */
 class CameraTrack extends Track {