@woosh/meep-engine 3.60.3 → 3.60.5

package/src/shade/renderer/geometry/virtual/MICRON_COMPARISON_2026_08_20.md

@@ -1,305 +0,0 @@
-# Micron — what the prior WebGL implementation knows
-
-Review of `moicon/prime/src/components/Viewer/Viewer.Meep/Micron/` (~11.8k lines, three.js /
-WebGL) against the current design and builder. Micron is this system's direct ancestor:
-same author, same problem, same 128-triangle patch. It shipped, which is worth something —
-where it agrees with the design that is corroboration, and where it disagrees it is usually
-because it hit something.
-
-Paths below are relative to the Micron root.
-
-> **Status.** Reviewed and decided. What was taken, what was declined and why, and what is
-> scheduled but not yet built, all live in
-> [VIRTUAL_GEOMETRY_PLAN.md](./VIRTUAL_GEOMETRY_PLAN.md) — that file is the one to act on.
-> This one is kept as the analysis behind those decisions.
->
-> It is a **snapshot dated in its filename** and is not maintained against the code. Statements
-> about meep that have since gone stale are corrected inline in block quotes like this one,
-> rather than edited away — the argument that was made at the time is the reason the decision
-> was taken, and rewriting it hides that.
-
-## 1. Where the two already agree
-
-Not findings, but worth stating, because agreement across a decade-apart rewrite is the
-cheapest evidence available that a decision is not arbitrary.
-
-| | Micron | meep |
-|---|---|---|
-| Patch/cluster cap | `MICRON_PATCH_SIZE_MAX = 128` | `VGEO_MAX_CLUSTER_TRIANGLE_COUNT = 128` |
-| Merge unit | group of patches, one error and one bounds for the whole step | same |
-| Termination | `while (__node_count > 1)`, throws when it cannot reduce | same, throws |
-| Nothing to merge with | `merge_patches`: `node_count === 1` → forward to output unchanged | frontier pass-through |
-| Group size | starts at 4, doubles on stall, hard limit 64 | starts at 4, doubles on stall |
-| Islands | `graph_create_off_mesh_links` once adjacency runs out | Morton proximity bundling once adjacency runs out |
-
-`build/hierarchy/buildAbstractPatchHierarchy.js` is the loop, and it reads like the round
-loop that just landed — including the two things that were fixed this week (single root,
-pass-through). Micron had both from the start.
-
-## 2. Worth borrowing
-
-Ranked by what they would actually change.
-
-### 2.1 Accumulated vertex quadrics carried through the whole hierarchy
-
-`buildAbstractPatchHierarchy` builds `Map<vertex_index, Quadratic3>` **once, from the
-leaves**, and threads it through every merge. `many_to_many_merge` deep-copies the relevant
-entries, simplifies against them, and writes them back only if the merge is accepted. The
-group's error is then
-
-```js
-vertex_error_sqr = vertex_quadratic.evaluate(vertex.x, vertex.y, vertex.z)   // max over vertices
-```
-
-— the accumulated quadric evaluated at the vertex's *final* position.
-
-meep instead composes per-step residuals: `step.error = Math.sqrt(residual) + max(child
-error)`. Design §4 already admits this over-estimates ("a sum over accumulated planes
-(over-scales with plane count)"), and the triangle inequality is doing the work. Micron's
-number is a deviation from the **original surface**, measured once, not a sum of deviations
-from each intermediate one. It is strictly tighter, and it costs one persistent map.
-
-Caveats, both real: accumulated quadrics drift over many collapses (the memoryless-vs-
-accumulated argument is not settled in the literature either way), and the map needs a
-vertex identity stable across levels. meep already has that identity —
-`VGeoSubmesh.source_vertex_ids` and the stitch's unify-by-source-id are exactly it.
-
-**This is the single largest algorithmic idea in Micron**, and it is the one thing that
-would materially improve the metric without a Hausdorff pass.
-
-### 2.2 Simplify to a cluster-count target, not a triangle ratio
-
-`many_to_many_merge`:
-
-```js
-const target_face_count = up_count * MICRON_PATCH_SIZE_MAX;
-```
-
-with `up_count = ceilPowerOfTwo(ceil(nodes.length / 2))`. Micron asks the simplifier for
-exactly as many triangles as `up_count` **full** patches hold, then splits into that many.
-Cluster-count halving is guaranteed by construction, and parents come out at the cap.
-
-meep simplifies to 50% of the triangle count and takes whatever cluster count falls out of
-the re-split. Measured fill on the current builder: 120 tris/cluster at the leaves, dropping
-to 67–98 in the coarse levels — up to 45% of the cap wasted where the DAG is narrowest.
-Since a cluster is a draw slot and a residency slot, that is a direct cost, and it compounds
-with §2.5.
-
-(The `ceilPowerOfTwo` is an artifact of Micron's recursive-bisection fallback and should not
-be copied — it rounds a target of 3 up to 4 and throws away simplification budget.)
-
-### 2.3 A merge objective richer than edge cut — especially `volume_score`
-
-`build/hierarchy/computePatchMergeScore.js` scores a candidate pair on six terms. Three are
-worth taking:
-
-```js
-volume_score = (vol(a) + vol(b)) / vol(bounding_sphere_of(a, b))
-```
-
-A **scale-free compactness penalty**: merging two things that are far apart produces a
-merged sphere far larger than the sum of its parts, and the score collapses. No absolute
-distance constant, no scene-scale tuning. This is precisely the criterion the packing pass
-needed and could not find — the current code settles for "the group already bounded it",
-which is true but coarse, and it is why leaf-level packing had to be dropped entirely rather
-than bounded.
-
-```js
-lod_score = 1 - normalized_difference(a.lod, b.lod)   // "creates a more flat hierarchy"
-```
-
-A **soft** version of meep's error octave. Micron prefers merging patches of similar level;
-meep hard-gates on an error band and falls back to a full sweep when the band has no work.
-The soft form has no escape hatch to justify, and would work as a tie-breaker *inside* a
-band, which is where meep currently uses shared-boundary weight alone.
-
-> **Since this was written**: not alone any more. The adjacency edge weight is shared boundary
-> *times* `compactness()` (plan §1), so the tie-break slot this proposes is occupied — by a
-> spatial term rather than an error-similarity one. A level tie-break would now have to argue
-> its way past compactness, not past nothing.
-
-```js
-normal_score = 1 - merged_cone_angle² / π²
-```
-
-Prefers merging co-facing patches, which keeps the normal cone tight. meep reserves
-`cone_reserved` in the cluster record and has no producer; if the cone ever lands, the
-grouping should be aware of it or the cones will be useless at coarse levels.
-
-> **Since this was written**: moot — **backface cone culling is declined** (plan §5). The
-> warning above turned out to be the argument against the whole idea rather than a caveat on
-> implementing it: making cones tight enough to be worth testing means letting cone angle
-> distort grouping, to feed a cull the two-pass HZB was already performing on evidence. The
-> producer did land in the meantime and has no callers
-> (`bt_face_cluster_compute_normal_bounding_cone`); `cone_reserved` stays 0 for good.
-
-The weighting itself should **not** be copied: the terms are heterogeneous in scale and
-`shared_vertex_count` enters unnormalized, so it dominates everything else. The terms are
-the finding, not the sum.
-
-### 2.4 Speculative merge with rollback
-
-`many_to_many_merge` copies the quadrics, simplifies, and if the face-count target is missed
-**rejects the merge and forwards the children unchanged**:
-
-```js
-if (merged_mesh_face_count > target_face_count) {
-    // simplification failed, reject
-    array_copy(nodes, 0, output, t, input_node_count);
-```
-
-meep's equivalents throw (`group boundary edge did not survive simplification`) or
-pass-through the whole group at the same face count. Reject-and-forward is gentler and fits
-the frontier model exactly: a group that cannot be simplified is a group whose clusters wait
-for a different grouping, which is already the model for a group that cannot be *formed*.
-
-### 2.5 Fixed-size residency slots
-
-`render/instanced/PatchDataTextures.js` gives every resident patch one slot of
-`MICRON_PATCH_SIZE_MAX * 3` vertices, occupancy in a `BitSet`, capacity grown by a factor.
-No allocator, no fragmentation, no compaction, **no address migration**.
-
-Design §2 records that `GPUMeshletManager` pools variable-size allocations through
-OffsetAllocator, that its compaction/growth is a CPU-side rebuild costing ~2× VRAM
-transiently, and that meshlet-address migration is an *acknowledged unhandled TODO* in
-`GPUGeometryManager`. Fixed slots delete that problem rather than solving it. The cost is
-internal fragmentation proportional to `1 − fill`, which is exactly what §2.2 is about —
-the two findings are one decision.
-
-Worth a measurement before committing: at 120/128 fill, fixed slots cost 6%; at 67/128 they
-cost 48%.
-
-### 2.6 Proxy geometry, free from the DAG
-
-`format/micron_build_proxy_geometry.js` extracts a low-poly stand-in by refining from the
-root with a heap keyed on `-patch.lod` until a target polygon fraction is reached. Shadows,
-physics, raycasts, editor previews, impostors — all of them want a cheap whole-object mesh,
-and a cluster DAG hands one over for the cost of a heap walk. Nothing in the design mentions
-it.
-
-### 2.7 Object-space refinement
-
-`render/refinement/RefinementSpec.js`:
-
-```js
-mat4.multiply(projection_matrix, view_projection_matrix, transform);
-frustum_from_projection_matrix_array(this.frustum_f32, projection_matrix);
-```
-
-One matrix multiply per *instance*, then every cull and error test runs in object space
-against untransformed cluster bounds. With thousands of instances sharing one geometry, the
-alternative — transforming every cluster's bounds to world space — is the whole cost. meep's
-cut pass will need this; it is not in the design.
-
-### 2.8 Two smaller ones
-
-**Sub-pixel patch culling.** `render/refinement/is_patch_visible.js` drops a patch whose
-entire projected area is below the error threshold. (Dead code in Micron — the function is
-not exported — but the idea stands.)
-
-**Anti-stranding in leaf clustering.** `build/clustering/computeOpenFaceFreedom.js` counts a
-candidate face's neighbours still in the open set, so the region-growing clusterer prefers
-faces that are about to be stranded. meep gets the same effect structurally, via
-`absorb_singleton_pieces`, but only *after* the partition; Micron avoids creating the
-orphan.
-
-## 3. What not to borrow
-
-### 3.1 The shipped error metric is a density heuristic
-
-`many_to_many_merge` computes two candidate errors and ships neither:
-
-```js
-const area_based_qem_error = largest_squared_error / group_bounding_sphere_section_area;
-const group_per_pixel_error = group_inverse_polycount;      //  <-- 1 / face_count
-// const group_per_pixel_error = Math.sqrt(largest_squared_error);
-```
-
-`group_inverse_polycount` is `1 / face_count`. Design §4 explicitly **rejects**
-"pixels-per-triangle density heuristics — they fail the flat-wall test".
-
-This matters beyond the metric itself: §4 cites the prior implementation for "pops stay
-invisible well above 1 px". That empirical result was obtained with `1 / face_count`, not
-with `r_e`. It is evidence about a threshold dial under a *different* metric and should not
-be read as calibration for the pinned one.
-
-The commented-out `area_based_qem_error` is more interesting than either — a dimensionless
-error, unit-matched to Micron's area-based screen projection.
-
-### 3.2 Crack repair instead of crack prevention
-
-`build/hierarchy/patch_fill_holes_by_uncollapse.js` and `patch_stitch_parent_border.js` are
-both unreferenced anywhere in the tree. They are attempts to let the simplifier move group
-boundaries freely and then repair the resulting cracks — by un-collapsing border edges, and
-by solving a min-cost matching between two patches' border vertices. Neither shipped.
-Locked perimeters won. That is a road already walked; there is no need to walk it again.
-
-### 3.3 Spectral partitioning
-
-`merge_patches.js` carries a third partitioner: build the face graph's Laplacian as a dense
-`SquareMatrix`, take its eigenvalues, and cut the Fiedler ordering into equal runs. O(n²)
-memory in face count, and the ordering is used as a 1-D sort rather than a real bisection.
-It exists as a fallback behind METIS and recursive bisection. Not worth porting.
-
-### 3.4 No paging
-
-`format/serialization/serialize_patch.js` writes the whole DAG as one blob, with parent and
-child references resolved by `patch_array.indexOf(...)` per edge — O(n²) serialization, and
-an all-or-nothing load. The `.vgeo` container's page/band/child-table structure is the
-clearest advance the rewrite makes over its ancestor, and there is nothing here to learn
-from except that the gap is real.
-
-## 4. The one genuine architectural fork: traversal vs flat evaluation
-
-Micron's cut is a **top-down DAG traversal** (`render/refinement/get_geometry_patch_cut.js`):
-push the root, frustum-test, and if the group's screen-space error exceeds the threshold push
-the children; a `BitSet` dedupes clusters reachable through more than one parent. Design §4
-pins the opposite — "evaluated independently per cluster, no traversal".
-
-Both are defensible and they trade cleanly:
-
-| | Micron traversal | meep flat rule |
-|---|---|---|
-| Work per frame | O(cut size) | O(resident clusters) |
-| Off-screen geometry | whole subtrees skipped, never visited | every resident cluster still evaluated |
-| Parallelism | serial, pointer-chasing, CPU | data-parallel, one GPU dispatch |
-| Views | inherently one view; a shadow view needs its own traversal | view-agnostic by construction (§7, §9) |
-| Streaming | a missing page stops the descent naturally | needs the residency clamp to avoid holes |
-| State | stateless here, but Micron also carries a stateful incremental variant | stateless |
-
-The design's choice is right for the stated goals (GPU cut, shadow reuse, dynamic
-resolution). But the traversal's ability to skip an entire off-screen subtree is a real
-advantage that grows with cluster count, and the flat rule pays for it in full every frame.
-Worth measuring rather than assuming: at billions of triangles the resident cluster count is
-in the millions, and a flat pass over all of them is not obviously cheap.
-
-Two details from the traversal are worth keeping regardless of which way that goes:
-
-- **A DAG cut needs a visited set.** A cluster reachable from two parents is emitted twice
-  without one. Any future traversal-shaped tool — the proxy builder of §2.6, a validator,
-  an offline cut — needs the same `BitSet`.
-- **Capacity-grow-and-retry.** `get_geometry_patch_cut` writes optimistically, and on
-  overflow grows the destination and redoes the whole cut. Simple, and correct because the
-  cut is a pure function of the spec.
-
-Micron also carries a **stateful incremental cut** (`render/refinement/ActivePatchList.js`)
-— a linked list of active patches with split/merge from frame to frame, amortising the cut
-across frames since the camera moves little. It is dead code; the stateless rebuild is what
-is wired. That is itself a data point: the stateful version was built and abandoned.
-
-## 5. Recommendation
-
-In order:
-
-1. **Accumulated quadrics** (§2.1). Biggest metric win available, and it does not touch the
-   format.
-2. **Cluster-count simplification target** (§2.2) — and measure fill before and after, since
-   §2.5 depends on the answer.
-3. **`volume_score` as the packing/bundling criterion** (§2.3). It is the missing piece that
-   forced leaf packing to be dropped rather than bounded.
-4. **Reject-and-forward instead of throw** on a failed simplification (§2.4).
-5. **Object-space refinement spec** (§2.7) when the cut pass is written.
-6. Park §2.5 (fixed slots) and §2.6 (proxy) as scoped follow-ups; both are self-contained.
-
-And one correction to the design rather than the code: §4's "pops stay invisible well above
-1 px (prior implementation)" should be marked as measured under `1 / face_count`, not `r_e`.