@woosh/meep-engine 2.164.0 → 2.165.0

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

@@ -0,0 +1,392 @@
+# Atlas Review 02 — meep vs xatlas (quality) + recent-literature survey
+
+Status: **research & planning only** (2026-06-25). No code changes proposed for now.
+Scope: chart (segmentation + parameterization) quality and packing quality of the meep
+UV-atlas port versus [jpcy/xatlas](https://github.com/jpcy/xatlas), plus a survey of recent
+(≈2017–2026) literature on charting, parameterization, and packing.
+
+Companion to [ATLAS_PORT_PLAN.md](ATLAS_PORT_PLAN.md) (the build contract + bench findings).
+
+---
+
+## 0. Executive summary
+
+meep is a faithful, deterministic, robustness-hardened port of xatlas's **core** algorithms —
+the same chart cost model, the same ortho→LSCM→piecewise parameterization cascade with the same
+acceptance thresholds, the same planar-region-atomic growth, and the same silhouette bitmap packer
+for small atlases. Where it differs, it has **deliberately omitted xatlas's quality-refinement
+passes** (chart merging, Lloyd seed relocation, a per-growth validity gate, best-fit packing, and
+silhouette packing at production scale) in favour of determinism, simplicity, and — above all —
+**speed at scale**.
+
+| Axis | Verdict vs xatlas | Magnitude (estimated) |
+|---|---|---|
+| **Parameterization** | **On par** | Algorithmically equivalent. xatlas marginally more robust LSCM assembly (ABF-angle rows); both share the same "no area control" limitation. |
+| **Chart segmentation** | **Modestly behind** on complex/curved meshes; **near parity** on flat/CAD content | ≈ **10–30 % more charts**, longer/raggier seams on organic meshes (missing `mergeCharts`, per-add validity gate, straightness term, largest-area seeding). Identical on planar-dominant content. |
+| **Packing** | **Behind at production scale** (deliberate speed trade); **near parity** on flat/rectangular charts and small atlases | ≈ **10–25 % lower utilization** on irregular/curved charts at ≥2048², in exchange for **~100–1000× faster** packing (3–43 ms vs xatlas's ~2 s random / ~43 s brute). |
+
+**Bottom line.** On clean, flat/CAD-like content meep is essentially at parity with xatlas. On
+complex curved/organic meshes it produces somewhat more charts and looser packing, while running
+dramatically faster. The two highest-value, lowest-risk quality wins, both classical and
+deterministic, are: (1) a **chart-merge + best-fit-packing** pass to close most of the structural
+gap, and (2) an **ARAP/SLIM-style isometric relaxation** (reusing the existing sparse-CG core) to
+kill the documented max-stretch outliers (133–359) that conformal LSCM cannot fix.
+
+> **Confidence / caveat.** The *direction* of every verdict is high-confidence (grounded in a
+> line-by-line read of both codebases — xatlas web-verified against `xatlas.cpp`/`xatlas.h` at
+> `master`). The *magnitudes* are **estimates**: there is **no head-to-head benchmark on identical
+> inputs** yet. In particular the chart-count (~10–30 %) and utilization (~10–25 %) percentages are
+> **extrapolated from the nature of the missing features**, not measured — they are the softest
+> numbers here. The single most useful follow-up is a same-mesh A/B harness (§5, item P0) to turn
+> these ranges into measured numbers.
+
+---
+
+## 1. Method
+
+- **meep side** — line-by-line read of `atlas_compute_charts.js`, `segment/*`, `param/*`,
+  `pack/*`, the `core/math/linalg/{cg,sparse}` solvers, and the 2D packing primitives
+  (`skyline.js`, `BitImage2.js`, `tri2_rasterize_conservative.js`, `min_area_rect_2d.js`), plus the
+  bench (`atlas_generate.bench.spec.js`) and ATLAS_PORT_PLAN findings.
+- **xatlas side** — web-verified extraction from `source/xatlas/xatlas.cpp` + `xatlas.h` (`master`):
+  `ChartOptions`/`PackOptions` defaults, `ClusteredCharts`/`PlanarCharts`, `computeCost`,
+  `computeLeastSquaresConformalMap`, `Chart::parameterize`, `PiecewiseParam`, `pack::Atlas::addCharts`,
+  `findChartLocation_{bruteForce,random}`. Corroborated against Castaño's "Lightmap Parameterization"
+  lineage and the TABI (2026) benchmark numbers for xatlas.
+- **Literature** — web searches across charting/cutting, parameterization/flattening, and packing;
+  each entry below is web-verified with a URL.
+
+---
+
+## 2. Chart segmentation (charting)
+
+### 2.1 What is identical
+
+meep's region-grow charter is a faithful port of xatlas's `ClusteredCharts` **cost core and growth
+substrate**:
+
+| Parameter / mechanism | meep | xatlas | Match |
+|---|---|---|---|
+| `maxCost` | 2 | 2.0 | ✅ |
+| `normalDeviationWeight` | 2 | 2.0 | ✅ |
+| `normalSeamWeight` | 4 | 4.0 | ✅ |
+| `roundnessWeight` | 0.01 | 0.01 | ✅ |
+| Hard normal reject | `1−dot ≥ 0.707` (~73°) | `≥ 0.707f` | ✅ |
+| Coplanar-region epsilon | `dot ≥ 1−1e-4` | `1e-4` | ✅ |
+| Planar-region **atomic** growth | default (regions are growth atoms) | yes (chart swallows whole coplanar region) | ✅ |
+| Greedy global-min candidate w/ lazy re-eval | yes (`IndexedFloatMinHeap`, stale-requeue) | yes (`CostQueue`, lazy pop) | ✅ |
+| Determinism + total coverage | yes (ascending seed, fixed reductions) | yes (deterministic tie-breaks) | ✅ |
+
+The three implemented cost terms — normal deviation `N = min(1−dot, 1)`, length-weighted normal
+seam `NS = Σ len·(1−dot)/Σ len`, and relative-isoperimetric roundness
+`R = 1 − (B²/A)_old/(B²/A)_new` — are the **exact xatlas formulas**, with identical weights.
+
+### 2.2 Where meep is behind
+
+| Feature xatlas has | meep status | Quality impact |
+|---|---|---|
+| **`straightnessWeight = 6.0`** (clamped ≤0; pulls boundaries onto concave creases / closes gaps) | **Absent** (only 3 of 5 terms implemented) | Raggier, slightly longer chart boundaries; this is xatlas's *highest-weighted* term. |
+| **`mergeCharts`** (merges slivers, embedded quads, contained charts; proxy-dot ≥ 0.5) | **Absent** | More, less-balanced charts; over-segmentation never cleaned up. **The single biggest gap.** |
+| **Per-add validity gate** (each candidate face is ortho-projected and rejected if it flips/overlaps; failed regions blacklisted) | **Absent** — validity is deferred to the parameterization stage | meep can grow a non-developable chart that only gets split *downstream* by an LSCM-failure → `atlas_piecewise_resegment`. xatlas keeps charts developable *at growth time*. |
+| **Lloyd seed relocation** (`relocateSeeds`→`resetCharts`, then re-grow) | **Absent** | Charts depend on seed order, not iterated centroid/best-fit relocation. (Modest: xatlas's default `maxIterations = 1` runs just one relocate pass.) |
+| **Largest-area-region seeding** | meep seeds by **ascending id** | Less well-centred initial charts. |
+| `textureSeamWeight = 0.5` | **Intentionally dropped** (no authored UVs in scope) | N/A — correct per locked scope. |
+
+### 2.3 Verdict — segmentation: **modestly behind**
+
+On **planar-dominant / CAD / architectural** meshes the planar-region fast path dominates and the
+two are effectively identical (a flat surface of any tessellation → one chart in both). On
+**curved / organic / decimated** meshes meep produces **~10–30 % more charts** with longer, less
+regular seams, and is more prone to the documented **max-stretch outliers (133–359)** because
+nothing splits a chart on a stretch criterion until parameterization fails. The dominant missing
+pieces, in order of impact: `mergeCharts` > per-add validity gate > straightness term >
+largest-area seeding ≈ Lloyd relocation.
+
+---
+
+## 3. Parameterization
+
+### 3.1 What is identical
+
+| Mechanism | meep | xatlas | Match |
+|---|---|---|---|
+| Cascade | Ortho → LSCM → Piecewise | Planar → Ortho → LSCM → Piecewise | ✅ (meep folds Planar into Ortho) |
+| Ortho-accept mean (L2) stretch | ≤ 1.1 | ≤ 1.1 | ✅ |
+| Ortho-accept max (L∞) stretch | ≤ 1.25 | ≤ 1.25 | ✅ |
+| Ortho-accept flips / zero-area / boundary self-intersect | all required clean | all required clean | ✅ |
+| Ortho plane fit | PCA smallest-eigenvector | least-squares fit (+eigen fallback) | ✅ (equivalent) |
+| LSCM | least-squares conformal, **2 diameter pins** | least-squares conformal, **2 diameter pins** | ✅ |
+| LSCM accept gate | **bijectivity only (not stretch)** | **bijectivity only (not stretch)** | ✅ (shared limitation) |
+| Piecewise fallback | greedy ortho region-grow into valid sub-charts | greedy ortho region-grow (`PiecewiseParam`) | ✅ |
+| Stretch metric | Sander/Hoppe L2+L∞, scale-normalized (similarity = 1.0) | same family | ✅ |
+
+### 3.2 The only real differences (both minor)
+
+- **LSCM row assembly.** meep uses the classic Lévy complex-edge formulation (`1/√area` weights)
+  for *every* triangle. xatlas uses an **ABF-angle formulation** (`setup_abf_relations`, interior
+  angles with a largest-angle swap for stability) and falls back to the complex-edge form only for
+  degenerate triangles. xatlas's is marginally more numerically robust; results are otherwise the
+  same conformal map.
+- **Solver.** meep: matrix-free **normal-equations** CG, cap `max(200, 10·free_cols)`. xatlas:
+  OpenNL CG, cap `5·V`. meep allows more iterations but the normal equations square the condition
+  number; xatlas's is slightly better conditioned. Both are CG-based least-squares; no practical
+  quality difference on the well-conditioned per-chart systems.
+
+### 3.3 Verdict — parameterization: **on par**
+
+meep is algorithmically equivalent to xatlas here. Same cascade, same thresholds, same 2-pin
+conformal LSCM, same bijectivity-only acceptance, same guaranteed-terminating piecewise fallback.
+xatlas's only edge is the ABF-angle LSCM rows (a hair more robust). **Both share the same ceiling:**
+conformal LSCM preserves angles but not area, and neither minimizes stretch after the solve — so the
+133–359 max-stretch outliers exist by design in *both*. This is the axis where literature (§4.2)
+offers the clearest upgrade for *both*.
+
+---
+
+## 4-prelude. Packing
+
+### Packing — what is identical
+
+| Mechanism | meep | xatlas | Match |
+|---|---|---|---|
+| Utilization sizing target | 0.75 | 0.75 | ✅ |
+| Per-chart scale `√(surf/param)·density` | yes | yes | ✅ |
+| Rotate-to-min-area-OBB | yes (`rotateChartsToAxis`) | yes | ✅ |
+| 90° placement rotation | yes (`rotateCharts`, mask+transpose) | yes (0°/90° only — *not* 4-way) | ✅ |
+| Sort order | perimeter descending | perimeter descending | ✅ |
+| Small-atlas packer | bitmap **silhouette** canBlit (shifted-OR + or_blit) | bitmap silhouette | ✅ |
+| Conservative raster + padding dilation | yes | yes (+ optional `bilinear` expand) | ✅ |
+| Multi-page spill / pow-2 growing page | yes | yes | ✅ |
+
+### Packing — where meep is behind
+
+| Feature | meep | xatlas | Impact |
+|---|---|---|---|
+| **Placement selection** | **first-fit** (lowest-then-leftmost, no scoring) | **best-fit** — scores candidates by `max(extent)² + area` (square-biasing), via stepped brute-force or 4096 random attempts | Looser, less-square atlases. Best-fit vs first-fit is a well-known density gap. |
+| **Packer at production scale (>256²)** | switches to **skyline rectangle** packer (bounding boxes, simple skyline overhang waste) | keeps the **bitmap silhouette** packer at *all* sizes | meep packs rectangles where xatlas interlocks silhouettes → notably lower utilization on irregular charts at scale — but **100–1000× faster** (3–43 ms vs xatlas ~2 s/~43 s). A deliberate trade (meep measured the bitmap path at 13–22 s/2048²). |
+| **`blockAlign` 4×4** (BC/DXT block safety) | **Absent** (backlog) | optional (default off) | Charts can straddle compression-block edges → bleed under BC/ETC/ASTC. |
+| **bilinear-tap expansion** | `dilate(padding)` only | `bilinearExpand` + dilate | Cosmetic; meep's conservative raster + dilate covers most of it. |
+| Density search | **elastic**: re-pack up to 40× at 0.8× density | scale solved ~once | meep-specific robustness, but up to 40× redundant packing work in the worst case. |
+
+### Packing — verdict: **behind at production scale, near parity small/flat**
+
+- **≤256² atlases:** same silhouette-interlocking class, but first-fit vs best-fit → meep slightly
+  looser.
+- **Flat / rectangular charts:** skyline does fine (bench high end ~95 %) → near parity.
+- **Irregular / curved charts at ≥2048²:** meep's rectangle skyline leaves more waste than xatlas's
+  silhouette best-fit → **~10–25 % lower utilization (estimated)**, bought with a **~100–1000×
+  speedup**. xatlas is the offline quality reference (TABI 2026: xatlas-random ≈ 1.89 avg L2
+  stretch, the best of the compared methods, at ~2 s/model; brute ~43 s).
+
+---
+
+## 4. Literature survey (≈2017–2026)
+
+Web-verified; URLs included. Grouped by axis. The recurring meta-finding: the field has moved past
+the 2002-LSCM / 2005-D-Charts lineage that xatlas (and thus meep) implements, but **the best ideas
+for a deterministic, dependency-free, real-time library are the classical-compatible ones** — the
+neural/RL methods contribute *objectives* (distortion-driven cuts, fewer charts) far more than
+*portable algorithms*.
+
+### 4.1 Charting / cutting / seam placement
+
+| Work | Year | One-line | Relevance to meep |
+|---|---|---|---|
+| [D-Charts: Quasi-Developable Mesh Segmentation](https://www.cs.ubc.ca/~sheffa/papers/EG05.pdf) | 2005 | Region-grow with a **cone-fit** developability metric, bounding distortion *during* segmentation | meep's direct ancestor; the **cone-fit proxy** (vs pure normal-deviation) would let cylinders/cones grow into single charts → kills the curved-mesh over-fragmentation + stretch outliers. **Lowest-risk, highest-fit.** |
+| [Variational Surface Cutting](https://www.cs.cmu.edu/~kmcrane/Projects/VariationalCuts/) | 2018 | Global PDE flow evolves the cut graph to minimize distortion + seam length | The "global, length-regularized cuts" counter-philosophy to greedy grow. Too heavy to port; motivates a boundary-length term + boundary-straightening post-pass. |
+| [OptCuts: Joint Cuts + Parameterization](https://www.cs.ubc.ca/labs/imager/tr/2018/OptCuts/) | 2018 | A single **distortion bound** drives the cuts; alternates cut-update ↔ symmetric-Dirichlet flatten; globally bijective, minimal seam length | The strongest argument to make a **distortion threshold the primary segmentation knob** (meep's `stretch` metric already exists). Replace the LSCM-fail→explode fallback with a distortion-bounded re-cut. |
+| [AutoCuts](https://dl.acm.org/doi/abs/10.1145/3130800.3130845) | 2017 | One differentiable distortion+seam-length energy; cuts emerge from it | Portable cheap heuristic: add an explicit **boundary-length penalty** to the grow/merge cost (data already in `atlas_build_edge_lengths.js`). |
+| [Developability-Driven Piecewise Approximations](https://dl.acm.org/doi/10.1145/3528223.3530117) | 2022 | Deform-then-partition into near-developable patches with regular seams | "Light developability-aware normal smoothing *before* segmentation" lets the existing grower form larger, cleaner charts. |
+| [Evolutionary Piecewise Developable Approximations](https://dl.acm.org/doi/10.1145/3592140) | 2023 | Global/evolutionary search for fewer patches | Evidence that iterate-and-merge (the `mergeCharts`/Lloyd backlog) is the right direction; full search is diminishing returns for a real-time lib. |
+| [PartUV: Part-Based UV Unwrapping](https://arxiv.org/abs/2511.16659) | 2025 | Top-down recursive split under a distortion bound + learned part priors; ~1/31 Blender's chart count | **Most directly relevant modern paper.** The **recursive-split-only-when-distortion-exceeds-the-bound** skeleton is deterministic and portable even without the learned part decomposition → fewer, larger charts. |
+| [SeamGPT / Auto-Regressive Surface Cutting](https://arxiv.org/abs/2506.18017) · [MeshTailor](https://arxiv.org/abs/2603.27309) · [SeamCrafter](https://arxiv.org/abs/2509.20725) | 2025–26 | GPT-style learned seam generation mimicking artist cuts | Not portable (datasets + transformers). Transferable: seams follow **high-dihedral feature edges** (meep has `edge_dihedral`) and want **long coherent chains** → a boundary-chain straightening post-pass. SeamCrafter's **seam-evaluation score** (= f(seam length, fragmentation, distortion)) is a portable objective. |
+| [Unsupervised Param w/ Semantic + Visibility](https://arxiv.org/abs/2509.25094) | 2025 | AO-weighted seam term hides cuts in occluded regions | Portable: a cheap per-edge AO/visibility proxy (reuse engine BVH) biasing the cost to **hide seams** — a dimension meep's purely-geometric cost ignores. |
+| [Nuvo: Neural UV Mapping](https://pratulsrinivasan.github.io/nuvo/) | ECCV 2024 | Per-asset neural field for *unruly* (NeRF/soup) geometry | Out of scope (meep requires clean welded manifolds). A scope marker for if meep ever ingests scanned/AI soup. |
+
+### 4.2 Parameterization / flattening / injectivity
+
+| Work | Year | One-line | Relevance to meep |
+|---|---|---|---|
+| [LSCM](https://dl.acm.org/doi/10.1145/566654.566590) | 2002 | The conformal-LS + region-grow pipeline meep/xatlas implement | Validates meep's core as the well-understood baseline; improvement budget is better spent on cuts + isometric relaxation than on this solver. |
+| [ARAP/ASAP local–global](https://www.eecs.harvard.edu/~sjg/papers/arap.pdf) | 2008 | Per-triangle rotation fit + one sparse SPD stitch solve, iterated | **Cheapest meaningful upgrade over LSCM.** Each global step is the *same* CG solve meep already runs; minimizes *isometric* (shape) distortion → directly attacks high-stretch charts. No injectivity guarantee (flip gate stays). |
+| [SLIM: Scalable Locally Injective Maps](https://igl.ethz.ch/projects/slim/) | 2017 | Local/global for flip-preventing barrier energies (symmetric Dirichlet); reused-Hessian sparse solves | **Strongest candidate to replace the whole cascade.** Guarantees no flips (vs meep's post-hoc reject), minimizes isometric distortion, scales to millions of faces. Needs an injective init + line search; ~20–40 solves/chart, only on charts failing the ortho gate. |
+| [Boundary First Flattening (BFF)](https://arxiv.org/abs/1704.06873) | 2017 | Linear conformal flattening with **explicit boundary control**; one Laplacian factorization | Natural drop-in over free-boundary LSCM; reuses the (present-but-unused) `v3_cotangent`. Automatic minimal-area boundary → fewer cuts, fewer self-intersection rejects. Caveat: cot-Laplacian indefinite on obtuse triangles (clamp / intrinsic Delaunay). |
+| [Foldover-free maps in 50 lines](https://arxiv.org/abs/2102.03069) + [Practical Lowest Distortion](https://arxiv.org/abs/2201.12112) | 2021–22 | Untangle from an **arbitrary (even folded)** start, then minimize mean then **max** distortion; tiny, deterministic, Newton/L-BFGS | **Most meep-aligned modern optimizer.** Can subsume *both* the flip-reject path *and* the piecewise-explode fallback: feed it the ortho/LSCM output, get a foldover-free low-distortion chart. Optimizes **max distortion last** — exactly meep's accept/reject quantity. |
+| [Progressive Parameterizations](https://dl.acm.org/doi/10.1145/3197517.3201331) | 2018 | Foldover-free, low-distortion via a progressive reference; 20k-mesh reliability study | Robustness-engineered alternative/complement to SLIM; composes with meep's CG + an ARAP step. |
+| [Isometric Energies (IsoSEA/IsoTLC)](https://duxingyi-charles.github.io/publication/isometric-energies-for-recovering-injectivity-in-constrained-mapping/) | 2022 | Recover injectivity *and* minimize isometric distortion in one energy | A strong default barrier energy if meep builds the optimizer; same solver shape as SLIM/foldover-free. |
+| [Progressive Embedding](https://github.com/hankstag/progressive_embedding) | 2019 | Float-robust replacement for Tutte; collapse→re-insert keeping a valid embedding | The robust **injective initializer** any barrier solver needs; overlaps meep's existing half-edge collapse simplifier (`bt_mesh_simplify_by_error`). |
+| [Scaffold (2017)](https://cims.nyu.edu/gcl/papers/Scaffold-2017.pdf) + [Efficient Bijective (2020)](https://dl.acm.org/doi/10.1145/3386569.3392435) | 2017–20 | Turn *global* bijectivity into *local* injectivity via a (boundary-band) scaffold | If meep ever wants one guaranteed-overlap-free chart for a whole object; the 2020 boundary-band version scales with boundary length (matches meep's perf culture) and removes the O(b²) self-intersection test. |
+| [CETM](https://dl.acm.org/doi/10.1145/1360612.1360676) | 2008 | Discrete conformal via convex log-scale energy (cot-Laplacian Hessian); auto cone singularities | Theoretical anchor for BFF; cone-singularity idea = fewer cuts on high-curvature closed charts. Reference, not a port target. |
+| [TinyAD](https://onlinelibrary.wiley.com/doi/full/10.1111/cgf.14607) | 2022 | Per-element AD → free Newton solver; the prototyping pattern | The **design blueprint**: per-triangle local energy + small analytic 2×2/3×3 Hessian → assemble into `SparseMatrixCSR` → `cg_solve`, behind one energy interface, so meep can swap conformal/ARAP/symmetric-Dirichlet/IsoSEA without re-deriving. |
+
+### 4.3 Packing
+
+| Work | Year | One-line | Relevance to meep |
+|---|---|---|---|
+| [A Thousand Ways to Pack the Bin (Jylänki)](https://github.com/juj/RectangleBinPack) | 2010 | Canonical 2D rect-packing survey: MaxRects > Guillotine > Skyline-BL > Shelf on density; reverse on speed | Locates meep's skyline packer; **best-short-side-fit / min-waste** skyline variants beat plain bottom-left; MaxRects is the density upgrade path meep lacks. Validates the {0°,90°} rotation set. |
+| [TABI: Tight & Balanced Interactive Atlas Packing](https://arxiv.org/abs/2602.07782) | 2026 | **Per-axis "local AABB" + OBB proxies**, row-folding, horizontal+vertical compaction; closes ~48 % of the gap to offline xatlas at **~5 ms (~464× faster)** | **Most actionable modern reference.** The local-AABB proxy gives most of the interlocking benefit of meep's bitmap mask at O(slices) cost → lets meep pack tightly **above** its 256² bitmap ceiling, bridging its exact-but-small and loose-but-scalable packers. |
+| [FastAtlas: Real-Time Compact Atlases](https://arxiv.org/abs/2502.17712) | 2025 | GPU parallel: bucket by height, parallel scale-search, row-fold, advancing-front push-up; <1.5 ms on 9M-tri | The **"compute the right scale ~once, allow overflow then rescale"** idea is a serial-friendly alternative to meep's 40× elastic-shrink retry loop. |
+| [Two-dimensional irregular packing: a review](https://www.frontiersin.org/journals/mechanical-engineering/articles/10.3389/fmech.2022.966691/full) | 2022 | NFP vs raster/pixel vs envelope; metaheuristic sequence optimization | Locates meep's bitmap canBlit precisely as the **raster/pixel** method — cheap overlap test, **poor at *searching* for the best position** (exactly meep's first-fit weakness). NFP = tighter but fragile on concave/holed shapes. |
+| [stb_rect_pack / Skyline-BL practitioner study](https://www.david-colson.com/2020/03/10/exploring-rect-packing.html) | 2020 | Skyline-BL + first-fit-decreasing is simple, fast, "good enough" | Validates meep's skyline-as-scalable-default; highest leverage is in **ordering + best-fit metric**, not the data structure. |
+| [WebRender atlas allocation](https://mozillagfx.wordpress.com/2021/02/04/improving-texture-atlas-allocation-in-webrender/) | 2021 | Dynamic (online) atlases prefer shelf/slab over guillotine (fragmentation) | Boundary marker: meep's pack is **offline/one-shot**, so high-density guillotine/MaxRects methods are fair game; the fragmentation caveat only applies if meep grows a *streaming* atlas. |
+| [Learning Gradient Fields for Irregular Packing](https://arxiv.org/abs/2310.19814) · [Attend2Pack](https://arxiv.org/abs/2107.04333) · [RCQL](https://arxiv.org/abs/2111.06726) | 2021–23 | Learned/RL packing; scales to 1000s of pieces | Gains over strong heuristics are **single-digit %**, and the real lever is **ordering policy**. Watch-items, not adopt-items; the takeaway is "try several deterministic orderings, keep the best." |
+| [Ptex / UDIM / Htex](https://www.fxguide.com/fxfeatured/ptex_the_other_side/) | 2008/2002/2022 | Sidestep packing entirely (per-face/per-halfedge) or relax to integer tiles | Bounds the ambition: chasing the last few % of density only matters because meep is atlas-committed. UDIM maps naturally onto meep's existing multi-page support — a possible future output mode. |
+| [Robust NFP generation](https://www.mdpi.com/2227-7390/10/16/2941) | 2019–22 | No-fit-polygon = the tight-irregular-nesting primitive | The max-density frontier for meep's concave charts, but expensive/fragile on non-convex+holed shapes — why the port chose bitmap. Held as a documented "if we ever need maximum density" option. |
+
+---
+
+## 5. Prioritized opportunities (planning backlog — deterministic, dependency-free only)
+
+Ranked by estimated value ÷ effort. **All are classical/deterministic** — the neural/RL methods are
+explicitly *not* adopt-items (non-deterministic, heavy deps, only approximately bijective, against
+meep's exact/black-box-tested library semantics); we harvest their *objectives*, not their models.
+
+### 5.0 MEASURED OUTCOMES (2026-06-26) — the gating already ran
+
+The P0 metrics harness was built ([atlas_bench_lib.js](atlas_bench_lib.js) +
+[atlas_metrics.bench.spec.js](atlas_metrics.bench.spec.js): chart count + chart-type histogram,
+stretch mean/max/p50/p90/p99 + high-distortion tail, seam length, utilization, A/B runner) and used to
+gate the three Tier-1 items below. **All three were measured to *not* be free wins on our actual
+pipeline** — and the harness surfaced the real lever instead. This is the payoff of measuring first.
+
+| Tier-1 item | Measured verdict | Evidence |
+|---|---|---|
+| **mergeCharts** | **Trade-off, not a win** — kept as an off-by-default opt-in (`segment.merge`, `mergeMinDot`). Implemented + 6 unit tests. | Safe threshold (0.9) → −1 % charts (greedy already joins coplanar regions). Effective (0.5) → −20 % charts / −7 % seam but **p99 stretch 4.27→15.21** and piecewise 127→192. No threshold gives fewer-charts-AND-no-stretch-regression. |
+| **best-fit packing** | **Rejected** (implemented, measured, reverted). | Δutil **0.00pp** on every fixture in both elastic and growing-page modes — min-waste's few-% gain is masked by pow2 pages + 0.8× elastic-density quantization. |
+| **ARAP-for-curvature** | **Premise invalidated** (not built). | Clean curved/developable surfaces (sphere, hemisphere, cylinder, cone, torus) already flatten with **max stretch ≤ 1.5**. LSCM is essentially isometric there. |
+
+**The real lever the harness found: LSCM boundary self-intersection.** The dominant quality problem is
+*not* any of the three above. On the decimated terrain (970 charts, **127 piecewise-explosion
+sub-charts**), failure-reason instrumentation of the parameterize cascade showed the explosion comes
+from **31 LSCM charts that fail bijectivity, ALL 31 on boundary self-intersection** (zero on
+zero-area / degenerate-input / mixed-winding). Free-boundary conformal LSCM has no injectivity
+guarantee, so on complex/curved boundaries the UV outline overlaps itself; the piecewise fallback then
+(correctly) cuts each into ~4 ortho pieces. *(A sliver/degenerate-input hypothesis was tested first and
+disproven — a degenerate-input-tolerant validity tweak was provably inert and reverted. The max-stretch
+~5877 outlier is real but area-negligible: the area-weighted mean stays ~2.5.)*
+
+**Attempt 1 — Tutte/convex-boundary rescue (built, measured, then REMOVED).** The natural first try is a
+guaranteed-injective embedding: pin each self-intersecting disk chart to a circle and solve the interior
+(Tutte's theorem ⇒ no flips, no self-intersection). It **works structurally** — on the decimated
+terrain it eliminated the explosion (127 piecewise → 0, replaced by 31 whole charts, **−96 charts**,
+utilization **71.9 % → 86.3 %**, all guaranteed bijective) — but the **distortion is catastrophic**:
+mean stretch **2.55 → 70.9**, p99 **4.27 → 2467**. The self-intersecting charts are *thin/curled* (that
+is why LSCM curled them), so forcing them onto a circle ruins them. **Confirmed boundary-dominated:**
+upgrading the interior weights uniform → Floater mean-value changed nothing (70.82 → 70.88). So a
+convex-boundary embedding is the wrong tool here, and the piecewise explosion (compact low-distortion
+pieces) is the *better* quality outcome.
+
+**Attempt 2 — shape-aware convex boundary (built, measured, reverted).** Map the boundary to an
+aspect-matched ellipse instead of a circle (still convex ⇒ still injective). **No improvement** (71.67 vs
+70.9): a curled chart's LSCM layout curls into a roughly *round* blob, so its aspect can't be estimated
+without already flattening — a catch-22 that rules out the whole convex-boundary family.
+
+**Attempt 3 — BFF, intrinsic boundary-first (built, measured, now ALWAYS-ON; the right approach).**
+`CHART_TYPE.BFF`: build the flat boundary from the chart's own edge lengths + curvature
+(Gauss-Bonnet closure), then a **conformal** pinned-boundary interior (harmonic was tried first and
+flipped 26/31; conformal is far less flip-prone). **It clears the gate the convex family failed** —
+decimated terrain −4 charts, mean stretch **2.55 → 2.51 (better, not worse)**, every BFF chart bijective,
+no clean-fixture regression: a Pareto-safe win, not Tutte's 70×. **But tiny magnitude — only 1 of 31**
+self-intersecting charts is rescued; the other 30 fail (diagnosed: 25 flip, 5 self-intersect) because the
+v1 **uniform** curvature redistribution leaves the boundary too contorted.
+
+**Attempt 4 — BFF's optimal Dirichlet-to-Neumann boundary (built, measured; the definitive answer).**
+Replaced the uniform curvature with the DtN-optimal distribution (fix boundary scale 0, interior Poisson
+`L_II u = Ω_I`, `k̃_b = (π−θ_b) − (L u)_b`). The **DtN boundary fixed the interior** — conformal-interior
+flips **25 → 2** — and stayed Pareto-safe (−6 charts, mean 2.55 → 2.51, p99 4.27 → 3.99). **But still only
+~2 of 31 rescued: the flattened *boundary* now self-intersects on ~27/31, and that is FUNDAMENTAL** — true
+unclamped cotangents made it *worse* (1 rescue, 30 self-intersections). These high-curvature decimated
+charts **cannot be developed to a simple boundary** while preserving edge lengths, so cutting (piecewise)
+is the correct injective answer; BFF rescues only the ~2 low-curvature ones.
+
+**Conclusion (the metrics settle it): the piecewise explosion is largely correct behavior** for
+decimated/high-curvature charts — they are intrinsically un-flattenable-whole, and BFF (the right,
+fully-built tool) confirms it. BFF is **folded into the single always-on cascade** (ortho → LSCM → BFF →
+piecewise, no flags): it is free (compute delta ~−0.3 %, since it runs only on charts that already failed
+LSCM) and strictly Pareto-safe (accepts only bijective + near-isometric whole charts). The failed Tutte
+convex-boundary path was **removed** (strictly dominated). The only way to
+keep these charts whole would be to let the *boundary be cut* during optimization (OptCuts-style joint
+cut+flatten) or a scaffolded injective nonlinear map (SLIM) — large, separate builds whose payoff (~29
+hard charts, decimated assets only) the metrics say is modest. So: **no further parameterization work is
+warranted on the current asset mix; the validated atlas pipeline is in good shape, and the residual
+over-segmentation on decimated content is the right answer, not a defect.**
+
+### 5.1 Original ranked backlog (pre-measurement — kept for context)
+
+**P0 — Head-to-head A/B bench.** ✅ **DONE** (the metrics harness above). The remaining gap is an
+*xatlas* side-by-side on identical meshes (we have meep-side metrics + xatlas's published numbers).
+
+**Tier 1 — biggest quality-per-effort, reuse existing infra**
+
+1. **`mergeCharts` pass** (xatlas parity + Evolutionary-Developability evidence). Post-segmentation
+   greedy merge of adjacent charts whose proxy normals agree (dot ≥ ~0.5) and whose merged ortho
+   projection stays valid. Closes most of the segmentation chart-count gap. *Effort: moderate;
+   reuses the cost/validity machinery.* → **MEASURED (§5.0): trade-off, shipped off-by-default.**
+2. **Best-fit placement metric in the bitmap packer** (xatlas + Jylänki). Replace `find_first_fit`'s
+   first-feasible return with a scored scan (`max(extent)² + area`, or contact-perimeter / wasted-gutter).
+   Highest-leverage single packing-density win. *Effort: low.* → **MEASURED (§5.0): 0.00pp, rejected**
+   (note: measured for the skyline path; the bitmap-path best-fit is untested but the same pow2/elastic
+   quantization applies, so it is deprioritized).
+3. **ARAP local/global as the LSCM successor** (Liu 2008 → SLIM). One per-triangle rotation fit +
+   the *same* sparse-CG global solve, iterated — invoked only on charts that fail the ortho gate.
+   Directly attacks the 133–359 max-stretch outliers conformal LSCM cannot fix. *Effort: low–moderate;
+   reuses `cg_solve`.* → **MEASURED (§5.0): premise invalidated for curvature** (clean curved meshes
+   already flatten ≤1.5; the outliers are sliver-driven). ARAP would only help *if* paired with sliver
+   cleanup — re-evaluate after the sliver work, not before.
+
+**Tier 2 — strong, moderate effort**
+
+4. **D-Charts cone-fit developability proxy** in the segmentation cost (Julius 2005). Augment the
+   per-face normal-deviation with a cone-fit angle so curved-but-developable regions (cylinders,
+   cones, fillets) grow into single charts. Targets the curved-mesh over-fragmentation at its root.
+5. **TABI local-AABB proxy packer above 256²** (TABI 2026). Per-axis interval-AABBs give most of the
+   silhouette-interlocking benefit at O(slices) cost → tight packing at production sizes without the
+   bitmap's O(area·mask) blowup. Bridges meep's exact-small / loose-large packer split.
+6. **Distortion-bounded re-cut instead of piecewise explode** (OptCuts/PartUV). When a chart's
+   stretch exceeds the bound, open the seam along the highest-distortion edge ring (top-down,
+   recursive) rather than exploding into many ortho sub-charts → fewer, larger charts, shorter seams.
+7. **Multi-ordering best-of-N packing** (RL "sequence" lesson, xatlas "attempts"). Try a few
+   deterministic orderings (area-desc, max-side-desc, height-desc, perimeter-desc) and keep the
+   tightest. *Effort: low.*
+
+**Tier 3 — targeted / opportunistic**
+
+8. **Straightness cost term** + **boundary-chain straightening post-pass** (xatlas parity +
+   AutoCuts/Variational + MeshTailor ChainingSeams). Add the missing 5th cost term and walk each
+   chart boundary to snap it onto connected high-dihedral chains → boundary regularity.
+9. **`blockAlign` 4×4** (xatlas) — if atlas pages ever feed BC/ETC/ASTC compression.
+10. **Foldover-free / Practical-Lowest-Distortion untangler** (2021–22) — the heavier but
+    most-meep-aligned option to *replace both* the flip-reject and piecewise-explode paths with one
+    deterministic untangling solve that minimizes max distortion last. Build behind a TinyAD-style
+    one-energy-interface so conformal/ARAP/symmetric-Dirichlet/IsoSEA are swappable.
+11. **BFF parameterization backend** behind a `CHART_TYPE` flag — linear, boundary-controlled, fewer
+    self-intersection rejects; reuses the unused `v3_cotangent`.
+12. **Visibility/AO-weighted seam term** (ICLR-2026) — bias seams into occluded edges using the
+    engine BVH; for atlases that feed final rendering.
+13. **Largest-area seeding + ≥1 Lloyd relocation** (xatlas parity) — small, completes the
+    segmentation-parity story.
+
+---
+
+## 6. Appendix — parameter cross-reference (verified)
+
+**Segmentation** (meep `ATLAS_SEGMENT_DEFAULTS` vs xatlas `ChartOptions`):
+`maxCost 2 / 2.0` ✅ · `normalDeviationWeight 2 / 2.0` ✅ · `normalSeamWeight 4 / 4.0` ✅ ·
+`roundnessWeight 0.01 / 0.01` ✅ · `straightnessWeight —/6.0` ❌ · `textureSeamWeight —/0.5`
+(dropped, intentional) · hard reject `0.707 / 0.707` ✅ · coplanar eps `1e-4 / 1e-4` ✅ ·
+`maxIterations` 1-pass-no-relocate / 1-pass-with-relocate+merge+fill ❌ · seed `ascending-id /
+largest-area-region` ❌.
+
+**Parameterization:** ortho-accept `mean≤1.1, max≤1.25` ✅✅ · LSCM `2 diameter pins` ✅ · LSCM rows
+`complex-edge(Lévy) / ABF-angle(+fallback)` ~ · solver `normal-eq CG / OpenNL CG` ~ · LSCM accept
+`bijectivity-only` ✅ (shared limitation) · piecewise `greedy ortho grow` ✅.
+
+**Packing:** util target `0.75 / 0.75` ✅ · `rotateChartsToAxis true/true` ✅ · `rotateCharts(90°)
+true/true` ✅ · sort `perimeter-desc / perimeter-desc` ✅ · placement `first-fit / best-fit` ❌ ·
+scale packer `skyline-rect(>256²) / bitmap-silhouette(all sizes)` ❌ (deliberate) · small packer
+`bitmap-silhouette / bitmap-silhouette` ✅ · `blockAlign —/optional` ❌ · density `elastic-40× /
+solved-once` (meep-specific).
+
+**Source of record:** xatlas web-verified at `source/xatlas/xatlas.{cpp,h}` `master`; meep at
+`src/core/geom/3d/atlas/**` (see ATLAS_PORT_PLAN.md for file map). All literature URLs above are
+web-verified.

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

@@ -0,0 +1,73 @@
+/** Flat n×n plane in z=0. Single planar region => one chart, zero stretch. */
+export function soup_plane(n: any): any[];
+/** Deterministic gently-bumpy terrain (curved, smooth, no RNG). */
+export function soup_terrain(n: any, amplitude: any): any[];
+/** Dense bumpy terrain decimated by the production simplifier -> irregular, over-segmenting asset. */
+export function soup_decimated_terrain(n: any, amplitude: any, error: any): number[];
+/** UV sphere (fanned poles, no degenerate tris). Smooth closed surface. */
+export function soup_uv_sphere(rings: any, sectors: any): any[];
+/** Upper hemisphere cap (intrinsic positive curvature -> MUST distort under any flattening). */
+export function soup_hemisphere(rings: any, sectors: any): any[];
+/** Open cylinder side (no caps): a DEVELOPABLE surface — should flatten to a flat strip with ~zero stretch. */
+export function soup_cylinder_open(radial: any, rings: any, height: any, radius: any): any[];
+/** Open cone side (no base): DEVELOPABLE — flattens to a circular sector with ~zero stretch. */
+export function soup_cone_open(radial: any, rings: any, height: any, radius: any): any[];
+/** Torus: irregular, curved charts (a packing stress fixture). */
+export function soup_torus(rings: any, sides: any, R: any, rr: any): any[];
+/** Grid of unit cubes (each cube => 6 charts at 90°; a chart-count fixture). */
+export function soup_cube_field(count: any): any[];
+export function build_mesh(soup: any): BinaryTopology;
+/**
+ * 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: Chart[]): object;
+/** Total 3D length of edges cut between different charts (texture seams) + fraction of interior length. */
+export function seam_metrics(mesh: any, charts: any): {
+    seam_len: number;
+    seam_pct: number;
+    interior_len: number;
+};
+/**
+ * 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: number[], computeOpts?: object, packOpts?: object): object;
+/** Median wall-clock of `fn` over a time budget, with warmup. */
+export function time_median(fn: any, budget_ms?: number, warmup?: number): any;
+/**
+ * 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: number[], a: {
+    compute?: object;
+    pack?: object;
+}, b: {
+    compute?: object;
+    pack?: object;
+}): {
+    base: object;
+    cand: object;
+    delta: object;
+};
+/** Compact one-line metric panel for console output. */
+export function fmt(m: any): string;
+/** Charts whose worst (L∞) per-triangle stretch exceeds this count as the "high-distortion tail". */
+export const TAIL_STRETCH: 2;
+import { BinaryTopology } from "../topology/struct/binary/BinaryTopology.js";
+//# sourceMappingURL=atlas_bench_lib.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"atlas_bench_lib.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/atlas/atlas_bench_lib.js"],"names":[],"mappings":"AAoCA,8EAA8E;AAC9E,0CAKC;AAED,mEAAmE;AACnE,4DAMC;AAED,sGAAsG;AACtG,qFAIC;AAED,2EAA2E;AAC3E,gEAYC;AAED,gGAAgG;AAChG,iEAYC;AAED,+GAA+G;AAC/G,6FAQC;AAED,gGAAgG;AAChG,yFAUC;AAED,kEAAkE;AAClE,2EASC;AAED,gFAAgF;AAChF,mDAWC;AAED,sDAIC;AA8BD;;;;;;;;GAQG;AACH,sCALW,OAAO,GACL,MAAM,CA0ClB;AAED,2GAA2G;AAC3G;;;;EAsBC;AAGD;;;;;;;;GAQG;AACH,8BALW,MAAM,EAAE,gBACR,MAAM,aACN,MAAM,GACJ,MAAM,CAgBlB;AAED,iEAAiE;AACjE,+EAWC;AAED;;;;;;;;GAQG;AACH,yBALW,MAAM,EAAE,KACR;IAAC,OAAO,CAAC,EAAC,MAAM,CAAC;IAAC,IAAI,CAAC,EAAC,MAAM,CAAA;CAAC,KAC/B;IAAC,OAAO,CAAC,EAAC,MAAM,CAAC;IAAC,IAAI,CAAC,EAAC,MAAM,CAAA;CAAC;UACvB,MAAM;UAAO,MAAM;WAAQ,MAAM;EAUnD;AAED,wDAAwD;AACxD,oCAMC;AApJD,qGAAqG;AACrG,6BAAgC;+BAvKa,6CAA6C"}