@woosh/meep-engine 2.164.0 → 2.165.0

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

@@ -0,0 +1,86 @@
+import { tri3_area } from "../../triangle/tri3_area.js";
+
+/**
+ * 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) {
+    const uv = chart.uv;
+    const pos = chart.positions;
+    const tri = chart.tri_local;
+    const triangle_count = chart.triangle_count;
+
+    let total_geom = 0;
+    let total_param = 0;
+    let weighted_l2_sq = 0;
+    let max_gamma_sq = 0;
+
+    for (let t = 0; t < triangle_count; t++) {
+        const i0 = tri[t * 3];
+        const i1 = tri[t * 3 + 1];
+        const i2 = tri[t * 3 + 2];
+
+        const s1 = uv[i0 * 2], t1 = uv[i0 * 2 + 1];
+        const s2 = uv[i1 * 2], t2 = uv[i1 * 2 + 1];
+        const s3 = uv[i2 * 2], t3 = uv[i2 * 2 + 1];
+
+        const q1x = pos[i0 * 3], q1y = pos[i0 * 3 + 1], q1z = pos[i0 * 3 + 2];
+        const q2x = pos[i1 * 3], q2y = pos[i1 * 3 + 1], q2z = pos[i1 * 3 + 2];
+        const q3x = pos[i2 * 3], q3y = pos[i2 * 3 + 1], q3z = pos[i2 * 3 + 2];
+
+        const two_param_area = (s2 - s1) * (t3 - t1) - (s3 - s1) * (t2 - t1);
+
+        total_geom += tri3_area(q1x, q1y, q1z, q2x, q2y, q2z, q3x, q3y, q3z);
+        total_param += Math.abs(two_param_area) * 0.5;
+
+        if (Math.abs(two_param_area) < 1e-20) {
+            continue;
+        }
+
+        const inv = 1 / two_param_area;
+        const ssx = (q1x * (t2 - t3) + q2x * (t3 - t1) + q3x * (t1 - t2)) * inv;
+        const ssy = (q1y * (t2 - t3) + q2y * (t3 - t1) + q3y * (t1 - t2)) * inv;
+        const ssz = (q1z * (t2 - t3) + q2z * (t3 - t1) + q3z * (t1 - t2)) * inv;
+        const stx = (q1x * (s3 - s2) + q2x * (s1 - s3) + q3x * (s2 - s1)) * inv;
+        const sty = (q1y * (s3 - s2) + q2y * (s1 - s3) + q3y * (s2 - s1)) * inv;
+        const stz = (q1z * (s3 - s2) + q2z * (s1 - s3) + q3z * (s2 - s1)) * inv;
+
+        const a = ssx * ssx + ssy * ssy + ssz * ssz;
+        const b = ssx * stx + ssy * sty + ssz * stz;
+        const c = stx * stx + sty * sty + stz * stz;
+
+        const geom_area = tri3_area(q1x, q1y, q1z, q2x, q2y, q2z, q3x, q3y, q3z);
+        weighted_l2_sq += ((a + c) / 2) * geom_area;
+
+        const disc = Math.sqrt(Math.max(0, (a - c) * (a - c) + 4 * b * b));
+        const gamma_max_sq = 0.5 * ((a + c) + disc);
+        if (gamma_max_sq > max_gamma_sq) {
+            max_gamma_sq = gamma_max_sq;
+        }
+    }
+
+    if (total_geom <= 0 || total_param <= 0) {
+        return { mean_stretch: Infinity, max_stretch: Infinity, geom_area: total_geom, param_area: total_param };
+    }
+
+    // Global linear scale^2 of the UV map relative to 3D (uv area / 3d area).
+    const scale_sq = total_param / total_geom;
+
+    return {
+        mean_stretch: Math.sqrt((weighted_l2_sq / total_geom) * scale_sq),
+        max_stretch: Math.sqrt(max_gamma_sq * scale_sq),
+        geom_area: total_geom,
+        param_area: total_param,
+    };
+}

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

@@ -0,0 +1,20 @@
+/**
+ * Region-grow piecewise re-segmentation (xatlas `PiecewiseParam`): split a chart
+ * whose LSCM map is still invalid into connected sub-charts that each
+ * parameterize bijectively by orthographic projection. Each sub-chart grows from
+ * a seed triangle, admitting an edge-adjacent triangle only if the projected
+ * sub-chart stays valid (no flip, no boundary self-intersection); a rejected
+ * triangle is left for a later sub-chart. A lone seed triangle is always valid,
+ * so this terminates and covers every triangle exactly once. Returned sub-charts
+ * are ortho-parameterized.
+ *
+ * (The validity re-check rebuilds the candidate each admission — O(k^2..k^3) for
+ * a k-triangle chart; acceptable for this rare fallback, an incremental check is
+ * a possible optimization.)
+ *
+ * @param {Chart} parent extracted chart (from atlas_extract_chart)
+ * @returns {Chart[]} ortho-parameterized sub-charts
+ */
+export function atlas_piecewise_resegment(parent: Chart): Chart[];
+import { Chart } from "../Chart.js";
+//# sourceMappingURL=atlas_piecewise_resegment.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"atlas_piecewise_resegment.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/geom/3d/atlas/param/atlas_piecewise_resegment.js"],"names":[],"mappings":"AA4GA;;;;;;;;;;;;;;;;GAgBG;AACH,kDAHW,KAAK,GACH,KAAK,EAAE,CAyCnB;sBApKqB,aAAa"}

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

