@nakednous/tree 0.0.16 → 0.0.18

package/README.md

@@ -84,7 +84,7 @@ Playback features: signed `rate` (negative reverses), `loop`, `bounce`, `seek(t)
 ```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({ mat4Model: mat4 })               // decompose a column-major model matrix into TRS
 track.add([ spec, spec, ... ])               // bulk
 ```
 
@@ -109,7 +109,7 @@ rot: { euler:[rx,ry,rz], order?:'YXZ' }  // intrinsic Euler angles (radians)
                                          // 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: { 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.
 
@@ -320,11 +320,14 @@ mat4Eye              — eye matrix (eye→world) from lookat params
 mat4FromTRS          — column-major mat4 from flat TRS scalars
 mat4FromTranslation  — translation-only mat4
 mat4FromScale        — scale-only mat4
-mat4Perspective      — perspective projection  (ndcZMin, ndcYSign)
-mat4Ortho            — orthographic projection (ndcZMin, ndcYSign)
-mat4Frustum          — off-centre perspective  (ndcZMin, ndcYSign)
+mat4Persp            — perspective projection, general frustum (ndcZMin, ndcYSign)
+mat4Ortho            — orthographic projection                 (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) {
@@ -390,30 +390,6 @@ function mat4FromScale(out, sx,sy,sz) {
 // Projection construction
 // =========================================================================
 
-/**
- * Perspective projection matrix.
- *
- * @param {Float32Array|number[]} out  16-element destination.
- * @param {number} fov       Vertical field of view (radians).
- * @param {number} aspect    Width / height.
- * @param {number} near      Near plane distance (positive).
- * @param {number} far       Far plane distance (positive, > near).
- * @param {number} ndcZMin   −1 (WEBGL) or 0 (WEBGPU).
- * @param {number} [ndcYSign=1]  +1 = NDC y-up (default); −1 = NDC y-down (native Vulkan).
- */
-function mat4Perspective(out, fov, aspect, near, far, ndcZMin, ndcYSign=1) {
-  const f = 1 / Math.tan(fov * 0.5);
-  out[0]=f/aspect;       out[1]=0;              out[2]=0;  out[3]=0;
-  out[4]=0;              out[5]=ndcYSign*f;     out[6]=0;  out[7]=0;
-  out[8]=0;              out[9]=0;
-  out[10]=(ndcZMin*near-far)/(far-near);
-  out[11]=-1;
-  out[12]=0; out[13]=0;
-  out[14]=(ndcZMin-1)*far*near/(far-near);
-  out[15]=0;
-  return out;
-}
-
 /**
  * Orthographic projection matrix.
  *
@@ -435,15 +411,18 @@ function mat4Ortho(out, left, right, bottom, top, near, far, ndcZMin, ndcYSign=1
 }
 
 /**
- * Frustum (off-centre perspective) projection matrix.
+ * Perspective projection matrix (general / off-centre frustum).
+ * Symmetric case: left=-right, bottom=-top — derive from fov+aspect in user space:
+ *   top = near * Math.tan(fov / 2);  right = top * aspect
+ *   mat4Persp(out, -right, right, -top, top, near, far, ndcZMin)
  *
  * @param {Float32Array|number[]} out  16-element destination.
- * @param {number} left,right,bottom,top  Near-plane extents.
+ * @param {number} left,right,bottom,top  Near-plane extents (signed, y-up: top>0, bottom<0).
  * @param {number} near,far              Clip plane distances (positive).
  * @param {number} ndcZMin               −1 (WEBGL) or 0 (WEBGPU).
  * @param {number} [ndcYSign=1]          +1 = NDC y-up (default); −1 = NDC y-down (native Vulkan).
  */
-function mat4Frustum(out, left, right, bottom, top, near, far, ndcZMin, ndcYSign=1) {
+function mat4Persp(out, left, right, bottom, top, near, far, ndcZMin, ndcYSign=1) {
   const rl=1/(right-left), tb=1/(top-bottom);
   out[0]=2*near*rl;        out[1]=0;                          out[2]=0;  out[3]=0;
   out[4]=0;                out[5]=ndcYSign*2*near*tb;         out[6]=0;  out[7]=0;
@@ -503,49 +482,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 +699,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 +1105,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
@@ -1260,13 +1259,13 @@ const hermiteVec3 = (out, p0, m0, p1, m1, t) => {
 };
 
 // Centripetal CR outgoing tangent at p1 for segment p1→p2, scaled by dt1.
-const _crTanOut = (out, p0, p1, p2, p3) => {
+const _crTanOut = (out, p0, p1, p2) => {
   const dt0=Math.pow(_dist3(p0,p1),0.5)||1, dt1=Math.pow(_dist3(p1,p2),0.5)||1;
   for (let i=0;i<3;i++) out[i]=((p1[i]-p0[i])/dt0-(p2[i]-p0[i])/(dt0+dt1)+(p2[i]-p1[i])/dt1)*dt1;
   return out;
 };
 
-const _crTanIn = (out, p0, p1, p2, p3) => {
+const _crTanIn = (out, p1, p2, p3) => {
   const dt1=Math.pow(_dist3(p1,p2),0.5)||1, dt2=Math.pow(_dist3(p2,p3),0.5)||1;
   for (let i=0;i<3;i++) out[i]=((p2[i]-p1[i])/dt1-(p3[i]-p1[i])/(dt1+dt2)+(p3[i]-p2[i])/dt2)*dt1;
   return out;
@@ -1940,13 +1939,13 @@ class PoseTrack extends Track {
       lerpVec3(out.pos, k0.pos, k1.pos, t);
     } else {
       const p0 = seg > 0      ? this.keyframes[seg - 1].pos : k0.pos;
-      const p3 = seg + 2 < n ? this.keyframes[seg + 2].pos  : k1.pos;
+      seg + 2 < n ? this.keyframes[seg + 2].pos  : k1.pos;
       const m0 = k0.tanOut != null ? k0.tanOut
                : k0.tanIn  != null ? k0.tanIn
                : _crTanOut(_m0, p0, k0.pos, k1.pos);
       const m1 = k1.tanIn  != null ? k1.tanIn
                : k1.tanOut != null ? k1.tanOut
-               : _crTanIn(_m1, p0, k0.pos, k1.pos, p3);
+               : _crTanIn(_m1, p0, k0.pos, k1.pos);
       hermiteVec3(out.pos, k0.pos, m0, k1.pos, m1, t);
     }
 
@@ -2091,13 +2090,13 @@ class CameraTrack extends Track {
       lerpVec3(out.eye, k0.eye, k1.eye, t);
     } else {
       const p0 = seg > 0      ? this.keyframes[seg - 1].eye : k0.eye;
-      const p3 = seg + 2 < n ? this.keyframes[seg + 2].eye  : k1.eye;
+      seg + 2 < n ? this.keyframes[seg + 2].eye  : k1.eye;
       const m0 = k0.eyeTanOut != null ? k0.eyeTanOut
                : k0.eyeTanIn  != null ? k0.eyeTanIn
                : _crTanOut(_m0, p0, k0.eye, k1.eye);
       const m1 = k1.eyeTanIn  != null ? k1.eyeTanIn
                : k1.eyeTanOut != null ? k1.eyeTanOut
-               : _crTanIn(_m1, p0, k0.eye, k1.eye, p3);
+               : _crTanIn(_m1, p0, k0.eye, k1.eye);
       hermiteVec3(out.eye, k0.eye, m0, k1.eye, m1, t);
     }
 
@@ -2106,13 +2105,13 @@ class CameraTrack extends Track {
       out.center[0]=k0.center[0]; out.center[1]=k0.center[1]; out.center[2]=k0.center[2];
     } else if (this.centerInterp === 'hermite') {
       const c0 = seg > 0      ? this.keyframes[seg - 1].center : k0.center;
-      const c3 = seg + 2 < n ? this.keyframes[seg + 2].center  : k1.center;
+      seg + 2 < n ? this.keyframes[seg + 2].center  : k1.center;
       const m0 = k0.centerTanOut != null ? k0.centerTanOut
                : k0.centerTanIn  != null ? k0.centerTanIn
                : _crTanOut(_m0, c0, k0.center, k1.center);
       const m1 = k1.centerTanIn  != null ? k1.centerTanIn
                : k1.centerTanOut != null ? k1.centerTanOut
-               : _crTanIn(_m1, c0, k0.center, k1.center, c3);
+               : _crTanIn(_m1, c0, k0.center, k1.center);
       hermiteVec3(out.center, k0.center, m0, k1.center, m1, t);
     } else {
       lerpVec3(out.center, k0.center, k1.center, t);
@@ -2293,5 +2292,5 @@ function boxVisibility(planes, x0, y0, z0, x1, y1, z1) {
   return allIn ? VISIBLE : SEMIVISIBLE;
 }
 
-export { CameraTrack, EYE, INVISIBLE, MATRIX, MODEL, NDC, ORIGIN, PLANE_BOTTOM, PLANE_FAR, PLANE_LEFT, PLANE_NEAR, PLANE_RIGHT, PLANE_TOP, PoseTrack, SCREEN, SEMIVISIBLE, VISIBLE, WEBGL, WEBGPU, WORLD, _i, _j, _k, boxVisibility, distanceToPlane, frustumPlanes, hermiteVec3, i, j, k, lerpVec3, mapDirection, mapLocation, mat3Direction, mat3NormalFromMat4, mat4Bias, mat4Eye, mat4FromBasis, mat4FromScale, mat4FromTRS, mat4FromTranslation, mat4Frustum, mat4Invert, mat4Location, mat4MV, mat4Mul, mat4MulDir, mat4MulPoint, mat4Ortho, mat4PV, mat4Perspective, mat4Pick, mat4Reflect, mat4ToRotation, mat4ToScale, mat4ToTransform, mat4ToTranslation, mat4View, pixelRatio, pointVisibility, projBottom, projFar, projFov, projHfov, projIsOrtho, projLeft, projNear, projRight, projTop, qCopy, qDot, qFromAxisAngle, qFromLookDir, qFromMat4, qFromRotMat3x3, qMul, qNegate, qNlerp, qNormalize, qSet, qSlerp, qToMat4, quatToAxisAngle, sphereVisibility, transformToMat4 };
+export { CameraTrack, EYE, INVISIBLE, MATRIX, MODEL, NDC, ORIGIN, PLANE_BOTTOM, PLANE_FAR, PLANE_LEFT, PLANE_NEAR, PLANE_RIGHT, PLANE_TOP, PoseTrack, SCREEN, SEMIVISIBLE, VISIBLE, WEBGL, WEBGPU, WORLD, _i, _j, _k, boxVisibility, 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, qCopy, qDot, qFromAxisAngle, qFromLookDir, qFromMat4, qFromRotMat3x3, qMul, qNegate, qNlerp, qNormalize, qSet, qSlerp, qToMat4, quatToAxisAngle, sphereVisibility, transformToMat4 };
 //# sourceMappingURL=index.js.map