@jwc/jscad-utils 5.1.0 → 5.5.0

package/src/util.js

@@ -1,5 +1,14 @@
+/**
+ * Generates a detailed documentation comment for the function.
+ * @param {any} o - The object to convert to a string representation
+ * @returns {string} A string representation of the object, including polygon count and properties for CSG-like objects, or the object's toString() result
+ * @function jscadToString
+ */
 /** @typedef { import('@jscad/csg').CSG } CSG */
 
+/** @typedef {"x"|"y"|"z"|"xy"|"yz"|"xz"|"xyz"} AxisStrings Composed axis strings*/
+/** @typedef {"x"|"y"|"z"} AxisString Individual axis strings */
+
 import * as array from './array';
 import { Debug } from './debug';
 // import jsCadCSG from '@jscad/csg';
@@ -16,7 +25,10 @@ import {
   vector_char,
   vector_text
 } from './jscad';
+import { AssertValidCSG } from './validate';
 const debug = Debug('jscadUtils:util');
+const assertValidCSG = AssertValidCSG('util');
+
 // import utilInit from '../src/add-prototype';
 // utilInit(CSG);
 // console.trace('CSG', CSG.prototype);
@@ -193,7 +205,7 @@ export function label(text, x, y, width, height) {
   // console.trace('label', Object.getPrototypeOf(union(o)));
   // var foo = union(o);
   // console.trace('typeof', typeof foo);
-  return center(union(o));
+  return assertValidCSG(center(union(o)), 'label');
 }
 
 export function text(text) {
@@ -209,10 +221,10 @@ export function text(text) {
 
 export function unitCube(length, radius) {
   radius = radius || 0.5;
-  return CSG.cube({
+  return assertValidCSG(CSG.cube({
     center: [0, 0, 0],
     radius: [radius, radius, length || 0.5]
-  });
+  }), 'unitCube');
 }
 
 export function unitAxis(length, radius, centroid) {
@@ -230,7 +242,7 @@ export function unitAxis(length, radius, centroid) {
     [1, 0, 0],
     [0, 1, 0]
   );
-  return unitaxis.translate(centroid);
+  return assertValidCSG(unitaxis.translate(centroid), 'unitAxis');
 }
 
 export function toArray(a) {
@@ -372,17 +384,17 @@ export function scale(size, value) {
 
 export function center(object, objectSize) {
   objectSize = objectSize || size(object.getBounds());
-  return centerY(centerX(object, objectSize), objectSize);
+  return assertValidCSG(centerY(centerX(object, objectSize), objectSize), 'center');
 }
 
 export function centerY(object, objectSize) {
   objectSize = objectSize || size(object.getBounds());
-  return object.translate([0, -objectSize.y / 2, 0]);
+  return assertValidCSG(object.translate([0, -objectSize.y / 2, 0]), 'centerY');
 }
 
 export function centerX(object, objectSize) {
   objectSize = objectSize || size(object.getBounds());
-  return object.translate([-objectSize.x / 2, 0, 0]);
+  return assertValidCSG(object.translate([-objectSize.x / 2, 0, 0]), 'centerX');
 }
 
 /**
@@ -419,7 +431,7 @@ export function enlarge(object, x, y, z) {
   /// Calculate the difference between the original centroid and the new
   var delta = new_centroid.minus(objectCentroid).times(-1);
 
-  return new_object.translate(delta);
+  return assertValidCSG(new_object.translate(delta), 'enlarge');
 }
 
 /**
@@ -458,7 +470,7 @@ export function fit(object, x, y, z, keep_aspect_ratio) {
     scale(objectSize.z, z)
   ];
   var min = array.min(s);
-  return centerWith(
+  return assertValidCSG(centerWith(
     object.scale(
       s.map(function (d, i) {
         if (a[i] === 0) return 1; // don't scale when value is zero
@@ -467,7 +479,7 @@ export function fit(object, x, y, z, keep_aspect_ratio) {
     ),
     'xyz',
     object
-  );
+  ), 'fit');
 }
 
 export function shift(object, x, y, z) {
@@ -477,15 +489,15 @@ export function shift(object, x, y, z) {
 
 export function zero(object) {
   var bounds = object.getBounds();
-  return object.translate([0, 0, -bounds[0].z]);
+  return assertValidCSG(object.translate([0, 0, -bounds[0].z]), 'zero');
 }
 
 export function mirrored4(x) {
-  return x.union([
+  return assertValidCSG(x.union([
     x.mirroredY(90),
     x.mirroredX(90),
     x.mirroredY(90).mirroredX(90)
-  ]);
+  ]), 'mirrored4');
 }
 
 export const flushSide = {
@@ -570,7 +582,7 @@ export function calcSnap(moveobj, withobj, axes, orientation, delta = 0) {
 export function snap(moveobj, withobj, axis, orientation, delta) {
   debug('snap', moveobj, withobj, axis, orientation, delta);
   var t = calcSnap(moveobj, withobj, axis, orientation, delta);
-  return moveobj.translate(t);
+  return assertValidCSG(moveobj.translate(t), 'snap');
 }
 
 /**
@@ -583,26 +595,40 @@ export function snap(moveobj, withobj, axis, orientation, delta) {
  * @return {CSG}         [description]
  */
 export function flush(moveobj, withobj, axis, mside, wside) {
-  return moveobj.translate(calcFlush(moveobj, withobj, axis, mside, wside));
+  return assertValidCSG(moveobj.translate(calcFlush(moveobj, withobj, axis, mside, wside)), 'flush');
 }
 
+/**
+ *
+ * @param {AxisStrings} axes
+ * @param {function(number, string): number} valfun
+ * @param {Array<number>} [a] In initial array to apply the values to, if not provided a new array will be created.
+ * @returns {Array<number>} The resulting array after applying the function to the specified axes.
+ */
 export function axisApply(axes, valfun, a) {
   debug('axisApply', axes, valfun, a);
+
+  /** @type {Array<number>} */
   var retval = a || [0, 0, 0];
+
+  /** @type {Record<AxisString, number>} */
   var lookup = {
     x: 0,
     y: 1,
     z: 2
   };
   axes.split('').forEach(function (axis) {
-    retval[lookup[axis]] = valfun(lookup[axis], axis);
+    retval[lookup[/** @type {AxisString} */ (axis)]] = valfun(
+      lookup[/** @type {AxisString} */ (axis)],
+      axis
+    );
   });
 
   return retval;
 }
 
 export function axis2array(axes, valfun) {
-  depreciated('axis2array');
+  depreciated('axis2array', false, 'Use axisApply instead.');
   var a = [0, 0, 0];
   var lookup = {
     x: 0,
@@ -652,7 +678,7 @@ export function calcmidlineTo(o, axis, to) {
 }
 
 export function midlineTo(o, axis, to) {
-  return o.translate(calcmidlineTo(o, axis, to));
+  return assertValidCSG(o.translate(calcmidlineTo(o, axis, to)), 'midlineTo');
 }
 
 export function translator(o, axis, withObj) {
@@ -678,7 +704,7 @@ export function calcCenterWith(o, axes, withObj, delta = 0) {
 }
 
 export function centerWith(o, axis, withObj) {
-  return o.translate(calcCenterWith(o, axis, withObj));
+  return assertValidCSG(o.translate(calcCenterWith(o, axis, withObj)), 'centerWith');
 }
 
 /**
@@ -709,6 +735,118 @@ export function getDelta(size, bounds, axis, offset, nonzero) {
   });
 }
 
+
+var EPS = 1e-5;
+
+/**
+ * Split a CSG object into two halves along a plane by directly
+ * splitting polygons. This avoids BSP-tree-based boolean operations
+ * which can fail on geometry produced by stretchAtPlane.
+ * @param {CSG} csg  The object to split
+ * @param {CSG.Plane} plane  The splitting plane
+ * @return {{ front: CSG, back: CSG }} front (positive normal side) and back (negative normal side)
+ */
+function splitCSGByPlane(csg, plane) {
+  var frontPolys = [];
+  var backPolys = [];
+
+  csg.polygons.forEach(function (poly) {
+    var vertices = poly.vertices;
+    var numVerts = vertices.length;
+    var hasfront = false;
+    var hasback = false;
+    var vertexIsBack = [];
+
+    for (var i = 0; i < numVerts; i++) {
+      var t = plane.normal.dot(vertices[i].pos) - plane.w;
+      vertexIsBack.push(t < 0);
+      if (t > EPS) hasfront = true;
+      if (t < -EPS) hasback = true;
+    }
+
+    if (!hasfront && !hasback) {
+      // coplanar — assign based on normal alignment
+      var d = plane.normal.dot(poly.plane.normal);
+      if (d >= 0) {
+        frontPolys.push(poly);
+      } else {
+        backPolys.push(poly);
+      }
+    } else if (!hasback) {
+      frontPolys.push(poly);
+    } else if (!hasfront) {
+      backPolys.push(poly);
+    } else {
+      // spanning — split the polygon
+      var fv = [];
+      var bv = [];
+      for (var vi = 0; vi < numVerts; vi++) {
+        var vertex = vertices[vi];
+        var nextVi = (vi + 1) % numVerts;
+        var isback = vertexIsBack[vi];
+        var nextisback = vertexIsBack[nextVi];
+
+        if (isback === nextisback) {
+          if (isback) {
+            bv.push(vertex);
+          } else {
+            fv.push(vertex);
+          }
+        } else {
+          var point = vertex.pos;
+          var nextpoint = vertices[nextVi].pos;
+          var ip = plane.splitLineBetweenPoints(point, nextpoint);
+          var iv = new CSG.Vertex(ip);
+          if (isback) {
+            bv.push(vertex);
+            bv.push(iv);
+            fv.push(iv);
+          } else {
+            fv.push(vertex);
+            fv.push(iv);
+            bv.push(iv);
+          }
+        }
+      }
+      // Remove degenerate (near-duplicate) adjacent vertices that arise
+      // when the cut plane passes very close to existing vertices.
+      // This matches the cleanup done by the BSP-tree splitter.
+      var EPSEPS = EPS * EPS;
+      if (fv.length >= 3) {
+        var prev = fv[fv.length - 1];
+        for (var fi = 0; fi < fv.length; fi++) {
+          var curr = fv[fi];
+          if (curr.pos.distanceToSquared(prev.pos) < EPSEPS) {
+            fv.splice(fi, 1);
+            fi--;
+          }
+          prev = curr;
+        }
+      }
+      if (bv.length >= 3) {
+        var prev = bv[bv.length - 1];
+        for (var bi = 0; bi < bv.length; bi++) {
+          var curr = bv[bi];
+          if (curr.pos.distanceToSquared(prev.pos) < EPSEPS) {
+            bv.splice(bi, 1);
+            bi--;
+          }
+          prev = curr;
+        }
+      }
+      if (fv.length >= 3)
+        frontPolys.push(new CSG.Polygon(fv, poly.shared, poly.plane));
+      if (bv.length >= 3)
+        backPolys.push(new CSG.Polygon(bv, poly.shared, poly.plane));
+    }
+  });
+
+  return {
+    front: CSG.fromPolygons(frontPolys),
+    back: CSG.fromPolygons(backPolys)
+  };
+}
+
 /**
  * Cut an object into two pieces, along a given axis. The offset
  * allows you to move the cut plane along the cut axis.  For example,
@@ -718,7 +856,7 @@ export function getDelta(size, bounds, axis, offset, nonzero) {
  *
  * You can angle the cut plane and position the rotation point.
  *
- * ![bisect example](./images/bisect.png)
+ * ![bisect example](../test/images/bisect%20object%20positive.snap.png)
  * @param  {CSG} object object to bisect
  * @param  {string} axis   axis to cut along
  * @param  {number} [offset] offset to cut at
@@ -841,9 +979,33 @@ export function bisect(...args) {
     }
   );
 
+  var negative = object.cutByPlane(cutplane.plane);
+  var positive = object.cutByPlane(cutplane.plane.flipped());
+
+  // Detect cutByPlane failure: if a half's bounding box in the cut axis
+  // is not smaller than the original, the BSP-tree-based cut failed.
+  // Fall back to direct polygon splitting which is more robust, then
+  // apply cutByPlane to the simpler half to add cap faces.
+  var negSize = size(negative);
+  var posSize = size(positive);
+  if (negSize[axis] >= objectSize[axis] - EPS ||
+    posSize[axis] >= objectSize[axis] - EPS) {
+    var halves = splitCSGByPlane(object, cutplane.plane);
+    if (negSize[axis] >= objectSize[axis] - EPS) {
+      negative = halves.back;
+      // Cap the open cut face
+      try { negative = negative.cutByPlane(cutplane.plane); } catch (e) { /* keep uncapped */ }
+    }
+    if (posSize[axis] >= objectSize[axis] - EPS) {
+      positive = halves.front;
+      // Cap the open cut face
+      try { positive = positive.cutByPlane(cutplane.plane.flipped()); } catch (e) { /* keep uncapped */ }
+    }
+  }
+
   var g = Group('negative,positive', [
-    object.cutByPlane(cutplane.plane).color(options.color && 'red'),
-    object.cutByPlane(cutplane.plane.flipped()).color(options.color && 'blue')
+    negative.color(options.color && 'red'),
+    positive.color(options.color && 'blue')
   ]);
 
   if (options.addRotationCenter)
@@ -905,7 +1067,7 @@ export function slice(
  * Creates a `JsCadUtilsGroup` object that has  `body` and `wedge` objects. The `wedge` object
  * is created by radially cutting the object from the `start` to the `end` angle.
  *
- * ![wedge example](./images/wedge.png)
+ * ![wedge example](../test/images/wedge.snap.png)
  *
  *
  * @example
@@ -961,7 +1123,7 @@ export function stretch(object, axis, distance, offset) {
   var objectSize = size(object);
   var cutDelta = getDelta(objectSize, bounds, axis, offset, true);
   // debug('stretch.cutDelta', cutDelta, normal[axis]);
-  return object.stretchAtPlane(normal[axis], cutDelta, distance);
+  return assertValidCSG(object.stretchAtPlane(normal[axis], cutDelta, distance), 'stretch');
 }
 
 /**
@@ -1018,7 +1180,7 @@ export function poly2solid(top, bottom, height) {
   );
   // }
 
-  return CSG.fromPolygons(polygons);
+  return assertValidCSG(CSG.fromPolygons(polygons), 'poly2solid');
 }
 
 export function slices2poly(slices, options, axis) {
@@ -1102,7 +1264,7 @@ export function slices2poly(slices, options, axis) {
     }
   });
 
-  return CSG.fromPolygons(polygons);
+  return assertValidCSG(CSG.fromPolygons(polygons), 'slices2poly');
 }
 
 export function normalVector(axis) {
@@ -1116,7 +1278,7 @@ export function normalVector(axis) {
       normalVector: CSG.Vector3D.Create(0, 0, 1)
     },
     y: {
-      orthoNormalCartesian: ['X', 'Z'],
+      orthoNormalCartesian: ['Z', 'X'],
       normalVector: CSG.Vector3D.Create(0, 0, 1)
     }
   };
@@ -1170,6 +1332,7 @@ export function sliceParams(orientation, radius, bounds) {
 //     };
 // },
 
+
 export function reShape(object, radius, orientation, options, slicer) {
   options = options || {};
   var b = object.getBounds();
@@ -1211,57 +1374,61 @@ export function reShape(object, radius, orientation, options, slicer) {
   ).color(options.color);
 
   var remainder = object.cutByPlane(plane);
-  return union([
+  return assertValidCSG(union([
     options.unionOriginal ? object : remainder,
     delta.translate(si.moveDelta)
-  ]);
+  ]), 'reShape');
 }
 
 export function chamfer(object, radius, orientation, options) {
-  return reShape(object, radius, orientation, options, function (
-    first,
-    last,
-    slice
-  ) {
-    return [
-      {
-        poly: slice,
-        offset: new CSG.Vector3D(first)
-      },
-      {
-        poly: enlarge(slice, [-radius * 2, -radius * 2]),
-        offset: new CSG.Vector3D(last)
-      }
-    ];
-  });
+  return assertValidCSG(reShape(
+    object,
+    radius,
+    orientation,
+    options,
+    function (first, last, slice) {
+      return [
+        {
+          poly: slice,
+          offset: new CSG.Vector3D(first)
+        },
+        {
+          poly: enlarge(slice, [-radius * 2, -radius * 2]),
+          offset: new CSG.Vector3D(last)
+        }
+      ];
+    }
+  ), 'chamfer');
 }
 
 export function fillet(object, radius, orientation, options) {
   options = options || {};
-  return reShape(object, radius, orientation, options, function (
-    first,
-    last,
-    slice
-  ) {
-    var v1 = new CSG.Vector3D(first);
-    var v2 = new CSG.Vector3D(last);
-
-    var res = options.resolution || CSG.defaultResolution3D;
-
-    var slices = array.range(0, res).map(function (i) {
-      var p = i > 0 ? i / (res - 1) : 0;
-      var v = v1.lerp(v2, p);
-
-      var size = -radius * 2 - Math.cos(Math.asin(p)) * (-radius * 2);
-
-      return {
-        poly: enlarge(slice, [size, size]),
-        offset: v
-      };
-    });
-
-    return slices;
-  });
+  return assertValidCSG(reShape(
+    object,
+    radius,
+    orientation,
+    options,
+    function (first, last, slice) {
+      var v1 = new CSG.Vector3D(first);
+      var v2 = new CSG.Vector3D(last);
+
+      var res = options.resolution || CSG.defaultResolution3D;
+
+      var slices = array.range(0, res).map(function (i) {
+        var p = i > 0 ? i / (res - 1) : 0;
+        var v = v1.lerp(v2, p);
+
+        var size = -radius * 2 - Math.cos(Math.asin(p)) * (-radius * 2);
+
+        return {
+          poly: enlarge(slice, [size, size]),
+          offset: v
+        };
+      });
+
+      return slices;
+    }
+  ), 'fillet');
 }
 
 export function calcRotate(part, solid, axis /* , angle */) {
@@ -1278,7 +1445,7 @@ export function calcRotate(part, solid, axis /* , angle */) {
 export function rotateAround(part, solid, axis, angle) {
   var { rotationCenter, rotationAxis } = calcRotate(part, solid, axis, angle);
 
-  return part.rotate(rotationCenter, rotationAxis, angle);
+  return assertValidCSG('rotateAround')(part.rotate(rotationCenter, rotationAxis, angle));
 }
 function cloneProperties(from, to, depth = 0) {
   return Object.entries(from).reduce((props, [key, value]) => {
@@ -1293,7 +1460,7 @@ export function clone(o) {
   cloneProperties(o, c);
 
   debug('clone', o, c, CSG);
-  return c;
+  return assertValidCSG(c, 'clone');
 }
 
 /**
@@ -1313,5 +1480,5 @@ export function addConnector(
   normal = [0, 0, 1]
 ) {
   object.properties[name] = new CSG.Connector(point, axis, normal);
-  return object;
+  return assertValidCSG('addConnector')(object);
 }