@@ -0,0 +1,183 @@
+import { Chart } from "../Chart.js";
+import { atlas_chart_param_validity } from "./atlas_chart_param_validity.js";
+import { atlas_chart_parameterize_ortho } from "./atlas_chart_parameterize_ortho.js";
+
+/**
+ * Build per-triangle adjacency within a chart: `tri_neighbor[t*3 + i]` is the
+ * triangle sharing edge i (between corner i and corner i+1) of triangle t, or
+ * -1 if that edge is a chart boundary. Internal edges of a manifold patch have
+ * exactly two triangles; a non-manifold edge keeps the first pairing.
+ *
+ * @param {Chart} chart
+ * @returns {Int32Array} per-triangle adjacency (3 entries per triangle, -1 = boundary)
+ */
+function build_triangle_adjacency(chart) {
+    const T = chart.triangle_count;
+    const VC = chart.vertex_count;
+    const tri_neighbor = new Int32Array(T * 3).fill(-1);
+    const edge_map = new Map();
+
+    for (let t = 0; t < T; t++) {
+        for (let i = 0; i < 3; i++) {
+            const a = chart.tri_local[t * 3 + i];
+            const b = chart.tri_local[t * 3 + ((i + 1) % 3)];
+            const key = a < b ? a * VC + b : b * VC + a;
+
+            const prev = edge_map.get(key);
+            if (prev === undefined) {
+                edge_map.set(key, t * 3 + i);
+            } else {
+                tri_neighbor[t * 3 + i] = (prev / 3) | 0;
+                tri_neighbor[prev] = t;
+            }
+        }
+    }
+    return tri_neighbor;
+}
+
+/**
+ * Build a standalone {@link Chart} from a subset of `parent`'s triangles.
+ *
+ * @param {Chart} parent chart whose triangles are being subset
+ * @param {number[]} tri_indices parent-triangle indices to include in the sub-chart
+ * @param {Int32Array} tri_neighbor per-triangle adjacency (3 entries per triangle, -1 = boundary)
+ * @returns {Chart} a standalone sub-chart
+ */
+function build_subchart(parent, tri_indices, tri_neighbor) {
+    const member = new Set(tri_indices);
+    const local_of_parent = new Map();
+    const vertex_of_local = [];
+    const positions = [];
+    const tri_local = [];
+    const tri_loops = [];
+    const tri_face = [];
+    const boundary_edges = [];
+
+    for (const t of tri_indices) {
+        const corners = [0, 0, 0];
+        for (let i = 0; i < 3; i++) {
+            const pv = parent.tri_local[t * 3 + i];
+            let sv = local_of_parent.get(pv);
+            if (sv === undefined) {
+                sv = vertex_of_local.length;
+                local_of_parent.set(pv, sv);
+                vertex_of_local.push(parent.vertex_of_local[pv]);
+                positions.push(parent.positions[pv * 3], parent.positions[pv * 3 + 1], parent.positions[pv * 3 + 2]);
+            }
+            corners[i] = sv;
+        }
+
+        tri_local.push(corners[0], corners[1], corners[2]);
+        tri_loops.push(parent.tri_loops[t * 3], parent.tri_loops[t * 3 + 1], parent.tri_loops[t * 3 + 2]);
+        tri_face.push(parent.tri_face[t]);
+
+        for (let i = 0; i < 3; i++) {
+            const nb = tri_neighbor[t * 3 + i];
+            if (nb === -1 || !member.has(nb)) {
+                boundary_edges.push(corners[i], corners[(i + 1) % 3]);
+            }
+        }
+    }
+
+    const sub = new Chart();
+    sub.vertex_count = vertex_of_local.length;
+    sub.vertex_of_local = Uint32Array.from(vertex_of_local);
+    sub.positions = Float64Array.from(positions);
+    sub.triangle_count = tri_face.length;
+    sub.tri_local = Uint32Array.from(tri_local);
+    sub.tri_loops = Uint32Array.from(tri_loops);
+    sub.tri_face = Uint32Array.from(tri_face);
+    sub.boundary_edges = Uint32Array.from(boundary_edges);
+    sub.uv = new Float64Array(vertex_of_local.length * 2);
+    return sub;
+}
+
+/**
+ * Ortho-parameterize `chart` and test whether the resulting UV layout is
+ * bijective: no mixed winding, no boundary self-intersection, and no zero-area
+ * triangles.
+ *
+ * @param {Chart} chart sub-chart from {@link build_subchart}
+ * @returns {boolean} true if the orthographic projection is a valid layout
+ */
+function is_ortho_valid(chart) {
+    atlas_chart_parameterize_ortho(chart);
+    const v = atlas_chart_param_validity(chart);
+    return !v.mixed_winding && !v.self_intersects && v.zero_area_count === 0;
+}
+
+/**
+ * Region-grow piecewise re-segmentation (xatlas `PiecewiseParam`): split a chart
+ * whose LSCM map is still invalid into connected sub-charts that each
+ * parameterize bijectively by orthographic projection. Each sub-chart grows from
+ * a seed triangle, admitting an edge-adjacent triangle only if the projected
+ * sub-chart stays valid (no flip, no boundary self-intersection); a rejected
+ * triangle is left for a later sub-chart. A lone seed triangle is always valid,
+ * so this terminates and covers every triangle exactly once. Returned sub-charts
+ * are ortho-parameterized.
+ *
+ * (The validity re-check rebuilds the candidate each admission — O(k^2..k^3) for
+ * a k-triangle chart; acceptable for this rare fallback, an incremental check is
+ * a possible optimization.)
+ *
+ * @param {Chart} parent extracted chart (from atlas_extract_chart)
+ * @returns {Chart[]} ortho-parameterized sub-charts
+ */
+export function atlas_piecewise_resegment(parent) {
+    const T = parent.triangle_count;
+    const tri_neighbor = build_triangle_adjacency(parent);
+    const assigned = new Uint8Array(T);
+    const subcharts = [];
+
+    for (let seed = 0; seed < T; seed++) {
+        if (assigned[seed]) {
+            continue;
+        }
+
+        const subset = [seed];
+        assigned[seed] = 1;
+
+        const frontier = [];
+        push_neighbours(seed, tri_neighbor, assigned, frontier);
+
+        while (frontier.length > 0) {
+            const g = frontier.pop();
+            if (assigned[g]) {
+                continue;
+            }
+
+            subset.push(g);
+            const candidate = build_subchart(parent, subset, tri_neighbor);
+            if (is_ortho_valid(candidate)) {
+                assigned[g] = 1;
+                push_neighbours(g, tri_neighbor, assigned, frontier);
+            } else {
+                subset.pop();
+            }
+        }
+
+        const sub = build_subchart(parent, subset, tri_neighbor);
+        atlas_chart_parameterize_ortho(sub);
+        subcharts.push(sub);
+    }
+
+    return subcharts;
+}
+
+/**
+ * Push every not-yet-assigned edge-adjacent triangle of `t` onto the frontier.
+ *
+ * @param {number} t triangle index whose neighbours to enqueue
+ * @param {Int32Array} tri_neighbor per-triangle adjacency (3 entries per triangle, -1 = boundary)
+ * @param {Uint8Array} assigned 1 if a triangle is already claimed by a sub-chart
+ * @param {number[]} frontier growth queue of candidate triangle indices
+ * @returns {void}
+ */
+function push_neighbours(t, tri_neighbor, assigned, frontier) {
+    for (let i = 0; i < 3; i++) {
+        const nb = tri_neighbor[t * 3 + i];
+        if (nb !== -1 && !assigned[nb]) {
+            frontier.push(nb);
+        }
+    }
+}

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

