@vib3code/sdk 2.0.3-canary.45332e3 → 2.0.3-canary.4874bcf

package/src/math/Projection.js

@@ -36,16 +36,28 @@ export class Projection {
      *
      * @param {Vec4} v - 4D point
      * @param {number} d - Distance parameter (typically 1.5-5)
+     * @param {object} [options] - Projection options
+     * @param {Vec4} [target] - Optional target vector to write result to
      * @returns {Vec4} Projected point (w=0)
      */
-    static perspective(v, d = 2, options = {}) {
+    static perspective(v, d = 2, options = {}, target = null) {
         if (typeof d === 'object') {
             options = d;
             d = options.d ?? 2;
         }
-        const epsilon = options.epsilon ?? DEFAULT_EPSILON;
+
+        // Handle options overload or direct target argument
+        if (!target && options && options.target) {
+            target = options.target;
+        }
+
+        const epsilon = (options && options.epsilon) ?? DEFAULT_EPSILON;
         const denom = clampDenominator(d - v.w, epsilon);
         const scale = 1 / denom;
+
+        if (target) {
+            return target.set(v.x * scale, v.y * scale, v.z * scale, 0);
+        }
         return new Vec4(v.x * scale, v.y * scale, v.z * scale, 0);
     }
 
@@ -60,12 +72,23 @@ export class Projection {
      * The projection point is at (0, 0, 0, 1) - the "north pole"
      *
      * @param {Vec4} v - 4D point (ideally on unit hypersphere)
+     * @param {object|Vec4} [options] - Projection options or target vector
+     * @param {Vec4} [target] - Optional target vector to write result to
      * @returns {Vec4} Projected point (w=0)
      */
-    static stereographic(v, options = {}) {
-        const epsilon = options.epsilon ?? DEFAULT_EPSILON;
+    static stereographic(v, options = {}, target = null) {
+        if (options instanceof Vec4) {
+            target = options;
+            options = {};
+        }
+
+        const epsilon = (options && options.epsilon) ?? DEFAULT_EPSILON;
         const denom = clampDenominator(1 - v.w, epsilon);
         const scale = 1 / denom;
+
+        if (target) {
+            return target.set(v.x * scale, v.y * scale, v.z * scale, 0);
+        }
         return new Vec4(v.x * scale, v.y * scale, v.z * scale, 0);
     }
 
@@ -95,9 +118,13 @@ export class Projection {
      * Parallel projection - no perspective distortion.
      *
      * @param {Vec4} v - 4D point
+     * @param {Vec4} [target] - Optional target vector to write result to
      * @returns {Vec4} Projected point (w=0)
      */
-    static orthographic(v) {
+    static orthographic(v, target = null) {
+        if (target) {
+            return target.set(v.x, v.y, v.z, 0);
+        }
         return new Vec4(v.x, v.y, v.z, 0);
     }
 
@@ -126,10 +153,33 @@ export class Projection {
      * Project array of Vec4s using perspective projection
      * @param {Vec4[]} vectors
      * @param {number} d
+     * @param {object} [options]
+     * @param {Vec4[]} [target] - Optional target array to write results to
      * @returns {Vec4[]}
      */
-    static perspectiveArray(vectors, d = 2, options = {}) {
-        return vectors.map(v => Projection.perspective(v, d, options));
+    static perspectiveArray(vectors, d = 2, options = {}, target = null) {
+        // Handle options overload for 'd'
+        if (typeof d === 'object') {
+             options = d;
+             d = options.d ?? 2;
+        }
+
+        if (!target) {
+            return vectors.map(v => Projection.perspective(v, d, options));
+        }
+
+        const count = vectors.length;
+        // Iterate and reuse
+        for (let i = 0; i < count; i++) {
+            const out = target[i];
+            if (out) {
+                Projection.perspective(vectors[i], d, options, out);
+            } else {
+                target[i] = Projection.perspective(vectors[i], d, options);
+            }
+        }
+
+        return target;
     }
 
     /**

package/src/math/Rotor4D.js

@@ -276,61 +276,70 @@ export class Rotor4D {
      * The result applies this rotation, then r's rotation
      *
      * @param {Rotor4D} r - Right operand
+     * @param {Rotor4D} [target=null] - Optional target rotor to write result into
      * @returns {Rotor4D} Composed rotor
      */
-    multiply(r) {
+    multiply(r, target = null) {
         // Full geometric product of two rotors in 4D
         // This is derived from the geometric algebra product rules
 
         const a = this;
         const b = r;
 
-        return new Rotor4D(
-            // Scalar component
-            a.s * b.s - a.xy * b.xy - a.xz * b.xz - a.yz * b.yz -
-            a.xw * b.xw - a.yw * b.yw - a.zw * b.zw - a.xyzw * b.xyzw,
+        // Compute all components first to ensure safety if target aliases a or b
+        const s = a.s * b.s - a.xy * b.xy - a.xz * b.xz - a.yz * b.yz -
+            a.xw * b.xw - a.yw * b.yw - a.zw * b.zw - a.xyzw * b.xyzw;
 
-            // XY bivector
-            a.s * b.xy + a.xy * b.s + a.xz * b.yz - a.yz * b.xz +
-            a.xw * b.yw - a.yw * b.xw - a.zw * b.xyzw - a.xyzw * b.zw,
+        const xy = a.s * b.xy + a.xy * b.s + a.xz * b.yz - a.yz * b.xz +
+            a.xw * b.yw - a.yw * b.xw - a.zw * b.xyzw - a.xyzw * b.zw;
 
-            // XZ bivector
-            a.s * b.xz + a.xz * b.s - a.xy * b.yz + a.yz * b.xy +
-            a.xw * b.zw + a.yw * b.xyzw - a.zw * b.xw + a.xyzw * b.yw,
+        const xz = a.s * b.xz + a.xz * b.s - a.xy * b.yz + a.yz * b.xy +
+            a.xw * b.zw + a.yw * b.xyzw - a.zw * b.xw + a.xyzw * b.yw;
 
-            // YZ bivector
-            a.s * b.yz + a.yz * b.s + a.xy * b.xz - a.xz * b.xy -
-            a.xw * b.xyzw + a.yw * b.zw - a.zw * b.yw - a.xyzw * b.xw,
+        const yz = a.s * b.yz + a.yz * b.s + a.xy * b.xz - a.xz * b.xy -
+            a.xw * b.xyzw + a.yw * b.zw - a.zw * b.yw - a.xyzw * b.xw;
 
-            // XW bivector
-            a.s * b.xw + a.xw * b.s - a.xy * b.yw + a.xz * b.zw +
-            a.yz * b.xyzw + a.yw * b.xy - a.zw * b.xz + a.xyzw * b.yz,
+        const xw = a.s * b.xw + a.xw * b.s - a.xy * b.yw + a.xz * b.zw +
+            a.yz * b.xyzw + a.yw * b.xy - a.zw * b.xz + a.xyzw * b.yz;
 
-            // YW bivector
-            a.s * b.yw + a.yw * b.s + a.xy * b.xw - a.xz * b.xyzw -
-            a.yz * b.zw - a.xw * b.xy + a.zw * b.yz - a.xyzw * b.xz,
+        const yw = a.s * b.yw + a.yw * b.s + a.xy * b.xw - a.xz * b.xyzw -
+            a.yz * b.zw - a.xw * b.xy + a.zw * b.yz - a.xyzw * b.xz;
 
-            // ZW bivector
-            a.s * b.zw + a.zw * b.s + a.xy * b.xyzw + a.xz * b.xw +
-            a.yz * b.yw - a.xw * b.xz - a.yw * b.yz + a.xyzw * b.xy,
+        const zw = a.s * b.zw + a.zw * b.s + a.xy * b.xyzw + a.xz * b.xw +
+            a.yz * b.yw - a.xw * b.xz - a.yw * b.yz + a.xyzw * b.xy;
 
-            // Pseudoscalar XYZW
-            a.s * b.xyzw + a.xyzw * b.s + a.xy * b.zw - a.xz * b.yw +
-            a.yz * b.xw + a.xw * b.yz - a.yw * b.xz + a.zw * b.xy
-        );
+        const xyzw = a.s * b.xyzw + a.xyzw * b.s + a.xy * b.zw - a.xz * b.yw +
+            a.yz * b.xw + a.xw * b.yz - a.yw * b.xz + a.zw * b.xy;
+
+        if (target) {
+            target.s = s;
+            target.xy = xy;
+            target.xz = xz;
+            target.yz = yz;
+            target.xw = xw;
+            target.yw = yw;
+            target.zw = zw;
+            target.xyzw = xyzw;
+            return target;
+        }
+
+        return new Rotor4D(s, xy, xz, yz, xw, yw, zw, xyzw);
     }
 
     /**
      * Rotate a 4D vector using sandwich product: v' = R v R†
      *
+     * Matrix math is inlined to avoid allocating a temporary Float32Array(16).
+     * Pass an optional target Vec4 to eliminate all allocations.
+     *
      * @param {Vec4} v - Vector to rotate
-     * @param {Vec4} [target] - Optional target vector to write result to
-     * @returns {Vec4} Rotated vector
+     * @param {Vec4} [target] - Optional pre-allocated Vec4 to write result into
+     * @returns {Vec4} Rotated vector (target if provided, otherwise new Vec4)
      */
     rotate(v, target) {
-        // Direct matrix multiplication without allocation
+        const x = v.x, y = v.y, z = v.z, w = v.w;
 
-        // Normalize components for stability (same as toMatrix)
+        // Normalize for numerical stability (same as toMatrix)
         const n = this.norm();
         const invN = n > 1e-10 ? 1 / n : 1;
 
@@ -343,7 +352,7 @@ export class Rotor4D {
         const zw = this.zw * invN;
         const xyzw = this.xyzw * invN;
 
-        // Pre-compute products
+        // Squared terms
         const s2 = s * s;
         const xy2 = xy * xy;
         const xz2 = xz * xz;
@@ -353,22 +362,20 @@ export class Rotor4D {
         const zw2 = zw * zw;
         const xyzw2 = xyzw * xyzw;
 
-        // Cross terms
+        // Cross terms (pre-multiplied by 2)
         const sxy = 2 * s * xy;
         const sxz = 2 * s * xz;
         const syz = 2 * s * yz;
         const sxw = 2 * s * xw;
         const syw = 2 * s * yw;
         const szw = 2 * s * zw;
-        // const sxyzw = 2 * s * xyzw; // Unused in rotation matrix
 
-        const xyxz = 2 * xy * xz;
+        const xzyz = 2 * xz * yz;
         const xyyz = 2 * xy * yz;
+        const xyxz = 2 * xy * xz;
         const xyxw = 2 * xy * xw;
         const xyyw = 2 * xy * yw;
-        // const xyzw_c = 2 * xy * zw; // Unused in rotation matrix
 
-        const xzyz = 2 * xz * yz;
         const xzxw = 2 * xz * xw;
         const xzyw = 2 * xz * yw;
         const xzzw = 2 * xz * zw;
@@ -388,40 +395,33 @@ export class Rotor4D {
         const ywxyzw = 2 * yw * xyzw;
         const zwxyzw = 2 * zw * xyzw;
 
-        // Matrix elements
-        // Col 0
-        const m00 = s2 - xy2 - xz2 + yz2 - xw2 + yw2 + zw2 - xyzw2;
-        const m01 = sxy + xzyz + xwyw - zwxyzw;
-        const m02 = sxz - xyyz + xwzw + ywxyzw;
-        const m03 = sxw - xyyw - xzzw - yzxyzw;
-
-        // Col 1
-        const m10 = -sxy + xzyz + xwyw + zwxyzw;
-        const m11 = s2 - xy2 + xz2 - yz2 + xw2 - yw2 + zw2 - xyzw2;
-        const m12 = syz + xyxz + ywzw - xwxyzw;
-        const m13 = syw + xyxw - yzzw + xzxyzw;
-
-        // Col 2
-        const m20 = -sxz - xyyz + xwzw - ywxyzw;
-        const m21 = -syz + xyxz + ywzw + xwxyzw;
-        const m22 = s2 + xy2 - xz2 - yz2 + xw2 + yw2 - zw2 - xyzw2;
-        const m23 = szw + xzxw + yzyw - xyxyzw;
-
-        // Col 3
-        const m30 = -sxw - xyyw - xzzw + yzxyzw;
-        const m31 = -syw + xyxw - yzzw - xzxyzw;
-        const m32 = -szw + xzxw + yzyw + xyxyzw;
-        const m33 = s2 + xy2 + xz2 + yz2 - xw2 - yw2 - zw2 - xyzw2;
-
-        const x = v.x;
-        const y = v.y;
-        const z = v.z;
-        const w = v.w;
-
-        const rx = m00 * x + m10 * y + m20 * z + m30 * w;
-        const ry = m01 * x + m11 * y + m21 * z + m31 * w;
-        const rz = m02 * x + m12 * y + m22 * z + m32 * w;
-        const rw = m03 * x + m13 * y + m23 * z + m33 * w;
+        // Column-major 4x4 rotation matrix entries (inlined from toMatrix)
+        // Column 0
+        const m0  = s2 - xy2 - xz2 + yz2 - xw2 + yw2 + zw2 - xyzw2;
+        const m1  = sxy + xzyz + xwyw - zwxyzw;
+        const m2  = sxz - xyyz + xwzw + ywxyzw;
+        const m3  = sxw - xyyw - xzzw - yzxyzw;
+        // Column 1
+        const m4  = -sxy + xzyz + xwyw + zwxyzw;
+        const m5  = s2 - xy2 + xz2 - yz2 + xw2 - yw2 + zw2 - xyzw2;
+        const m6  = syz + xyxz + ywzw - xwxyzw;
+        const m7  = syw + xyxw - yzzw + xzxyzw;
+        // Column 2
+        const m8  = -sxz - xyyz + xwzw - ywxyzw;
+        const m9  = -syz + xyxz + ywzw + xwxyzw;
+        const m10 = s2 + xy2 - xz2 - yz2 + xw2 + yw2 - zw2 - xyzw2;
+        const m11 = szw + xzxw + yzyw - xyxyzw;
+        // Column 3
+        const m12 = -sxw - xyyw - xzzw + yzxyzw;
+        const m13 = -syw + xyxw - yzzw - xzxyzw;
+        const m14 = -szw + xzxw + yzyw + xyxyzw;
+        const m15 = s2 + xy2 + xz2 + yz2 - xw2 - yw2 - zw2 - xyzw2;
+
+        // Matrix-vector multiply
+        const rx = m0 * x + m4 * y + m8  * z + m12 * w;
+        const ry = m1 * x + m5 * y + m9  * z + m13 * w;
+        const rz = m2 * x + m6 * y + m10 * z + m14 * w;
+        const rw = m3 * x + m7 * y + m11 * z + m15 * w;
 
         if (target) {
             target.x = rx;
@@ -430,15 +430,15 @@ export class Rotor4D {
             target.w = rw;
             return target;
         }
-
         return new Vec4(rx, ry, rz, rw);
     }
 
     /**
      * Convert rotor to 4x4 rotation matrix (column-major for WebGL)
+     * @param {Float32Array|Array} [target] - Optional target array to write into
      * @returns {Float32Array} 16-element array in column-major order
      */
-    toMatrix() {
+    toMatrix(target = null) {
         // Normalize first for numerical stability
         const n = this.norm();
         const invN = n > 1e-10 ? 1 / n : 1;
@@ -502,6 +502,35 @@ export class Rotor4D {
         // Formula derived from sandwich product R v R†
         // Diagonal: s² minus bivectors containing that axis, plus others
         // Off-diagonal: 2*s*bivector terms for single-plane contributions
+
+        if (target) {
+            // Column 0 (transformed X axis)
+            target[0] = s2 - xy2 - xz2 + yz2 - xw2 + yw2 + zw2 - xyzw2;
+            target[1] = sxy + xzyz + xwyw - zwxyzw;
+            target[2] = sxz - xyyz + xwzw + ywxyzw;
+            target[3] = sxw - xyyw - xzzw - yzxyzw;
+
+            // Column 1 (transformed Y axis)
+            target[4] = -sxy + xzyz + xwyw + zwxyzw;
+            target[5] = s2 - xy2 + xz2 - yz2 + xw2 - yw2 + zw2 - xyzw2;
+            target[6] = syz + xyxz + ywzw - xwxyzw;
+            target[7] = syw + xyxw - yzzw + xzxyzw;
+
+            // Column 2 (transformed Z axis)
+            target[8] = -sxz - xyyz + xwzw - ywxyzw;
+            target[9] = -syz + xyxz + ywzw + xwxyzw;
+            target[10] = s2 + xy2 - xz2 - yz2 + xw2 + yw2 - zw2 - xyzw2;
+            target[11] = szw + xzxw + yzyw - xyxyzw;
+
+            // Column 3 (transformed W axis)
+            target[12] = -sxw - xyyw - xzzw + yzxyzw;
+            target[13] = -syw + xyxw - yzzw - xzxyzw;
+            target[14] = -szw + xzxw + yzyw + xyxyzw;
+            target[15] = s2 + xy2 + xz2 + yz2 - xw2 - yw2 - zw2 - xyzw2;
+
+            return target;
+        }
+
         return new Float32Array([
             // Column 0 (transformed X axis)
             s2 - xy2 - xz2 + yz2 - xw2 + yw2 + zw2 - xyzw2,