@jwc/jscad-utils 5.1.0 → 5.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jwc/jscad-utils",
-  "version": "5.1.0",
+  "version": "5.5.0",
   "description": "Utilities for use in a jscad script.",
   "main": "src/index.js",
   "module": "src/index.js",
@@ -32,14 +32,13 @@
   "dependencies": {
     "@jscad/csg": "0.7.0",
     "@jscad/scad-api": "0.5.1",
-    "@jwc/jscad-test-utils": "3.0.1",
-    "@jwc/jscad2-regl-renderer": "3.0.0",
-    "gl": "8.1.6",
-    "vitepress": "1.6.4",
-    "vitest": "4.0.18"
+    "vitepress": "1.6.4"
   },
   "devDependencies": {
     "@babel/preset-env": "7.29.0",
+    "@jwc/jscad-test-utils": "3.0.1",
+    "@jwc/jscad2-regl-renderer": "3.0.0",
+    "gl": "9.0.0-rc.9",
     "gulp": "5.0.1",
     "gulp-debug": "5.0.1",
     "gulp-eslint": "6.0.0",
@@ -49,7 +48,9 @@
     "rollup": "2.79.2",
     "rollup-plugin-babel": "4.4.0",
     "rollup-plugin-commonjs": "10.1.0",
-    "rollup-plugin-node-resolve": "5.2.0"
+    "rollup-plugin-node-resolve": "5.2.0",
+    "vitepress-jsdoc": "1.0.4",
+    "vitest": "4.1.2"
   },
   "babel": {
     "presets": [

package/src/add-prototype.js

@@ -76,7 +76,7 @@
 /** @typedef {import('@jscad/csg').CSG & ExtendedCSG} CSG */
 import { color } from './color';
 import * as util from './util';
-
+import { validateCSG } from './validate';
 /**
  * Initialize `jscad-utils` and add utilities to the `proto` object.
  * @param  {CSG} proto The global `proto` object
@@ -204,6 +204,10 @@ export default function init(proto) {
     return condition ? this.subtract(util.result(this, object)) : this;
   };
 
+  proto.prototype.validate = function validate(options) {
+    return validateCSG(this, options);
+  };
+
   proto.prototype._translate = proto.prototype.translate;
 
   /**

package/src/boxes.js

@@ -54,7 +54,7 @@ export function topMiddleBottom(box, thickness) {
  * This will bisect an object using a rabett join.  Returns a
  * `group` object with `positive` and `negative` parts.
  *
- * * ![parts example](./images/rabett.png)
+ * ![rabett example](../test/images/boxes-Rabett.snap.png)
  * @example
  *include('dist/jscad-utils.jscad');
  *
@@ -93,6 +93,14 @@ export function Rabett(box, thickness, gap, height, face, options = {}) {
   gap = gap || 0.25;
   var inside = thickness - gap;
   var outside = -thickness + gap;
+
+  var boxHeight = box.size().z;
+  if (Math.abs(height) >= boxHeight) {
+    throw new Error(
+      `Rabett: height (${height}) must be less than the object height (${boxHeight})`
+    );
+  }
+
   // options.color = true;
   debug('inside', inside, 'outside', outside);
   var group = Group();
@@ -154,7 +162,7 @@ export function Rabett(box, thickness, gap, height, face, options = {}) {
  * Used on a hollow object, this will rabett out the top and/or
  * bottom of the object.
  *
- * ![A hollow hexagon with removable top and bottom](../images/rabett-tb.png)
+ * ![A hollow hexagon with removable top and bottom](../test/images/boxes-RabettTopBottom.snap.png)
  *
  * @example
  *include('dist/jscad-utils.jscad');
@@ -312,7 +320,7 @@ export const Rectangle = function (size, thickness, cb) {
  * wall thickness.  This is done by reducing the object by half the
  * thickness and subtracting the reduced version from the original object.
  *
- * ![A hollowed out cylinder](../images/rabett.png)
+ * ![A hollowed out cylinder](../test/images/boxes-Rabett.snap.png)
  *
  * @param {CSG}   object    A CSG object
  * @param {Number}   [thickness=2] The thickness of the walls.

package/src/compat.js

@@ -38,6 +38,9 @@ function initJscadutils(_CSG, options = {}) {
     { enabled: [], disabled: [] }
   );
 
+  var jscadUtilsAssertValidCSGWarnings = options.assertValidCSGWarnings || false;
+  var jscadUtilsAssertValidCSG = options.assertValidCSG || false;
+
   // include:compat
   // endinject
 

package/src/group.js

@@ -12,7 +12,9 @@ import {
   unitCube,
   zipObject
 } from './util';
+import { AssertValidCSG } from './validate';
 const debug = Debug('jscadUtils:group');
+const assertValidCSG = AssertValidCSG('group');
 
 /**
  * @function JsCadUtilsGroup
@@ -112,10 +114,10 @@ JsCadUtilsGroup.prototype.combine = function (
       )
     );
 
-    return g.subtractIf(
+    return assertValidCSG(g.subtractIf(
       self.holes && Array.isArray(self.holes) ? union(self.holes) : self.holes,
       self.holes && !options.noholes
-    );
+    ), 'combine');
   } catch (err) {
     debug('combine error', this, pieces, options, err);
     throw error(
@@ -188,7 +190,7 @@ JsCadUtilsGroup.prototype.clone = function (name, map) {
 
   if (self.holes) {
     group.holes = toArray(self.holes).map(function (part) {
-      return map(CSG.fromPolygons(part.toPolygons()), 'holes');
+      return assertValidCSG(map(CSG.fromPolygons(part.toPolygons()), 'holes'), 'clone');
     });
   }
   return group;
@@ -217,7 +219,7 @@ JsCadUtilsGroup.prototype.rotate = function (solid, axis, angle) {
   var rotationAxis = axes[axis];
 
   self.map(function (part) {
-    return part.rotate(rotationCenter, rotationAxis, angle);
+    return assertValidCSG(part.rotate(rotationCenter, rotationAxis, angle), 'rotate');
   });
 
   return self;
@@ -258,7 +260,7 @@ JsCadUtilsGroup.prototype.snap = function snap(
     // debug(', self);
     var t = calcSnap(self.combine(part), to, axis, orientation, delta);
     self.map(function (part) {
-      return part.translate(t);
+      return assertValidCSG(part.translate(t), 'snap');
     });
     return self;
   } catch (err) {
@@ -298,7 +300,7 @@ JsCadUtilsGroup.prototype.align = function align(part, to, axis, delta) {
       delta
     );
     self.map(function (part /*, name */) {
-      return part.translate(t);
+      return assertValidCSG(part.translate(t), 'align');
     });
 
     // if (self.holes)
