@woosh/meep-engine 3.60.4 → 3.60.5

package/src/core/geom/3d/gjk/GJK_REVIEW_NOTES.md

@@ -1,146 +0,0 @@
-# GJK review notes — Johnson distance subalgorithm & robustness
-
-Notes from a 2026-06-18 research pass (capsule-vs-AABB / segment-vs-box work) on
-how this engine's GJK family relates to the known GJK robustness literature —
-chiefly the **Johnson distance subalgorithm** and its 2017 **signed-volumes**
-replacement. See `NOTES.md` (same dir) for the raw reference links.
-
-**TL;DR:** the specific Johnson failure mode does **not** apply here, because this
-engine has **no distance-returning GJK** — nothing computes the Johnson
-sub-distance, so there is nothing to replace. The finding is *forward-looking*:
-it becomes relevant the day a closest-distance-between-separated-convexes query
-is added (speculative contacts, conservative-advancement CCD, proximity
-queries). The analogous simplex-degeneracy risk in our boolean/penetration GJK is
-real but already mitigated by explicit floating-point-dust guards.
-
-## What this engine actually has
-
-There are three Minkowski-difference routines here, and **none is a distance
-subalgorithm**:
-
-| File | Role | Simplex / sub-distance method |
-|---|---|---|
-| `gjk.js` | **Boolean** overlap test (used by `physics/queries/shape_cast.js`) | Voronoi-region simplex update via triple cross products (Kevin Moran adaptation). Returns a bool; never computes a closest point. |
-| `gjk_epa_penetration.js` | **Penetration** axis+depth (narrowphase convex / mesh / concave-per-triangle) | GJK builds a rank-4 origin-enclosing simplex (Voronoi-region updates), then EPA expands faces toward the closest one (Bullet `btGjkEpa2` structure). |
-| `mpr.js` | Penetration normal on **smooth** supports (sphere/capsule), where EPA stalls | Minkowski Portal Refinement — portal, not simplex sub-distance. |
-
-The thing the literature calls the *Johnson distance subalgorithm* — given a
-simplex of ≤4 points, find the closest point on it to the origin and the minimal
-sub-simplex (which Voronoi region the origin projects into), via recursively
-computed barycentric cofactors — is **absent**. Our GJK only ever asks "does the
-simplex enclose / has the support passed the origin?", never "what is the
-closest point on the simplex?". So there is no Johnson cofactor recursion and no
-Backup procedure in this codebase.
-
-## The Johnson subalgorithm and why it fails
-
-In a *distance* GJK (Gilbert–Johnson–Keerthi 1988), each iteration must solve the
-sub-distance problem: project the origin onto the current simplex and discard the
-vertices not contributing to the closest feature. Johnson's method expresses the
-barycentric weights as ratios of determinants (Δ cofactors) built from dot
-products of support-point *differences*.
-
-Failure mode (the part relevant to robustness reviews): for a **near-degenerate
-simplex** — points nearly coincident or nearly coplanar/collinear, which GJK
-*naturally drives toward* as it converges on a near-contact configuration — those
-determinants are differences of nearly-equal products and lose most of their
-significant digits to **subtractive cancellation**. The algorithm then either
-fails to find any valid sub-simplex (the historical "Backup procedure" brute-forces
-all subsets as a fallback) or, worse, selects the wrong Voronoi region and returns
-a **wrong closest point / distance**. Net effect in practice: the distance is
-*under-estimated just before contact* — i.e. under-detection, the same direction
-of error we found in the capsule-box alternating projection.
-
-## The 2017 fix — signed volumes (Montanari, Petrinic & Barbieri)
-
-*"Improving the GJK Algorithm for Faster and More Reliable Distance Queries
-Between Convex Objects"*, ACM TOG 36(3), 2017; reference impl **openGJK**
-(SoftwareX 2018). Both already cited in `NOTES.md`.
-
-It replaces Johnson's distance subalgorithm **and** the Backup procedure with a
-**signed-volumes** subalgorithm:
-
-- determines the Voronoi region by comparing **signed volumes** (determinants) of
-  the simplex and its sub-faces, projecting onto the lowest-dimensional one that
-  contains the origin's projection;
-- crucially **does not multiply together potentially small quantities**, so it is
-  *accurate to machine precision* and, per the paper, "cannot possibly generate
-  systems of linearly dependent equations" — **degenerate simplices are handled
-  naturally** (they collapse to a lower-dimensional projection instead of
-  triggering a fallback);
-- side benefit: ~10% faster on average, 15–30% in the contact-heavy regime.
-
-This is the single most relevant robustness upgrade for any GJK that returns a
-**distance**. It is *not* a drop-in change to a boolean or penetration GJK, which
-do not run a sub-distance step.
-
-## Applicability to this codebase
-
-1. **No live bug.** Nothing here runs the Johnson subalgorithm, so there is
-   nothing to "fix". Do not retrofit signed-volumes onto `gjk.js` /
-   `gjk_epa_penetration.js` — they have no sub-distance step to replace.
-
-2. **The analogous risk is the Voronoi-region update**, not Johnson cofactors.
-   `gjk.js` and the GJK phase of `gjk_epa_penetration.js` decide regions with
-   triple-cross-products and dot products, which suffer the *same class* of
-   cancellation on degenerate simplices. This is already mitigated deliberately:
-   - `gjk.js` `perpendicular_to_edge()` + the exact-zero direction checks are FP-dust
-     guards for exactly the collapsed-simplex case (see the comment block there —
-     a wedge dot rounding a hair above zero while the triple product rounds to
-     zero). Documented as off the hot path.
-   - `gjk_epa_penetration.js` carries `DIR_EPS`/`EPA_EPS` floors and pool-overflow
-     "use current best face" degradations.
-   These are spot mitigations, not a machine-precision guarantee — but they cover
-   the inputs the narrowphase actually feeds (the convex hulls / triangles), and
-   the penetration path is cross-checked by MPR on smooth shapes.
-
-3. **Signed-volumes becomes relevant when a distance query is added.** If/when the
-   engine grows speculative/“soft” contacts that need a *separation distance*, a
-   conservative-advancement CCD that needs closest-distance per step, or general
-   proximity queries, implement that as a **new** signed-volumes distance GJK
-   (port openGJK) rather than coaxing distance out of the boolean/penetration
-   routines. Capsule primitives should keep using the closed-form contacts
-   (`capsule_contacts.js`, now exact — see below), not GJK-with-margin.
-
-## Related robustness notes (same review)
-
-- **EPA precision wall on flat supports.** `Triangle3D`'s support is degenerate
-  along the face normal (all 3 vertices project equally), which stalls EPA and
-  yields noisy depths. The narrowphase already routes sphere/box/capsule-vs-
-  triangle through **closed-form** fast-paths in `narrowphase_step.js` for exactly
-  this reason, and `shape_cast.js` recovers the TOI normal with **MPR** rather
-  than EPA on smooth-vs-smooth. Good — keep new primitive pairs on closed forms.
-- **Capsule-as-segment-support-with-margin is intentionally NOT used here.** Jolt
-  and PhysX-PCM collide capsules as a segment support inflated by the radius
-  inside GJK/EPA (with bounded corner error from the shrink-margin model). This
-  engine instead uses exact closed-form capsule contacts. That is the more
-  accurate choice for these primitive pairs and should stay.
-- **Non-convergence policy.** Both `gjk.js` and `gjk_epa_penetration.js` cap at
-  `*_MAX_ITER = 64` and treat exhaustion as *no intersection*. For well-conditioned
-  convex inputs this is unreachable; it is a backstop against pathological input,
-  not a correctness lever.
-
-## Action items (low urgency — none is a known live defect)
-
-- [ ] If a separation-distance / proximity / conservative-advancement query is
-      ever needed, port **openGJK signed-volumes** as a dedicated distance GJK.
-      Do not extend the boolean/penetration routines for it.
-- [ ] (Optional, deeper) A focused robustness pass on
-      `gjk_epa_penetration.js`'s simplex phase — confirm the degenerate-simplex
-      guards hold under near-coplanar convex-hull inputs at scale. Out of scope
-      for this note; flagged only because it is the nearest analog to the Johnson
-      concern.
-
-## References
-
-- Gilbert, Johnson, Keerthi (1988), *A Fast Procedure for Computing the Distance
-  Between Complex Objects in Three-Dimensional Space*, IEEE J. Robotics &
-  Automation — the original GJK + Johnson distance subalgorithm.
-- Montanari, Petrinic, Barbieri (2017), *Improving the GJK Algorithm…*, ACM TOG
-  36(3), DOI 10.1145/3072959.3083724; openGJK reference impl
-  (github.com/MattiaMontanari/openGJK). Already in `NOTES.md`.
-- van den Bergen (1999), *A Fast and Robust GJK Implementation for Collision
-  Detection of Convex Objects* — the classic robustness treatment (error bounds,
-  the Backup procedure) that motivates the 2017 work.
-- Ericson, *Real-Time Collision Detection* (2005), §9.5 (GJK), Ch. 9 (EPA context).
-- `gjk.js` header — adapted from github.com/kevinmoran/GJK (boolean Voronoi GJK).