@@ -0,0 +1,27 @@
+/**
+ * Fit a proxy-plane orthonormal basis to a set of 3D points (xatlas
+ * `Fit::computeBasis`). The plane normal is the smallest-variance principal
+ * axis — the eigenvector of the smallest eigenvalue of the point covariance —
+ * and the tangent/bitangent span the plane.
+ *
+ * The basis is written tangent (ATLAS_BASIS_TANGENT), bitangent
+ * (ATLAS_BASIS_BITANGENT), normal (ATLAS_BASIS_NORMAL); project a point onto
+ * the chart with `u = dot(tangent, p)`, `v = dot(bitangent, p)`.
+ *
+ * Precondition: point_count >= 1; a meaningful plane needs >= 3 non-collinear
+ * points (a degenerate set still yields a valid orthonormal basis, just an
+ * arbitrary in-plane orientation).
+ *
+ * @param {Float32Array|Float64Array|number[]} out_basis length >= 9
+ * @param {Float32Array|Float64Array|number[]} points flat xyz, length >= 3*point_count
+ * @param {number} point_count
+ */
+export function fit_plane_basis(out_basis: Float32Array | Float64Array | number[], points: Float32Array | Float64Array | number[], point_count: number): void;
+/**
+ * Offsets into a 9-float atlas basis. Layout matches
+ * {@link v3_orthonormal_matrix_from_normal}: tangent, bitangent, normal.
+ */
+export const ATLAS_BASIS_TANGENT: 0;
+export const ATLAS_BASIS_BITANGENT: 3;
+export const ATLAS_BASIS_NORMAL: 6;
+//# sourceMappingURL=fit_plane_basis.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fit_plane_basis.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/geom/3d/atlas/param/fit_plane_basis.js"],"names":[],"mappings":"AAeA;;;;;;;;;;;;;;;;;GAiBG;AACH,2CAJW,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,UAClC,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,eAClC,MAAM,QAkChB;AA9DD;;;GAGG;AACH,oCAAqC;AACrC,sCAAuC;AACvC,mCAAoC"}

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

