archived-stlTexturizer/js/subdivision.js

/**
 * Edge-based adaptive mesh subdivision.
 *
 * Subdivides until every edge is ≤ maxEdgeLength.  A hard safety cap of
 * SAFETY_CAP triangles prevents OOM on very fine settings; the caller
 * (export pipeline) hands the result to the QEM decimator which then trims
 * it to the user-requested budget.
 *
 * @param {THREE.BufferGeometry} geometry   – non-indexed input from STLLoader
 * @param {number} maxEdgeLength            – maximum allowed edge length (same unit as STL)
 * @param {function} [onProgress]           – optional callback(fraction 0–1)
 * @returns {{ geometry: THREE.BufferGeometry, safetyCapHit: boolean }}
 */

import * as THREE from 'three';

const QUANTISE   = 1e4;
const SAFETY_CAP = 10_000_000; // absolute OOM guard

// ── Public entry point ───────────────────────────────────────────────────────

export async function subdivide(geometry, maxEdgeLength, onProgress, faceWeights = null) {
  // Derive per-face exclusion BEFORE toIndexed so we use the untouched
  // non-indexed weights (toIndexed uses MAX-merge which can push boundary
  // vertices to weight 1.0 even on included triangles).
  let initialFaceExcluded = null;
  if (faceWeights) {
    const triCount = faceWeights.length / 3;
    initialFaceExcluded = new Uint8Array(triCount);
    for (let i = 0; i < triCount; i++) {
      // Non-indexed vertex i*3 belongs to face i; weight > 0.99 → excluded
      if (faceWeights[i * 3] > 0.99) initialFaceExcluded[i] = 1;
    }
  }

  const { positions, normals, weights, indices } = toIndexed(geometry, faceWeights);

  const maxIterations = 12;
  let currentIndices = indices;
  let currentFaceExcluded = initialFaceExcluded;
  let safetyCapHit = false;

  for (let iter = 0; iter < maxIterations; iter++) {
    const triCount = currentIndices.length / 3;
    if (triCount >= SAFETY_CAP) {
      safetyCapHit = true;
      break;
    }

    const { newIndices, newFaceExcluded, changed } = subdividePass(
      positions, normals, weights, currentIndices, maxEdgeLength, SAFETY_CAP, currentFaceExcluded
    );
    currentIndices = newIndices;
    if (newFaceExcluded) currentFaceExcluded = newFaceExcluded;

    if (newIndices.length / 3 >= SAFETY_CAP) safetyCapHit = true;

    if (onProgress) onProgress(Math.min(0.95, (iter + 1) / maxIterations));
    await new Promise(r => setTimeout(r, 0));
    if (!changed || safetyCapHit) break;
  }

  return { geometry: toNonIndexed(positions, normals, weights, currentIndices, currentFaceExcluded), safetyCapHit };
}

// ── One subdivision pass ──────────────────────────────────────────────────────
//
// Uses a two-step approach to eliminate T-junctions:
//
//  Step 1 – scan ALL triangles and mark every edge whose squared length
//            exceeds maxSq.  Because this is global, both triangles that
//            share an edge always agree on whether to split it.
//
//  Step 2 – rebuild the index list.  Each triangle is handled according to
//            how many of its three edges are marked:
//
//    0 edges → keep as-is
//    1 edge  → 2 sub-triangles  (bisect the one long edge)
//    2 edges → 3 sub-triangles  (fan from the vertex opposite the short edge)
//    3 edges → 4 sub-triangles  (classic 1→4 midpoint subdivision – most regular)
//
// The 2- and 3-edge cases are new compared to the old single-edge split and
// produce significantly more regular results.  Thin slivers with one very
// long edge still produce chains of thin children (unavoidable without moving
// vertices off the surface), but the mesh is now crack-free in all cases.

