@woosh/meep-engine 2.163.11 → 2.165.0

package/src/core/geom/3d/atlas/param/atlas_chart_parameterize_bff.js

@@ -0,0 +1,270 @@
+import { cg_solve } from "../../../../math/linalg/cg/cg_solve.js";
+import { cg_solve_normal_equations } from "../../../../math/linalg/cg/cg_solve_normal_equations.js";
+import { SparseMatrixCSR } from "../../../../math/linalg/sparse/SparseMatrixCSR.js";
+import { v3_cotangent } from "../../../vec3/v3_cotangent.js";
+
+const TWO_PI = 2 * Math.PI;
+/** Cotangent weights are clamped to [0, COT_MAX]: ≥0 keeps the Dirichlet
+ *  Laplacian an SPD M-matrix (obtuse triangles otherwise make it indefinite) and
+ *  preserves zero row sums (so the DtN boundary curvature still closes); the upper
+ *  bound stops a sliver corner from dominating. */
+const COT_MAX = 1e3;
+
+/** Cotangent of the angle at o (opposite edge p-q), clamped to [0, COT_MAX].
+ *  ≥0 keeps the interior Poisson SPD (`cg_solve`) and preserves zero row sums
+ *  (so the DtN boundary still closes); measured to give marginally more rescues
+ *  than the true signed cotangent (the indefinite solve is no better here). */
+function clamped_cot(pos, o, p, q) {
+    const c = v3_cotangent(
+        pos[p * 3] - pos[o * 3], pos[p * 3 + 1] - pos[o * 3 + 1], pos[p * 3 + 2] - pos[o * 3 + 2],
+        pos[q * 3] - pos[o * 3], pos[q * 3 + 1] - pos[o * 3 + 1], pos[q * 3 + 2] - pos[o * 3 + 2]
+    );
+    if (!Number.isFinite(c) || c <= 0) return 0;
+    return c > COT_MAX ? COT_MAX : c;
+}
+
+/** Interior angle (radians) at vertex i0 in triangle (i0,i1,i2). */
+function interior_angle(pos, i0, i1, i2) {
+    const ux = pos[i1 * 3] - pos[i0 * 3], uy = pos[i1 * 3 + 1] - pos[i0 * 3 + 1], uz = pos[i1 * 3 + 2] - pos[i0 * 3 + 2];
+    const vx = pos[i2 * 3] - pos[i0 * 3], vy = pos[i2 * 3 + 1] - pos[i0 * 3 + 1], vz = pos[i2 * 3 + 2] - pos[i0 * 3 + 2];
+    const lu = Math.sqrt(ux * ux + uy * uy + uz * uz);
+    const lv = Math.sqrt(vx * vx + vy * vy + vz * vz);
+    if (lu < 1e-20 || lv < 1e-20) return 0;
+    const c = (ux * vx + uy * vy + uz * vz) / (lu * lv);
+    return Math.acos(Math.max(-1, Math.min(1, c)));
+}
+
+/** Flatten a triangle into an isometric local 2D frame (vertex 0 at origin,
+ *  vertex 1 on +x): writes [x2, x3, y3] into `out`. (Same as LSCM.) */
+function project_triangle(pos, i0, i1, i2, out) {
+    const ax = pos[i0 * 3], ay = pos[i0 * 3 + 1], az = pos[i0 * 3 + 2];
+    const e1x = pos[i1 * 3] - ax, e1y = pos[i1 * 3 + 1] - ay, e1z = pos[i1 * 3 + 2] - az;
+    const len1 = Math.sqrt(e1x * e1x + e1y * e1y + e1z * e1z);
+    const inv1 = len1 > 0 ? 1 / len1 : 0;
+    const ux = e1x * inv1, uy = e1y * inv1, uz = e1z * inv1;
+    const e2x = pos[i2 * 3] - ax, e2y = pos[i2 * 3 + 1] - ay, e2z = pos[i2 * 3 + 2] - az;
+    const x3 = e2x * ux + e2y * uy + e2z * uz;
+    const px = e2x - x3 * ux, py = e2y - x3 * uy, pz = e2z - x3 * uz;
+    out[0] = len1;
+    out[1] = x3;
+    out[2] = Math.sqrt(px * px + py * py + pz * pz);
+}
+
+/**
+ * Intrinsic boundary-first flattening (a tractable BFF, Sawhney & Crane 2018).
+ *
+ * Unlike a Tutte/convex embedding (which forces a circle and so distorts
+ * thin/curled charts catastrophically — the aspect cannot be guessed without
+ * already flattening), this builds the flattened boundary from the chart's OWN
+ * geometry: keep each boundary edge's 3D length and turn at each boundary vertex
+ * by the optimal Dirichlet-to-Neumann curvature — fix the boundary scale to 0,
+ * solve the interior Poisson `L_II u = Ω_I` (flatten the interior), then
+ * `k̃_b = (π − θ_b) − (L u)_b`. By the cot-Laplacian's zero row sums ∑ k̃ = 2π so
+ * the boundary closes, with the curvature distributed by the mesh's harmonic
+ * structure (not uniformly). The interior is then a CONFORMAL extension of that
+ * boundary (least-squares Cauchy-Riemann, every boundary vertex pinned) — the u,v
+ * coupling is far less flip-prone than a harmonic interior on a non-convex
+ * boundary. The result is a natural, low-distortion, length-preserving boundary —
+ * not a forced convex shape.
+ *
+ * Measured outcome (decimated terrain): a Pareto-safe rescue but SMALL — the DtN
+ * boundary fixed the conformal-interior flips (25 → 2), yet only ~2 of 31
+ * self-intersecting charts are rescued because the flattened BOUNDARY itself then
+ * self-intersects on ~27/31. That is fundamental, not an implementation gap (true
+ * unclamped cotangents made it worse): these high-curvature decimated charts can't
+ * be developed to a SIMPLE boundary while preserving edge lengths, so cutting
+ * (piecewise) is the correct injective answer for them. Injectivity is NOT
+ * guaranteed; the caller validates and falls back to piecewise otherwise. Solves
+ * in place on `chart.uv`. See BFF_PLAN.md / REVIEW_02.md §5.0.
+ *
+ * @param {Chart} chart with `boundary_edges`, `tri_local`, `positions`, `uv`
+ * @param {{tolerance?:number, maxIterations?:number}} [options]
+ * @returns {boolean} true if a flattening was produced; false if the chart is not
+ *   a single-boundary-loop disk or the interior system is degenerate
+ */
+export function atlas_chart_parameterize_bff(chart, options = {}) {
+    const V = chart.vertex_count;
+    const be = chart.boundary_edges;
+    if (be.length === 0) return false;
+    const pos = chart.positions;
+    const uv = chart.uv;
+    const tri = chart.tri_local;
+    const T = chart.triangle_count;
+
+    // ── 1. trace the single oriented boundary loop (disk check) ──────────────
+    const is_boundary = new Uint8Array(V);
+    const succ = new Int32Array(V).fill(-1);
+    let boundary_count = 0;
+    for (let i = 0; i < be.length; i += 2) {
+        const a = be[i], b = be[i + 1];
+        if (!is_boundary[a]) { is_boundary[a] = 1; boundary_count++; }
+        if (!is_boundary[b]) { is_boundary[b] = 1; boundary_count++; }
+        if (succ[a] !== -1) return false;
+        succ[a] = b;
+    }
+    const loop = [];
+    let cur = be[0];
+    do {
+        loop.push(cur);
+        cur = succ[cur];
+        if (cur === -1) return false;
+        if (loop.length > boundary_count) return false;
+    } while (cur !== be[0]);
+    if (loop.length !== boundary_count) return false;
+    const n = loop.length;
+
+    // ── 2. interior angle sums + Gaussian curvature ──────────────────────────
+    const angle_sum = new Float64Array(V);
+    for (let t = 0; t < T; t++) {
+        const a = tri[t * 3], b = tri[t * 3 + 1], c = tri[t * 3 + 2];
+        angle_sum[a] += interior_angle(pos, a, b, c);
+        angle_sum[b] += interior_angle(pos, b, c, a);
+        angle_sum[c] += interior_angle(pos, c, a, b);
+    }
+    // re-index interior (shared by the DtN boundary solve and the conformal interior)
+    const interior = new Int32Array(V).fill(-1);
+    const vertex_of = new Int32Array(V);
+    let m = 0;
+    for (let v = 0; v < V; v++) {
+        if (!is_boundary[v]) { vertex_of[m] = v; interior[v] = m++; }
+    }
+
+    // ── 3. Dirichlet-to-Neumann optimal boundary curvature. Fix the boundary
+    //       scale factor to 0 (preserve boundary edge lengths), solve the interior
+    //       Poisson L_II u = Ω_I (flatten the interior), then read off the boundary
+    //       turning k̃_b = (π − θ_b) − (L u)_b. By the (clamped) cot-Laplacian's zero
+    //       row sums ∑ k̃ = 2π, so the flattened boundary still closes — but the
+    //       curvature is now distributed by the mesh's harmonic structure rather
+    //       than uniformly, giving a far less contorted boundary. ───────────────
+    const kappa = new Float64Array(n);
+    if (m === 0) {
+        for (let k = 0; k < n; k++) kappa[k] = Math.PI - angle_sum[loop[k]];
+    } else {
+        const wmap = new Array(V).fill(null);
+        const add_w = (i, j, w) => {
+            const M = wmap[i] ?? (wmap[i] = new Map());
+            M.set(j, (M.get(j) ?? 0) + w);
+        };
+        for (let t = 0; t < T; t++) {
+            const a = tri[t * 3], b = tri[t * 3 + 1], c = tri[t * 3 + 2];
+            const wa = 0.5 * clamped_cot(pos, a, b, c); // opposite edge (b,c)
+            const wb = 0.5 * clamped_cot(pos, b, c, a); // opposite edge (c,a)
+            const wc = 0.5 * clamped_cot(pos, c, a, b); // opposite edge (a,b)
+            add_w(b, c, wa); add_w(c, b, wa);
+            add_w(c, a, wb); add_w(a, c, wb);
+            add_w(a, b, wc); add_w(b, a, wc);
+        }
+        // assemble + solve the interior Poisson  L_II u = Ω_I
+        const diag = new Float64Array(m);
+        const adj = [];
+        const rhs = new Float64Array(m);
+        for (let i = 0; i < m; i++) {
+            const vi = vertex_of[i];
+            let d = 0;
+            const list = [];
+            const M = wmap[vi];
+            if (M) for (const [j, w] of M) { d += w; if (!is_boundary[j]) list.push(interior[j], w); }
+            if (d <= 0) return false; // fully-clamped interior vertex -> not solvable
+            diag[i] = d;
+            adj.push(list);
+            rhs[i] = TWO_PI - angle_sum[vi];
+        }
+        const apply = (out, vec) => {
+            for (let i = 0; i < m; i++) {
+                let s = diag[i] * vec[i];
+                const list = adj[i];
+                for (let k = 0; k < list.length; k += 2) s -= list[k + 1] * vec[list[k]];
+                out[i] = s;
+            }
+        };
+        const u = new Float64Array(m);
+        cg_solve(u, apply, rhs, m, Math.max(200, 10 * m), 1e-10);
+        // k̃_b = (π − θ_b) − (L u)_b,  with  (L u)_b = −Σ_{interior nbr j} w_bj u_j
+        for (let k = 0; k < n; k++) {
+            const bv = loop[k];
+            let lu_b = 0;
+            const M = wmap[bv];
+            if (M) for (const [j, w] of M) if (!is_boundary[j]) lu_b -= w * u[interior[j]];
+            kappa[k] = (Math.PI - angle_sum[bv]) - lu_b;
+        }
+    }
+
+    // integrate the flattened boundary curve (preserve 3D edge lengths, turn by k̃)
+    const bx = new Float64Array(n);
+    const by = new Float64Array(n);
+    let dir = 0, px = 0, py = 0;
+    for (let k = 0; k < n; k++) {
+        bx[k] = px;
+        by[k] = py;
+        const a = loop[k], b = loop[(k + 1) % n];
+        const ex = pos[a * 3] - pos[b * 3], ey = pos[a * 3 + 1] - pos[b * 3 + 1], ez = pos[a * 3 + 2] - pos[b * 3 + 2];
+        const len = Math.sqrt(ex * ex + ey * ey + ez * ez);
+        px += len * Math.cos(dir);
+        py += len * Math.sin(dir);
+        dir += kappa[(k + 1) % n];
+    }
+    for (let k = 0; k < n; k++) {
+        uv[loop[k] * 2] = bx[k];
+        uv[loop[k] * 2 + 1] = by[k];
+    }
+
+    // ── 4. conformal interior extension with the boundary pinned to the BFF
+    //       curve: least-squares conformal (Cauchy-Riemann) energy over all
+    //       triangles, every boundary vertex locked, interior free. Couples u,v
+    //       (unlike harmonic) so it is far less flip-prone on a non-convex
+    //       boundary. Solved via the matrix-free normal-equations CG. ──────────
+    if (m === 0) return true; // boundary-only chart already placed
+
+    const rows = 2 * T;
+    const tr = [];
+    const tc = [];
+    const tv = [];
+    const b = new Float64Array(rows);
+    /** Accumulate `coef · (component of vertex)`: pinned → RHS, free → triplet. */
+    const add = (row, vtx, comp, coef) => {
+        if (is_boundary[vtx]) {
+            b[row] -= coef * uv[vtx * 2 + comp];
+        } else {
+            tr.push(row); tc.push(interior[vtx] * 2 + comp); tv.push(coef);
+        }
+    };
+
+    const local = [0, 0, 0];
+    let row = 0;
+    for (let t = 0; t < T; t++) {
+        const i0 = tri[t * 3], i1 = tri[t * 3 + 1], i2 = tri[t * 3 + 2];
+        project_triangle(pos, i0, i1, i2, local);
+        const x2 = local[0], x3 = local[1], y3 = local[2];
+        const area = 0.5 * x2 * y3;
+        if (area <= 1e-20) { row += 2; continue; }
+        const w = 1 / Math.sqrt(area);
+        const wr = [(x3 - x2) * w, -x3 * w, x2 * w];
+        const wi = [y3 * w, -y3 * w, 0];
+        const verts = [i0, i1, i2];
+        const rr = row, ir = row + 1;
+        for (let j = 0; j < 3; j++) {
+            const a_j = wr[j], b_j = wi[j], vtx = verts[j];
+            add(rr, vtx, 0, a_j);   // real: a_j·u
+            add(rr, vtx, 1, -b_j);  //       - b_j·v
+            add(ir, vtx, 0, b_j);   // imag: b_j·u
+            add(ir, vtx, 1, a_j);   //       + a_j·v
+        }
+        row += 2;
+    }
+
+    const A = SparseMatrixCSR.from_triplets(rows, 2 * m, tr, tc, tv, tr.length);
+    const sol = new Float64Array(2 * m);
+    for (let v = 0; v < V; v++) {
+        const ii = interior[v];
+        if (ii >= 0) { sol[ii * 2] = uv[v * 2]; sol[ii * 2 + 1] = uv[v * 2 + 1]; } // warm start from prior interior
+    }
+    const tolerance = options.tolerance ?? 1e-8;
+    const max_iterations = options.maxIterations ?? Math.max(200, 20 * m);
+    cg_solve_normal_equations(sol, A, b, max_iterations, tolerance);
+
+    for (let v = 0; v < V; v++) {
+        const ii = interior[v];
+        if (ii >= 0) { uv[v * 2] = sol[ii * 2]; uv[v * 2 + 1] = sol[ii * 2 + 1]; }
+    }
+    return true;
+}