@@ -0,0 +1,66 @@
+import { matrix_symmetric_3x3_eigen } from "../../../../math/linalg/eigen/matrix_symmetric_3x3_eigen.js";
+import { v3_orthonormal_matrix_from_normal } from "../../../vec3/v3_orthonormal_matrix_from_normal.js";
+
+/**
+ * Offsets into a 9-float atlas basis. Layout matches
+ * {@link v3_orthonormal_matrix_from_normal}: tangent, bitangent, normal.
+ */
+export const ATLAS_BASIS_TANGENT = 0;
+export const ATLAS_BASIS_BITANGENT = 3;
+export const ATLAS_BASIS_NORMAL = 6;
+
+const _cov = new Float64Array(9);
+const _values = new Float64Array(3);
+const _vectors = new Float64Array(9);
+
+/**
+ * Fit a proxy-plane orthonormal basis to a set of 3D points (xatlas
+ * `Fit::computeBasis`). The plane normal is the smallest-variance principal
+ * axis — the eigenvector of the smallest eigenvalue of the point covariance —
+ * and the tangent/bitangent span the plane.
+ *
+ * The basis is written tangent (ATLAS_BASIS_TANGENT), bitangent
+ * (ATLAS_BASIS_BITANGENT), normal (ATLAS_BASIS_NORMAL); project a point onto
+ * the chart with `u = dot(tangent, p)`, `v = dot(bitangent, p)`.
+ *
+ * Precondition: point_count >= 1; a meaningful plane needs >= 3 non-collinear
+ * points (a degenerate set still yields a valid orthonormal basis, just an
+ * arbitrary in-plane orientation).
+ *
+ * @param {Float32Array|Float64Array|number[]} out_basis length >= 9
+ * @param {Float32Array|Float64Array|number[]} points flat xyz, length >= 3*point_count
+ * @param {number} point_count
+ */
+export function fit_plane_basis(out_basis, points, point_count) {
+    let cx = 0, cy = 0, cz = 0;
+    for (let i = 0; i < point_count; i++) {
+        const i3 = i * 3;
+        cx += points[i3];
+        cy += points[i3 + 1];
+        cz += points[i3 + 2];
+    }
+    const inv = 1 / point_count;
+    cx *= inv;
+    cy *= inv;
+    cz *= inv;
+
+    let c00 = 0, c01 = 0, c02 = 0, c11 = 0, c12 = 0, c22 = 0;
+    for (let i = 0; i < point_count; i++) {
+        const i3 = i * 3;
+        const dx = points[i3] - cx;
+        const dy = points[i3 + 1] - cy;
+        const dz = points[i3 + 2] - cz;
+        c00 += dx * dx; c01 += dx * dy; c02 += dx * dz;
+        c11 += dy * dy; c12 += dy * dz;
+        c22 += dz * dz;
+    }
+
+    _cov[0] = c00; _cov[1] = c01; _cov[2] = c02;
+    _cov[3] = c01; _cov[4] = c11; _cov[5] = c12;
+    _cov[6] = c02; _cov[7] = c12; _cov[8] = c22;
+
+    matrix_symmetric_3x3_eigen(_values, _vectors, _cov);
+
+    // smallest eigenvalue is index 0 -> its eigenvector is the plane normal
+    v3_orthonormal_matrix_from_normal(out_basis, 0, _vectors[0], _vectors[1], _vectors[2]);
+}

