@woosh/meep-engine 2.164.0 → 2.165.0

package/src/core/geom/3d/atlas/BFF_PLAN.md

@@ -0,0 +1,174 @@
+# Plan: fix LSCM self-intersection (shape-aware boundary → BFF)
+
+Status: **planning** (2026-06-26). No build started. Goal: rescue the LSCM
+boundary-self-intersection charts that currently explode into piecewise
+sub-charts, **with low distortion** — the one lever the metrics validated
+([REVIEW_02.md §5.0](REVIEW_02.md), [atlas_metrics.bench.spec.js](atlas_metrics.bench.spec.js)).
+
+## 0. Problem recap (measured, not assumed)
+
+On the decimated-terrain bench: 970 charts, of which 31 LSCM charts fail
+bijectivity, **all 31 on boundary self-intersection** (free-boundary conformal
+LSCM has no injectivity guarantee → the patch curls so its UV outline overlaps).
+Each explodes into ~4 ortho piecewise pieces (+96 charts).
+
+The convex-boundary rescue (`atlas_chart_parameterize_tutte.js`, built then removed —
+see §5) eliminated the explosion (−96 charts, util 71.9 %→86.3 %,
+**guaranteed bijective**) **but at catastrophic distortion** (mean stretch 2.55→70.9,
+p99 4.27→2467). Confirmed **boundary-dominated**: uniform→mean-value interior
+weights changed nothing (70.82→70.88). The charts are thin/curled, so a *circle*
+is the wrong target. We need a **low-distortion boundary** that is still safe.
+
+## 1. Reuse inventory (what already exists in meep)
+
+**Directly reusable — no rebuild:**
+
+| Need | Reuse |
+|---|---|
+| Cotangent edge weight (Laplacian core) | `core/geom/vec3/v3_cotangent.js` |
+| Sparse assembly + matvec | `core/math/linalg/sparse/SparseMatrixCSR.js` (`from_triplets`), `spm_matvec`, `spm_matvec_transpose` |
+| SPD / least-squares iterative solve | `core/math/linalg/cg/cg_solve.js`, `cg_solve_normal_equations.js` (used by LSCM + BFF) |
+| Boundary-loop trace, disk detection, interior/boundary re-index, UV write-back | (prototyped in the now-removed Tutte module; carried into `param/atlas_chart_parameterize_bff.js`) |
+| Pipeline slot: cascade + `param.*` option + bijectivity gate + new `CHART_TYPE` | `atlas_compute_charts.js`, `atlas_chart_type.js` |
+| **Acceptance harness**: metrics + A/B + failure-reason diagnostic + the Tutte A/B (mirror it) | `atlas_bench_lib.js`, `atlas_metrics.bench.spec.js` |
+
+**Must build new (no existing primitive):**
+
+- Cotangent-**Laplacian assembly** (chart-local → `SparseMatrixCSR` via `v3_cotangent`). Small.
+- Interior **angle-defect** (Gaussian curvature) + boundary **exterior/geodesic angle**. From triangle geometry.
+- **Obtuse-triangle handling**: cotangent weights go negative on obtuse triangles → the Laplacian can be indefinite (CG divergence / interior flips). v1: **clamp negative weights to 0** (simple, slight bias); intrinsic-Delaunay flips are the better-but-heavier option, deferred.
+- (BFF only) **DtN / Schur boundary operator**, the discrete-Yamabe **scale-factor solve**, boundary-**curve integration** (cumulative turning angles → 2D), and the **conformal interior extension** (harmonic + conjugate/Hilbert).
+
+There is **no** existing discrete Laplacian, curvature, or conjugate operator in meep (the `harmonic`/`geodesic` hits are spherical-harmonics and pathfinding). The reusable scaffolding is the Tutte module + the linalg/cotangent primitives.
+
+## 2. Staged plan — cheap variant first, BFF only if it fails the gate
+
+### Phase A — shape-aware **convex** boundary (cheap; ~all reuse) — TRIED, FAILED ❌
+
+Mapped the boundary to an aspect-matched convex **ellipse** (aspect from the prior
+LSCM-layout PCA) instead of a circle; still convex ⇒ still guaranteed-injective.
+**Measured: no improvement** — decimated terrain mean stretch **71.67 vs the
+circle's 70.9** (and util 86.9 % vs 86.3 %). Reverted.
+
+Root cause — a **catch-22**: a curled chart's LSCM layout curls into a roughly
+*round* blob, so its PCA aspect ≈ 1 (the ellipse collapses back to a circle); and
+3D PCA is no better (a curled strip is 3D-compact). **You cannot estimate the
+flattened aspect of a curled chart without first flattening it.** No *pre-guessed*
+convex boundary escapes this. The whole convex-boundary family is now ruled out by
+measurement: circle 70.9, aspect-ellipse 71.67, mean-value-weights 70.88 — all
+catastrophic. **The boundary MUST be derived from the chart's intrinsic geometry
+(curvature), which is exactly what BFF does and nothing cheaper can.** Proceed to
+Phase B.
+
+### Phase B — full **BFF** (only if Phase A insufficient)
+
+Boundary First Flattening computes a *minimal-distortion, non-convex* boundary
+(not a forced convex shape) and a conformal interior, so it is the only method
+that can be both low-distortion AND (in practice) non-self-intersecting. Staged so
+each sub-phase is independently testable:
+
+- **B1 — analytic infra (de-risk first).** Cotangent-Laplacian assembly + interior
+  angle-defect + boundary geodesic curvature + obtuse clamping. *Test:* the
+  Laplacian reproduces a known harmonic field on a flat grid; angle defects sum to
+  2πχ (Gauss–Bonnet). Reuses `v3_cotangent` + `SparseMatrixCSR` + `cg_solve`.
+- **B2 — BFF boundary.** Discrete-Yamabe scale-factor solve (interior flat,
+  least-area-distortion boundary via the Neumann↔Dirichlet relation on the
+  boundary; small dense system → `lu_factor`/`lu_solve`), then integrate scaled
+  boundary edge lengths + target turning angles into a 2D boundary curve. *Test:* a
+  developable patch (cone/cylinder) flattens to ~zero stretch; boundary curve
+  closes up.
+- **B3 — conformal interior extension** (the riskiest). Harmonic extension of the
+  boundary curve + the conjugate (discrete Hilbert) recovery, via two Laplace
+  solves (`cg_solve`). *Test:* on a disk, stretch ≪ Tutte; bijective. If the
+  conjugate step proves too costly/risky, fall back to plain harmonic extension
+  (loses the guarantee) + the validity gate + piecewise as last resort.
+- **B4 — wire in.** New `CHART_TYPE.BFF`, behind `param.bff`, inserted in the
+  cascade before piecewise (ortho → LSCM → BFF → piecewise); accept only if it
+  comes out bijective, else piecewise. Mirror the Tutte A/B test.
+
+*Effort: substantial. B3 is the principal risk. BFF does not *strictly* guarantee
+non-self-intersection, so any chart it can't flatten validly still falls to
+piecewise — never worse than today.*
+
+## 3. Acceptance gate (the candidate must beat BOTH baselines)
+
+Measured via the existing A/B harness on the **decimated terrain** plus a second
+curved fixture (e.g. a noisy sphere), candidate (`param.{tutteShaped|bff}=true`)
+vs the piecewise baseline (`tutte=false`):
+
+1. **Fewer charts** — `cand.chart_count < base.chart_count` (eliminates the
+   piecewise explosion). *Tutte already passes this.*
+2. **Distortion not worse than piecewise** — `cand.mean_stretch ≤ base.mean_stretch`
+   (≈ 2.55) **and** `cand.p99_stretch ≤ ~2× base.p99_stretch`. **This is the gate
+   Tutte fails (70.9 vs 2.55) — the whole point.** A candidate that cuts charts but
+   balloons distortion does not ship default-on.
+3. **Bijective** — every rescued chart: no flips, no self-intersection, no
+   zero-area (`atlas_chart_param_validity`).
+4. **Deterministic** — bit-identical UVs across reruns.
+5. **No regression on clean fixtures** — cube / plane / uv-sphere / cylinder / cone
+   unchanged (the rescue triggers only on LSCM-self-intersecting disk charts).
+6. **Bounded cost** — per-chart solve only on the self-intersecting charts; no
+   global slowdown on clean meshes.
+
+**Ship rules:**
+- Pass **1 + 2 + 3** → **default-on** (a genuine quality win over both piecewise and Tutte).
+- Pass **1 + 3** but fail **2** → **off-by-default** opt-in knob (chart-count vs distortion trade-off), like Tutte.
+- Fail **3** → **reject**.
+
+## 4. Risks & mitigations
+
+| Risk | Mitigation |
+|---|---|
+| Obtuse triangles → indefinite cot-Laplacian (CG divergence / interior flips) | Clamp negative cotangents to 0 (v1); intrinsic-Delaunay flips deferred. Phase A's convex boundary keeps injectivity regardless of clamping. |
+| BFF conjugate/Hilbert step (B3) too costly/subtle | Fall back to harmonic extension + validity gate; worst case piecewise (no regression). |
+| BFF boundary may still self-intersect on pathological charts | Accept only if bijective; else piecewise — strictly ≤ today's chart count. |
+| Effort for a ~10 % over-segmentation win on curved/decimated assets only | Phase A is cheap and may suffice; only escalate to BFF if the metric demands it. Clean assets are unaffected either way. |
+
+## 5. Status / next action
+
+> **FINAL STATE (2026-06-26).** BFF is built ([atlas_chart_parameterize_bff.js](param/atlas_chart_parameterize_bff.js),
+> `CHART_TYPE.BFF`) with the intrinsic boundary + DtN-optimal curvature + conformal
+> interior, and is **folded into the single always-on cascade** (ortho → LSCM → BFF →
+> piecewise, no flags) — free (compute Δ ~−0.3 %, runs only post-LSCM-failure) and
+> strictly Pareto-safe (accepts only bijective + near-isometric whole charts). The
+> **Tutte convex-boundary path was removed** (dominated). Net effect on the
+> decimated terrain: 970 → 964 charts, mean stretch 2.553 → 2.508. The history below
+> records how each variant was measured and ruled in/out.
+
+- **Phase A — done, failed the gate (§2).** Reverted. Convex-boundary family ruled
+  out by measurement (catch-22 on the aspect estimate).
+- **Phase B v1 — done, built + measured ([atlas_chart_parameterize_bff.js](param/atlas_chart_parameterize_bff.js),
+  `CHART_TYPE.BFF`, `param.bff`, default off).** Intrinsic boundary (uniform
+  curvature redistribution) + **conformal** pinned-boundary interior (harmonic was
+  tried first and flipped 26/31; conformal is far less flip-prone). **Clears the
+  gate** (decimated terrain: −4 charts, mean stretch 2.553 → 2.509 *better*, all
+  BFF charts bijective, no clean-fixture regression — a Pareto-safe win, unlike
+  Tutte's 70×) **but at tiny magnitude: only 1 of 31** self-intersecting charts is
+  rescued. Diagnosed: the other 30 fail because the v1 **uniform** curvature
+  redistribution leaves the boundary too contorted (25 flip the conformal interior,
+  5 self-intersect at the boundary).
+- **Phase B v2 — DtN boundary, done + measured.** Replaced the uniform
+  redistribution with the optimal Dirichlet-to-Neumann curvature (fix boundary
+  scale 0, solve interior Poisson `L_II u = Ω_I` via `cg_solve`, `k̃_b = (π−θ_b) −
+  (L u)_b`; ∑ k̃ = 2π keeps it closed). **The DtN boundary fixed the interior**
+  (conformal-interior flips 25 → 2). Still Pareto-safe (−6 charts, mean 2.553 →
+  2.508, p99 4.27 → 3.99, bijective, torus unchanged) **but still only ~2 of 31
+  rescued — the flattened BOUNDARY now self-intersects on ~27/31.**
+
+- **CONCLUSION: these charts are intrinsically un-flattenable-whole.** The boundary
+  self-intersection is **fundamental, not an implementation gap** — true unclamped
+  cotangents made it *worse* (1 rescue, 30 self-intersections). A high-curvature
+  decimated chart cannot be *developed* to a SIMPLE planar boundary while
+  preserving edge lengths (the curvature forces the flat boundary to overlap
+  itself), so **cutting (piecewise) is the correct injective answer** for them; BFF
+  rescues only the ~2 low-curvature ones. BFF is the right tool and is kept
+  off-by-default (correct, tested, Pareto-safe), but it does NOT unlock the
+  majority. The metrics conclusively show the **piecewise explosion is largely
+  correct behavior** for decimated/high-curvature assets.
+
+- **If a future need demands keeping these whole:** the only remaining option is a
+  method that allows the *boundary to be cut* as part of the optimization
+  (OptCuts-style joint cut+flatten) or a guaranteed-injective nonlinear map with a
+  scaffold (SLIM + boundary-band scaffold). Both are large, separate builds, and
+  the metrics say the payoff (~29 hard charts on decimated assets) is modest. Not
+  recommended unless the asset mix shifts toward heavily-decimated content.

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

@@ -0,0 +1,58 @@
+/**
+ * One UV chart: a connected patch of the source mesh extracted into a
+ * self-contained, indexable structure for parameterization and packing
+ * (xatlas `Chart`).
+ *
+ * A chart-local ("unified") vertex is a distinct source mesh vertex used by the
+ * chart's faces — one geometric vertex shared by several faces of the chart maps
+ * to ONE chart vertex (and one UV), while the same geometric vertex in another
+ * chart is a separate chart vertex, which is how a seam arises. Triangle corners
+ * carry their source loop ids so solved UVs can be written back to the per-corner
+ * loop_data channel.
+ *
+ * Built by {@link atlas_extract_chart} (and the piecewise re-segmenter);
+ * parameterization fills {@link uv}/{@link type}; packing fills the `atlas_*`
+ * fields and rewrites {@link uv} into atlas space.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class Chart {
+    /** Number of chart-local (unified) vertices. @type {number} */
+    vertex_count: number;
+    /** Chart-local vertex id -> source mesh vertex id. @type {Uint32Array} */
+    vertex_of_local: Uint32Array;
+    /** Flat xyz per chart-local vertex (length 3 * vertex_count). @type {Float64Array} */
+    positions: Float64Array;
+    /** Triangle count. @type {number} */
+    triangle_count: number;
+    /** 3 chart-local vertex ids per triangle. @type {Uint32Array} */
+    tri_local: Uint32Array;
+    /** 3 source mesh loop ids per triangle (per-corner UV write-back). @type {Uint32Array} */
+    tri_loops: Uint32Array;
+    /** Source mesh face id per triangle. @type {Uint32Array} */
+    tri_face: Uint32Array;
+    /** Flat pairs of chart-local vertex ids forming the chart outline. @type {Uint32Array} */
+    boundary_edges: Uint32Array;
+    /**
+     * (u, v) per chart-local vertex — local during parameterization, atlas-space
+     * (normalized to its page) after packing.
+     * @type {Float64Array}
+     */
+    uv: Float64Array;
+    /** How the UVs were produced — a {@link CHART_TYPE} value. @type {number} */
+    type: number;
+    /** Total 3D surface area. @type {number} */
+    surface_area: number;
+    /** Total UV (parametric) area. @type {number} */
+    parametric_area: number;
+    /** Atlas page the chart was packed onto. @type {number} */
+    atlas_page: number;
+    /** Chart placement x within its page (texels). @type {number} */
+    atlas_x: number;
+    /** Chart placement y within its page (texels). @type {number} */
+    atlas_y: number;
+    /** Whether the chart was placed 90-degrees rotated during packing. @type {boolean} */
+    atlas_rotated: boolean;
+}
+//# sourceMappingURL=Chart.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Chart.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/atlas/Chart.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;GAkBG;AACH;IACI,+DAA+D;IAC/D,cADqD,MAAM,CAC1C;IAEjB,0EAA0E;IAC1E,iBAD2D,WAAW,CAC1C;IAE5B,sFAAsF;IACtF,WADsE,YAAY,CAC5D;IAEtB,qCAAqC;IACrC,gBAD2B,MAAM,CACd;IAEnB,iEAAiE;IACjE,WADkD,WAAW,CACvC;IAEtB,0FAA0F;IAC1F,WAD2E,WAAW,CAChE;IAEtB,4DAA4D;IAC5D,UAD6C,WAAW,CACnC;IAErB,0FAA0F;IAC1F,gBAD2E,WAAW,CAC3D;IAE3B;;;;OAIG;IACH,IAFU,YAAY,CAEP;IAEf,6EAA6E;IAC7E,MADmE,MAAM,CACjD;IAExB,4CAA4C;IAC5C,cADkC,MAAM,CACvB;IAEjB,iDAAiD;IACjD,iBADuC,MAAM,CACzB;IAEpB,2DAA2D;IAC3D,YADiD,MAAM,CACxC;IAEf,iEAAiE;IACjE,SADuD,MAAM,CACjD;IAEZ,iEAAiE;IACjE,SADuD,MAAM,CACjD;IAEZ,sFAAsF;IACtF,eAD2E,OAAO,CAC5D;CACzB"}

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

