@vib3code/sdk 2.0.3-canary.91a95f3 → 2.0.3-canary.98b84da

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);
     }
 
@@ -126,10 +138,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,108 +276,169 @@ 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
-     * @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) {
-        // For efficiency, we expand the sandwich product directly
-        // rather than doing two rotor multiplications
-
+    rotate(v, target) {
         const x = v.x, y = v.y, z = v.z, w = v.w;
 
-        // Compute R v (rotor times vector)
-        // Vector in GA is: x*e1 + y*e2 + z*e3 + w*e4
-        // This produces a mixed multivector
-
-        // Then multiply by R† (reverse of rotor)
-        // Extract the vector part of the result
+        // Normalize for numerical stability (same as toMatrix)
+        const n = this.norm();
+        const invN = n > 1e-10 ? 1 / n : 1;
 
-        // Pre-compute some common terms
-        const s = this.s;
-        const xy = this.xy, xz = this.xz, yz = this.yz;
-        const xw = this.xw, yw = this.yw, zw = this.zw;
-        const xyzw = this.xyzw;
+        const s = this.s * invN;
+        const xy = this.xy * invN;
+        const xz = this.xz * invN;
+        const yz = this.yz * invN;
+        const xw = this.xw * invN;
+        const yw = this.yw * invN;
+        const zw = this.zw * invN;
+        const xyzw = this.xyzw * invN;
 
-        // Squared terms for the rotation formula
+        // Squared terms
         const s2 = s * s;
-        const xy2 = xy * xy, xz2 = xz * xz, yz2 = yz * yz;
-        const xw2 = xw * xw, yw2 = yw * yw, zw2 = zw * zw;
+        const xy2 = xy * xy;
+        const xz2 = xz * xz;
+        const yz2 = yz * yz;
+        const xw2 = xw * xw;
+        const yw2 = yw * yw;
+        const zw2 = zw * zw;
         const xyzw2 = xyzw * xyzw;
 
-        // The full rotation formula derived from R v R†
-        const newX =
-            x * (s2 + xy2 + xz2 - yz2 + xw2 - yw2 - zw2 - xyzw2) +
-            2 * y * (s * xy + xz * yz + xw * yw - s * xyzw * zw + xy * s - xyzw * zw) +
-            2 * z * (s * xz - xy * yz + xw * zw + xyzw * yw) +
-            2 * w * (s * xw - xy * yw - xz * zw - xyzw * yz);
-
-        // Simplified rotation using matrix form
-        // This is equivalent but clearer
-
-        // Actually, let's use the direct matrix multiplication approach
-        // which is more numerically stable
-
-        const m = this.toMatrix();
-        return new Vec4(
-            m[0] * x + m[4] * y + m[8] * z + m[12] * w,
-            m[1] * x + m[5] * y + m[9] * z + m[13] * w,
-            m[2] * x + m[6] * y + m[10] * z + m[14] * w,
-            m[3] * x + m[7] * y + m[11] * z + m[15] * w
-        );
+        // 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 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 xzxw = 2 * xz * xw;
+        const xzyw = 2 * xz * yw;
+        const xzzw = 2 * xz * zw;
+
+        const yzxw = 2 * yz * xw;
+        const yzyw = 2 * yz * yw;
+        const yzzw = 2 * yz * zw;
+
+        const xwyw = 2 * xw * yw;
+        const xwzw = 2 * xw * zw;
+        const ywzw = 2 * yw * zw;
+
+        const xyxyzw = 2 * xy * xyzw;
+        const xzxyzw = 2 * xz * xyzw;
+        const yzxyzw = 2 * yz * xyzw;
+        const xwxyzw = 2 * xw * xyzw;
+        const ywxyzw = 2 * yw * xyzw;
+        const zwxyzw = 2 * zw * xyzw;
+
+        // 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;
+            target.y = ry;
+            target.z = rz;
+            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;
@@ -441,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,