@woosh/meep-engine 2.164.0 → 2.165.0

package/src/core/geom/3d/atlas/atlas_bench_lib.js

@@ -0,0 +1,315 @@
+import { BinaryTopology, NULL_POINTER } from "../topology/struct/binary/BinaryTopology.js";
+import { bt_mesh_from_unindexed_geometry } from "../topology/struct/binary/io/bt_mesh_from_unindexed_geometry.js";
+import { bt_mesh_simplify_by_error } from "../topology/struct/binary/io/bt_mesh_simplify_by_error.js";
+import { CHART_TYPE } from "./atlas_chart_type.js";
+import { atlas_compute_charts } from "./atlas_compute_charts.js";
+import { atlas_pack_charts } from "./pack/atlas_pack_charts.js";
+import { atlas_chart_stretch_metric } from "./param/atlas_chart_stretch_metric.js";
+
+/**
+ * Test/bench-only shared library for the atlas metrics benches. NOT imported by
+ * production code. Provides deterministic geometry generators (triangle soups),
+ * a rich per-run metric panel (chart count, stretch distribution incl. the
+ * high-distortion tail, chart-type histogram, seam length, packing utilization),
+ * and an A/B runner so a candidate option can be measured against the baseline
+ * with a directional gate.
+ *
+ * The metrics here are the standing instrument for validating the REVIEW_02.md
+ * "top opportunities": LSCM stretch tail (-> ARAP/cone-fit), chart count + seam
+ * length (-> mergeCharts), and packing utilization (-> best-fit placement).
+ */
+
+// ─── Geometry generators (deterministic triangle soups) ──────────────────────
+function pushTri(soup, ax, ay, az, bx, by, bz, cx, cy, cz) {
+    soup.push(ax, ay, az, bx, by, bz, cx, cy, cz);
+}
+
+/** Quad as two triangles; skips degenerate (coincident-vertex) triangles. */
+function pushQuad(soup, a, b, c, d) {
+    if (!(same(a, b) || same(b, c) || same(a, c))) pushTri(soup, a[0], a[1], a[2], b[0], b[1], b[2], c[0], c[1], c[2]);
+    if (!(same(a, c) || same(c, d) || same(a, d))) pushTri(soup, a[0], a[1], a[2], c[0], c[1], c[2], d[0], d[1], d[2]);
+}
+
+function same(a, b) {
+    return a[0] === b[0] && a[1] === b[1] && a[2] === b[2];
+}
+
+/** Flat n×n plane in z=0. Single planar region => one chart, zero stretch. */
+export function soup_plane(n) {
+    const soup = [];
+    const v = (i, j) => [i / n, j / n, 0];
+    for (let j = 0; j < n; j++) for (let i = 0; i < n; i++) pushQuad(soup, v(i, j), v(i + 1, j), v(i + 1, j + 1), v(i, j + 1));
+    return soup;
+}
+
+/** Deterministic gently-bumpy terrain (curved, smooth, no RNG). */
+export function soup_terrain(n, amplitude) {
+    const h = (i, j) => amplitude * (Math.sin(i * 0.35) * Math.cos(j * 0.4) + 0.5 * Math.sin(i * 0.8 + j * 0.25));
+    const v = (i, j) => [i / n, j / n, h(i, j)];
+    const soup = [];
+    for (let j = 0; j < n; j++) for (let i = 0; i < n; i++) pushQuad(soup, v(i, j), v(i + 1, j), v(i + 1, j + 1), v(i, j + 1));
+    return soup;
+}
+
+/** Dense bumpy terrain decimated by the production simplifier -> irregular, over-segmenting asset. */
+export function soup_decimated_terrain(n, amplitude, error) {
+    const mesh = build_mesh(soup_terrain(n, amplitude));
+    bt_mesh_simplify_by_error(mesh, error);
+    return topology_to_soup(mesh);
+}
+
+/** UV sphere (fanned poles, no degenerate tris). Smooth closed surface. */
+export function soup_uv_sphere(rings, sectors) {
+    const soup = [];
+    const north = [0, 1, 0], south = [0, -1, 0];
+    const pos = (i, s) => {
+        const phi = (i / rings) * Math.PI, th = (s / sectors) * 2 * Math.PI;
+        return [Math.sin(phi) * Math.cos(th), Math.cos(phi), Math.sin(phi) * Math.sin(th)];
+    };
+    const vtx = (i, s) => (i === 0 ? north : i === rings ? south : pos(i, s));
+    for (let i = 0; i < rings; i++) for (let s = 0; s < sectors; s++) {
+        pushQuad(soup, vtx(i, s), vtx(i + 1, s), vtx(i + 1, s + 1), vtx(i, s + 1));
+    }
+    return soup;
+}
+
+/** Upper hemisphere cap (intrinsic positive curvature -> MUST distort under any flattening). */
+export function soup_hemisphere(rings, sectors) {
+    const soup = [];
+    const north = [0, 1, 0];
+    const pos = (i, s) => {
+        const phi = (i / rings) * (Math.PI / 2), th = (s / sectors) * 2 * Math.PI;
+        return [Math.sin(phi) * Math.cos(th), Math.cos(phi), Math.sin(phi) * Math.sin(th)];
+    };
+    const vtx = (i, s) => (i === 0 ? north : pos(i, s));
+    for (let i = 0; i < rings; i++) for (let s = 0; s < sectors; s++) {
+        pushQuad(soup, vtx(i, s), vtx(i + 1, s), vtx(i + 1, s + 1), vtx(i, s + 1));
+    }
+    return soup;
+}
+
+/** Open cylinder side (no caps): a DEVELOPABLE surface — should flatten to a flat strip with ~zero stretch. */
+export function soup_cylinder_open(radial, rings, height, radius) {
+    const soup = [];
+    const v = (i, s) => {
+        const y = -height / 2 + (i / rings) * height, th = (s / radial) * 2 * Math.PI;
+        return [radius * Math.cos(th), y, radius * Math.sin(th)];
+    };
+    for (let i = 0; i < rings; i++) for (let s = 0; s < radial; s++) pushQuad(soup, v(i, s), v(i + 1, s), v(i + 1, s + 1), v(i, s + 1));
+    return soup;
+}
+
+/** Open cone side (no base): DEVELOPABLE — flattens to a circular sector with ~zero stretch. */
+export function soup_cone_open(radial, rings, height, radius) {
+    const soup = [];
+    const apex = [0, height, 0];
+    const v = (i, s) => {
+        const t = i / rings, th = (s / radial) * 2 * Math.PI;
+        return [t * radius * Math.cos(th), (1 - t) * height, t * radius * Math.sin(th)];
+    };
+    const vtx = (i, s) => (i === 0 ? apex : v(i, s));
+    for (let i = 0; i < rings; i++) for (let s = 0; s < radial; s++) pushQuad(soup, vtx(i, s), vtx(i + 1, s), vtx(i + 1, s + 1), vtx(i, s + 1));
+    return soup;
+}
+
+/** Torus: irregular, curved charts (a packing stress fixture). */
+export function soup_torus(rings, sides, R, rr) {
+    const soup = [];
+    const v = (i, j) => {
+        const u = (i / rings) * 2 * Math.PI, w = (j / sides) * 2 * Math.PI;
+        const cx = R + rr * Math.cos(w);
+        return [cx * Math.cos(u), rr * Math.sin(w), cx * Math.sin(u)];
+    };
+    for (let i = 0; i < rings; i++) for (let j = 0; j < sides; j++) pushQuad(soup, v(i, j), v(i + 1, j), v(i + 1, j + 1), v(i, j + 1));
+    return soup;
+}
+
+/** Grid of unit cubes (each cube => 6 charts at 90°; a chart-count fixture). */
+export function soup_cube_field(count) {
+    const soup = [];
+    const corners = [[0, 0, 0], [1, 0, 0], [1, 1, 0], [0, 1, 0], [0, 0, 1], [1, 0, 1], [1, 1, 1], [0, 1, 1]];
+    const quads = [[0, 1, 5, 4], [1, 2, 6, 5], [2, 3, 7, 6], [3, 0, 4, 7], [3, 2, 1, 0], [4, 5, 6, 7]];
+    const side = Math.ceil(Math.cbrt(count));
+    for (let n = 0; n < count; n++) {
+        const ox = (n % side) * 2, oy = (Math.floor(n / side) % side) * 2, oz = Math.floor(n / (side * side)) * 2;
+        const c = corners.map((p) => [ox + p[0], oy + p[1], oz + p[2]]);
+        for (const q of quads) pushQuad(soup, c[q[0]], c[q[1]], c[q[2]], c[q[3]]);
+    }
+    return soup;
+}
+
+export function build_mesh(soup) {
+    const mesh = new BinaryTopology();
+    bt_mesh_from_unindexed_geometry(mesh, soup);
+    return mesh;
+}
+
+function topology_to_soup(mesh) {
+    const soup = [];
+    const a = [0, 0, 0];
+    const faces = mesh.faces;
+    for (let f = 0; f < faces.size; f++) {
+        if (!faces.is_allocated(f)) continue;
+        let l = mesh.face_read_loop(f);
+        const start = l;
+        const verts = [];
+        do {
+            mesh.vertex_read_coordinate(a, 0, mesh.loop_read_vertex(l));
+            verts.push(a[0], a[1], a[2]);
+            l = mesh.loop_read_next(l);
+        } while (l !== start);
+        if (verts.length === 9) soup.push(...verts);
+    }
+    return soup;
+}
+
+// ─── Metrics ─────────────────────────────────────────────────────────────────
+/** Charts whose worst (L∞) per-triangle stretch exceeds this count as the "high-distortion tail". */
+export const TAIL_STRETCH = 2.0;
+
+function percentile(sorted, p) {
+    if (sorted.length === 0) return 0;
+    return sorted[Math.min(sorted.length - 1, Math.floor(p * sorted.length))];
+}
+
+/**
+ * Per-run chart-quality metrics. `charts` are finalized charts (each with
+ * `surface_area`, `parametric_area`, `type`, and solved `uv`).
+ *
+ * @param {Chart[]} charts
+ * @returns {object} chart_count, ortho/lscm/piecewise counts, area-weighted
+ *   mean_stretch, max_stretch, p50/p90/p99 of per-chart worst stretch,
+ *   tail_count + tail_area_frac (charts above TAIL_STRETCH), degenerate count.
+ */
+export function chart_metrics(charts) {
+    let total_area = 0, weighted_mean_sum = 0, max_stretch = 0, degenerate = 0;
+    let tail_count = 0, tail_area = 0;
+    const per_chart_max = [];
+    const types = { ortho: 0, lscm: 0, piecewise: 0, bff: 0 };
+
+    for (const c of charts) {
+        if (c.type === CHART_TYPE.ORTHO) types.ortho++;
+        else if (c.type === CHART_TYPE.LSCM) types.lscm++;
+        else if (c.type === CHART_TYPE.PIECEWISE) types.piecewise++;
+        else if (c.type === CHART_TYPE.BFF) types.bff++;
+
+        const m = atlas_chart_stretch_metric(c);
+        if (!Number.isFinite(m.mean_stretch) || !Number.isFinite(m.max_stretch)) {
+            degenerate++;
+            continue;
+        }
+        const area = c.surface_area;
+        total_area += area;
+        weighted_mean_sum += m.mean_stretch * area;
+        per_chart_max.push(m.max_stretch);
+        if (m.max_stretch > max_stretch) max_stretch = m.max_stretch;
+        if (m.max_stretch > TAIL_STRETCH) { tail_count++; tail_area += area; }
+    }
+
+    per_chart_max.sort((a, b) => a - b);
+    return {
+        chart_count: charts.length,
+        types,
+        mean_stretch: total_area > 0 ? weighted_mean_sum / total_area : 0,
+        max_stretch,
+        p50_stretch: percentile(per_chart_max, 0.5),
+        p90_stretch: percentile(per_chart_max, 0.9),
+        p99_stretch: percentile(per_chart_max, 0.99),
+        tail_count,
+        tail_area_frac: total_area > 0 ? tail_area / total_area : 0,
+        degenerate,
+    };
+}
+
+/** Total 3D length of edges cut between different charts (texture seams) + fraction of interior length. */
+export function seam_metrics(mesh, charts) {
+    const face_chart = new Int32Array(mesh.faces.size).fill(-1);
+    for (let ci = 0; ci < charts.length; ci++) {
+        const c = charts[ci];
+        for (let t = 0; t < c.triangle_count; t++) face_chart[c.tri_face[t]] = ci;
+    }
+    const v1 = [0, 0, 0], v2 = [0, 0, 0];
+    let seam_len = 0, interior_len = 0;
+    const edges = mesh.edges;
+    for (let e = 0; e < edges.size; e++) {
+        if (!edges.is_allocated(e)) continue;
+        const l1 = mesh.edge_read_loop(e);
+        if (l1 === NULL_POINTER) continue;
+        const l2 = mesh.loop_read_radial_next(l1);
+        if (l2 === l1) continue; // boundary edge, not a cut
+        mesh.vertex_read_coordinate(v1, 0, mesh.edge_read_vertex1(e));
+        mesh.vertex_read_coordinate(v2, 0, mesh.edge_read_vertex2(e));
+        const len = Math.hypot(v1[0] - v2[0], v1[1] - v2[1], v1[2] - v2[2]);
+        interior_len += len;
+        if (face_chart[mesh.loop_read_face(l1)] !== face_chart[mesh.loop_read_face(l2)]) seam_len += len;
+    }
+    return { seam_len, seam_pct: interior_len > 0 ? (seam_len / interior_len) * 100 : 0, interior_len };
+}
+
+// ─── Pipeline + A/B runner ───────────────────────────────────────────────────
+/**
+ * Run the full pipeline once and return the metric panel. Always rebuilds the
+ * mesh from the soup so packing-only A/Bs are independent (pack mutates uv).
+ *
+ * @param {number[]} soup triangle soup
+ * @param {object} [computeOpts] atlas_compute_charts options
+ * @param {object} [packOpts] atlas_pack_charts options
+ * @returns {object} flattened metric panel
+ */
+export function measure(soup, computeOpts = {}, packOpts = {}) {
+    const mesh = build_mesh(soup);
+    const computed = atlas_compute_charts(mesh, computeOpts);
+    const packed = atlas_pack_charts(computed.charts, packOpts);
+    const cm = chart_metrics(computed.charts);
+    const sm = seam_metrics(mesh, computed.charts);
+    return {
+        ...cm,
+        seam_len: sm.seam_len,
+        seam_pct: sm.seam_pct,
+        utilization: packed.utilization,
+        pages: packed.page_count,
+        atlas: `${packed.atlas_width}x${packed.atlas_height}`,
+    };
+}
+
+/** Median wall-clock of `fn` over a time budget, with warmup. */
+export function time_median(fn, budget_ms = 2000, warmup = 2) {
+    for (let i = 0; i < warmup; i++) fn();
+    const samples = [];
+    const start = performance.now();
+    while (performance.now() - start < budget_ms) {
+        const t0 = performance.now();
+        fn();
+        samples.push(performance.now() - t0);
+    }
+    samples.sort((a, b) => a - b);
+    return percentile(samples, 0.5);
+}
+
+/**
+ * A/B: measure baseline vs candidate on the same fixture and return both panels
+ * plus per-key deltas. The caller asserts the expected direction (the gate).
+ *
+ * @param {number[]} soup
+ * @param {{compute?:object, pack?:object}} a baseline options
+ * @param {{compute?:object, pack?:object}} b candidate options
+ * @returns {{base:object, cand:object, delta:object}}
+ */
+export function ab(soup, a, b) {
+    const base = measure(soup, a.compute, a.pack);
+    const cand = measure(soup, b.compute, b.pack);
+    const delta = {};
+    for (const k of ["chart_count", "mean_stretch", "max_stretch", "p90_stretch", "p99_stretch", "tail_count", "tail_area_frac", "seam_len", "seam_pct", "utilization"]) {
+        delta[k] = cand[k] - base[k];
+    }
+    return { base, cand, delta };
+}
+
+/** Compact one-line metric panel for console output. */
+export function fmt(m) {
+    return `charts ${m.chart_count} (O${m.types.ortho}/L${m.types.lscm}/P${m.types.piecewise}/B${m.types.bff})` +
+        `  stretch mean ${m.mean_stretch.toFixed(3)} max ${m.max_stretch.toFixed(1)} p90 ${m.p90_stretch.toFixed(2)} p99 ${m.p99_stretch.toFixed(2)}` +
+        `  tail ${m.tail_count} (${(m.tail_area_frac * 100).toFixed(1)}% area)` +
+        `  seam ${m.seam_len.toFixed(2)} (${m.seam_pct.toFixed(1)}%)` +
+        `  util ${(m.utilization * 100).toFixed(1)}%  ${m.atlas} x${m.pages}`;
+}

