@jwc/jscad-utils 5.2.0 → 5.5.0

package/src/validate.js

@@ -0,0 +1,335 @@
+/* globals jscadUtilsAssertValidCSG jscadUtilsAssertValidCSGWarnings */
+/**
+ * @typedef {Object} CSG
+ * @property {Array<{vertices: Array<{pos: any}>}>} polygons
+ * @property {function(): CSG} [canonicalized]
+ * @property {function(): CSG} [reTesselated]
+ * @property {function(): CSG} [fixTJunctions]
+ * @property {function(): Array} [getBounds]
+ * @property {Object} [properties]
+ */
+/**
+ * Validate that a CSG object represents a solid, watertight mesh
+ * without degenerate faces. Returns an object with an `ok` boolean
+ * and an `errors` array describing any problems found.
+ *
+ * Checks performed:
+ * - **No empty mesh** – the object must contain at least one polygon.
+ * - **No degenerate polygons** – every polygon must have ≥ 3 vertices
+ *   and a computable area greater than `EPS²`.
+ * - **Watertight / manifold edges** – every directed edge A→B in the
+ *   mesh must be matched by exactly one reverse edge B→A in another
+ *   polygon.  Unmatched edges indicate holes; edges shared more than
+ *   twice indicate non-manifold geometry.
+ *
+ * By default, the mesh is canonicalized and T-junctions are repaired
+ * before validation so that results from boolean operations (union,
+ * subtract, intersect) can be validated successfully.  Pass
+ * `{ fixTJunctions: false }` to skip this step and validate the raw
+ * mesh.
+ *
+ * @param  {CSG} csg  The CSG object to validate.
+ * @param  {object} [options]  Validation options.
+ * @param  {boolean} [options.fixTJunctions=true]  Whether to canonicalize and fix T-junctions before validation.
+ * @return {{ ok: boolean, errors: string[], warnings: string[] }}  Validation result.
+ * @function validateCSG
+ */
+export function validateCSG(csg, options) {
+  /** @type {string[]} */
+  var errors = [];
+  /** @type {string[]} */
+  var warnings = [];
+
+  if (!csg || !csg.polygons || csg.polygons.length === 0) {
+    errors.push('Empty mesh: no polygons');
+    return { ok: false, errors, warnings };
+  }
+
+  const opts = { fixTJunctions: true, ...options };
+
+  // Optionally canonicalize and fix T-junctions so that boolean-op
+  // output can pass the watertight check.
+  if (opts.fixTJunctions && typeof csg.canonicalized === 'function') {
+    csg = csg.canonicalized();
+    if (typeof csg.reTesselated === 'function') {
+      csg = csg.reTesselated();
+    }
+    if (typeof csg.fixTJunctions === 'function') {
+      csg = csg.fixTJunctions();
+    }
+  }
+
+  var AREA_EPS = 1e-10;
+  var KEY_EPS = 1e-5;
+  var degenerateCount = 0;
+  var invalidVertexCount = 0;
+
+  // Check for NaN/Infinity vertex coordinates which cause WebGL errors
+  // (GL_INVALID_VALUE: glVertexAttribPointer: Vertex attribute size must be 1, 2, 3, or 4)
+  for (const npoly of csg.polygons) {
+    for (const nvert of npoly.vertices) {
+      const np = nvert.pos;
+      if (
+        !Number.isFinite(np.x) || !Number.isFinite(np.y) || !Number.isFinite(np.z) ||
+        Number.isNaN(np.x) || Number.isNaN(np.y) || Number.isNaN(np.z)
+      ) {
+        invalidVertexCount++;
+        break;
+      }
+    }
+  }
+  if (invalidVertexCount > 0) {
+    errors.push(
+      invalidVertexCount +
+      ' polygon(s) with invalid vertex coordinates (NaN or Infinity)'
+    );
+  }
+
+  // Position-based vertex key (shared vertices across polygons have different
+  // object tags but the same position, so we round coordinates to match them).
+  /** @param {{ pos: { x: number, y: number, z: number } }} v */
+  function vtxKey(v) {
+    var p = v.pos;
+    return (
+      Math.round(p.x / KEY_EPS) +
+      ',' +
+      Math.round(p.y / KEY_EPS) +
+      ',' +
+      Math.round(p.z / KEY_EPS)
+    );
+  }
+
+  // First pass: identify degenerate polygons
+  var validPolygons = [];
+  for (const poly of csg.polygons) {
+    const verts = poly.vertices;
+    const nv = verts.length;
+
+    if (nv < 3) {
+      degenerateCount++;
+      continue;
+    }
+
+    // Skip polygons with invalid vertex coordinates
+    let hasInvalid = false;
+    for (const vert of verts) {
+      const ip = vert.pos;
+      if (!Number.isFinite(ip.x) || !Number.isFinite(ip.y) || !Number.isFinite(ip.z)) {
+        hasInvalid = true;
+        break;
+      }
+    }
+    if (hasInvalid) continue;
+
+    // Check degenerate area using cross-product summation
+    let area = 0;
+    for (let ai = 0; ai < nv - 2; ai++) {
+      area += verts[ai + 1].pos
+        .minus(verts[0].pos)
+        .cross(verts[ai + 2].pos.minus(verts[ai + 1].pos))
+        .length();
+    }
+    area *= 0.5;
+    if (area < AREA_EPS) {
+      degenerateCount++;
+      continue;
+    }
+
+    validPolygons.push(poly);
+  }
+
+  if (degenerateCount > 0) {
+    warnings.push(
+      degenerateCount +
+      ' degenerate polygon(s) (fewer than 3 vertices or near-zero area)'
+    );
+
+    // Rebuild the CSG from valid polygons only and re-run the repair
+    // pipeline so that fixTJunctions can close gaps left by the removed
+    // degenerate faces.
+    /* eslint-disable no-undef */
+    // @ts-ignore — CSG is a runtime global injected by the JSCAD compat layer
+    if (opts.fixTJunctions && typeof CSG !== 'undefined') {
+      // @ts-ignore
+      var cleaned = CSG.fromPolygons(validPolygons);
+      /* eslint-enable no-undef */
+      cleaned = cleaned.canonicalized();
+      if (typeof cleaned.reTesselated === 'function') {
+        cleaned = cleaned.reTesselated();
+      }
+      if (typeof cleaned.fixTJunctions === 'function') {
+        cleaned = cleaned.fixTJunctions();
+      }
+      // Re-scan for valid polygons after second repair pass
+      validPolygons = [];
+      for (const cpoly of cleaned.polygons) {
+        const cverts = cpoly.vertices;
+        const cnv = cverts.length;
+        if (cnv < 3) continue;
+        let carea = 0;
+        for (let cai = 0; cai < cnv - 2; cai++) {
+          carea += cverts[cai + 1].pos
+            .minus(cverts[0].pos)
+            .cross(cverts[cai + 2].pos.minus(cverts[cai + 1].pos))
+            .length();
+        }
+        carea *= 0.5;
+        if (carea < AREA_EPS) continue;
+        validPolygons.push(cpoly);
+      }
+    }
+  }
+
+  // Edge map: key = "vtxKeyA/vtxKeyB", value = count
+  /** @type {Record<string, number>} */
+  var edgeCounts = {};
+
+  // Accumulate directed edges from valid polygons only
+  for (const vpoly of validPolygons) {
+    const vverts = vpoly.vertices;
+    const vnv = vverts.length;
+    for (let ei = 0; ei < vnv; ei++) {
+      const v0 = vverts[ei];
+      const v1 = vverts[(ei + 1) % vnv];
+      const edgeKey = vtxKey(v0) + '/' + vtxKey(v1);
+      edgeCounts[edgeKey] = (edgeCounts[edgeKey] || 0) + 1;
+    }
+  }
+
+  // Check edge manifoldness: every edge A→B should be cancelled by B→A
+  var unmatchedEdges = 0;
+  var nonManifoldEdges = 0;
+  /** @type {Record<string, boolean>} */
+  var checked = {};
+
+  for (const edgeKey of Object.keys(edgeCounts)) {
+    if (checked[edgeKey]) continue;
+
+    const parts = edgeKey.split('/');
+    const reverseKey = parts[1] + '/' + parts[0];
+    const forwardCount = edgeCounts[edgeKey] || 0;
+    const reverseCount = edgeCounts[reverseKey] || 0;
+
+    checked[edgeKey] = true;
+    checked[reverseKey] = true;
+
+    if (forwardCount !== reverseCount) {
+      unmatchedEdges += Math.abs(forwardCount - reverseCount);
+    }
+    if (forwardCount > 1 || reverseCount > 1) {
+      nonManifoldEdges++;
+    }
+  }
+
+  if (unmatchedEdges > 0) {
+    errors.push(
+      unmatchedEdges +
+      ' unmatched edge(s): mesh is not watertight'
+    );
+  }
+  if (nonManifoldEdges > 0) {
+    errors.push(
+      nonManifoldEdges +
+      ' non-manifold edge(s): edge shared by more than 2 polygons'
+    );
+  }
+
+  return { ok: errors.length === 0, errors: errors, warnings: warnings };
+}
+
+/** @param {any} csg @returns {any} */
+function _noOp(csg) {
+  return csg;
+}
+
+/**
+ * @param {boolean} warnEnabled
+ * @returns {function(*, string=, string=): *}
+ */
+function _makeAssertFn(warnEnabled) {
+  return function _assert(csg, functionName = 'unknown', moduleName = 'unknown') {
+    // Only validate CSG-like objects (they have a polygons array).
+    // CAG objects (2D cross-sections) have `sides` instead and are passed through.
+    if (!csg || csg.polygons === undefined) return csg;
+    var result = validateCSG(csg);
+    if (!result.ok) {
+      throw new Error(
+        moduleName + ':' + functionName + ': ' + 'invalid CSG: ' + result.errors.join(', ')
+      );
+    }
+    if (warnEnabled && result.warnings.length > 0) {
+      throw new Error(
+        moduleName + ':' + functionName + ': ' + 'CSG warnings: ' + result.warnings.join(', ')
+      );
+    }
+    return csg;
+  };
+}
+
+// Live pointer that all returned closures call through — swap this and all
+// existing closures immediately pick up the change.
+/** @type {function(*, string=, string=): *} */
+var _assertFn = _noOp;
+
+// True once setValidationEnabled() has been called explicitly, preventing
+// compat globals from overriding the programmatic setting.
+var _setExplicitly = false;
+
+// Read compat globals set by initJscadutils — mirrors the Debug() pattern
+// in debug.js.  Returns _noOp when globals are absent (ESM / test context).
+function _resolveFromGlobals() {
+  /* eslint-disable no-undef */
+  // @ts-ignore — globals set by the JSCAD compat layer before bundle injection
+  var enabled = typeof jscadUtilsAssertValidCSG !== 'undefined' && !!jscadUtilsAssertValidCSG;
+  // @ts-ignore
+  var warnEnabled = typeof jscadUtilsAssertValidCSGWarnings !== 'undefined' && !!jscadUtilsAssertValidCSGWarnings;
+  /* eslint-enable no-undef */
+  return enabled ? _makeAssertFn(warnEnabled) : _noOp;
+}
+
+/**
+ * Enable or disable CSG validation assertions globally.
+ * Overrides any compat globals. Because all asserters call through the live
+ * `_assertFn` pointer, toggling here takes effect immediately with no
+ * per-call conditional overhead.
+ * @param {boolean} enabled
+ * @param {boolean} [warnEnabled]  Also throw on warnings when true.
+ */
+export function setValidationEnabled(enabled, warnEnabled) {
+  _assertFn = enabled ? _makeAssertFn(!!warnEnabled) : _noOp;
+  _setExplicitly = true;
+}
+
+/**
+ * Returns an asserter function bound to `moduleName`. Call the returned
+ * function with a CSG object and the calling function's name to validate it
+ * (when enabled) or pass it through unchanged (when disabled).
+ *
+ * Best practice is to call `AssertValidCSG` once per module at load time and
+ * capture the result as a module-level constant so that `moduleName` appears
+ * consistently in every error message thrown from that module.
+ *
+ * On creation, reads compat globals (jscadUtilsAssertValidCSG /
+ * jscadUtilsAssertValidCSGWarnings) if setValidationEnabled() has not been
+ * called explicitly — identical to how Debug('name') reads jscadUtilsDebug.
+ *
+ * Error message format: `moduleName:functionName: invalid CSG: <errors>`
+ *
+ * @example
+ *   // Once at the top of your module:
+ *   const assertValidCSG = AssertValidCSG('myModule');
+ *
+ *   export function enlarge(object, ...) {
+ *     // ...
+ *     return assertValidCSG(new_object.translate(delta), 'enlarge');
+ *   }
+ *
+ * @param {string} [moduleName='unknown']  Module name, included in error messages.
+ * @return {function(CSG, string=): CSG}
+ */
+export function AssertValidCSG(moduleName = 'unknown') {
+  if (!_setExplicitly) {
+    _assertFn = _resolveFromGlobals();
+  }
+  return function (csg, name) { return _assertFn(csg, name, moduleName); };
+}