package/src/core/geom/3d/atlas/param/atlas_chart_parameterize_lscm.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Least-Squares Conformal Map parameterization (xatlas
+ * `computeLeastSquaresConformalMap`). Solves the discrete Cauchy-Riemann
+ * (conformal energy) least-squares system with two pinned boundary vertices,
+ * via the matrix-free normal-equations CG ({@link cg_solve_normal_equations}).
+ *
+ * Each triangle is flattened isometrically and contributes one complex equation
+ * `Σ_j W_j (u_j + i v_j) = 0` (two real rows), weighted by `1/sqrt(area)`. The
+ * two diameter pins are locked to their current (ortho) UVs, anchoring the
+ * conformal map's translation/rotation/scale; the rest is warm-started from the
+ * ortho layout. Writes the solved UVs into `chart.uv`.
+ *
+ * @param {Chart} chart from atlas_extract_chart, with `chart.uv` pre-filled by
+ *   the ortho pass (used for pins + warm start)
+ * @param {{tolerance?:number, maxIterations?:number}} [options]
+ * @returns {boolean} true if LSCM ran; false if the chart has no boundary
+ *   (caller should keep ortho or re-segment piecewise)
+ */
+export function atlas_chart_parameterize_lscm(chart: Chart, options?: {
+    tolerance?: number;
+    maxIterations?: number;
+}): boolean;
+//# sourceMappingURL=atlas_chart_parameterize_lscm.d.ts.map