package/src/core/geom/3d/atlas/atlas_chart_type.d.ts

@@ -0,0 +1,17 @@
+/**
+ * How a chart's UVs were produced. Typed constant (no stringly-typed states),
+ * mirroring xatlas `ChartType`.
+ * @readonly
+ */
+export const CHART_TYPE: Readonly<{
+    /** Orthographic projection accepted (planar or near-planar). */
+    ORTHO: 0;
+    /** Least-squares conformal map. */
+    LSCM: 1;
+    /** Single-triangle fallback after ortho and LSCM both failed validity. */
+    PIECEWISE: 2;
+    /** Boundary-first flattening: intrinsic low-distortion boundary + conformal
+     *  interior, the rescue for a chart whose LSCM free boundary self-intersects. */
+    BFF: 3;
+}>;
+//# sourceMappingURL=atlas_chart_type.d.ts.map

package/src/core/geom/3d/atlas/atlas_chart_type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"atlas_chart_type.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/atlas/atlas_chart_type.js"],"names":[],"mappings":"AAAA;;;;GAIG;AACH;IACI,gEAAgE;;IAEhE,mCAAmC;;IAEnC,0EAA0E;;IAE1E;qFACiF;;GAElF"}

package/src/core/geom/3d/atlas/atlas_chart_type.js