package/src/core/geom/3d/atlas/segment/RegionGraph.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Planar-region adjacency graph for region-atomic chart segmentation (the
+ * coarsening of a segmented mesh produced by {@link atlas_build_region_graph}).
+ * Each planar region is a node; adjacent region pairs are undirected CSR edges.
+ *
+ * Per-node arrays are indexed by region id; the CSR arrays (`adj`, `adj_shared`,
+ * `adj_seam`) are indexed by edge slot, with `offsets[r]..offsets[r+1]` giving
+ * region r's neighbour slots.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class RegionGraph {
+    /** Number of planar regions. @type {number} */
+    region_count: number;
+    /** Total 3D area per region. @type {Float32Array} */
+    region_area: Float32Array;
+    /** Area-weighted (un-normalized) normal accumulator per region — 3 floats each. @type {Float32Array} */
+    region_normal: Float32Array;
+    /** Boundary length per region. @type {Float32Array} */
+    region_boundary: Float32Array;
+    /** CSR row offsets, length region_count + 1. @type {Uint32Array} */
+    offsets: Uint32Array;
+    /** CSR neighbour region ids. @type {Uint32Array} */
+    adj: Uint32Array;
+    /** Shared boundary length per CSR edge slot. @type {Float32Array} */
+    adj_shared: Float32Array;
+    /** Accumulated normal-seam cost per CSR edge slot. @type {Float32Array} */
+    adj_seam: Float32Array;
+}
+//# sourceMappingURL=RegionGraph.d.ts.map