package/src/core/geom/3d/gjk/NOTES.md

@@ -1,8 +0,0 @@
-
-References:
-
-* See "Improving the GJK Algorithm for Faster and More Reliable Distance Queries Between Convex Objects", Nik Petrinic 2017, method proposed here: https://www.youtube.com/watch?v=jETkRhyHOJM, DOI 10.1145/3072959.3083724
-* https://github.com/MattiaMontanari/openGJK
-* https://github.com/ghodges413/VulkanStuff/blob/031cc0a3a301b6d45f1d24670c8fcaa283501f90/Stuff18_Map/Map/code/Math/epa.cpp
-* [A Strange But Elegant Approach to a Surprisingly Hard Problem (GJK Algorithm)](https://www.youtube.com/watch?v=ajv46BSqcK4)
-* [GJK + Expanding Polytope Algorithm - Implementation and Visualization](https://www.youtube.com/watch?v=6rgiPrzqt9w)

package/src/core/geom/3d/topology/TOPO_MESH_RETIREMENT_PLAN.md

@@ -1,135 +0,0 @@
-# TopoMesh retirement — done
-
-`TopoMesh`, `TopoVertex`, `TopoEdge` and `TopoTriangle` are gone, along with everything built on them.
-`BinaryTopology` is the engine's only mesh-topology structure.
-
-This file is what survives the plan it used to be: a migration map, for anyone who reaches for a name
-that is no longer there. The reasoning behind each choice is in the commit history and in the JSDoc of
-the replacements.
-
-## What made this cheap
-
-Nothing outside `src/core/geom/3d/topology/` imported a `TopoMesh`-based module — the survey that
-preceded the deletion found zero such imports, and the one file elsewhere that named the types
-(`core/graph/metis/mesh_to_metis_graph.js`) had no callers of its own. Every live consumer — navmesh
-build, lightmap bake, meshlet build, virtual geometry, UV-tension optimisation, scene geometry
-optimisation, the acoustic simulator — was already on `BinaryTopology`. So there was no deprecation
-cycle to run and no caller to migrate: 101 files were deleted outright.
-
-## Migration map
-
-### The structure
-
-| Gone | Use instead |
-| --- | --- |
-| `TopoMesh` | `BinaryTopology` |
-| `TopoVertex` / `TopoEdge` / `TopoTriangle` | pool ids — an element *is* its id |
-| `TopoMesh#build` / `setVerticesFromArray` / `setFacesFromIndexArray` | `bt_mesh_from_indexed_geometry` |
-| `TopoMesh#setFacedUnindexed` | `bt_mesh_from_unindexed_geometry` |
-| `TopoMesh#createTriangle` | `bt_face_create_triangle` (or `bt_face_create` for n-gons) |
-| `TopoMesh#add` / `addFaceCopy` / `patchFaceEdges` | `bt_mesh_append` |
-| `TopoMesh#validate` | `bt_mesh_validate` / `bt_mesh_assert_valid` |
-| `TopoMesh#ensureEdge` | `bt_edge_get_or_create` |
-| `TopoMesh#mergeEdges` | `bt_mesh_fuse_duplicate_edges` |
-| `TopoMesh#clone` | `BinaryTopology#clone` |
-| `TopoMesh#getFaceByIndex` | the id is the identity — no lookup |
-| `TopoEdge#computeSquaredLength` | `bt_vertex_distance_to_vertex` |
-
-### Element queries
-
-| Gone | Use instead |
-| --- | --- |
-| `query_edge_is_boundary` | `bt_edge_is_boundary` |
-| `query_edge_is_manifold` | `bt_edge_is_manifold` |
-| `query_edge_is_manifold_or_boundary` | `bt_edge_is_manifold_or_boundary` |
-| `query_edge_is_wire` | `bt_edge_is_wire` |
-| `query_edge_other_vertex` | `bt_edge_other_vertex` |
-| `query_edge_share_vert` | `bt_edge_shares_vertex` |
-| `query_vertex_in_edge` / `query_vertices_in_edge` | `bt_edge_has_vertex` |
-| `query_vertex_is_boundary` | `bt_vertex_is_boundary` |
-| `query_vertex_pair_share_face` | `bt_vertex_shares_face` |
-| `query_face_get_other_edges` | `bt_face_get_other_edges` |
-| `query_face_next_vertex` / `query_face_prev_vertex` | `loop_read_next` / `loop_read_prev` + `loop_read_vertex` |
-| `compare_edges` / `compareFaces` / `compareVertices` | ids sort — that *is* the ordering |
-| `topology_find_broken_links` / `debugValidateMesh` | `bt_mesh_validate` / `bt_mesh_assert_valid` |
-
-### Mesh operations
-
-| Gone | Use instead |
-| --- | --- |
-| `tm_edge_kill` | `bt_edge_kill` |
-| `tm_edge_kill_only` | `bt_kill_only_edge` |
-| `tm_edge_splice` | `bt_vertex_fuse_duplicate_edges` / `bt_mesh_fuse_duplicate_edges` |
-| `tm_face_kill` | `bt_face_kill` |
-| `tm_face_kill_only` | `bt_kill_only_face` |
-| `tm_face_area` | `bt_face_area` (over the shared `bt_face_compute_newell_normal`) |
-| `tm_face_normal` / `update_topo_face_normals` | `bt_mesh_compute_face_normals` |
-| `tm_vertex_kill` | `bt_vertex_kill` |
-| `tm_vertex_kill_only` | `bt_vertex_kill_only` |
-| `tm_vertex_splice` | `bt_vertex_replace` + `bt_vertex_kill_only` |
-| `tm_vertex_compute_normal` | `bt_mesh_compute_vertex_normals` |
-| `tm_weld_duplicate_vertices` | `bt_merge_vertices_by_distance` |
-| `tm_mesh_cleanup` / `tm_edges_cleanup_empty` / `tm_vertices_cleanup_empty` | `bt_mesh_cleanup_faceless_references` |
-| `expandConnectivityByLocality` / `compute_topo_mesh_vertex_duplicates` | `bt_merge_vertices_by_distance` |
-| `mesh_flood_fill` | `bt_face_island_flood_fill` |
-| `compute_face_connection_weight` | `bt_face_get_edge_adjacent_faces_weighted` |
-| `build_face_graph_from_mesh` / `mesh_to_metis_graph` | `bt_mesh_build_face_graph` |
-
-### Simplification
-
-The whole `simplify/` tree is replaced by `bt_mesh_simplify`, `bt_mesh_simplify_with_quadrics` and
-`bt_mesh_simplify_by_error`, which subsume the candidate heap, the collapse machinery and the flip
-guard.
-
-| Gone | Use instead |
-| --- | --- |
-| `simplifyTopoMesh` / `simplifyTopoMesh2` / `decimate_edge_collapse_snap` | `bt_mesh_simplify`, `bt_mesh_simplify_by_error` |
-| `collapse_edge` / `tm_edge_collapse` / `partial_edge_collapse` | `bt_edge_collapse` |
-| `collapse_degenerate_edge` / `collapse_all_degenerate_edges` | `bt_mesh_kill_degenerate_faces` |
-| `build_vertex_quadrics` / `apply_border_penalt*_to_vertex_quadrics` | `bt_mesh_compute_vertex_quadrics` |
-| `compute_face_normal_change_dot_product` / `tm_edge_collapse_is_degenerate_flip` | `bt_face_normal_change_dot_product` |
-| `EdgeCollapseCandidate` / `build_edge_collapse_candidates` / `compute_edge_collapse_cost*` | internal to `bt_mesh_simplify` |
-
-### Bounds and geometry I/O
-
-| Gone | Use instead |
-| --- | --- |
-| `compute_topo_mesh_bounding_box` | `bt_mesh_compute_bounding_box` |
-| `compute_topo_mesh_bounding_sphere` | `bt_mesh_compute_bounding_sphere` |
-| `compute_triangle_cluster_normal_bounding_cone` | `bt_face_cluster_compute_normal_bounding_cone` |
-| `three_buffer_geometry_to_topo_mesh` | `bt_mesh_from_three_buffer_geometry` |
-| `topo_mesh_to_three_buffer_geometry` | `bt_mesh_to_three_buffer_geometry` |
-| — (nothing had one) | `bt_mesh_to_indexed_geometry` |
-
-### Moved, not removed
-
-Two things in the deleted tree were never about `TopoMesh` and now live somewhere that says so:
-
-| Was | Is |
-| --- | --- |
-| `topology/simplify/quadratic/Quadric3.js` | `geom/3d/quadric/Quadric3.js` |
-| `topology/simplify/quadratic/quadric3_set_from_plane_through_point.js` | `geom/3d/quadric/quadric3_set_from_plane_through_point.js` |
-| `topology/graph_create_off_mesh_links.js` | `core/graph/graph_create_off_mesh_links.js` |
-
-## Behaviour that changed on the way across
-
-Two replacements are not bit-identical to what they replace. Both differences are deliberate.
-
-**Vertex normals are area-weighted.** `tm_vertex_compute_normal` averaged *unit* face normals, giving
-every incident face an equal vote. `bt_mesh_compute_vertex_normals` accumulates Newell vectors, whose
-magnitude is twice the face's area. On a decimated mesh, where triangle sizes around one vertex differ
-by orders of magnitude, equal voting lets a cluster of slivers outvote the surface they sit on. The
-two agree wherever the incident faces have equal area.
-
-**Coordinates are float32.** `TopoVertex` held plain JS numbers. Anything that used to round-trip
-through `TopoMesh` exactly now rounds to float32 — which is what the mesh was always going to be
-stored as, one step earlier.
-
-## One thing that was not ported
-
-`compute_topo_mesh_vertex_duplicates` reported which vertices are within a tolerance of each other
-*without* merging them. Its only two callers (`expandConnectivityByLocality` and
-`tm_weld_duplicate_vertices`) both wanted the merge, which `bt_merge_vertices_by_distance` does. Adding
-a report-only variant means either a second spatial hash alongside the one inside
-`bt_merge_vertices_by_distance` or refactoring that tested code for a function nothing calls. Neither
-is worth doing on speculation — if a caller ever needs the report, extract the grid then.