@woosh/meep-engine 2.164.0 → 2.165.0

package/src/core/geom/3d/topology/struct/binary/query/bt_mesh_face_find_path_polyanya.js

@@ -1,8 +1,13 @@
 import { Uint32Heap4 } from "../../../../../../collection/heap/Uint32Heap4.js";
-import { line2_segment_intersection_fraction_2d } from "../../../../../2d/line/line2_segment_intersection_fraction_2d.js";
+import {
+    line2_segment_intersection_fraction_2d
+} from "../../../../../2d/line/line2_segment_intersection_fraction_2d.js";
 import { tri2_signed_area } from "../../../../../2d/triangle/tri2_signed_area.js";
-import { NULL_POINTER } from "../BinaryTopology.js";
+import {
+    line3_compute_point_segment_point_distance_unfolded
+} from "../../../../../3d/line/line3_compute_point_segment_point_distance_unfolded.js";
 import { v2_distance } from "../../../../../vec2/v2_distance.js";
+import { NULL_POINTER } from "../BinaryTopology.js";
 
 /*
  * Polyanya: exact any-angle shortest path on a triangle navmesh.
@@ -79,30 +84,6 @@ function touch_distance(rx, ry, i0x, i0y, i1x, i1y, gx, gy) {
     );
 }
 
-/**
- * Shortest root->interval->goal measured with straight 3D chords (admissible heuristic: it is the
- * 3D-space unfolding of the two segments across the interval's line, always <= the on-surface geodesic).
- */
-function touch_distance_3d(rx, ry, rz, i0x, i0y, i0z, i1x, i1y, i1z, gx, gy, gz) {
-    const dx = i1x - i0x, dy = i1y - i0y, dz = i1z - i0z;
-    const dlen2 = dx * dx + dy * dy + dz * dz;
-    const viaI0 = Math.hypot(rx - i0x, ry - i0y, rz - i0z) + Math.hypot(gx - i0x, gy - i0y, gz - i0z);
-    if (dlen2 < 1e-18) return viaI0;
-
-    const dlen = Math.sqrt(dlen2), ux = dx / dlen, uy = dy / dlen, uz = dz / dlen;
-    const rt = (rx - i0x) * ux + (ry - i0y) * uy + (rz - i0z) * uz;
-    const rperp = Math.hypot(rx - i0x - rt * ux, ry - i0y - rt * uy, rz - i0z - rt * uz);
-    const gt = (gx - i0x) * ux + (gy - i0y) * uy + (gz - i0z) * uz;
-    const gperp = Math.hypot(gx - i0x - gt * ux, gy - i0y - gt * uy, gz - i0z - gt * uz);
-
-    const denom = rperp + gperp;
-    const xs = denom < 1e-12 ? rt : rt + (gt - rt) * rperp / denom; // edge crossing of the unfolded line
-    if (xs >= 0 && xs <= dlen) return Math.hypot(gt - rt, denom);
-
-    const viaI1 = Math.hypot(rx - i1x, ry - i1y, rz - i1z) + Math.hypot(gx - i1x, gy - i1y, gz - i1z);
-    return Math.min(viaI0, viaI1);
-}
-
 // ---- mesh helpers ----------------------------------------------------------------------------------
 
 const _va = new Float64Array(3), _vb = new Float64Array(3), _vc = new Float64Array(3);