package/src/core/geom/3d/atlas/segment/RegionGraph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RegionGraph.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/geom/3d/atlas/segment/RegionGraph.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;GAWG;AACH;IACI,+CAA+C;IAC/C,cADqC,MAAM,CAC1B;IAEjB,qDAAqD;IACrD,aADqC,YAAY,CACzB;IAExB,wGAAwG;IACxG,eADwF,YAAY,CAC1E;IAE1B,uDAAuD;IACvD,iBADuC,YAAY,CACvB;IAE5B,oEAAoE;IACpE,SADqD,WAAW,CAC5C;IAEpB,oDAAoD;IACpD,KADqC,WAAW,CAChC;IAEhB,qEAAqE;IACrE,YADqD,YAAY,CAC1C;IAEvB,2EAA2E;IAC3E,UAD2D,YAAY,CAClD;CACxB"}

package/src/core/geom/3d/atlas/segment/RegionGraph.js

@@ -0,0 +1,40 @@
+const EMPTY_U32 = new Uint32Array(0);
+const EMPTY_F32 = new Float32Array(0);
+
+/**
+ * Planar-region adjacency graph for region-atomic chart segmentation (the
+ * coarsening of a segmented mesh produced by {@link atlas_build_region_graph}).
+ * Each planar region is a node; adjacent region pairs are undirected CSR edges.
+ *
+ * Per-node arrays are indexed by region id; the CSR arrays (`adj`, `adj_shared`,
+ * `adj_seam`) are indexed by edge slot, with `offsets[r]..offsets[r+1]` giving
+ * region r's neighbour slots.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class RegionGraph {
+    /** Number of planar regions. @type {number} */
+    region_count = 0;
+
+    /** Total 3D area per region. @type {Float32Array} */
+    region_area = EMPTY_F32;
+
+    /** Area-weighted (un-normalized) normal accumulator per region — 3 floats each. @type {Float32Array} */
+    region_normal = EMPTY_F32;
+
+    /** Boundary length per region. @type {Float32Array} */
+    region_boundary = EMPTY_F32;
+
+    /** CSR row offsets, length region_count + 1. @type {Uint32Array} */
+    offsets = EMPTY_U32;
+
+    /** CSR neighbour region ids. @type {Uint32Array} */
+    adj = EMPTY_U32;
+
+    /** Shared boundary length per CSR edge slot. @type {Float32Array} */
+    adj_shared = EMPTY_F32;
+
+    /** Accumulated normal-seam cost per CSR edge slot. @type {Float32Array} */
+    adj_seam = EMPTY_F32;
+}

package/src/core/geom/3d/atlas/segment/atlas_build_region_graph.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Coarsen a segmented mesh into a planar-region adjacency graph for
+ * region-atomic chart growth (xatlas `nextRegionFace`). Each planar region
+ * (from {@link atlas_compute_planar_regions}) becomes a node carrying its total
+ * area, its area-weighted (un-normalized) normal accumulator, and its boundary
+ * length; each pair of adjacent regions becomes an undirected CSR edge carrying
+ * the shared boundary length and the accumulated normal-seam cost
+ * `Σ len·(1 − dihedral_dot)`.
+ *
+ * Precondition: face normals populated; `region_of_face` / `region_count` from
+ * atlas_compute_planar_regions; the AtlasData arrays from M1.
+ *
+ * @param {BinaryTopology} mesh
+ * @param {Uint32Array} region_of_face face -> region id (NULL_POINTER if unallocated)
+ * @param {number} region_count
+ * @param {Float32Array} face_areas
+ * @param {Float32Array} edge_lengths
+ * @param {Float32Array} edge_dihedrals
+ * @returns {RegionGraph}
+ */
+export function atlas_build_region_graph(mesh: BinaryTopology, region_of_face: Uint32Array, region_count: number, face_areas: Float32Array, edge_lengths: Float32Array, edge_dihedrals: Float32Array): RegionGraph;
+import { RegionGraph } from "./RegionGraph.js";
+//# sourceMappingURL=atlas_build_region_graph.d.ts.map

