@woosh/meep-engine 3.28.0 → 3.30.0

package/src/core/geom/3d/topology/struct/binary/io/bt_mesh_simplify.d.ts

@@ -6,9 +6,24 @@
  * removed. If the target cannot be reached (e.g. too many restricted vertices),
  * simplification stops early without failing.
  *
- * A collapse that would turn a surviving triangle inside out is refused however cheap the quadric
- * says it is ({@link bt_edge_collapse_would_fold}) -- the quadric cannot see a fold, because a flat
- * region scores zero for every placement in its plane.
+ * No collapse ever turns a surviving triangle inside out, and the quadric cannot help with that: it
+ * cannot see a fold at all, because a flat region scores zero for every placement in its plane. So
+ * the placement is *constrained* rather than merely checked. Where the quadric's own answer folds,
+ * the collapse is re-placed at the best point that does not — see {@link constrain_placement}, and
+ * {@link bt_edge_collapse_fold_limit} for why that point can be found exactly instead of hunted for.
+ * A collapse is refused only when the pair has no such placement anywhere, which is a statement
+ * about the geometry rather than about the quadric's preference.
+ *
+ * Every edge is priced at the placement it would actually use, including the constrained ones, and
+ * the queue is ordered on that. It is the expensive way round — the constraint costs a walk of both
+ * the pair's fans, and pricing happens once per edge at the start and again for every neighbour of
+ * every collapse, which measures at 1.4x to 2.5x the build time of the alternative. The alternative
+ * is to order on the unconstrained price, which is a genuine lower bound ({@link placement_cost}),
+ * and settle only on the way out of the queue. That was built and measured, and it is not here: the
+ * greedy order it produces is approximate, and on a pinwheel whose whole rim is pinned it stopped at
+ * 28 faces against a target of 21 — which is precisely the shape a vgeo group step hands this, since
+ * such a step pins its entire outer boundary. A cheaper order that cannot finish a pinned
+ * simplification is no bargain.
  *
  * **Topology is not preserved**, and cannot be here. The other standard guard, the *link condition*
  * ({@link bt_edge_collapse_breaks_link_condition}), refuses collapses that weld together two parts
@@ -24,21 +39,36 @@
  * At the end of the call the mesh is cleaned up so that no dangling loops, edges,
  * or vertices remain in the topology.
  *