@@ -0,0 +1,16 @@
+/**
+ * How a chart's UVs were produced. Typed constant (no stringly-typed states),
+ * mirroring xatlas `ChartType`.
+ * @readonly
+ */
+export const CHART_TYPE = Object.freeze({
+    /** Orthographic projection accepted (planar or near-planar). */
+    ORTHO: 0,
+    /** Least-squares conformal map. */
+    LSCM: 1,
+    /** Single-triangle fallback after ortho and LSCM both failed validity. */
+    PIECEWISE: 2,
+    /** Boundary-first flattening: intrinsic low-distortion boundary + conformal
+     *  interior, the rescue for a chart whose LSCM free boundary self-intersects. */
+    BFF: 3,
+});

package/src/core/geom/3d/atlas/atlas_compute_charts.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Compute UV charts for a mesh (xatlas `ComputeCharts`): condition the mesh,
+ * segment it, and parameterize each chart. The returned charts carry their own
+ * vertex/triangle tables and per-chart UVs (local, unpacked) in `chart.uv`, ready
+ * for {@link atlas_pack_charts}. UVs are NOT written onto the mesh here — that is
+ * the explicit {@link atlas_write_chart_uvs} step (kept separate so charts from
+ * several meshes can be packed together before being actualized).
+ *
+ * @param {BinaryTopology} mesh mutated in place (welding, normals) but not its loop UVs
+ * @param {object} [options]
+ * @param {boolean} [options.weld] colocal-weld the input first (default true)
+ * @param {object} [options.segment] overrides for atlas_segment_charts
+ * @param {object} [options.lscm] overrides for atlas_chart_parameterize_lscm
+ * @returns {{charts: Chart[], face_chart: Int32Array, chart_count: number}}
+ */
+export function atlas_compute_charts(mesh: BinaryTopology, options?: {
+    weld?: boolean;
+    segment?: object;
+    lscm?: object;
+}): {
+    charts: Chart[];
+    face_chart: Int32Array;
+    chart_count: number;
+};
+//# sourceMappingURL=atlas_compute_charts.d.ts.map