package/src/core/geom/3d/atlas/segment/atlas_build_region_graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"atlas_build_region_graph.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/geom/3d/atlas/segment/atlas_build_region_graph.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,+EAPW,WAAW,gBACX,MAAM,cACN,YAAY,gBACZ,YAAY,kBACZ,YAAY,GACV,WAAW,CAiHvB;4BArI2B,kBAAkB"}

package/src/core/geom/3d/atlas/segment/atlas_build_region_graph.js

@@ -0,0 +1,136 @@
+import { NULL_POINTER } from "../../topology/struct/binary/BinaryTopology.js";
+import { EDGE_DIHEDRAL_BOUNDARY } from "../data/atlas_build_edge_dihedrals.js";
+import { RegionGraph } from "./RegionGraph.js";
+
+/**
+ * Coarsen a segmented mesh into a planar-region adjacency graph for
+ * region-atomic chart growth (xatlas `nextRegionFace`). Each planar region
+ * (from {@link atlas_compute_planar_regions}) becomes a node carrying its total
+ * area, its area-weighted (un-normalized) normal accumulator, and its boundary
+ * length; each pair of adjacent regions becomes an undirected CSR edge carrying
+ * the shared boundary length and the accumulated normal-seam cost
+ * `Σ len·(1 − dihedral_dot)`.
+ *
+ * Precondition: face normals populated; `region_of_face` / `region_count` from
+ * atlas_compute_planar_regions; the AtlasData arrays from M1.
+ *
+ * @param {BinaryTopology} mesh
+ * @param {Uint32Array} region_of_face face -> region id (NULL_POINTER if unallocated)
+ * @param {number} region_count
+ * @param {Float32Array} face_areas
+ * @param {Float32Array} edge_lengths
+ * @param {Float32Array} edge_dihedrals
+ * @returns {RegionGraph}
+ */
+export function atlas_build_region_graph(mesh, region_of_face, region_count, face_areas, edge_lengths, edge_dihedrals) {
+    const faces = mesh.faces;
+    const face_count = faces.size;
+
+    const region_area = new Float32Array(region_count);
+    const region_normal = new Float32Array(region_count * 3);
+    const region_boundary = new Float32Array(region_count);
+
+    const fn = new Float32Array(3);
+    for (let f = 0; f < face_count; f++) {
+        if (!faces.is_allocated(f)) {
+            continue;
+        }
+        const r = region_of_face[f];
+        if (r === NULL_POINTER) {
+            continue;
+        }
+        const a = face_areas[f];
+        region_area[r] += a;
+        mesh.face_read_normal(fn, 0, f);
+        region_normal[r * 3] += fn[0] * a;
+        region_normal[r * 3 + 1] += fn[1] * a;
+        region_normal[r * 3 + 2] += fn[2] * a;
+    }
+
+    const edges = mesh.edges;
+    const edge_count = edges.size;
+    const pair_map = new Map();
+
+    for (let e = 0; e < edge_count; e++) {
+        if (!edges.is_allocated(e)) {
+            continue;
+        }
+        const len = edge_lengths[e];
+
+        const l1 = mesh.edge_read_loop(e);
+        if (l1 === NULL_POINTER) {
+            continue;
+        }
+        const l2 = mesh.loop_read_radial_next(l1);
+
+        if (l2 === l1) {
+            // mesh boundary edge -> boundary of its single region
+            const r = region_of_face[mesh.loop_read_face(l1)];
+            if (r !== NULL_POINTER) {
+                region_boundary[r] += len;
+            }
+            continue;
+        }
+
+        const r1 = region_of_face[mesh.loop_read_face(l1)];
+        const r2 = region_of_face[mesh.loop_read_face(l2)];
+        if (r1 === r2 || r1 === NULL_POINTER || r2 === NULL_POINTER) {
+            continue;
+        }
+
+        // region-boundary edge between r1 and r2
+        region_boundary[r1] += len;
+        region_boundary[r2] += len;
+
+        const a = r1 < r2 ? r1 : r2;
+        const b = r1 < r2 ? r2 : r1;
+        const key = a * region_count + b;
+        let rec = pair_map.get(key);
+        if (rec === undefined) {
+            rec = { a, b, len: 0, seam: 0 };
+            pair_map.set(key, rec);
+        }
+        const dih = edge_dihedrals[e];
+        const dd = dih === EDGE_DIHEDRAL_BOUNDARY ? 1 : dih;
+        rec.len += len;
+        rec.seam += len * (1 - dd);
+    }
+
+    // Build the symmetric CSR adjacency from the pair map.
+    const degree = new Uint32Array(region_count);
+    for (const rec of pair_map.values()) {
+        degree[rec.a]++;
+        degree[rec.b]++;
+    }
+    const offsets = new Uint32Array(region_count + 1);
+    for (let r = 0; r < region_count; r++) {
+        offsets[r + 1] = offsets[r] + degree[r];
+    }
+    const adj_len = offsets[region_count];
+    const adj = new Uint32Array(adj_len);
+    const adj_shared = new Float32Array(adj_len);
+    const adj_seam = new Float32Array(adj_len);
+
+    const cursor = offsets.slice(0, region_count);
+    for (const rec of pair_map.values()) {
+        const ia = cursor[rec.a]++;
+        adj[ia] = rec.b;
+        adj_shared[ia] = rec.len;
+        adj_seam[ia] = rec.seam;
+        const ib = cursor[rec.b]++;
+        adj[ib] = rec.a;
+        adj_shared[ib] = rec.len;
+        adj_seam[ib] = rec.seam;
+    }
+
+    const graph = new RegionGraph();
+    graph.region_count = region_count;
+    graph.region_area = region_area;
+    graph.region_normal = region_normal;
+    graph.region_boundary = region_boundary;
+    graph.offsets = offsets;
+    graph.adj = adj;
+    graph.adj_shared = adj_shared;
+    graph.adj_seam = adj_seam;
+    return graph;
+}