@@ -0,0 +1,77 @@
+import { CHART_TYPE } from "./atlas_chart_type.js";
+
+const EMPTY_U32 = new Uint32Array(0);
+const EMPTY_F64 = new Float64Array(0);
+
+/**
+ * One UV chart: a connected patch of the source mesh extracted into a
+ * self-contained, indexable structure for parameterization and packing
+ * (xatlas `Chart`).
+ *
+ * A chart-local ("unified") vertex is a distinct source mesh vertex used by the
+ * chart's faces — one geometric vertex shared by several faces of the chart maps
+ * to ONE chart vertex (and one UV), while the same geometric vertex in another
+ * chart is a separate chart vertex, which is how a seam arises. Triangle corners
+ * carry their source loop ids so solved UVs can be written back to the per-corner
+ * loop_data channel.
+ *
+ * Built by {@link atlas_extract_chart} (and the piecewise re-segmenter);
+ * parameterization fills {@link uv}/{@link type}; packing fills the `atlas_*`
+ * fields and rewrites {@link uv} into atlas space.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class Chart {
+    /** Number of chart-local (unified) vertices. @type {number} */
+    vertex_count = 0;
+
+    /** Chart-local vertex id -> source mesh vertex id. @type {Uint32Array} */
+    vertex_of_local = EMPTY_U32;
+
+    /** Flat xyz per chart-local vertex (length 3 * vertex_count). @type {Float64Array} */
+    positions = EMPTY_F64;
+
+    /** Triangle count. @type {number} */
+    triangle_count = 0;
+
+    /** 3 chart-local vertex ids per triangle. @type {Uint32Array} */
+    tri_local = EMPTY_U32;
+
+    /** 3 source mesh loop ids per triangle (per-corner UV write-back). @type {Uint32Array} */
+    tri_loops = EMPTY_U32;
+
+    /** Source mesh face id per triangle. @type {Uint32Array} */
+    tri_face = EMPTY_U32;
+
+    /** Flat pairs of chart-local vertex ids forming the chart outline. @type {Uint32Array} */
+    boundary_edges = EMPTY_U32;
+
+    /**
+     * (u, v) per chart-local vertex — local during parameterization, atlas-space
+     * (normalized to its page) after packing.
+     * @type {Float64Array}
+     */
+    uv = EMPTY_F64;
+
+    /** How the UVs were produced — a {@link CHART_TYPE} value. @type {number} */
+    type = CHART_TYPE.ORTHO;
+
+    /** Total 3D surface area. @type {number} */
+    surface_area = 0;
+
+    /** Total UV (parametric) area. @type {number} */
+    parametric_area = 0;
+
+    /** Atlas page the chart was packed onto. @type {number} */
+    atlas_page = 0;
+
+    /** Chart placement x within its page (texels). @type {number} */
+    atlas_x = 0;
+
+    /** Chart placement y within its page (texels). @type {number} */
+    atlas_y = 0;
+
+    /** Whether the chart was placed 90-degrees rotated during packing. @type {boolean} */
+    atlas_rotated = false;
+}