function subdividePass(positions, normals, weights, indices, maxEdgeLength, safetyCap, faceExcluded = null) {
  const maxSq = maxEdgeLength * maxEdgeLength;
  const midCache = new Map();

  // ── Step 1: globally mark edges that need splitting ─────────────────────
  // Excluded triangles do NOT proactively mark their own edges – their
  // interior edges will never be split, saving triangles on untextured
  // regions.  Boundary edges are still marked by the included neighbour, so
  // excluded triangles respond to those splits and T-junctions are avoided.
  const splitEdges = new Set();
  for (let t = 0; t < indices.length; t += 3) {
    if (faceExcluded && faceExcluded[t / 3]) continue; // skip excluded faces
    const a = indices[t], b = indices[t + 1], c = indices[t + 2];
    if (edgeLenSq(positions, a, b) > maxSq) splitEdges.add(edgeKey(a, b));
    if (edgeLenSq(positions, b, c) > maxSq) splitEdges.add(edgeKey(b, c));
    if (edgeLenSq(positions, c, a) > maxSq) splitEdges.add(edgeKey(c, a));
  }

  if (splitEdges.size === 0) return { newIndices: indices, newFaceExcluded: faceExcluded, changed: false };

  // ── Step 2: rebuild index list ───────────────────────────────────────────
  const nextIndices = [];
  const nextFaceExcluded = faceExcluded ? [] : null;

  for (let t = 0; t < indices.length; t += 3) {
    // Safety cap: stop splitting, carry remaining triangles as-is
    if (nextIndices.length / 3 >= safetyCap) {
      for (let r = t; r < indices.length; r++) nextIndices.push(indices[r]);
      // Carry remaining face-exclusion flags as-is
      if (nextFaceExcluded && faceExcluded) {
        for (let r = t / 3; r < indices.length / 3; r++) nextFaceExcluded.push(faceExcluded[r]);
      }
      break;
    }

    const a = indices[t], b = indices[t + 1], c = indices[t + 2];
    const fIdx = t / 3;
    const excl = faceExcluded ? faceExcluded[fIdx] : 0;
    const sAB = splitEdges.has(edgeKey(a, b));
    const sBC = splitEdges.has(edgeKey(b, c));
    const sCA = splitEdges.has(edgeKey(c, a));
    const n   = (sAB ? 1 : 0) + (sBC ? 1 : 0) + (sCA ? 1 : 0);

    if (n === 0) {
      // ── 0-split: keep triangle ─────────────────────────────────────────
      nextIndices.push(a, b, c);
      if (nextFaceExcluded) nextFaceExcluded.push(excl);

    } else if (n === 3) {
      // ── 3-split: 1→4 regular midpoint subdivision ──────────────────────
      //
      //        a
      //       / \
      //     mCA─mAB
      //     / \ / \
      //    c─mBC───b
      //
      const mAB = getMidpoint(positions, normals, weights, midCache, a, b);
      const mBC = getMidpoint(positions, normals, weights, midCache, b, c);
      const mCA = getMidpoint(positions, normals, weights, midCache, c, a);
      nextIndices.push(
        a,   mAB, mCA,
        mAB, b,   mBC,
        mCA, mBC, c,
        mAB, mBC, mCA,
      );
      if (nextFaceExcluded) nextFaceExcluded.push(excl, excl, excl, excl);

    } else if (n === 1) {
      // ── 1-split: bisect the one marked edge → 2 sub-triangles ──────────
      if (sAB) {
        const m = getMidpoint(positions, normals, weights, midCache, a, b);
        nextIndices.push(a, m, c,  m, b, c);
        if (nextFaceExcluded) nextFaceExcluded.push(excl, excl);
      } else if (sBC) {
        const m = getMidpoint(positions, normals, weights, midCache, b, c);
        nextIndices.push(a, b, m,  a, m, c);
        if (nextFaceExcluded) nextFaceExcluded.push(excl, excl);
      } else {                           // sCA
        const m = getMidpoint(positions, normals, weights, midCache, c, a);
        nextIndices.push(a, b, m,  m, b, c);
        if (nextFaceExcluded) nextFaceExcluded.push(excl, excl);
      }

    } else {
      // ── 2-split: 3 sub-triangles, fan from the untouched-edge vertex ───
      //
      // For each case the unsplit-edge vertex forms a small corner triangle
      // with its two adjacent midpoints; the remaining quadrilateral is
      // split along the diagonal that connects those two midpoints to the
      // opposite vertices, preserving consistent CCW winding throughout.

      if (!sAB) {                        // sBC + sCA: fan from C
        const mBC = getMidpoint(positions, normals, weights, midCache, b, c);
        const mCA = getMidpoint(positions, normals, weights, midCache, c, a);
        nextIndices.push(
          a,   b,   mBC,
          a,   mBC, mCA,
          c,   mCA, mBC,
        );
        if (nextFaceExcluded) nextFaceExcluded.push(excl, excl, excl);
      } else if (!sBC) {                 // sAB + sCA: fan from A
        const mAB = getMidpoint(positions, normals, weights, midCache, a, b);
        const mCA = getMidpoint(positions, normals, weights, midCache, c, a);
        nextIndices.push(
          a,   mAB, mCA,
          mAB, b,   c,
          mAB, c,   mCA,
        );
        if (nextFaceExcluded) nextFaceExcluded.push(excl, excl, excl);
      } else {                           // sAB + sBC: fan from B
        const mAB = getMidpoint(positions, normals, weights, midCache, a, b);
        const mBC = getMidpoint(positions, normals, weights, midCache, b, c);
        nextIndices.push(
          b,   mBC, mAB,
          a,   mAB, mBC,
          a,   mBC, c,
        );
        if (nextFaceExcluded) nextFaceExcluded.push(excl, excl, excl);
      }
    }
  }

  return { newIndices: nextIndices, newFaceExcluded: nextFaceExcluded, changed: true };
}