@@ -370,7 +372,7 @@ JsCadUtilsGroup.prototype.connectTo = function connectTo(
   debug('connectTo', matrix);
 
   self.map(function (part) {
-    return part.transform(matrix);
+    return assertValidCSG(part.transform(matrix), 'connectTo');
   });
 
   return self;
@@ -392,7 +394,7 @@ JsCadUtilsGroup.prototype.midlineTo = function midlineTo(part, axis, to) {
   // debug(' part, t);
   // var t = util.calcCenterWith(self.combine(part), axis, to, delta);
   self.map(function (part) {
-    return part.translate(t);
+    return assertValidCSG(part.translate(t), 'midlineTo');
   });
 
   // if (self.holes)
@@ -417,7 +419,7 @@ JsCadUtilsGroup.prototype.translate = function translate(x, y, z) {
   var t = Array.isArray(x) ? x : [x, y, z];
   debug('translate', t);
   self.map(function (part) {
-    return part.translate(t);
+    return assertValidCSG(part.translate(t), 'translate');
   });
 
   // if (self.holes)
@@ -442,7 +444,7 @@ JsCadUtilsGroup.prototype.pick = function (parts, map) {
 
   var g = Group();
   p.forEach(function (name) {
-    g.add(map(CSG.fromPolygons(self.parts[name].toPolygons()), name), name);
+    g.add(assertValidCSG(map(CSG.fromPolygons(self.parts[name].toPolygons()), name), 'pick'), name);
   });
   return g;
 };
@@ -473,7 +475,7 @@ parts: "${parts}"
       );
     }
 
-    a.push(map(CSG.fromPolygons(self.parts[name].toPolygons()), name));
+    a.push(assertValidCSG(map(CSG.fromPolygons(self.parts[name].toPolygons()), name), 'array'));
   });
   return a;
   //   } catch (err) {

package/src/parts.js

@@ -1,10 +1,12 @@
-import { CSG, CAG, union } from './jscad';
-import { fromxyz, div } from './array';
-import * as util from './util';
-import Group from './group';
+import { div, fromxyz } from './array';
 import { Debug } from './debug';