package/src/core/geom/3d/atlas/param/atlas_chart_parameterize_lscm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"atlas_chart_parameterize_lscm.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/geom/3d/atlas/param/atlas_chart_parameterize_lscm.js"],"names":[],"mappings":"AAmFA;;;;;;;;;;;;;;;;;GAiBG;AACH;gBAJuB,MAAM;oBAAiB,MAAM;IACvC,OAAO,CA6HnB"}

package/src/core/geom/3d/atlas/param/atlas_chart_parameterize_lscm.js

@@ -0,0 +1,224 @@
+import { cg_solve_normal_equations } from "../../../../math/linalg/cg/cg_solve_normal_equations.js";
+import { SparseMatrixCSR } from "../../../../math/linalg/sparse/SparseMatrixCSR.js";
+
+/**
+ * Find the two boundary vertices to pin: the extremes along the chart's widest
+ * 3D bounding-box axis (xatlas `findApproximateDiameterVertices`). Returns null
+ * when the chart has no boundary (LSCM is then not applicable) or the pins are
+ * degenerate.
+ *
+ * @param {Chart} chart
+ * @returns {[number, number]|null}
+ */
+function find_diameter_pins(chart) {
+    const be = chart.boundary_edges;
+    if (be.length === 0) {
+        return null;
+    }
+
+    const is_boundary = new Uint8Array(chart.vertex_count);
+    for (let i = 0; i < be.length; i++) {
+        is_boundary[be[i]] = 1;
+    }
+
+    const min_i = [-1, -1, -1];
+    const max_i = [-1, -1, -1];
+    const min_v = [Infinity, Infinity, Infinity];
+    const max_v = [-Infinity, -Infinity, -Infinity];
+
+    for (let v = 0; v < chart.vertex_count; v++) {
+        if (!is_boundary[v]) continue;
+        for (let a = 0; a < 3; a++) {
+            const c = chart.positions[v * 3 + a];
+            if (c < min_v[a]) { min_v[a] = c; min_i[a] = v; }
+            if (c > max_v[a]) { max_v[a] = c; max_i[a] = v; }
+        }
+    }
+
+    let best_axis = 0;
+    let best_extent = -1;
+    for (let a = 0; a < 3; a++) {
+        const ext = max_v[a] - min_v[a];
+        if (ext > best_extent) { best_extent = ext; best_axis = a; }
+    }
+
+    const p0 = min_i[best_axis];
+    const p1 = max_i[best_axis];
+    if (p0 < 0 || p1 < 0 || p0 === p1) {
+        return null;
+    }
+    return [p0, p1];
+}
+
+/**
+ * Flatten a triangle into an isometric local 2D frame: vertex 0 at the origin,
+ * vertex 1 along +x. Writes [x2, x3, y3] (x1=y1=y2=0) into `out`.
+ *
+ * @param {Float64Array} pos packed xyz vertex positions (3 floats per vertex)
+ * @param {number} i0 local index of the first triangle vertex (origin)
+ * @param {number} i1 local index of the second triangle vertex (along +x)
+ * @param {number} i2 local index of the third triangle vertex
+ * @param {number[]} out destination [x2, x3, y3]
+ * @returns {void}
+ */
+function project_triangle(pos, i0, i1, i2, out) {
+    const ax = pos[i0 * 3], ay = pos[i0 * 3 + 1], az = pos[i0 * 3 + 2];
+    const bx = pos[i1 * 3], by = pos[i1 * 3 + 1], bz = pos[i1 * 3 + 2];
+    const cx = pos[i2 * 3], cy = pos[i2 * 3 + 1], cz = pos[i2 * 3 + 2];
+
+    const e1x = bx - ax, e1y = by - ay, e1z = bz - az;
+    const len1 = Math.sqrt(e1x * e1x + e1y * e1y + e1z * e1z);
+    const inv1 = len1 > 0 ? 1 / len1 : 0;
+    const ux = e1x * inv1, uy = e1y * inv1, uz = e1z * inv1;
+
+    const e2x = cx - ax, e2y = cy - ay, e2z = cz - az;
+    const x3 = e2x * ux + e2y * uy + e2z * uz;
+    const px = e2x - x3 * ux, py = e2y - x3 * uy, pz = e2z - x3 * uz;
+    const y3 = Math.sqrt(px * px + py * py + pz * pz);
+
+    out[0] = len1;
+    out[1] = x3;
+    out[2] = y3;
+}
+
+/**
+ * Least-Squares Conformal Map parameterization (xatlas
+ * `computeLeastSquaresConformalMap`). Solves the discrete Cauchy-Riemann
+ * (conformal energy) least-squares system with two pinned boundary vertices,
+ * via the matrix-free normal-equations CG ({@link cg_solve_normal_equations}).
+ *
+ * Each triangle is flattened isometrically and contributes one complex equation
+ * `Σ_j W_j (u_j + i v_j) = 0` (two real rows), weighted by `1/sqrt(area)`. The
+ * two diameter pins are locked to their current (ortho) UVs, anchoring the
+ * conformal map's translation/rotation/scale; the rest is warm-started from the
+ * ortho layout. Writes the solved UVs into `chart.uv`.
+ *
+ * @param {Chart} chart from atlas_extract_chart, with `chart.uv` pre-filled by
+ *   the ortho pass (used for pins + warm start)
+ * @param {{tolerance?:number, maxIterations?:number}} [options]
+ * @returns {boolean} true if LSCM ran; false if the chart has no boundary
+ *   (caller should keep ortho or re-segment piecewise)
+ */
+export function atlas_chart_parameterize_lscm(chart, options = {}) {
+    const pins = find_diameter_pins(chart);
+    if (pins === null) {
+        return false;
+    }
+
+    const p0 = pins[0];
+    const p1 = pins[1];
+    const V = chart.vertex_count;
+    const T = chart.triangle_count;
+
+    const pinned = new Uint8Array(2 * V);
+    pinned[2 * p0] = 1;
+    pinned[2 * p0 + 1] = 1;
+    pinned[2 * p1] = 1;
+    pinned[2 * p1 + 1] = 1;
+
+    const col_of = new Int32Array(2 * V).fill(-1);
+    let free_cols = 0;
+    for (let s = 0; s < 2 * V; s++) {
+        if (!pinned[s]) {
+            col_of[s] = free_cols++;
+        }
+    }
+
+    const pin_val = chart.uv;
+    const rows = 2 * T;
+    const tr = [];
+    const tc = [];
+    const tv = [];
+    const b = new Float64Array(rows);
+
+    /**
+     * Accumulate one coefficient into the least-squares system. A pinned scalar
+     * moves to the right-hand side `b`; a free scalar becomes a triplet entry.
+     *
+     * @param {number} row destination row in the 2T-row system
+     * @param {number} scalar packed unknown index (2*vertex for u, +1 for v)
+     * @param {number} coef coefficient multiplying that scalar
+     * @returns {void}
+     */
+    function add(row, scalar, coef) {
+        if (pinned[scalar]) {
+            b[row] -= coef * pin_val[scalar];
+        } else {
+            tr.push(row);
+            tc.push(col_of[scalar]);
+            tv.push(coef);
+        }
+    }
+
+    const local = [0, 0, 0];
+    let row = 0;
+
+    for (let t = 0; t < T; t++) {
+        const i0 = chart.tri_local[t * 3];
+        const i1 = chart.tri_local[t * 3 + 1];
+        const i2 = chart.tri_local[t * 3 + 2];
+
+        project_triangle(chart.positions, i0, i1, i2, local);
+        const x2 = local[0];
+        const x3 = local[1];
+        const y3 = local[2];
+
+        const area = 0.5 * x2 * y3;
+        if (area <= 1e-20) {
+            // degenerate triangle contributes nothing; leave the two rows zero
+            row += 2;
+            continue;
+        }
+
+        const w = 1 / Math.sqrt(area);
+
+        // W1 = p3 - p2, W2 = p1 - p3, W3 = p2 - p1  (complex, local coords)
+        const w1r = (x3 - x2) * w, w1i = y3 * w;
+        const w2r = -x3 * w, w2i = -y3 * w;
+        const w3r = x2 * w, w3i = 0;
+
+        const verts = [i0, i1, i2];
+        const wr = [w1r, w2r, w3r];
+        const wi = [w1i, w2i, w3i];
+
+        const real_row = row;
+        const imag_row = row + 1;
+
+        for (let j = 0; j < 3; j++) {
+            const a_j = wr[j];
+            const b_j = wi[j];
+            const su = 2 * verts[j];
+            const sv = 2 * verts[j] + 1;
+
+            // real part: a_j*u_j - b_j*v_j
+            add(real_row, su, a_j);
+            add(real_row, sv, -b_j);
+            // imaginary part: b_j*u_j + a_j*v_j
+            add(imag_row, su, b_j);
+            add(imag_row, sv, a_j);
+        }
+
+        row += 2;
+    }
+
+    const A = SparseMatrixCSR.from_triplets(rows, free_cols, tr, tc, tv, tr.length);
+
+    const x = new Float64Array(free_cols);
+    for (let s = 0; s < 2 * V; s++) {
+        if (col_of[s] >= 0) {
+            x[col_of[s]] = chart.uv[s];
+        }
+    }
+
+    const tolerance = options.tolerance ?? 1e-8;
+    const max_iterations = options.maxIterations ?? Math.max(200, 10 * free_cols);
+    cg_solve_normal_equations(x, A, b, max_iterations, tolerance);
+
+    for (let s = 0; s < 2 * V; s++) {
+        if (col_of[s] >= 0) {
+            chart.uv[s] = x[col_of[s]];
+        }
+    }
+
+    return true;
+}