// ── Helpers ──────────────────────────────────────────────────────────────────

/** Canonical order key for an undirected edge – matches the getMidpoint cache key. */
function edgeKey(a, b) {
  return a < b ? `${a}:${b}` : `${b}:${a}`;
}

function edgeLenSq(pos, a, b) {
  const dx = pos[a*3]   - pos[b*3];
  const dy = pos[a*3+1] - pos[b*3+1];
  const dz = pos[a*3+2] - pos[b*3+2];
  return dx*dx + dy*dy + dz*dz;
}

function getMidpoint(positions, normals, weights, cache, a, b) {
  const key = a < b ? `${a}:${b}` : `${b}:${a}`;
  if (cache.has(key)) return cache.get(key);

  // Midpoint position
  const mx = (positions[a*3]   + positions[b*3])   / 2;
  const my = (positions[a*3+1] + positions[b*3+1]) / 2;
  const mz = (positions[a*3+2] + positions[b*3+2]) / 2;

  // Midpoint normal (average + normalise)
  const nx = normals[a*3]   + normals[b*3];
  const ny = normals[a*3+1] + normals[b*3+1];
  const nz = normals[a*3+2] + normals[b*3+2];
  const nl = Math.sqrt(nx*nx + ny*ny + nz*nz) || 1;

  const idx = (positions.length / 3) | 0;
  positions.push(mx, my, mz);
  normals.push(nx / nl, ny / nl, nz / nl);
  // Interpolate exclusion weight: 0 = included, 1 = excluded.
  // A midpoint between two excluded vertices → 1.0; between mixed → 0.5
  // (displacement.js treats > 0.5 average as excluded for the face).
  if (weights) weights.push((weights[a] + weights[b]) / 2);
  cache.set(key, idx);
  return idx;
}

// ── Non-indexed → indexed conversion ────────────────────────────────────────