+import Group from './group';
+import { CAG, CSG, union } from './jscad';
+import * as util from './util';
+import { AssertValidCSG } from './validate';
 
 const debug = Debug('jscadUtils:parts');
+const assertValidCSG = AssertValidCSG('parts');
 
 export default { BBox, Cube, RoundedCube, Cylinder, Cone };
 
@@ -22,18 +24,18 @@ export function BBox(...objects) {
       radius: object.size().dividedBy(2)
     });
   }
-  return objects.reduce(function(bbox, part) {
+  return assertValidCSG(objects.reduce(function (bbox, part) {
     var object = bbox ? union([bbox, box(part)]) : part;
     return box(object);
-  }, undefined);
+  }, undefined), 'BBox');
 }
 
 export function Cube(width) {
   var r = div(fromxyz(width), 2);
-  return CSG.cube({
+  return assertValidCSG(CSG.cube({
     center: r,
     radius: r
-  });
+  }), 'Cube');
 }
 
 // export function Sphere(diameter) {
@@ -73,7 +75,7 @@ export function RoundedCube(x, y, thickness, corner_radius) {
     offset: [0, 0, thickness || 1.62]
   });
 
-  return roundedcube;
+  return assertValidCSG(roundedcube, 'RoundedCube');
 }
 
 /**
@@ -96,7 +98,7 @@ export function Cylinder(diameter, height, options = {}) {
     options
   );
 
-  return CSG.cylinder(options);
+  return assertValidCSG(CSG.cylinder(options), 'Cylinder');
 }
 
 /**
@@ -110,7 +112,7 @@ export function Cylinder(diameter, height, options = {}) {
  */
 export function Cone(diameter1, diameter2, height, options = {}) {
   debug('parts.Cone', diameter1, diameter2, height, options);
-  return CSG.cylinder(
+  return assertValidCSG(CSG.cylinder(
     Object.assign(
       {
         start: [0, 0, 0],
@@ -121,7 +123,7 @@ export function Cone(diameter1, diameter2, height, options = {}) {
       },
       options
     )
-  );
+  ), 'Cone');
 }
 
 /**
@@ -142,9 +144,9 @@ export function Hexagon(diameter, height) {
     [radius / 2, -radius * sqrt3]
   ]);
 
-  return hex.extrude({
+  return assertValidCSG(hex.extrude({
     offset: [0, 0, height]
-  });
+  }), 'Hexagon');
 }
 
 /**
@@ -162,9 +164,9 @@ export function Triangle(base, height) {
     [0, Math.sin(30) * radius]
   ]);
 
-  return tri.extrude({
+  return assertValidCSG(tri.extrude({
     offset: [0, 0, height]
-  });
+  }), 'Triangle');
 }
 
 /**
@@ -185,9 +187,9 @@ export function Tube(
   outsideOptions,
   insideOptions
 ) {
-  return Cylinder(outsideDiameter, height, outsideOptions).subtract(
+  return assertValidCSG(Cylinder(outsideDiameter, height, outsideOptions).subtract(
     Cylinder(insideDiameter, height, insideOptions || outsideOptions)
-  );
+  ), 'Tube');
 }
 
 /**
@@ -219,7 +221,7 @@ export function Board(width, height, corner_radius, thickness) {
     offset: [0, 0, thickness || 1.62]
   });
 
-  return board;
+  return assertValidCSG(board, 'Board');
 }
 
 export const Hardware = {
@@ -234,7 +236,7 @@ export const Hardware = {
     }
   },
 
-  Screw: function(head, thread, headClearSpace, options) {
+  Screw: function (head, thread, headClearSpace, options) {
     util.depreciated(
       'Screw',
       false,
@@ -274,7 +276,7 @@ export const Hardware = {
    * @param {number} clearLength  Length of the clearance section of the head.
    * @param {object} options      Screw options include orientation and clerance scale.
    */
-  PanHeadScrew: function(
+  PanHeadScrew: function (
     headDiameter,
     headLength,
     diameter,
@@ -307,7 +309,7 @@ export const Hardware = {
    * @param {number} clearLength  Length of the clearance section of the head.
    * @param {object} options      Screw options include orientation and clerance scale.
    */
-  HexHeadScrew: function(
+  HexHeadScrew: function (
     headDiameter,
     headLength,
     diameter,
@@ -339,7 +341,7 @@ export const Hardware = {
    * @param {number} clearLength  clearance length
    * @param {object} options      options
    */
-  FlatHeadScrew: function(
+  FlatHeadScrew: function (
     headDiameter,
     headLength,
     diameter,