package/src/core/geom/3d/atlas/segment/atlas_compute_planar_regions.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Merge connected, (near-)coplanar faces into planar regions via union-find
+ * over interior edges (xatlas `computePlanarCharts` seeding). Two faces sharing
+ * an edge are unioned when the edge's adjacent-normal dot is >= 1 - tolerance.
+ * Boundary edges never merge across.
+ *
+ * @param {BinaryTopology} mesh
+ * @param {Float32Array} edge_dihedrals from {@link atlas_build_edge_dihedrals}
+ * @param {number} [coplanar_tolerance]
+ * @returns {{region_of_face: Uint32Array, region_count: number}} `region_of_face`
+ *   maps each allocated face to a dense region id in [0, region_count);
+ *   unallocated faces map to {@link NULL_POINTER}.
+ */
+export function atlas_compute_planar_regions(mesh: BinaryTopology, edge_dihedrals: Float32Array, coplanar_tolerance?: number): {
+    region_of_face: Uint32Array;
+    region_count: number;
+};
+/**
+ * How close to coplanar (adjacent-normal dot == 1) two faces must be to merge
+ * into the same planar region. xatlas uses a strict kEpsilon coplanarity test.
+ * @type {number}
+ */
+export const ATLAS_COPLANAR_TOLERANCE: number;
+//# sourceMappingURL=atlas_compute_planar_regions.d.ts.map

package/src/core/geom/3d/atlas/segment/atlas_compute_planar_regions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"atlas_compute_planar_regions.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/geom/3d/atlas/segment/atlas_compute_planar_regions.js"],"names":[],"mappings":"AAWA;;;;;;;;;;;;GAYG;AACH,mFANW,YAAY,uBACZ,MAAM;oBACa,WAAW;kBAAgB,MAAM;EAwD9D;AAxED;;;;GAIG;AACH,uCAFU,MAAM,CAE6B"}