// nonIndexedWeights: optional Float32Array(vertexCount) where vertex i has
// weight = 1.0 if its triangle (floor(i/3)) is user-excluded, else 0.
// When multiple original vertices map to the same indexed vertex, the MAX
// weight wins (conservative: any excluded face marks the shared vertex).
function toIndexed(geometry, nonIndexedWeights = null) {
  const posAttr = geometry.attributes.position;
  const nrmAttr = geometry.attributes.normal;

  const positions = [];
  const normals   = [];
  const normalSums = [];
  const weights   = nonIndexedWeights ? [] : null;
  const indices   = [];
  const vertMap   = new Map();

  const n = posAttr.count;
  for (let i = 0; i < n; i++) {
    const px = posAttr.getX(i);
    const py = posAttr.getY(i);
    const pz = posAttr.getZ(i);
    const nx_ = nrmAttr ? nrmAttr.getX(i) : 0;
    const ny_ = nrmAttr ? nrmAttr.getY(i) : 0;
    const nz_ = nrmAttr ? nrmAttr.getZ(i) : 1;

    const key = `${Math.round(px * QUANTISE)}_${Math.round(py * QUANTISE)}_${Math.round(pz * QUANTISE)}`;
    let idx = vertMap.get(key);
    if (idx === undefined) {
      idx = positions.length / 3;
      positions.push(px, py, pz);
      normals.push(nx_, ny_, nz_);
      normalSums.push(nx_, ny_, nz_);
      if (weights) weights.push(nonIndexedWeights[i]);
      vertMap.set(key, idx);
    } else {
      normalSums[idx * 3]     += nx_;
      normalSums[idx * 3 + 1] += ny_;
      normalSums[idx * 3 + 2] += nz_;
      if (weights && nonIndexedWeights[i] > weights[idx]) {
        // MAX: if any incident original face was excluded, the shared vertex is excluded
        weights[idx] = nonIndexedWeights[i];
      }
    }
    indices.push(idx);
  }

  for (let i = 0; i < positions.length / 3; i++) {
    const nx = normalSums[i * 3];
    const ny = normalSums[i * 3 + 1];
    const nz = normalSums[i * 3 + 2];
    const len = Math.sqrt(nx * nx + ny * ny + nz * nz) || 1;
    normals[i * 3]     = nx / len;
    normals[i * 3 + 1] = ny / len;
    normals[i * 3 + 2] = nz / len;
  }

  return { positions, normals, weights, indices };
}

// ── Indexed → non-indexed ────────────────────────────────────────────────────

function toNonIndexed(positions, normals, weights, indices, faceExcluded = null) {
  const triCount  = indices.length / 3;
  const posArray  = new Float32Array(triCount * 9);
  const nrmArray  = new Float32Array(triCount * 9);
  const wgtArray  = (faceExcluded || weights) ? new Float32Array(triCount * 3) : null;

  for (let t = 0; t < triCount; t++) {
    // Use the binary faceExcluded flag (tracked accurately through subdivision)
    // rather than the interpolated weights[vidx].  The interpolated weights can
    // be pushed to 1.0 on included faces via the MAX-merge in toIndexed: if an
    // included face shares edges with TWO excluded neighbours all three of its
    // vertices are merged to weight 1.0, making its average exceed the 0.99
    // threshold and falsely excluding it from displacement.
    const faceW = faceExcluded ? (faceExcluded[t] ? 1.0 : 0.0) : null;
    for (let v = 0; v < 3; v++) {
      const vidx = indices[t * 3 + v];
      posArray[t * 9 + v * 3]     = positions[vidx * 3];
      posArray[t * 9 + v * 3 + 1] = positions[vidx * 3 + 1];
      posArray[t * 9 + v * 3 + 2] = positions[vidx * 3 + 2];

      nrmArray[t * 9 + v * 3]     = normals[vidx * 3];
      nrmArray[t * 9 + v * 3 + 1] = normals[vidx * 3 + 1];
      nrmArray[t * 9 + v * 3 + 2] = normals[vidx * 3 + 2];

      if (wgtArray) wgtArray[t * 3 + v] = faceW !== null ? faceW : weights[vidx];
    }
  }

  const geo = new THREE.BufferGeometry();
  geo.setAttribute('position', new THREE.BufferAttribute(posArray, 3));
  geo.setAttribute('normal',   new THREE.BufferAttribute(nrmArray, 3));
  if (wgtArray) geo.setAttribute('excludeWeight', new THREE.BufferAttribute(wgtArray, 1));
  return geo;
}