@woosh/meep-engine 2.164.0 → 2.165.0

package/src/core/geom/3d/atlas/pack/atlas_pack_charts.js

@@ -0,0 +1,551 @@
+import { BitImage2 } from "../../../../binary/BitImage2.js";
+import { ceilPowerOfTwo } from "../../../../binary/operations/ceilPowerOfTwo.js";
+import { min_area_rect_2d } from "../../../2d/oriented-box/min_area_rect_2d.js";
+import { Skyline } from "../../../2d/packing/skyline.js";
+import { tri2_rasterize_conservative } from "../../../2d/triangle/tri2_rasterize_conservative.js";
+import { ChartPlacement } from "./ChartPlacement.js";
+
+/** Target atlas utilization used when auto-estimating density. */
+const UTILIZATION_TARGET = 0.75;
+
+/** Upper bound on single-page growth — a runaway backstop, not a real limit. */
+const MAX_ATLAS_SIZE = 1 << 16;
+
+/** Elastic density: shrink factor per attempt, and the attempt cap. */
+const ELASTIC_SHRINK = 0.8;
+const MAX_ELASTIC_ATTEMPTS = 40;
+
+/**
+ * The exact bitmap canBlit packer (tight, non-rectangular interlocking) is used
+ * only for atlases up to this many texels — its scan is O(area·mask). Above it,
+ * and unless `bruteForce` is forced, the fast O(n) skyline rectangle packer is
+ * used so packing scales to production atlas sizes.
+ */
+const BRUTE_FORCE_AREA = 1 << 16; // 256 x 256
+
+// ─── Shared ──────────────────────────────────────────────────────────────────
+/**
+ * Rotate a chart's UVs so its minimum-area oriented box becomes axis-aligned
+ * (xatlas `rotateChartsToAxis`). Rigid, so validity/stretch are unchanged.
+ *
+ * @param {Chart} chart chart whose UVs are rotated in place
+ */
+function rotate_uv_to_min_area_box(chart) {
+    const box = min_area_rect_2d(chart.uv, chart.vertex_count);
+    const c = Math.cos(box.angle);
+    const s = Math.sin(box.angle);
+    const uv = chart.uv;
+    for (let i = 0; i < chart.vertex_count; i++) {
+        const u = uv[i * 2];
+        const v = uv[i * 2 + 1];
+        uv[i * 2] = u * c + v * s;
+        uv[i * 2 + 1] = -u * s + v * c;
+    }
+}
+
+/**
+ * Per-chart placeable at a given texel density: scale + UV bbox + integer rect
+ * size (w, h, padding-inflated). With `need_mask`, also a dilated coverage mask
+ * (+ transpose) for the bitmap packer; skyline only needs w/h.
+ *
+ * @param {Chart[]} charts parameterized charts to build placeables from
+ * @param {number} density texels per unit of surface area
+ * @param {number} padding gutter texels added on each side
+ * @param {boolean} rotate_charts allow 90-degree placement (builds the transposed mask)
+ * @param {boolean} need_mask build per-chart coverage masks (bitmap packer) vs w/h only (skyline)
+ * @returns {{packs:ChartPlacement[], mask_total:number}} placements and the total occupied/area texel count
+ */
+function build_packs(charts, density, padding, rotate_charts, need_mask) {
+    const packs = [];
+    let mask_total = 0;
+
+    for (const chart of charts) {
+        const scale = Math.sqrt(chart.surface_area / Math.max(chart.parametric_area, 1e-12)) * density;
+
+        let min_u = Infinity, min_v = Infinity, max_u = -Infinity, max_v = -Infinity;
+        for (let i = 0; i < chart.vertex_count; i++) {
+            const u = chart.uv[i * 2];
+            const v = chart.uv[i * 2 + 1];
+            if (u < min_u) min_u = u;
+            if (u > max_u) max_u = u;
+            if (v < min_v) min_v = v;
+            if (v > max_v) max_v = v;
+        }
+
+        const ext_w = Math.max(1, Math.ceil((max_u - min_u) * scale) + 1);
+        const ext_h = Math.max(1, Math.ceil((max_v - min_v) * scale) + 1);
+        const w = ext_w + 2 * padding;
+        const h = ext_h + 2 * padding;
+
+        let mask = null;
+        let mask_t = null;
+        if (need_mask) {
+            mask = new BitImage2(w, h);
+            for (let t = 0; t < chart.triangle_count; t++) {
+                const i0 = chart.tri_local[t * 3];
+                const i1 = chart.tri_local[t * 3 + 1];
+                const i2 = chart.tri_local[t * 3 + 2];
+                tri2_rasterize_conservative(
+                    mask,
+                    (chart.uv[i0 * 2] - min_u) * scale + padding, (chart.uv[i0 * 2 + 1] - min_v) * scale + padding,
+                    (chart.uv[i1 * 2] - min_u) * scale + padding, (chart.uv[i1 * 2 + 1] - min_v) * scale + padding,
+                    (chart.uv[i2 * 2] - min_u) * scale + padding, (chart.uv[i2 * 2 + 1] - min_v) * scale + padding
+                );
+            }
+            if (padding > 0) {
+                mask.dilate(padding);
+            }
+            mask_t = rotate_charts ? mask.transposed() : null;
+            mask_total += mask.cardinality();
+        } else {
+            mask_total += w * h;
+        }
+
+        const placement = new ChartPlacement();
+        placement.chart = chart;
+        placement.scale = scale;
+        placement.min_u = min_u;
+        placement.min_v = min_v;
+        placement.w = w;
+        placement.h = h;
+        placement.mask = mask;
+        placement.mask_t = mask_t;
+        packs.push(placement);
+    }
+
+    return { packs, mask_total };
+}
+
+/**
+ * Largest-perimeter-first order (first-fit-decreasing).
+ *
+ * @param {ChartPlacement[]} packs placements to order
+ * @returns {number[]} pack indices sorted by descending (w + h)
+ */
+function pack_order(packs) {
+    const order = packs.map((_, i) => i);
+    order.sort((a, b) => (packs[b].w + packs[b].h) - (packs[a].w + packs[a].h));
+    return order;
+}
+
+/**
+ * Pick the bottom-left-most of two candidate placements (rot 0 / rot 1).
+ *
+ * @param {{x:number, y:number}|null} fit0 unrotated candidate position, or null
+ * @param {{x:number, y:number}|null} fit1 90-degree-rotated candidate position, or null
+ * @returns {{rot:number, pos:{x:number, y:number}}|null} chosen placement, or null if neither fits
+ */
+function choose_placement(fit0, fit1) {
+    if (fit0 === null && fit1 === null) {
+        return null;
+    }
+    if (fit1 === null) {
+        return { rot: 0, pos: fit0 };
+    }
+    if (fit0 === null) {
+        return { rot: 1, pos: fit1 };
+    }
+    if (fit1.y < fit0.y || (fit1.y === fit0.y && fit1.x < fit0.x)) {
+        return { rot: 1, pos: fit1 };
+    }
+    return { rot: 0, pos: fit0 };
+}
+
+// ─── Skyline rectangle packer (default, scalable) ────────────────────────────
+/**
+ * Try to place one placement into the skyline page, choosing the bottom-left-most
+ * of the unrotated and (if allowed) 90-degree-rotated fit. On success, writes
+ * page/rot/x/y onto the placement and raises the skyline. Non-allocating —
+ * reads {@link Skyline.found_x}/{@link Skyline.found_y} after each `find`.
+ *
+ * @param {Skyline} sky page skyline
+ * @param {ChartPlacement} pack placement to position (mutated on success)
+ * @param {number} page_index
+ * @param {boolean} rotate_charts allow 90-degree placement
+ * @returns {boolean} true if placed
+ */
+function skyline_try_place(sky, pack, page_index, rotate_charts) {
+    const ok0 = sky.find(pack.w, pack.h);
+    const x0 = sky.found_x;
+    const y0 = sky.found_y;
+
+    let ok1 = false;
+    let x1 = 0;
+    let y1 = 0;
+    if (rotate_charts) {
+        ok1 = sky.find(pack.h, pack.w);
+        x1 = sky.found_x;
+        y1 = sky.found_y;
+    }
+
+    let rot = -1;
+    let px = 0;
+    let py = 0;
+    if (ok0) {
+        rot = 0;
+        px = x0;
+        py = y0;
+    }
+    if (ok1 && (rot === -1 || y1 < py || (y1 === py && x1 < px))) {
+        rot = 1;
+        px = x1;
+        py = y1;
+    }
+    if (rot === -1) {
+        return false;
+    }
+
+    pack.page = page_index;
+    pack.rot = rot;
+    pack.x = px;
+    pack.y = py;
+    if (rot === 0) {
+        sky.place(px, py, pack.w, pack.h);
+    } else {
+        sky.place(px, py, pack.h, pack.w);
+    }
+    return true;
+}
+
+/**
+ * Place all packs on a single skyline page that grows by powers of two until
+ * every pack fits (xatlas growing-page mode, skyline variant).
+ *
+ * @param {ChartPlacement[]} packs
+ * @param {number} start_resolution initial square page size
+ * @param {boolean} rotate_charts allow 90-degree placement
+ * @returns {Skyline[]} single-element page list
+ */
+function place_growing_skyline(packs, start_resolution, rotate_charts) {
+    const sky = new Skyline(start_resolution, start_resolution);
+    for (const idx of pack_order(packs)) {
+        const p = packs[idx];
+        while (!skyline_try_place(sky, p, 0, rotate_charts)) {
+            const need = Math.max(p.w, p.h);
+            const nw = ceilPowerOfTwo(Math.max(sky.width + 1, need));
+            const nh = ceilPowerOfTwo(Math.max(sky.height + 1, need));
+            if (nw > MAX_ATLAS_SIZE || nh > MAX_ATLAS_SIZE) {
+                throw new Error("atlas_pack_charts: atlas grew past the size limit");
+            }
+            sky.grow(nw, nh);
+        }
+    }
+    return [sky];
+}
+
+/**
+ * Place all packs into up to `max_pages` fixed-size skyline pages at the current
+ * density, spilling onto a fresh page when one fills.
+ *
+ * @param {ChartPlacement[]} packs
+ * @param {number} page_size fixed square page size
+ * @param {number} max_pages page cap
+ * @param {boolean} rotate_charts allow 90-degree placement
+ * @returns {Skyline[]|null} page list, or null if the packs do not fit
+ */
+function place_fixed_skyline(packs, page_size, max_pages, rotate_charts) {
+    const pages = [new Skyline(page_size, page_size)];
+    for (const idx of pack_order(packs)) {
+        const p = packs[idx];
+
+        let placed = false;
+        for (let pi = 0; pi < pages.length; pi++) {
+            if (skyline_try_place(pages[pi], p, pi, rotate_charts)) {
+                placed = true;
+                break;
+            }
+        }
+        if (placed) {
+            continue;
+        }
+        if (pages.length >= max_pages) {
+            return null;
+        }
+        const fresh = new Skyline(page_size, page_size);
+        if (!skyline_try_place(fresh, p, pages.length, rotate_charts)) {
+            return null;
+        }
+        pages.push(fresh);
+    }
+    return pages;
+}
+
+// ─── Bitmap canBlit packer (exact, small atlases / bruteForce) ───────────────
+/**
+ * Lowest-then-leftmost (row-major scan) position where `mask` can be blitted
+ * into `page` without overlapping a set bit, or null if it does not fit.
+ *
+ * @param {BitImage2} page atlas occupancy
+ * @param {BitImage2} mask chart coverage mask
+ * @returns {{x:number, y:number}|null}
+ */
+function find_first_fit(page, mask) {
+    const max_y = page.height - mask.height;
+    const max_x = page.width - mask.width;
+    for (let y = 0; y <= max_y; y++) {
+        for (let x = 0; x <= max_x; x++) {
+            if (page.canBlit(mask, x, y)) {
+                return { x, y };
+            }
+        }
+    }
+    return null;
+}
+
+/**
+ * Try to place one pack into a bitmap page, choosing the bottom-left-most of the
+ * unrotated and (if a transpose exists) 90-degree-rotated fit. On success, writes
+ * page/rot/x/y onto the pack and ORs its mask into the page.
+ *
+ * @param {BitImage2} page atlas occupancy
+ * @param {ChartPlacement} pack placement to position (mutated on success)
+ * @param {number} page_index
+ * @returns {boolean} true if placed
+ */
+function bitmap_try_place(page, pack, page_index) {
+    const fit0 = find_first_fit(page, pack.mask);
+    const fit1 = pack.mask_t !== null ? find_first_fit(page, pack.mask_t) : null;
+    const choice = choose_placement(fit0, fit1);
+    if (choice === null) {
+        return false;
+    }
+    pack.page = page_index;
+    pack.rot = choice.rot;
+    pack.x = choice.pos.x;
+    pack.y = choice.pos.y;
+    page.or_blit(choice.rot === 1 ? pack.mask_t : pack.mask, pack.x, pack.y);
+    return true;
+}
+
+/**
+ * Place all packs on a single bitmap page that grows by powers of two until
+ * every pack fits (xatlas growing-page mode, exact bitmap variant).
+ *
+ * @param {ChartPlacement[]} packs
+ * @param {number} start_resolution initial square page size
+ * @returns {BitImage2[]} single-element page list
+ */
+function place_growing_bitmap(packs, start_resolution) {
+    const page = new BitImage2(start_resolution, start_resolution);
+    for (const idx of pack_order(packs)) {
+        const p = packs[idx];
+        while (!bitmap_try_place(page, p, 0)) {
+            const need_w = Math.max(p.mask.width, p.mask_t !== null ? p.mask_t.width : 0);
+            const need_h = Math.max(p.mask.height, p.mask_t !== null ? p.mask_t.height : 0);
+            const nw = ceilPowerOfTwo(Math.max(page.width + 1, need_w));
+            const nh = ceilPowerOfTwo(Math.max(page.height + 1, need_h));
+            if (nw > MAX_ATLAS_SIZE || nh > MAX_ATLAS_SIZE) {
+                throw new Error("atlas_pack_charts: atlas grew past the size limit");
+            }
+            page.grow_preserving(nw, nh);
+        }
+    }
+    return [page];
+}
+
+/**
+ * Place all packs into up to `max_pages` fixed-size bitmap pages at the current
+ * density, spilling onto a fresh page when one fills.
+ *
+ * @param {ChartPlacement[]} packs
+ * @param {number} page_size fixed square page size
+ * @param {number} max_pages page cap
+ * @returns {BitImage2[]|null} page list, or null if the packs do not fit
+ */
+function place_fixed_bitmap(packs, page_size, max_pages) {
+    const pages = [new BitImage2(page_size, page_size)];
+    for (const idx of pack_order(packs)) {
+        const p = packs[idx];
+        let placed = false;
+        for (let pi = 0; pi < pages.length; pi++) {
+            if (bitmap_try_place(pages[pi], p, pi)) {
+                placed = true;
+                break;
+            }
+        }
+        if (placed) {
+            continue;
+        }
+        if (pages.length >= max_pages) {
+            return null;
+        }
+        const fresh = new BitImage2(page_size, page_size);
+        if (!bitmap_try_place(fresh, p, pages.length)) {
+            return null;
+        }
+        pages.push(fresh);
+    }
+    return pages;
+}
+
+/**
+ * Pack parameterized charts into one or more atlas pages (xatlas `PackCharts`),
+ * mutating each chart in place: its `uv` becomes final atlas-space [0,1]
+ * coordinates and `atlas_page`/`atlas_x`/`atlas_y`/`atlas_rotated` record its
+ * placement. Charts are pre-rotated to their min-area box and may be placed
+ * 90-degrees rotated for density.
+ *
+ * This works purely at the {@link Chart} level — no mesh — so charts from several
+ * different meshes can be packed into a single shared atlas. To write the packed
+ * UVs back onto a mesh, call {@link atlas_write_chart_uvs} (once per source mesh).
+ *
+ * Placement strategy is chosen by atlas size: small atlases use the exact
+ * bitmap shifted-OR `canBlit` packer (tight, non-rectangular interlocking);
+ * large atlases use the fast O(n) skyline rectangle packer (so packing scales).
+ * `bruteForce: true` forces the bitmap packer regardless of size.
+ *
+ * Page modes:
+ *  - `maxResolution = 0` (default): a single page that grows by powers of two.
+ *  - `maxResolution > 0`, `maxPages = 1` (default): one fixed-size page with
+ *    **elastic density** — density shrinks until the charts fit.
+ *  - `maxResolution > 0`, `maxPages > 1`: spill into up to `maxPages` fixed-size
+ *    pages at fixed density (`maxPages = Infinity` = pure fixed-density spill).
+ *
+ * @param {Chart[]} charts from {@link atlas_compute_charts} (mutated: `uv` + placement)
+ * @param {object} [options]
+ * @param {number} [options.padding] gutter texels (default 1)
+ * @param {number} [options.resolution] start/target size for the growing page; 0 = auto
+ * @param {number} [options.texelsPerUnit] texel density; 0 = auto
+ * @param {number} [options.maxResolution] fixed page size; 0 = unbounded growing page (default 0)
+ * @param {number} [options.maxPages] page cap; density is elastic to honour it (default 1)
+ * @param {boolean} [options.bruteForce] force the exact bitmap packer (default false)
+ * @param {boolean} [options.rotateChartsToAxis] align charts to their OBB (default true)
+ * @param {boolean} [options.rotateCharts] allow 90-degree placement (default true)
+ * @returns {{pages: Array<{width:number, height:number, occupied_texels:number, utilization:number}>,
+ *   page_count:number, atlas_width:number, atlas_height:number, utilization:number,
+ *   occupied_texels:number, mask_texels_total:number, charts:Chart[]}}
+ */
+export function atlas_pack_charts(charts, options = {}) {
+    const padding = options.padding ?? 1;
+    const rotate_to_axis = options.rotateChartsToAxis ?? true;
+    const rotate_charts = options.rotateCharts ?? true;
+    const max_resolution = options.maxResolution ?? 0;
+    const max_pages = options.maxPages ?? 1;
+    const brute_force = options.bruteForce ?? false;
+
+    if (rotate_to_axis) {
+        for (const chart of charts) {
+            rotate_uv_to_min_area_box(chart);
+        }
+    }
+
+    let total_surface = 0;
+    for (const c of charts) {
+        total_surface += c.surface_area;
+    }
+    if (total_surface <= 0) {
+        total_surface = 1;
+    }
+
+    let packs;
+    let mask_total;
+    let pages;
+    let use_skyline;
+
+    if (max_resolution === 0) {
+        let resolution = options.resolution ?? 0;
+        let density = options.texelsPerUnit ?? 0;
+        if (resolution === 0 && density === 0) {
+            resolution = 1024;
+        }
+        if (density === 0) {
+            density = resolution * Math.sqrt(UTILIZATION_TARGET / total_surface);
+        }
+        if (resolution === 0) {
+            resolution = Math.max(1, Math.ceil(Math.sqrt(total_surface * density * density / UTILIZATION_TARGET)));
+        }
+
+        use_skyline = !brute_force && resolution * resolution > BRUTE_FORCE_AREA;
+        const built = build_packs(charts, density, padding, rotate_charts, !use_skyline);
+        packs = built.packs;
+        mask_total = built.mask_total;
+        pages = use_skyline ? place_growing_skyline(packs, resolution, rotate_charts) : place_growing_bitmap(packs, resolution);
+    } else {
+        use_skyline = !brute_force && max_resolution * max_resolution > BRUTE_FORCE_AREA;
+        const estimate_pages = Number.isFinite(max_pages) ? max_pages : 1;
+        let density = options.texelsPerUnit ?? 0;
+        if (density === 0) {
+            density = Math.sqrt(UTILIZATION_TARGET * estimate_pages * max_resolution * max_resolution / total_surface);
+        }
+
+        for (let attempt = 0; attempt < MAX_ELASTIC_ATTEMPTS; attempt++) {
+            const built = build_packs(charts, density, padding, rotate_charts, !use_skyline);
+            const placed = use_skyline
+                ? place_fixed_skyline(built.packs, max_resolution, max_pages, rotate_charts)
+                : place_fixed_bitmap(built.packs, max_resolution, max_pages);
+            if (placed !== null) {
+                packs = built.packs;
+                mask_total = built.mask_total;
+                pages = placed;
+                break;
+            }
+            density *= ELASTIC_SHRINK;
+        }
+        if (pages === undefined) {
+            throw new Error("atlas_pack_charts: could not fit charts within maxPages pages");
+        }
+    }
+
+    // Update each chart's UVs to final atlas-space coordinates (page-relative)
+    // and record its placement. Actualizing onto a mesh is a separate, explicit
+    // step (atlas_write_chart_uvs) the caller controls.
+    for (const p of packs) {
+        const page = pages[p.page];
+        const pw = page.width;
+        const ph = page.height;
+        const chart = p.chart;
+        const final_uv = new Float64Array(chart.vertex_count * 2);
+        for (let i = 0; i < chart.vertex_count; i++) {
+            const tu = (chart.uv[i * 2] - p.min_u) * p.scale;
+            const tv = (chart.uv[i * 2 + 1] - p.min_v) * p.scale;
+            if (p.rot === 1) {
+                final_uv[i * 2] = (p.x + padding + tv) / pw;
+                final_uv[i * 2 + 1] = (p.y + padding + tu) / ph;
+            } else {
+                final_uv[i * 2] = (p.x + padding + tu) / pw;
+                final_uv[i * 2 + 1] = (p.y + padding + tv) / ph;
+            }
+        }
+        chart.uv = final_uv;
+        chart.atlas_page = p.page;
+        chart.atlas_x = p.x;
+        chart.atlas_y = p.y;
+        chart.atlas_rotated = p.rot === 1;
+    }
+
+    // Per-page occupancy: bitmap = set texels; skyline = placed rectangle areas.
+    const occupied = new Array(pages.length).fill(0);
+    if (use_skyline) {
+        for (const p of packs) {
+            occupied[p.page] += p.w * p.h;
+        }
+    } else {
+        for (let i = 0; i < pages.length; i++) {
+            occupied[i] = pages[i].cardinality();
+        }
+    }
+
+    const page_infos = pages.map((pg, i) => ({
+        width: pg.width,
+        height: pg.height,
+        occupied_texels: occupied[i],
+        utilization: occupied[i] / (pg.width * pg.height),
+    }));
+    let total_occupied = 0;
+    let total_cells = 0;
+    for (const info of page_infos) {
+        total_occupied += info.occupied_texels;
+        total_cells += info.width * info.height;
+    }
+
+    return {
+        pages: page_infos,
+        page_count: pages.length,
+        atlas_width: page_infos[0].width,
+        atlas_height: page_infos[0].height,
+        utilization: total_occupied / total_cells,
+        occupied_texels: total_occupied,
+        mask_texels_total: mask_total,
+        charts,
+    };
+}

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