package/src/core/geom/3d/atlas/atlas_compute_charts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"atlas_compute_charts.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/atlas/atlas_compute_charts.js"],"names":[],"mappings":"AAiHA;;;;;;;;;;;;;;GAcG;AACH;IAL6B,IAAI,GAAtB,OAAO;IACU,OAAO,GAAxB,MAAM;IACW,IAAI,GAArB,MAAM;;YACK,OAAO;gBAAc,UAAU;iBAAe,MAAM;EA6DzE"}

package/src/core/geom/3d/atlas/atlas_compute_charts.js

@@ -0,0 +1,188 @@
+import { bt_mesh_compute_face_normals } from "../topology/struct/binary/io/bt_mesh_compute_face_normals.js";
+import { CHART_TYPE } from "./atlas_chart_type.js";
+import { atlas_extract_chart } from "./atlas_extract_chart.js";
+import { atlas_build_edge_dihedrals } from "./data/atlas_build_edge_dihedrals.js";
+import { atlas_build_edge_lengths } from "./data/atlas_build_edge_lengths.js";
+import { atlas_build_face_areas } from "./data/atlas_build_face_areas.js";
+import { atlas_mesh_weld_colocals } from "./io/atlas_mesh_weld_colocals.js";
+import { atlas_chart_param_validity } from "./param/atlas_chart_param_validity.js";
+import { atlas_chart_parameterize_bff } from "./param/atlas_chart_parameterize_bff.js";
+import { atlas_chart_parameterize_lscm } from "./param/atlas_chart_parameterize_lscm.js";
+import { atlas_chart_parameterize_ortho } from "./param/atlas_chart_parameterize_ortho.js";
+import { atlas_chart_stretch_metric } from "./param/atlas_chart_stretch_metric.js";
+import { atlas_piecewise_resegment } from "./param/atlas_piecewise_resegment.js";
+import { atlas_build_region_graph } from "./segment/atlas_build_region_graph.js";
+import { atlas_compute_planar_regions } from "./segment/atlas_compute_planar_regions.js";
+import { atlas_merge_charts } from "./segment/atlas_merge_charts.js";
+import { atlas_segment_charts } from "./segment/atlas_segment_charts.js";
+import { atlas_segment_charts_atomic } from "./segment/atlas_segment_charts_atomic.js";
+
+/** Ortho is accepted only below these stretch bounds (xatlas thresholds). */
+const ORTHO_MEAN_STRETCH_MAX = 1.1;
+const ORTHO_MAX_STRETCH_MAX = 1.25;
+
+/** The BFF rescue keeps a chart whole instead of exploding it into piecewise pieces,
+ *  accepted only when its whole-chart map is near-isometric in the mean — bounded
+ *  just above the ortho mean gate (measured rescues are ~1.0). This bounds AVERAGE
+ *  distortion, not the worst triangle or shape compactness, so it is a chart-COUNT
+ *  win at comparable mean stretch, not a strict per-metric improvement; charts above
+ *  the bound fall through to piecewise's compact, individually ortho-valid pieces.
+ *  Measured net effect is Pareto-positive (decimated terrain: −6 charts, mean and
+ *  p99 stretch both down). */
+const BFF_MAX_MEAN_STRETCH = 1.25;
+
+/**
+ * Whether a parameterization validity report describes a bijective (no-overlap,
+ * consistent-winding) UV map: no flipped triangles, no self-intersection, no
+ * degenerate (zero-area) UV triangles.
+ *
+ * @param {{mixed_winding: boolean, self_intersects: boolean, zero_area_count: number}} validity from atlas_chart_param_validity
+ * @returns {boolean}
+ */
+function is_bijective(validity) {
+    return !validity.mixed_winding && !validity.self_intersects && validity.zero_area_count === 0;
+}
+
+/**
+ * Finalize a chart: record its type and 3D/UV areas, then append.
+ *
+ * @param {Chart} chart the chart from {@link atlas_extract_chart}, with solved UVs
+ * @param {number} type one of {@link CHART_TYPE}
+ * @param {Chart[]} out finished charts accumulator, appended to
+ */
+function finalize(chart, type, out) {
+    const s = atlas_chart_stretch_metric(chart);
+    chart.type = type;
+    chart.surface_area = s.geom_area;
+    chart.parametric_area = s.param_area;
+    out.push(chart);
+}
+
+/**
+ * Parameterize one segmentation chart, appending one or more finished charts to
+ * `out`: orthographic if it passes the stretch gate, otherwise LSCM if the
+ * chart has a boundary, otherwise region-grow piecewise re-segmentation into
+ * connected, ortho-valid sub-charts.
+ *
+ * @param {Chart} chart the chart from {@link atlas_extract_chart}; its `uv` is solved in place
+ * @param {object} [lscm_options] overrides for {@link atlas_chart_parameterize_lscm}
+ * @param {Chart[]} out finished charts accumulator, appended to
+ */
+function parameterize_chart(chart, lscm_options, out) {
+    atlas_chart_parameterize_ortho(chart);
+    const ortho_validity = atlas_chart_param_validity(chart);
+    const ortho_stretch = atlas_chart_stretch_metric(chart);
+
+    if (
+        is_bijective(ortho_validity) &&
+        ortho_stretch.mean_stretch <= ORTHO_MEAN_STRETCH_MAX &&
+        ortho_stretch.max_stretch <= ORTHO_MAX_STRETCH_MAX
+    ) {
+        finalize(chart, CHART_TYPE.ORTHO, out);
+        return;
+    }
+
+    if (atlas_chart_parameterize_lscm(chart, lscm_options)) {
+        if (is_bijective(atlas_chart_param_validity(chart))) {
+            finalize(chart, CHART_TYPE.LSCM, out);
+            return;
+        }
+    }
+
+    // Rescue a disk chart whose LSCM free boundary self-intersected by flattening
+    // it whole with boundary-first flattening (BFF), instead of exploding it into
+    // piecewise sub-charts — but only when the result is bijective AND near
+    // isometric (else piecewise's compact pieces are the better outcome). BFF runs
+    // only on charts that already failed ortho and LSCM, so it is free on clean
+    // meshes (no chart reaches here) and ~0 cost where LSCM was already failing.
+    if (atlas_chart_parameterize_bff(chart, lscm_options)) {
+        if (
+            is_bijective(atlas_chart_param_validity(chart)) &&
+            atlas_chart_stretch_metric(chart).mean_stretch <= BFF_MAX_MEAN_STRETCH
+        ) {
+            finalize(chart, CHART_TYPE.BFF, out);
+            return;
+        }
+    }
+
+    // Fallback: region-grow into connected, ortho-valid sub-charts.
+    for (const piece of atlas_piecewise_resegment(chart)) {
+        finalize(piece, CHART_TYPE.PIECEWISE, out);
+    }
+}
+
+/**
+ * Compute UV charts for a mesh (xatlas `ComputeCharts`): condition the mesh,
+ * segment it, and parameterize each chart. The returned charts carry their own
+ * vertex/triangle tables and per-chart UVs (local, unpacked) in `chart.uv`, ready
+ * for {@link atlas_pack_charts}. UVs are NOT written onto the mesh here — that is
+ * the explicit {@link atlas_write_chart_uvs} step (kept separate so charts from
+ * several meshes can be packed together before being actualized).
+ *
+ * @param {BinaryTopology} mesh mutated in place (welding, normals) but not its loop UVs
+ * @param {object} [options]
+ * @param {boolean} [options.weld] colocal-weld the input first (default true)
+ * @param {object} [options.segment] overrides for atlas_segment_charts
+ * @param {object} [options.lscm] overrides for atlas_chart_parameterize_lscm
+ * @returns {{charts: Chart[], face_chart: Int32Array, chart_count: number}}
+ */
+export function atlas_compute_charts(mesh, options = {}) {
+    const weld = options.weld ?? true;
+
+    if (weld) {
+        atlas_mesh_weld_colocals(mesh);
+    }
+
+    bt_mesh_compute_face_normals(mesh);
+
+    const face_areas = atlas_build_face_areas(mesh);
+    const edge_lengths = atlas_build_edge_lengths(mesh);
+    const edge_dihedrals = atlas_build_edge_dihedrals(mesh);
+
+    // Region-atomic segmentation (default) grows whole coplanar regions as
+    // units; set options.segment.atomic = false for the face-granular twin.
+    const atomic = options.segment?.atomic ?? true;
+    let segmentation;
+    if (atomic) {
+        const regions = atlas_compute_planar_regions(mesh, edge_dihedrals);
+        const region_graph = atlas_build_region_graph(
+            mesh, regions.region_of_face, regions.region_count, face_areas, edge_lengths, edge_dihedrals
+        );
+        segmentation = atlas_segment_charts_atomic(region_graph, regions.region_of_face, options.segment);
+    } else {
+        segmentation = atlas_segment_charts(mesh, face_areas, edge_lengths, edge_dihedrals, options.segment);
+    }
+
+    let face_chart = segmentation.face_chart;
+    let chart_count = segmentation.chart_count;
+
+    // Optional: merge adjacent near-coplanar charts (xatlas mergeCharts) to undo
+    // over-segmentation from the greedy growth. Off by default; the merged charts
+    // are re-extracted + re-parameterized below.
+    if (options.segment?.merge) {
+        const merged = atlas_merge_charts(mesh, face_chart, chart_count, face_areas, options.segment);
+        face_chart = merged.face_chart;
+        chart_count = merged.chart_count;
+    }
+
+    // Bucket faces by chart in one pass so each extraction touches only its own
+    // faces, instead of re-scanning every face once per chart (O(charts × faces)).
+    const chart_faces = [];
+    for (let c = 0; c < chart_count; c++) {
+        chart_faces.push([]);
+    }
+    const faces = mesh.faces;
+    for (let f = 0; f < faces.size; f++) {
+        if (!faces.is_allocated(f)) continue;
+        const c = face_chart[f];
+        if (c >= 0) chart_faces[c].push(f);
+    }
+
+    const charts = [];
+    for (let c = 0; c < chart_count; c++) {
+        const chart = atlas_extract_chart(mesh, face_chart, c, chart_faces[c]);
+        parameterize_chart(chart, options.lscm, charts);
+    }
+
+    return { charts, face_chart, chart_count };
+}

