Function regularizeMesh

js/regularize.js:52–526

(geometry, faceParentId, maxEdgeLength, opts = {})

 *   excludeWeight-marked faces so untextured surfaces are never modified (beta)
 * @returns {{ geometry, faceParentId, collapseCount }}
 */

import { THREE } from './threeCompat.js';
import { QuantizedPointMap } from './meshIndex.js';

const QUANTISE = 1e5;

export function regularizeMesh(geometry, faceParentId, maxEdgeLength, opts = {}) {
  // Candidate filter — triangles with thinness ABOVE this become collapse
  // candidates.  Bumped from 3 → 5 when we switched from edge-ratio to
  // thinness: the new metric is more sensitive (catches near-collinear
  // tris), so 3 swept up moderate-shape fillet triangles and broke them.
  // 5 still catches every meaningful sliver — chain slivers routinely have
  // thinness > 50 and the user's reported case was ≈ 1800.
  const aspectThreshold   = opts.aspectThreshold   ?? 5;
  // Two-tier slack.  The BASE (slack) is already loose so non-sliver boundary
  // collapses still succeed — that's what gives sliver chains the topological
  // room to dissolve.  The AGGRESSIVE tier kicks in when at least one wing is
  // an extreme sliver and adds extra leeway on top, letting tough chain ends
  // clear that the base tier alone wouldn't reach.  An earlier attempt with a
  // tight base (1.2) BLOCKED the helper collapses and made chains worse —
  // hence the loose base here.
  const slack             = opts.slack             ?? 3.0;
  const aggressiveSlack   = opts.aggressiveSlack   ?? 8.0;
  // Note: extremeSliverAspect is measured in the new thinness metric (lmax/hmin),
  // so a value of 8 means "longest edge is at least 8× the shortest altitude".
  // This skips moderate-shape fillet triangles (typically thinness 2–5) so the
  // loose aggressive normal cap doesn't bend fine fillets, while still catching
  // every real chain sliver (thinness routinely > 50).
  const extremeSliverAspect = opts.extremeSliverAspect ?? 8;
  // Per-collapse normal swing is bounded by `maxNormalDeltaCos` BUT we measure
  // the swing against each affected triangle's *original* normal (captured
  // once before any collapse), not its current post-drift normal.  Without
  // this, multiple rounds of 15° drift each compound into >100° corner
  // damage on 45° edges.
  //
  // Like edge-cap, normal-change is two-tier.  The aggressive tier fires only
  // when BOTH wings are extreme slivers (not just one) — that matches the
  // chain-of-needles-on-a-curved-face shape but NOT the fillet-sliver-next-to-
  // a-larger-fillet-face shape, so fine fillets keep their tight gate.
  const maxNormalDeltaCos        = opts.maxNormalDeltaCos        ?? Math.cos(15 * Math.PI / 180);
  const aggressiveNormalDeltaCos = opts.aggressiveNormalDeltaCos ?? Math.cos(25 * Math.PI / 180);
  // Vertices on edges with dihedral > sharpEdgeAngle are frozen: they cannot
  // be collapse endpoints, so 45°/90° feature edges keep every original
  // vertex.  Slivers in the interior of a flat face are still collapsible.
  const sharpEdgeCos      = opts.sharpEdgeCos      ?? Math.cos(30 * Math.PI / 180);
  const maxRounds         = opts.maxRounds         ?? 8;

  // Squared caps precomputed for both tiers; the per-collapse logic picks one.
  const baseMaxLenSqAllowed       = (maxEdgeLength * slack)           * (maxEdgeLength * slack);
  const aggressiveMaxLenSqAllowed = (maxEdgeLength * aggressiveSlack) * (maxEdgeLength * aggressiveSlack);
  const extremeAspect2 = extremeSliverAspect * extremeSliverAspect;

  // ── Build indexed mesh ──
  const pa = geometry.attributes.position.array;
  const triCount = pa.length / 9;

  const posMap = new QuantizedPointMap(QUANTISE, Math.min(triCount * 3, 1 << 22));