- * The return value is the **object-space distance** the surface moved: the largest, over every
- * vertex, of that vertex's accumulated quadric evaluated where the vertex ended up, normalized by
- * the quadric's weight. Because a survivor inherits its victim's quadric, this measures deviation
- * from the mesh as it stood when the call began — not merely from the step before.
+ * The return value is the **object-space distance** the surface moved: the largest reading taken at
+ * any collapse the call performed, a collapse being read by evaluating *each* of its two endpoints'
+ * accumulated quadrics at the placement the survivor is about to take, each normalized by its own
+ * weight. Because a survivor inherits its victim's quadric, every such reading is a deviation from
+ * the mesh as it stood when the call began — not merely from the step before.
+ *
+ * **At the collapses, and per endpoint, and both of those are what keep it from diluting.** The
+ * weight is what makes the value a length ({@link Quadric3#distance}) and it is also a divisor that
+ * grows every time a vertex absorbs another. A vertex that flattens a spike and then spends the rest
+ * of the call swallowing the plane around it ends up standing mostly for planes it sits exactly on,
+ * and a single reading taken at the end divides the spike it destroyed by all of them — measured on
+ * a unit spike at the centre of a pinned grid, the same spike came back at 0.64 on a 7-vertex grid
+ * and at 0.040 on a 33-vertex one, which is the reported error falling as the surface grows.
+ * Reading at every collapse catches the spike while the quadric is still mostly about it. Reading
+ * the two endpoints apart rather than summed stops a small victim's residual being averaged into a
+ * large survivor's untouched history, which is that same dilution one collapse at a time.
  *
- * It is taken *before* faceless vertices are cleaned away, and that is not an implementation detail.
- * A patch that is consumed entirely leaves a vertex behind that belongs to no face; that vertex is
- * the only thing still holding the quadric of everything that used to be there, and reading the mesh
- * after cleanup would find no trace of it. A soup of separate triangles simplifies by *deleting*
- * them, and measuring survivors alone reports the deletion of ninety per cent of a model as costing
- * nothing at all.
+ * Nothing is given up by no longer scanning the survivors, and it is a domination rather than a
+ * coincidence. What the scan would read off a survivor is its *merged* quadric at the placement its
+ * last collapse chose — and a merged quadric's reading is the weight-weighted mean of its two parts'
+ * readings at that same point, so it can never exceed the larger of the two this already took there.
+ * Every value the scan could report is therefore one this maximum has seen or beaten, and the
+ * maximum holds the earlier and sharper readings besides. A patch consumed entirely, which leaves
+ * behind a faceless vertex that the cleanup then sweeps, is read at the collapse that consumed it
+ * instead of in the window between the last collapse and the sweep.
  *
- * A caller that needs deviation from something *older* than this call's input — a mesh several
- * simplification passes back — supplies its own quadrics through
- * {@link bt_mesh_simplify_with_quadrics} and keeps them across passes.
+ * So what comes back is what *this call's* collapses cost. A caller carrying quadrics across calls
+ * through {@link bt_mesh_simplify_with_quadrics} carries the maximum across them too — and the
+ * deviation a vertex arrives already carrying is, by construction, a reading that the call which
+ * placed it there has already returned.
  *
  * `protected_faces` names faces that must still be there when the call returns. Pinning vertices
  * does not by itself protect the *edges* between them: a collapse elsewhere in the fan can take away
@@ -71,9 +101,55 @@ export function bt_mesh_simplify(mesh: BinaryTopology, target_face_count: number
  * @param {number} target_face_count Desired face count after simplification.
  * @param {Set<number>} restricted_vertices Vertices that must not move or be removed.
  * @param {Set<number>} protected_faces Faces that must not be removed.
+ * `attributes` is per-vertex data that travels *through* the collapse rather than being re-derived
+ * from the result. Whatever a merged vertex is to carry has to be decided here, from the values
+ * being merged: the mesh a collapse leaves behind is a different surface, and a value read off it
+ * afterwards describes that one rather than the one the caller started with.
+ *
+ * It is carried per **wedge** — a set of corners at one vertex that shade as one — so a hard edge
+ * or a texture seam survives a collapse instead of being averaged away. Which of the pair's wedges
+ * become one is decided by the faces the collapse destroys, in {@link reduce_pair_attributes}; a
+ * mesh with no seams has one wedge per vertex, every collapse merges the pair, and all of this is
+ * the arithmetic it always was.
+ *
+ * It is **fitted**, not inherited and not averaged. Each channel varies affinely over a triangle, so
+ * every triangle a wedge has ever absorbed says what that channel should be at any position; the
+ * survivor takes the value that best explains all of them at once, at the position it is being moved
+ * to ({@link quadric_attribute_solve}). Those same accumulated fields also reach the *placement* and
+ * the cost, through {@link quadric_attribute_reduce} -- so a collapse that would smear a crease or a
+ * texture seam is both moved away from it and priced for it. A vertex with no field to fit from
+ * falls back to a weighted blend, and a **restricted** survivor is left exactly as it is, for the
+ * same reason its position is.
+ *
+ * The values themselves mean nothing here. A caller whose record holds a direction or a flag rather
+ * than a quantity has to say so afterwards, over the array this leaves behind.
+ *
+ * What the call **returns** is still the pure geometric quadric's answer, evaluated at wherever the
+ * higher-dimensional metric put each vertex. Solving in one metric and reporting in the other is
+ * what keeps the number an object-space length (`VIRTUAL_GEOMETRY_DESIGN.md` §3).
+ *
  * @param {Quadric3[]} quadratics indexed by vertex id, one per allocated vertex; mutated in place
+ * @param {{values: Float64Array, components: number, quadrics: Float64Array, weights: Float64Array}|null} [attributes]
+ *     per-wedge records to carry through the collapses, with the attribute quadrics that fit them
+ *     ({@link bt_mesh_compute_wedge_attribute_quadrics}) and the per-channel weights those were
+ *     built with. `values` and `quadrics` are indexed by **wedge id**;
+ *     {@link bt_wedges_per_vertex} is the set where that is the vertex id. `null` to carry nothing,
+ *     which is what every caller but the virtual-geometry builder does. {@link bt_mesh_simplify_by_error}
+ *     is not among them at all — it is a separate implementation with its own cost function, and so
+ *     is untouched by any of this, which matters because it simplifies to a *tolerance* that an
+ *     attribute term would quietly move.
+ * @param {BtWedgeSet|null} [wedges] which corners of each vertex shade as one, **mutated in place**
+ *     as the collapses merge them. Required when `attributes` is given, and useful without it: a
+ *     caller that carries no values may still care which corners of the result belong together, and
+ *     a set that is not maintained is a set whose ids go stale — corners of one vertex would resolve
+ *     to different wedges and every consumer downstream would see a seam that is not there.
  * @returns {number} object-space distance the surface moved, `0` when no collapse was performed
  */
-export function bt_mesh_simplify_with_quadrics(mesh: BinaryTopology, target_face_count: number, restricted_vertices: Set<number>, protected_faces: Set<number>, quadratics: Quadric3[]): number;
+export function bt_mesh_simplify_with_quadrics(mesh: BinaryTopology, target_face_count: number, restricted_vertices: Set<number>, protected_faces: Set<number>, quadratics: Quadric3[], attributes?: {
+    values: Float64Array;
+    components: number;
+    quadrics: Float64Array;
+    weights: Float64Array;
+} | null, wedges?: BtWedgeSet | null): number;
 import { Quadric3 } from "../../../../quadric/Quadric3.js";
 //# sourceMappingURL=bt_mesh_simplify.d.ts.map

package/src/core/geom/3d/topology/struct/binary/io/bt_mesh_simplify.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bt_mesh_simplify.d.ts","sourceRoot":"","sources":["../../../../../../../../../src/core/geom/3d/topology/struct/binary/io/bt_mesh_simplify.js"],"names":[],"mappings":"AA8NA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,0EALW,MAAM,wBACN,IAAI,MAAM,CAAC,oBACX,IAAI,MAAM,CAAC,GACT,MAAM,CAwBlB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wFANW,MAAM,uBACN,IAAI,MAAM,CAAC,mBACX,IAAI,MAAM,CAAC,cACX,QAAQ,EAAE,GACR,MAAM,CAqJlB;yBAldwB,iCAAiC"}
+{"version":3,"file":"bt_mesh_simplify.d.ts","sourceRoot":"","sources":["../../../../../../../../../src/core/geom/3d/topology/struct/binary/io/bt_mesh_simplify.js"],"names":[],"mappings":"AAw9BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoFG;AACH,0EALW,MAAM,wBACN,IAAI,MAAM,CAAC,oBACX,IAAI,MAAM,CAAC,GACT,MAAM,CAwBlB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH,wFA/CW,MAAM,uBACN,IAAI,MAAM,CAAC,mBACX,IAAI,MAAM,CAAC,cA4BX,QAAQ,EAAE,eACV;IAAC,MAAM,EAAE,YAAY,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,YAAY,CAAC;IAAC,OAAO,EAAE,YAAY,CAAA;CAAC,GAAC,IAAI,WAS9F,aAAW,IAAI,GAKb,MAAM,CA4MlB;yBA10CwB,iCAAiC"}