package/src/core/geom/3d/atlas/param/atlas_chart_parameterize_ortho.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Orthographic chart parameterization (xatlas Ortho/Planar path): fit the
+ * chart's proxy plane, then project every vertex onto it —
+ * `uv = (dot(tangent, p), dot(bitangent, p))`. Exact and isometric for a planar
+ * chart; for a non-planar chart this is the cheap first attempt whose quality
+ * the validity gate / stretch metric then accepts or rejects in favour of LSCM.
+ *
+ * Writes `chart.uv` in place.
+ *
+ * @param {Chart} chart
+ * @returns {Float64Array} the fitted 9-float basis (tangent, bitangent, normal)
+ */
+export function atlas_chart_parameterize_ortho(chart: Chart): Float64Array;
+//# sourceMappingURL=atlas_chart_parameterize_ortho.d.ts.map

package/src/core/geom/3d/atlas/param/atlas_chart_parameterize_ortho.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"atlas_chart_parameterize_ortho.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/geom/3d/atlas/param/atlas_chart_parameterize_ortho.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;GAWG;AACH,8DAFa,YAAY,CAwBxB"}

package/src/core/geom/3d/atlas/param/atlas_chart_parameterize_ortho.js

@@ -0,0 +1,38 @@
+import { v3_dot } from "../../../vec3/v3_dot.js";
+import { ATLAS_BASIS_BITANGENT, ATLAS_BASIS_TANGENT, fit_plane_basis } from "./fit_plane_basis.js";
+
+/**
+ * Orthographic chart parameterization (xatlas Ortho/Planar path): fit the
+ * chart's proxy plane, then project every vertex onto it —
+ * `uv = (dot(tangent, p), dot(bitangent, p))`. Exact and isometric for a planar
+ * chart; for a non-planar chart this is the cheap first attempt whose quality
+ * the validity gate / stretch metric then accepts or rejects in favour of LSCM.
+ *
+ * Writes `chart.uv` in place.
+ *
+ * @param {Chart} chart
+ * @returns {Float64Array} the fitted 9-float basis (tangent, bitangent, normal)
+ */
+export function atlas_chart_parameterize_ortho(chart) {
+    const basis = new Float64Array(9);
+    fit_plane_basis(basis, chart.positions, chart.vertex_count);
+
+    const tx = basis[ATLAS_BASIS_TANGENT];
+    const ty = basis[ATLAS_BASIS_TANGENT + 1];
+    const tz = basis[ATLAS_BASIS_TANGENT + 2];
+    const bx = basis[ATLAS_BASIS_BITANGENT];
+    const by = basis[ATLAS_BASIS_BITANGENT + 1];
+    const bz = basis[ATLAS_BASIS_BITANGENT + 2];
+
+    const pos = chart.positions;
+    const uv = chart.uv;
+    for (let i = 0; i < chart.vertex_count; i++) {
+        const px = pos[i * 3];
+        const py = pos[i * 3 + 1];
+        const pz = pos[i * 3 + 2];
+        uv[i * 2] = v3_dot(tx, ty, tz, px, py, pz);
+        uv[i * 2 + 1] = v3_dot(bx, by, bz, px, py, pz);
+    }
+
+    return basis;
+}