@@ -0,0 +1,22 @@
+/**
+ * Validity of a chart's current UV layout (xatlas
+ * `isChartParameterizationValid`). A layout is bijective when every triangle
+ * has the same winding (all positive or all flipped — a uniformly mirrored
+ * chart is fine) with no zero-area triangles, and the chart outline does not
+ * self-intersect.
+ *
+ * Boundary self-intersection is a brute-force O(b^2) test over the chart's
+ * boundary edges, skipping pairs that share an endpoint.
+ *
+ * @param {Chart} chart
+ * @returns {{positive_count:number, flipped_count:number, zero_area_count:number,
+ *   mixed_winding:boolean, self_intersects:boolean}}
+ */
+export function atlas_chart_param_validity(chart: Chart): {
+    positive_count: number;
+    flipped_count: number;
+    zero_area_count: number;
+    mixed_winding: boolean;
+    self_intersects: boolean;
+};
+//# sourceMappingURL=atlas_chart_param_validity.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"atlas_chart_param_validity.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/geom/3d/atlas/param/atlas_chart_param_validity.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;GAaG;AACH;oBAH6B,MAAM;mBAAgB,MAAM;qBAAkB,MAAM;mBAC9D,OAAO;qBAAkB,OAAO;EAuDlD"}

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

@@ -0,0 +1,73 @@
+import { segment2_intersects_segment2_2d } from "../../../2d/line/segment2_intersects_segment2_2d.js";
+import { tri2_signed_area } from "../../../2d/triangle/tri2_signed_area.js";
+
+const AREA_EPSILON = 1e-12;
+
+/**
+ * Validity of a chart's current UV layout (xatlas
+ * `isChartParameterizationValid`). A layout is bijective when every triangle
+ * has the same winding (all positive or all flipped — a uniformly mirrored
+ * chart is fine) with no zero-area triangles, and the chart outline does not
+ * self-intersect.
+ *
+ * Boundary self-intersection is a brute-force O(b^2) test over the chart's
+ * boundary edges, skipping pairs that share an endpoint.
+ *
+ * @param {Chart} chart
+ * @returns {{positive_count:number, flipped_count:number, zero_area_count:number,
+ *   mixed_winding:boolean, self_intersects:boolean}}
+ */
+export function atlas_chart_param_validity(chart) {
+    const uv = chart.uv;
+    const tri = chart.tri_local;
+    const triangle_count = chart.triangle_count;
+
+    let positive_count = 0;
+    let flipped_count = 0;
+    let zero_area_count = 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 area = tri2_signed_area(
+            uv[i0 * 2], uv[i0 * 2 + 1],
+            uv[i1 * 2], uv[i1 * 2 + 1],
+            uv[i2 * 2], uv[i2 * 2 + 1]
+        );
+        if (area > AREA_EPSILON) positive_count++;
+        else if (area < -AREA_EPSILON) flipped_count++;
+        else zero_area_count++;
+    }
+
+    const mixed_winding = positive_count > 0 && flipped_count > 0;
+
+    const be = chart.boundary_edges;
+    const edge_count = be.length / 2;
+    let self_intersects = false;
+
+    outer:
+    for (let i = 0; i < edge_count; i++) {
+        const a0 = be[i * 2];
+        const a1 = be[i * 2 + 1];
+        const a0x = uv[a0 * 2], a0y = uv[a0 * 2 + 1];
+        const a1x = uv[a1 * 2], a1y = uv[a1 * 2 + 1];
+
+        for (let j = i + 1; j < edge_count; j++) {
+            const b0 = be[j * 2];
+            const b1 = be[j * 2 + 1];
+            // adjacent edges share an endpoint — a shared endpoint is not a crossing
+            if (a0 === b0 || a0 === b1 || a1 === b0 || a1 === b1) {
+                continue;
+            }
+            const b0x = uv[b0 * 2], b0y = uv[b0 * 2 + 1];
+            const b1x = uv[b1 * 2], b1y = uv[b1 * 2 + 1];
+            if (segment2_intersects_segment2_2d(a0x, a0y, a1x, a1y, b0x, b0y, b1x, b1y)) {
+                self_intersects = true;
+                break outer;
+            }
+        }
+    }
+
+    return { positive_count, flipped_count, zero_area_count, mixed_winding, self_intersects };
+}

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

@@ -0,0 +1,37 @@
+/**
+ * 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: Chart, options?: {
+    tolerance?: number;
+    maxIterations?: number;
+}): boolean;
+//# sourceMappingURL=atlas_chart_parameterize_bff.d.ts.map

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

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