package/src/core/geom/3d/atlas/atlas_extract_chart.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Extract a single chart from a segmented mesh into a {@link Chart} for
+ * parameterization and packing (xatlas chart construction). `boundary_edges` is
+ * flat pairs of chart-local vertex indices forming the chart outline; `uv` is
+ * zero-filled for the solver.
+ *
+ * @param {BinaryTopology} mesh
+ * @param {Int32Array} face_chart from atlas_segment_charts (face -> chart id, -1 if none)
+ * @param {number} chart_id
+ * @param {number[]} [face_list] the chart's face ids; when omitted they are found
+ *   by scanning the whole mesh. The multi-chart driver precomputes one bucket per
+ *   chart so it does not re-scan all faces once per chart (O(charts × faces)).
+ * @returns {Chart}
+ */
+export function atlas_extract_chart(mesh: BinaryTopology, face_chart: Int32Array, chart_id: number, face_list?: number[]): Chart;
+import { Chart } from "./Chart.js";
+//# sourceMappingURL=atlas_extract_chart.d.ts.map

package/src/core/geom/3d/atlas/atlas_extract_chart.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"atlas_extract_chart.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/atlas/atlas_extract_chart.js"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;GAaG;AACH,sEAPW,UAAU,YACV,MAAM,cACN,MAAM,EAAE,GAGN,KAAK,CAmFjB;sBA1GqB,YAAY"}