@@ -660,7 +641,7 @@ function emit_node(topology, neighbour, Pv, Qv, Px, Py, Qx, Qy, rx, ry, rootVid,
     else { topology.vertex_read_coordinate(_qa, 0, rootVid); r3x = _qa[0]; r3y = _qa[1]; r3z = _qa[2]; }
     topology.vertex_read_coordinate(_va, 0, Pv);
     topology.vertex_read_coordinate(_vb, 0, Qv);
-    const h = touch_distance_3d(
+    const h = line3_compute_point_segment_point_distance_unfolded(
         r3x, r3y, r3z,
         _va[0] + t0 * (_vb[0] - _va[0]), _va[1] + t0 * (_vb[1] - _va[1]), _va[2] + t0 * (_vb[2] - _va[2]),
         _va[0] + t1 * (_vb[0] - _va[0]), _va[1] + t1 * (_vb[1] - _va[1]), _va[2] + t1 * (_vb[2] - _va[2]),

package/src/core/geom/vec3/v3_cotangent.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Cotangent of the angle between two 3D vectors `a` and `b`.
+ *
+ *     cot(θ) = cos(θ) / sin(θ) = (a · b) / |a × b|
+ *
+ * This is the building block of the cotangent-weight Laplacian and the
+ * discrete conformal energy: to weight the mesh edge opposite a triangle
+ * corner, pass the two edge vectors emanating from that corner.
+ *
+ * Precondition: `a` and `b` are non-degenerate and non-parallel (a real
+ * triangle corner). On a degenerate corner `|a × b|` is 0 and the result is
+ * non-finite — callers exclude degenerate faces upstream rather than guarding
+ * here.
+ *
+ * @param {number} ax @param {number} ay @param {number} az
+ * @param {number} bx @param {number} by @param {number} bz
+ * @returns {number}
+ */
+export function v3_cotangent(ax: number, ay: number, az: number, bx: number, by: number, bz: number): number;
+//# sourceMappingURL=v3_cotangent.d.ts.map

package/src/core/geom/vec3/v3_cotangent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"v3_cotangent.d.ts","sourceRoot":"","sources":["../../../../../src/core/geom/vec3/v3_cotangent.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;GAiBG;AACH,iCAJW,MAAM,MAAa,MAAM,MAAa,MAAM,MAC5C,MAAM,MAAa,MAAM,MAAa,MAAM,GAC1C,MAAM,CAUlB"}

package/src/core/geom/vec3/v3_cotangent.js

@@ -0,0 +1,29 @@
+import { v3_dot } from "./v3_dot.js";
+
+/**
+ * Cotangent of the angle between two 3D vectors `a` and `b`.
+ *
+ *     cot(θ) = cos(θ) / sin(θ) = (a · b) / |a × b|
+ *
+ * This is the building block of the cotangent-weight Laplacian and the
+ * discrete conformal energy: to weight the mesh edge opposite a triangle
+ * corner, pass the two edge vectors emanating from that corner.
+ *
+ * Precondition: `a` and `b` are non-degenerate and non-parallel (a real
+ * triangle corner). On a degenerate corner `|a × b|` is 0 and the result is
+ * non-finite — callers exclude degenerate faces upstream rather than guarding
+ * here.
+ *
+ * @param {number} ax @param {number} ay @param {number} az
+ * @param {number} bx @param {number} by @param {number} bz
+ * @returns {number}
+ */
+export function v3_cotangent(ax, ay, az, bx, by, bz) {
+    const cx = ay * bz - az * by;
+    const cy = az * bx - ax * bz;
+    const cz = ax * by - ay * bx;
+
+    const sin_length = Math.sqrt(cx * cx + cy * cy + cz * cz);
+
+    return v3_dot(ax, ay, az, bx, by, bz) / sin_length;
+}

package/src/core/geom/vec3/v3_matrix3_multiply.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Transform a 3d vector by a 3x3 (column-major) matrix. `output = mat3 * input`.
+ *
+ * Unlike {@link v3_matrix3_rotate} this does NOT renormalize the result, so it is
+ * suitable for transforming positions / arbitrary vectors (not just directions).
+ * Companion to {@link v3_matrix4_multiply}. Reads the input components up front, so
+ * `output` may alias `input`. Allocation-free.
+ *
+ * @param {number[]|Float32Array|Float64Array} output
+ * @param {number} output_offset
+ * @param {number[]|Float32Array|Float64Array} input
+ * @param {number} input_offset
+ * @param {number[]|Float32Array|Float64Array} mat3 column-major 3x3 matrix
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function v3_matrix3_multiply(output: number[] | Float32Array | Float64Array, output_offset: number, input: number[] | Float32Array | Float64Array, input_offset: number, mat3: number[] | Float32Array | Float64Array): void;
+//# sourceMappingURL=v3_matrix3_multiply.d.ts.map

package/src/core/geom/vec3/v3_matrix3_multiply.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"v3_matrix3_multiply.d.ts","sourceRoot":"","sources":["../../../../../src/core/geom/vec3/v3_matrix3_multiply.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,4CATW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,iBAClC,MAAM,SACN,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,gBAClC,MAAM,QACN,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,QAiB5C"}

package/src/core/geom/vec3/v3_matrix3_multiply.js

@@ -0,0 +1,30 @@
+/**
+ * Transform a 3d vector by a 3x3 (column-major) matrix. `output = mat3 * input`.
+ *
+ * Unlike {@link v3_matrix3_rotate} this does NOT renormalize the result, so it is
+ * suitable for transforming positions / arbitrary vectors (not just directions).
+ * Companion to {@link v3_matrix4_multiply}. Reads the input components up front, so
+ * `output` may alias `input`. Allocation-free.
+ *
+ * @param {number[]|Float32Array|Float64Array} output
+ * @param {number} output_offset
+ * @param {number[]|Float32Array|Float64Array} input
+ * @param {number} input_offset
+ * @param {number[]|Float32Array|Float64Array} mat3 column-major 3x3 matrix
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function v3_matrix3_multiply(
+    output, output_offset,
+    input, input_offset,
+    mat3
+) {
+    const x = input[input_offset];
+    const y = input[input_offset + 1];
+    const z = input[input_offset + 2];
+
+    output[output_offset] = mat3[0] * x + mat3[3] * y + mat3[6] * z;
+    output[output_offset + 1] = mat3[1] * x + mat3[4] * y + mat3[7] * z;
+    output[output_offset + 2] = mat3[2] * x + mat3[5] * y + mat3[8] * z;
+}

package/src/core/geom/vec3/v3_multiply.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Component-wise vector product `a * b`, written to `result[result_offset .. result_offset+2]`.
+ *
+ * Scalar-argument, out-parameter form: lets callers multiply two vectors straight
+ * into a scratch buffer (or in place) without allocating a temporary. Allocation-free.
+ *
+ * @param {number[]|Float32Array|Float64Array} result destination
+ * @param {number} result_offset offset into `result`
+ * @param {number} ax @param {number} ay @param {number} az  first factor
+ * @param {number} bx @param {number} by @param {number} bz  second factor
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function v3_multiply(result: number[] | Float32Array | Float64Array, result_offset: number, ax: number, ay: number, az: number, bx: number, by: number, bz: number): void;
+//# sourceMappingURL=v3_multiply.d.ts.map

package/src/core/geom/vec3/v3_multiply.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"v3_multiply.d.ts","sourceRoot":"","sources":["../../../../../src/core/geom/vec3/v3_multiply.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,oCARW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,iBAClC,MAAM,MACN,MAAM,MAAa,MAAM,MAAa,MAAM,MAC5C,MAAM,MAAa,MAAM,MAAa,MAAM,QAStD"}

package/src/core/geom/vec3/v3_multiply.js

@@ -0,0 +1,19 @@
+/**
+ * Component-wise vector product `a * b`, written to `result[result_offset .. result_offset+2]`.
+ *
+ * Scalar-argument, out-parameter form: lets callers multiply two vectors straight
+ * into a scratch buffer (or in place) without allocating a temporary. Allocation-free.
+ *
+ * @param {number[]|Float32Array|Float64Array} result destination
+ * @param {number} result_offset offset into `result`
+ * @param {number} ax @param {number} ay @param {number} az  first factor
+ * @param {number} bx @param {number} by @param {number} bz  second factor
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function v3_multiply(result, result_offset, ax, ay, az, bx, by, bz) {
+    result[result_offset] = ax * bx;
+    result[result_offset + 1] = ay * by;
+    result[result_offset + 2] = az * bz;
+}

package/src/core/math/linalg/cg/cg_solve.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Conjugate Gradient solve of `A x = b` for a symmetric positive-definite
+ * operator `A`, supplied as a matrix-free callback. This is the generic core
+ * shared by the cotangent-Laplacian harmonic solve and the LSCM normal
+ * equations (via {@link cg_solve_normal_equations}).
+ *
+ * `x` is both the initial guess and the output (warm-start it with a prior
+ * solution to cut iterations; zero-fill for a cold start). Convergence is the
+ * relative residual: the solve stops when `‖r‖ <= tolerance · ‖r0‖`.
+ *
+ * Determinism: reductions run in fixed index order with no wall-clock exit, so
+ * the result is bit-reproducible for a given `apply_A`.
+ *
+ * @param {Float64Array} x length n; initial guess in, solution out
+ * @param {(out: Float64Array, vec: Float64Array) => void} apply_A computes out = A·vec
+ *   over the first n entries
+ * @param {Float64Array} b right-hand side, length n
+ * @param {number} n system size
+ * @param {number} max_iterations hard cap on iterations
+ * @param {number} tolerance relative residual target in [0, 1]; 0 runs to max_iterations
+ * @returns {number} iterations performed
+ */
+export function cg_solve(x: Float64Array, apply_A: (out: Float64Array, vec: Float64Array) => void, b: Float64Array, n: number, max_iterations: number, tolerance: number): number;
+//# sourceMappingURL=cg_solve.d.ts.map

package/src/core/math/linalg/cg/cg_solve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cg_solve.d.ts","sourceRoot":"","sources":["../../../../../../src/core/math/linalg/cg/cg_solve.js"],"names":[],"mappings":"AAwBA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,4BATW,YAAY,iBACN,YAAY,OAAO,YAAY,KAAK,IAAI,KAE9C,YAAY,KACZ,MAAM,kBACN,MAAM,aACN,MAAM,GACJ,MAAM,CA6DlB"}

package/src/core/math/linalg/cg/cg_solve.js

@@ -0,0 +1,106 @@
+/**
+ * Module-static scratch vectors, grown on demand and reused across calls.
+ * The solver is therefore NOT re-entrant: `apply_A` must not itself call
+ * `cg_solve` (it may call lower-level matvecs freely).
+ */
+let _r = new Float64Array(0);
+let _p = new Float64Array(0);
+let _Ap = new Float64Array(0);
+
+/**
+ * Grow the module-static scratch vectors (`_r`, `_p`, `_Ap`) so each holds at
+ * least `n` entries. A no-op once they are large enough; existing contents are
+ * not preserved, since each `cg_solve` re-initializes them.
+ *
+ * @param {number} n required minimum length
+ */
+function ensure_scratch(n) {
+    if (_r.length < n) {
+        _r = new Float64Array(n);
+        _p = new Float64Array(n);
+        _Ap = new Float64Array(n);
+    }
+}
+
+/**
+ * Conjugate Gradient solve of `A x = b` for a symmetric positive-definite
+ * operator `A`, supplied as a matrix-free callback. This is the generic core
+ * shared by the cotangent-Laplacian harmonic solve and the LSCM normal
+ * equations (via {@link cg_solve_normal_equations}).
+ *
+ * `x` is both the initial guess and the output (warm-start it with a prior
+ * solution to cut iterations; zero-fill for a cold start). Convergence is the
+ * relative residual: the solve stops when `‖r‖ <= tolerance · ‖r0‖`.
+ *
+ * Determinism: reductions run in fixed index order with no wall-clock exit, so
+ * the result is bit-reproducible for a given `apply_A`.
+ *
+ * @param {Float64Array} x length n; initial guess in, solution out
+ * @param {(out: Float64Array, vec: Float64Array) => void} apply_A computes out = A·vec
+ *   over the first n entries
+ * @param {Float64Array} b right-hand side, length n
+ * @param {number} n system size
+ * @param {number} max_iterations hard cap on iterations
+ * @param {number} tolerance relative residual target in [0, 1]; 0 runs to max_iterations
+ * @returns {number} iterations performed
+ */
+export function cg_solve(x, apply_A, b, n, max_iterations, tolerance) {
+    ensure_scratch(n);
+
+    const r = _r;
+    const p = _p;
+    const Ap = _Ap;
+
+    apply_A(Ap, x);
+
+    let rs = 0;
+    for (let i = 0; i < n; i++) {
+        const ri = b[i] - Ap[i];
+        r[i] = ri;
+        p[i] = ri;
+        rs += ri * ri;
+    }
+
+    if (rs === 0) {
+        return 0;
+    }
+
+    const rs0 = rs;
+    const target = tolerance * tolerance * rs0;
+
+    for (let iter = 0; iter < max_iterations; iter++) {
+        apply_A(Ap, p);
+
+        let p_dot_Ap = 0;
+        for (let i = 0; i < n; i++) {
+            p_dot_Ap += p[i] * Ap[i];
+        }
+
+        if (p_dot_Ap === 0) {
+            return iter;
+        }
+
+        const alpha = rs / p_dot_Ap;
+
+        let rs_new = 0;
+        for (let i = 0; i < n; i++) {
+            x[i] += alpha * p[i];
+            const ri = r[i] - alpha * Ap[i];
+            r[i] = ri;
+            rs_new += ri * ri;
+        }
+
+        if (rs_new <= target) {
+            return iter + 1;
+        }
+
+        const beta = rs_new / rs;
+        for (let i = 0; i < n; i++) {
+            p[i] = r[i] + beta * p[i];
+        }
+
+        rs = rs_new;
+    }
+
+    return max_iterations;
+}

package/src/core/math/linalg/cg/cg_solve_normal_equations.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Least-squares solve of the overdetermined (or square) system `A x ≈ b` via
+ * the normal equations `AᵀA x = Aᵀb`, using {@link cg_solve} on the
+ * matrix-free operator `x ↦ Aᵀ(A x)`. `AᵀA` is symmetric positive
+ * semi-definite, and positive-definite when `A` has full column rank — which is
+ * the case for the LSCM conformal system once two vertices are pinned.
+ *
+ * The normal-equations operator squares the condition number of `A`, so this is
+ * appropriate for the well-conditioned, modest-size per-chart systems of UV
+ * parameterization; it is not a general-purpose least-squares routine for
+ * ill-conditioned problems.
+ *
+ * @param {Float64Array} x length A.cols; initial guess in, solution out
+ * @param {import("../sparse/SparseMatrixCSR.js").SparseMatrixCSR} A
+ * @param {Float64Array} b right-hand side, length A.rows
+ * @param {number} max_iterations
+ * @param {number} tolerance relative residual target for the normal equations
+ * @returns {number} iterations performed
+ */
+export function cg_solve_normal_equations(x: Float64Array, A: import("../sparse/SparseMatrixCSR.js").SparseMatrixCSR, b: Float64Array, max_iterations: number, tolerance: number): number;
+//# sourceMappingURL=cg_solve_normal_equations.d.ts.map

package/src/core/math/linalg/cg/cg_solve_normal_equations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cg_solve_normal_equations.d.ts","sourceRoot":"","sources":["../../../../../../src/core/math/linalg/cg/cg_solve_normal_equations.js"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;;;;;GAkBG;AACH,6CAPW,YAAY,KACZ,OAAO,8BAA8B,EAAE,eAAe,KACtD,YAAY,kBACZ,MAAM,aACN,MAAM,GACJ,MAAM,CA8BlB"}

package/src/core/math/linalg/cg/cg_solve_normal_equations.js

@@ -0,0 +1,59 @@
+import { spm_matvec } from "../sparse/spm_matvec.js";
+import { spm_matvec_transpose } from "../sparse/spm_matvec_transpose.js";
+import { cg_solve } from "./cg_solve.js";
+
+/**
+ * Module-static scratch for the intermediate `A x` (length rows) reused across
+ * calls. Like {@link cg_solve}, this is not re-entrant.
+ */
+let _Ax = new Float64Array(0);
+let _Atb = new Float64Array(0);
+
+/**
+ * Least-squares solve of the overdetermined (or square) system `A x ≈ b` via
+ * the normal equations `AᵀA x = Aᵀb`, using {@link cg_solve} on the
+ * matrix-free operator `x ↦ Aᵀ(A x)`. `AᵀA` is symmetric positive
+ * semi-definite, and positive-definite when `A` has full column rank — which is
+ * the case for the LSCM conformal system once two vertices are pinned.
+ *
+ * The normal-equations operator squares the condition number of `A`, so this is
+ * appropriate for the well-conditioned, modest-size per-chart systems of UV
+ * parameterization; it is not a general-purpose least-squares routine for
+ * ill-conditioned problems.
+ *
+ * @param {Float64Array} x length A.cols; initial guess in, solution out
+ * @param {import("../sparse/SparseMatrixCSR.js").SparseMatrixCSR} A
+ * @param {Float64Array} b right-hand side, length A.rows
+ * @param {number} max_iterations
+ * @param {number} tolerance relative residual target for the normal equations
+ * @returns {number} iterations performed
+ */
+export function cg_solve_normal_equations(x, A, b, max_iterations, tolerance) {
+    const rows = A.rows;
+    const cols = A.cols;
+
+    if (_Ax.length < rows) {
+        _Ax = new Float64Array(rows);
+    }
+    if (_Atb.length < cols) {
+        _Atb = new Float64Array(cols);
+    }
+
+    const Ax = _Ax;
+
+    // Right-hand side of the normal equations.
+    spm_matvec_transpose(_Atb, A, b);
+
+    /**
+     * Matrix-free normal-equations operator: `out = Aᵀ(A·vec)`.
+     *
+     * @param {Float64Array} out length A.cols; overwritten with AᵀA·vec
+     * @param {Float64Array} vec length A.cols
+     */
+    const apply_normal = (out, vec) => {
+        spm_matvec(Ax, A, vec);
+        spm_matvec_transpose(out, A, Ax);
+    };
+
+    return cg_solve(x, apply_normal, _Atb, cols, max_iterations, tolerance);
+}

package/src/core/math/linalg/eigen/matrix_symmetric_3x3_eigen.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Eigendecomposition of a symmetric 3x3 matrix via cyclic Jacobi rotations.
+ *
+ * Only the upper triangle of `m` is read (the matrix is assumed symmetric);
+ * the input is not modified. Eigenpairs are emitted sorted by **ascending
+ * eigenvalue**, so index 0 is the smallest — convenient for proxy-plane fits,
+ * where the plane normal is the eigenvector of the smallest variance.
+ *
+ * Eigenvector sign is arbitrary (an eigenvector and its negation are both
+ * valid); callers that need a consistent orientation must fix the sign
+ * themselves.
+ *
+ * @param {Float64Array|Float32Array|number[]} out_values length >= 3, eigenvalues ascending
+ * @param {Float64Array|Float32Array|number[]} out_vectors length >= 9, eigenvector k
+ *   in out_vectors[k*3 .. k*3 + 2] (column-major: contiguous per eigenvector)
+ * @param {Float64Array|Float32Array|number[]} m symmetric 3x3, row-major (index = row*3 + col)
+ */
+export function matrix_symmetric_3x3_eigen(out_values: Float64Array | Float32Array | number[], out_vectors: Float64Array | Float32Array | number[], m: Float64Array | Float32Array | number[]): void;
+//# sourceMappingURL=matrix_symmetric_3x3_eigen.d.ts.map

package/src/core/math/linalg/eigen/matrix_symmetric_3x3_eigen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"matrix_symmetric_3x3_eigen.d.ts","sourceRoot":"","sources":["../../../../../../src/core/math/linalg/eigen/matrix_symmetric_3x3_eigen.js"],"names":[],"mappings":"AA8DA;;;;;;;;;;;;;;;;GAgBG;AACH,uDALW,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,eAClC,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,KAElC,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,QAuC5C"}

package/src/core/math/linalg/eigen/matrix_symmetric_3x3_eigen.js

@@ -0,0 +1,117 @@
+/**
+ * Maximum number of cyclic Jacobi sweeps. A symmetric 3x3 reaches full double
+ * precision in ~5-6 sweeps (Jacobi converges quadratically); 50 is a generous
+ * cap that the relative-off-diagonal early-out almost always beats.
+ * @type {number}
+ */
+const MAX_SWEEPS = 50;
+
+/**
+ * One Jacobi rotation in the (p, q) plane that zeroes the off-diagonal entry
+ * a[p][q]. `a` and `v` are 3x3 matrices stored row-major (index = row*3 + col).
+ * `a` is the symmetric working matrix; `v` accumulates the rotations so its
+ * columns become the eigenvectors.
+ *
+ * @param {number[]} a symmetric 3x3, mutated in place
+ * @param {number[]} v 3x3 rotation accumulator, mutated in place
+ * @param {number} p
+ * @param {number} q
+ */
+function jacobi_rotate(a, v, p, q) {
+    const apq = a[p * 3 + q];
+
+    if (apq === 0) {
+        return;
+    }
+
+    const app = a[p * 3 + p];
+    const aqq = a[q * 3 + q];
+
+    // tan of the rotation angle (Numerical Recipes form, |angle| <= pi/4).
+    const theta = (aqq - app) / (2 * apq);
+    const t = (theta >= 0)
+        ? 1 / (theta + Math.sqrt(theta * theta + 1))
+        : -1 / (-theta + Math.sqrt(theta * theta + 1));
+    const c = 1 / Math.sqrt(t * t + 1);
+    const s = t * c;
+
+    // The third (untouched) index.
+    const r = 3 - p - q;
+    const arp = a[r * 3 + p];
+    const arq = a[r * 3 + q];
+
+    a[p * 3 + p] = app - t * apq;
+    a[q * 3 + q] = aqq + t * apq;
+    a[p * 3 + q] = 0;
+    a[q * 3 + p] = 0;
+
+    const new_rp = c * arp - s * arq;
+    const new_rq = s * arp + c * arq;
+    a[r * 3 + p] = new_rp;
+    a[p * 3 + r] = new_rp;
+    a[r * 3 + q] = new_rq;
+    a[q * 3 + r] = new_rq;
+
+    for (let row = 0; row < 3; row++) {
+        const vrp = v[row * 3 + p];
+        const vrq = v[row * 3 + q];
+        v[row * 3 + p] = c * vrp - s * vrq;
+        v[row * 3 + q] = s * vrp + c * vrq;
+    }
+}
+
+/**
+ * Eigendecomposition of a symmetric 3x3 matrix via cyclic Jacobi rotations.
+ *
+ * Only the upper triangle of `m` is read (the matrix is assumed symmetric);
+ * the input is not modified. Eigenpairs are emitted sorted by **ascending
+ * eigenvalue**, so index 0 is the smallest — convenient for proxy-plane fits,
+ * where the plane normal is the eigenvector of the smallest variance.
+ *
+ * Eigenvector sign is arbitrary (an eigenvector and its negation are both
+ * valid); callers that need a consistent orientation must fix the sign
+ * themselves.
+ *
+ * @param {Float64Array|Float32Array|number[]} out_values length >= 3, eigenvalues ascending
+ * @param {Float64Array|Float32Array|number[]} out_vectors length >= 9, eigenvector k
+ *   in out_vectors[k*3 .. k*3 + 2] (column-major: contiguous per eigenvector)
+ * @param {Float64Array|Float32Array|number[]} m symmetric 3x3, row-major (index = row*3 + col)
+ */
+export function matrix_symmetric_3x3_eigen(out_values, out_vectors, m) {
+    const a = [
+        m[0], m[1], m[2],
+        m[1], m[4], m[5],
+        m[2], m[5], m[8],
+    ];
+    const v = [
+        1, 0, 0,
+        0, 1, 0,
+        0, 0, 1,
+    ];
+
+    for (let sweep = 0; sweep < MAX_SWEEPS; sweep++) {
+        const scale = Math.abs(a[0]) + Math.abs(a[4]) + Math.abs(a[8]);
+        const off = Math.abs(a[1]) + Math.abs(a[2]) + Math.abs(a[5]);
+
+        if (off <= 1e-18 * scale) {
+            break;
+        }
+
+        jacobi_rotate(a, v, 0, 1);
+        jacobi_rotate(a, v, 0, 2);
+        jacobi_rotate(a, v, 1, 2);
+    }
+
+    // Eigenvalues live on the diagonal; eigenvector k is column k of V.
+    const eig = [a[0], a[4], a[8]];
+    const order = [0, 1, 2];
+    order.sort((i, j) => eig[i] - eig[j]);
+
+    for (let k = 0; k < 3; k++) {
+        const col = order[k];
+        out_values[k] = eig[col];
+        out_vectors[k * 3 + 0] = v[0 * 3 + col];
+        out_vectors[k * 3 + 1] = v[1 * 3 + col];
+        out_vectors[k * 3 + 2] = v[2 * 3 + col];
+    }
+}

package/src/core/math/linalg/sparse/SparseMatrixCSR.d.ts

@@ -0,0 +1,50 @@
+/**
+ * An `m x n` sparse matrix in Compressed Sparse Row form.
+ *
+ * The three parallel arrays follow the standard CSR convention:
+ *   - `row_ptr[r]`   = start of row r's entries in `col_idx`/`values`
+ *   - `row_ptr[r+1]` = end (exclusive); `row_ptr[rows]` = nnz
+ *   - `col_idx[k]`   = column of entry k
+ *   - `values[k]`    = value of entry k
+ *
+ * Entries within a row are NOT required to be sorted by column, and duplicate
+ * (row, col) entries are permitted: matrix-vector products sum over a row, so
+ * duplicates simply accumulate — which is exactly what finite-element style
+ * assembly (many small per-element contributions to the same cell) wants. This
+ * is why {@link SparseMatrixCSR.from_triplets} performs no de-duplication pass.
+ *
+ * Fields are exposed directly (not via accessors) so hot matvec loops can run
+ * `for (let k = row_ptr[r]; k < row_ptr[r+1]; k++)` without closure overhead,
+ * mirroring {@link CSRGraph}.
+ */
+export class SparseMatrixCSR {
+    /**
+     * Build a CSR matrix from a triplet (coordinate) list. The triplet arrays
+     * are parallel; `count` entries are read. Duplicate (row, col) triplets are
+     * kept and will sum during matvec.
+     *
+     * @param {number} rows
+     * @param {number} cols
+     * @param {Uint32Array|number[]} triplet_rows
+     * @param {Uint32Array|number[]} triplet_cols
+     * @param {Float64Array|number[]} triplet_values
+     * @param {number} count number of triplets to read
+     * @returns {SparseMatrixCSR}
+     */
+    static from_triplets(rows: number, cols: number, triplet_rows: Uint32Array | number[], triplet_cols: Uint32Array | number[], triplet_values: Float64Array | number[], count: number): SparseMatrixCSR;
+    /**
+     * @param {number} rows
+     * @param {number} cols
+     * @param {Uint32Array} row_ptr length rows + 1
+     * @param {Uint32Array} col_idx length nnz
+     * @param {Float64Array} values length nnz
+     */
+    constructor(rows: number, cols: number, row_ptr: Uint32Array, col_idx: Uint32Array, values: Float64Array);
+    rows: number;
+    cols: number;
+    row_ptr: Uint32Array;
+    col_idx: Uint32Array;
+    values: Float64Array;
+    nnz: number;
+}
+//# sourceMappingURL=SparseMatrixCSR.d.ts.map

package/src/core/math/linalg/sparse/SparseMatrixCSR.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SparseMatrixCSR.d.ts","sourceRoot":"","sources":["../../../../../../src/core/math/linalg/sparse/SparseMatrixCSR.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AACH;IAiBI;;;;;;;;;;;;OAYG;IACH,2BARW,MAAM,QACN,MAAM,gBACN,WAAW,GAAC,MAAM,EAAE,gBACpB,WAAW,GAAC,MAAM,EAAE,kBACpB,YAAY,GAAC,MAAM,EAAE,SACrB,MAAM,GACJ,eAAe,CAqC3B;IAhED;;;;;;OAMG;IACH,kBANW,MAAM,QACN,MAAM,WACN,WAAW,WACX,WAAW,UACX,YAAY,EAStB;IANG,aAAgB;IAChB,aAAgB;IAChB,qBAAsB;IACtB,qBAAsB;IACtB,qBAAoB;IACpB,YAAwB;CAoD/B"}