package/src/core/geom/3d/atlas/param/atlas_chart_stretch_metric.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Sander/Hoppe texture-stretch metric of a chart's UV map (xatlas
+ * `computeMetrics`). For each triangle it forms the parameterization gradients
+ * Ss = dq/du, St = dq/dv, whose first fundamental form `[[a,b],[b,c]]` has
+ * singular values Gamma_max, Gamma_min. The per-triangle L2 stretch is
+ * `(Gamma_max^2 + Gamma_min^2)/2 = (a + c)/2`.
+ *
+ * Results are normalized by the chart's global UV-to-3D linear scale, so a
+ * pure isometry OR any uniform similarity returns exactly 1; non-uniform
+ * distortion returns > 1. `mean_stretch` is the area-weighted RMS;
+ * `max_stretch` is the worst per-triangle Gamma_max.
+ *
+ * @param {Chart} chart
+ * @returns {{mean_stretch:number, max_stretch:number, geom_area:number, param_area:number}}
+ */
+export function atlas_chart_stretch_metric(chart: Chart): {
+    mean_stretch: number;
+    max_stretch: number;
+    geom_area: number;
+    param_area: number;
+};
+//# sourceMappingURL=atlas_chart_stretch_metric.d.ts.map

package/src/core/geom/3d/atlas/param/atlas_chart_stretch_metric.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"atlas_chart_stretch_metric.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/geom/3d/atlas/param/atlas_chart_stretch_metric.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AACH,0DAFa;IAAC,YAAY,EAAC,MAAM,CAAC;IAAC,WAAW,EAAC,MAAM,CAAC;IAAC,SAAS,EAAC,MAAM,CAAC;IAAC,UAAU,EAAC,MAAM,CAAA;CAAC,CAsE1F"}