@jscad/modeling 2.7.2 → 2.9.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jscad/modeling",
-  "version": "2.7.2",
+  "version": "2.9.1",
   "description": "Constructive Solid Geometry (CSG) Library for JSCAD",
   "repository": "https://github.com/jscad/OpenJSCAD.org",
   "main": "src/index.js",
@@ -60,5 +60,5 @@
     "nyc": "15.1.0",
     "uglifyify": "5.0.2"
   },
-  "gitHead": "b6c5675d2d9a292e0ba24896bf22d0e9dc5d4270"
+  "gitHead": "a90b9bad95a417661c619dc733e62c587dc71a4a"
 }

package/src/curves/bezier/tangentAt.test.js

@@ -20,7 +20,7 @@ test('quadratic bezier (3 control points)', (t) => {
   t.is(bezier.tangentAt(1, OneDCurve), 20)
 })
 
-test('quadratic bezier (3 control points, non symetric)', (t) => {
+test('quadratic bezier (3 control points, non symmetric)', (t) => {
   const OneDCurve = bezier.create([0, 0, 20])
   t.is(bezier.tangentAt(0, OneDCurve), 0)
   t.is(bezier.tangentAt(0.5, OneDCurve), 20)

package/src/curves/bezier/valueAt.test.js

@@ -20,7 +20,7 @@ test('quadratic bezier (3 control points)', (t) => {
   t.is(bezier.valueAt(1, OneDCurve), 20)
 })
 
-test('quadratic bezier (3 control points, non symetric)', (t) => {
+test('quadratic bezier (3 control points, non symmetric)', (t) => {
   const OneDCurve = bezier.create([0, 0, 20])
   t.is(bezier.valueAt(0, OneDCurve), 0)
   t.is(bezier.valueAt(0.5, OneDCurve), 5)

package/src/geometries/geom2/index.d.ts

@@ -10,6 +10,7 @@ export { default as toSides } from './toSides'
 export { default as toString } from './toString'
 export { default as toCompactBinary } from './toCompactBinary'
 export { default as transform } from './transform'
+export { default as validate } from './validate'
 
 export { default as Geom2 } from './type'
 export as namespace geom2

package/src/geometries/geom2/index.js

@@ -2,6 +2,16 @@
  * Represents a 2D geometry consisting of a list of sides.
  * @see {@link geom2} for data structure information.
  * @module modeling/geometries/geom2
+ *
+ * @example
+ * colorize([0.5,0,1,1], square()) // purple square
+ *
+ * @example
+ * {
+ *   "sides": [[[-1,1],[-1,-1]],[[-1,-1],[1,-1]],[[1,-1],[1,1]],[[1,1],[-1,1]]],
+ *   "transforms": [1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1],
+ *   "color": [0.5,0,1,1]
+ * }
  */
 module.exports = {
   clone: require('./clone'),
@@ -15,5 +25,6 @@ module.exports = {
   toSides: require('./toSides'),
   toString: require('./toString'),
   toCompactBinary: require('./toCompactBinary'),
-  transform: require('./transform')
+  transform: require('./transform'),
+  validate: require('./validate')
 }

package/src/geometries/geom2/isA.js

@@ -1,6 +1,6 @@
 /**
- * Determin if the given object is a 2D geometry.
- * @param {Object} object - the object to interogate
+ * Determine if the given object is a 2D geometry.
+ * @param {Object} object - the object to interrogate
  * @returns {Boolean} true, if the object matches a geom2 based object
  * @alias module:modeling/geometries/geom2.isA
  */

package/src/geometries/geom2/toCompactBinary.js

@@ -4,11 +4,11 @@
  * @returns {TypedArray} compact binary representation
  * @alias module:modeling/geometries/geom2.toCompactBinary
  */
-const toCompactBinary = (geom) => {
-  const sides = geom.sides
-  const transforms = geom.transforms
+const toCompactBinary = (geometry) => {
+  const sides = geometry.sides
+  const transforms = geometry.transforms
   let color = [-1, -1, -1, -1]
-  if (geom.color) color = geom.color
+  if (geometry.color) color = geometry.color
 
   // FIXME why Float32Array?
   const compacted = new Float32Array(1 + 16 + 4 + (sides.length * 4)) // type + transforms + color + sides data

package/src/geometries/geom2/toString.js

@@ -5,7 +5,7 @@ const toSides = require('./toSides')
 /**
  * Create a string representing the contents of the given geometry.
  * @param {geom2} geometry - the geometry
- * @returns {String} a representive string
+ * @returns {String} a representative string
  * @alias module:modeling/geometries/geom2.toString
  *
  * @example

package/src/geometries/geom2/transform.test.js

@@ -11,7 +11,7 @@ test('transform: adjusts the transforms of geom2', (t) => {
   const rotation = 90 * 0.017453292519943295
   const rotate90 = mat4.fromZRotation(mat4.create(), rotation)
 
-  // continue with typical user scenario, several itterations of transforms and access
+  // continue with typical user scenario, several iterations of transforms and access
 
   // expect lazy transform, i.e. only the transforms change
   const expected = {

package/src/geometries/geom2/validate.d.ts

@@ -0,0 +1,3 @@
+export default validate
+
+declare function validate(object: any): void

package/src/geometries/geom2/validate.js

@@ -0,0 +1,36 @@
+const vec2 = require('../../maths/vec2')
+const isA = require('./isA')
+const toOutlines = require('./toOutlines')
+
+/**
+ * Determine if the given object is a valid geom2.
+ * Checks for closedness, self-edges, and valid data points.
+ *
+ * **If the geometry is not valid, an exception will be thrown with details of the geometry error.**
+ *
+ * @param {Object} object - the object to interrogate
+ * @throws {Error} error if the geometry is not valid
+ * @alias module:modeling/geometries/geom2.validate
+ */
+const validate = (object) => {
+  if (!isA(object)) {
+    throw new Error('invalid geom2 structure')
+  }
+
+  // check for closedness
+  toOutlines(object)
+
+  // check for self-edges
+  object.sides.forEach((side) => {
+    if (vec2.equals(side[0], side[1])) {
+      throw new Error(`geom2 self-edge ${side[0]}`)
+    }
+  })
+
+  // check transforms
+  if (!object.transforms.every(Number.isFinite)) {
+    throw new Error(`geom2 invalid transforms ${object.transforms}`)
+  }
+}
+
+module.exports = validate

package/src/geometries/geom3/fromCompactBinary.js

@@ -33,7 +33,7 @@ const fromCompactBinary = (data) => {
     created.polygons.push(poly3.create(vertices))
   }
 
-  // transfer known properities, i.e. color
+  // transfer known properties, i.e. color
   if (data[17] >= 0) {
     created.color = [data[17], data[18], data[19], data[20]]
   }

package/src/geometries/geom3/index.d.ts

@@ -9,6 +9,7 @@ export { default as toPolygons } from './toPolygons'
 export { default as toString } from './toString'
 export { default as toCompactBinary } from './toCompactBinary'
 export { default as transform } from './transform'
+export { default as validate } from './validate'
 
 export { default as Geom3 } from './type'
 export as namespace geom3

package/src/geometries/geom3/index.js

@@ -2,6 +2,23 @@
  * Represents a 3D geometry consisting of a list of polygons.
  * @see {@link geom3} for data structure information.
  * @module modeling/geometries/geom3
+ *
+ * @example
+ * colorize([0,0.5,1,0.6], cube()) // transparent ice cube
+ *
+ * @example
+ * {
+ *   "polygons": [
+ *     {"vertices": [[-1,-1,-1], [-1,-1,1], [-1,1,1], [-1,1,-1]]},
+ *     {"vertices": [[1,-1,-1], [1,1,-1], [1,1,1], [1,-1,1]]},
+ *     {"vertices": [[-1,-1,-1], [1,-1,-1], [1,-1,1], [-1,-1,1]]},
+ *     {"vertices": [[-1,1,-1], [-1,1,1], [1,1,1], [1,1,-1]]},
+ *     {"vertices": [[-1,-1,-1], [-1,1,-1], [1,1,-1], [1,-1,-1]]},
+ *     {"vertices": [[-1,-1,1], [1,-1,1], [1,1,1], [-1,1,1]]}
+ *   ],
+ *   "transforms": [1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1],
+ *   "color": [0,0.5,1,0.6]
+ * }
  */
 module.exports = {
   clone: require('./clone'),
@@ -14,5 +31,6 @@ module.exports = {
   toPolygons: require('./toPolygons'),
   toString: require('./toString'),
   toCompactBinary: require('./toCompactBinary'),
-  transform: require('./transform')
+  transform: require('./transform'),
+  validate: require('./validate')
 }

package/src/geometries/geom3/isA.js

@@ -1,6 +1,6 @@
 /**
- * Determin if the given object is a 3D geometry.
- * @param {object} object - the object to interogate
+ * Determine if the given object is a 3D geometry.
+ * @param {Object} object - the object to interrogate
  * @returns {Boolean} true if the object matches a geom3
  * @alias module:modeling/geometries/geom3.isA
  */

package/src/geometries/geom3/toCompactBinary.js

@@ -6,14 +6,14 @@ const poly3 = require('../poly3')
  * @return {TypedArray} compact binary representation
  * @alias module:modeling/geometries/geom3.toCompactBinary
  */
-const toCompactBinary = (geom) => {
-  const polygons = geom.polygons
-  const transforms = geom.transforms
+const toCompactBinary = (geometry) => {
+  const polygons = geometry.polygons
+  const transforms = geometry.transforms
 
   const numberOfPolygons = polygons.length
   const numberOfVertices = polygons.reduce((count, polygon) => count + polygon.vertices.length, 0)
   let color = [-1, -1, -1, -1]
-  if (geom.color) color = geom.color
+  if (geometry.color) color = geometry.color
 
   // FIXME why Float32Array?
   const compacted = new Float32Array(1 + 16 + 4 + 1 + numberOfPolygons + (numberOfVertices * 3))

package/src/geometries/geom3/toString.js

@@ -5,7 +5,7 @@ const toPolygons = require('./toPolygons')
 /**
  * Create a string representing the contents of the given geometry.
  * @param {geom3} geometry - the geometry
- * @returns {String} a representive string
+ * @returns {String} a representative string
  * @alias module:modeling/geometries/geom3.toString
  *
  * @example

package/src/geometries/geom3/transform.test.js

@@ -11,7 +11,7 @@ test('transform: Adjusts the transforms of a populated geom3', (t) => {
   const rotation = 90 * 0.017453292519943295
   const rotate90 = mat4.fromZRotation(mat4.create(), rotation)
 
-  // continue with typical user scenario, several itterations of transforms and access
+  // continue with typical user scenario, several iterations of transforms and access
 
   // expect lazy transform, i.e. only the transforms change
   const expected = {

package/src/geometries/geom3/validate.d.ts

@@ -0,0 +1,3 @@
+export default validate
+
+declare function validate(object: any): void

package/src/geometries/geom3/validate.js

@@ -0,0 +1,62 @@
+const poly3 = require('../poly3')
+const isA = require('./isA')
+
+/**
+ * Determine if the given object is a valid 3D geometry.
+ * Checks for valid data structure, convex polygon faces, and manifold edges.
+ *
+ * **If the geometry is not valid, an exception will be thrown with details of the geometry error.**
+ *
+ * @param {Object} object - the object to interrogate
+ * @throws {Error} error if the geometry is not valid
+ * @alias module:modeling/geometries/geom3.validate
+ */
+const validate = (object) => {
+  if (!isA(object)) {
+    throw new Error('invalid geom3 structure')
+  }
+
+  // check polygons
+  object.polygons.forEach(poly3.validate)
+  validateManifold(object)
+
+  // check transforms
+  if (!object.transforms.every(Number.isFinite)) {
+    throw new Error(`geom3 invalid transforms ${object.transforms}`)
+  }
+
+  // TODO: check for self-intersecting
+}
+
+/*
+ * Check manifold edge condition: Every edge is in exactly 2 faces
+ */
+const validateManifold = (object) => {
+  // count of each edge
+  const edgeCount = new Map()
+  object.polygons.forEach(({ vertices }) => {
+    vertices.forEach((v, i) => {
+      const v1 = `${v}`
+      const v2 = `${vertices[(i + 1) % vertices.length]}`
+      // sort for undirected edge
+      const edge = `${v1}/${v2}`
+      const count = edgeCount.has(edge) ? edgeCount.get(edge) : 0
+      edgeCount.set(edge, count + 1)
+    })
+  })
+
+  // check that edges are always matched
+  const nonManifold = []
+  edgeCount.forEach((count, edge) => {
+    const complementEdge = edge.split('/').reverse().join('/')
+    const complementCount = edgeCount.get(complementEdge)
+    if (count !== complementCount) {
+      nonManifold.push(edge.replace('/', ' -> '))
+    }
+  })
+  if (nonManifold.length > 0) {
+    throw new Error(`non-manifold edges ${nonManifold.length}\n${nonManifold.join('\n')}`)
+  }
+}
+
+module.exports = validate

package/src/geometries/index.js

@@ -1,6 +1,13 @@
 /**
  * Geometries are objects that represent the contents of primitives or the results of operations.
- * Note: Geometries are consider immutable, so never change the contents directly.
+ * Note: Geometries are considered immutable, so never change the contents directly.
+ *
+ * @see {@link geom2} - 2D geometry consisting of sides
+ * @see {@link geom3} - 3D geometry consisting of polygons
+ * @see {@link path2} - 2D geometry consisting of ordered points
+ * @see {@link poly2} - 2D polygon consisting of ordered vertices
+ * @see {@link poly3} - 3D polygon consisting of ordered vertices
+ *
  * @module modeling/geometries
  * @example
  * const { geom2, geom3, path2, poly2, poly3 } = require('@jscad/modeling').geometries

package/src/geometries/path2/eachPoint.js

@@ -1,14 +1,14 @@
 const toPoints = require('./toPoints')
 
 /**
- * Calls a function for each point in the geometry.
+ * Calls a function for each point in the path.
  * @param {Object} options - options
  * @param {Function} thunk - the function to call
- * @param {path2} geometry - the geometry to traverse
+ * @param {path2} path - the path to traverse
  * @alias module:modeling/geometries/path2.eachPoint
  *
  * @example
- * eachPoint({}, accumulate, geometry)
+ * eachPoint({}, accumulate, path)
  */
 const eachPoint = (options, thunk, path) => {
   toPoints(path).forEach(thunk)

package/src/geometries/path2/index.d.ts

@@ -15,6 +15,7 @@ export { default as toPoints } from './toPoints'
 export { default as toString } from './toString'
 export { default as toCompactBinary } from './toCompactBinary'
 export { default as transform } from './transform'
+export { default as validate } from './validate'
 
 export { default as Path2 } from './type'
 export as namespace path2

package/src/geometries/path2/index.js

@@ -2,6 +2,17 @@
  * Represents a 2D geometry consisting of a list of ordered points.
  * @see {@link path2} for data structure information.
  * @module modeling/geometries/path2
+ *
+ * @example
+ * colorize([0,0,0,1], path2.fromPoints({ closed: true }, [[0,0], [4,0], [4,3]]))
+ *
+ * @example
+ * {
+ *   "points": [[0,0], [4,0], [4,3]],
+ *   "isClosed": true,
+ *   "transforms": [1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1],
+ *   "color": [0,0,0,1]
+ * }
  */
 module.exports = {
   appendArc: require('./appendArc'),
@@ -20,5 +31,6 @@ module.exports = {
   toPoints: require('./toPoints'),
   toString: require('./toString'),
   toCompactBinary: require('./toCompactBinary'),
-  transform: require('./transform')
+  transform: require('./transform'),
+  validate: require('./validate')
 }

package/src/geometries/path2/isA.js

@@ -1,6 +1,6 @@
 /**
- * Determin if the given object is a path2 geometry.
- * @param {Object} object - the object to interogate
+ * Determine if the given object is a path2 geometry.
+ * @param {Object} object - the object to interrogate
  * @returns {Boolean} true if the object matches a path2
  * @alias module:modeling/geometries/path2.isA
  */

package/src/geometries/path2/reverse.js

@@ -3,17 +3,17 @@ const clone = require('./clone')
 /**
  * Reverses the path so that the points are in the opposite order.
  * This swaps the left (interior) and right (exterior) edges.
- * @param {path2} geometry - the geometry to reverse
+ * @param {path2} geometry - the path to reverse
  * @returns {path2} a new path
  * @alias module:modeling/geometries/path2.reverse
  *
  * @example
  * let newpath = reverse(mypath)
  */
-const reverse = (path) => {
+const reverse = (geometry) => {
   // NOTE: this only updates the order of the points
-  const cloned = clone(path)
-  cloned.points = path.points.slice().reverse()
+  const cloned = clone(geometry)
+  cloned.points = geometry.points.slice().reverse()
   return cloned
 }
 

package/src/geometries/path2/toCompactBinary.js

@@ -1,14 +1,14 @@
 /**
  * Produce a compact binary representation from the given path.
- * @param {path2} geometry - the path
+ * @param {path2} geometry - the path geometry
  * @returns {TypedArray} compact binary representation
  * @alias module:modeling/geometries/path2.toCompactBinary
  */
-const toCompactBinary = (geom) => {
-  const points = geom.points
-  const transforms = geom.transforms
+const toCompactBinary = (geometry) => {
+  const points = geometry.points
+  const transforms = geometry.transforms
   let color = [-1, -1, -1, -1]
-  if (geom.color) color = geom.color
+  if (geometry.color) color = geometry.color
 
   // FIXME why Float32Array?
   const compacted = new Float32Array(1 + 16 + 1 + 4 + (points.length * 2)) // type + transforms + isClosed + color + points data
@@ -32,7 +32,7 @@ const toCompactBinary = (geom) => {
   compacted[15] = transforms[14]
   compacted[16] = transforms[15]
 
-  compacted[17] = geom.isClosed ? 1 : 0
+  compacted[17] = geometry.isClosed ? 1 : 0
 
   compacted[18] = color[0]
   compacted[19] = color[1]

package/src/geometries/path2/toString.js

@@ -5,7 +5,7 @@ const toPoints = require('./toPoints')
 /**
  * Create a string representing the contents of the given path.
  * @param {path2} geometry - the path
- * @returns {String} a representive string
+ * @returns {String} a representative string
  * @alias module:modeling/geometries/path2.toString
  *
  * @example

package/src/geometries/path2/transform.test.js

@@ -11,7 +11,7 @@ test('transform: adjusts the transforms of path', (t) => {
   const rotation = 90 * 0.017453292519943295
   const rotate90 = mat4.fromZRotation(mat4.create(), rotation)
 
-  // continue with typical user scenario, several itterations of transforms and access
+  // continue with typical user scenario, several iterations of transforms and access
 
   // expect lazy transform, i.e. only the transforms change
   const expected = {

package/src/geometries/path2/validate.d.ts

@@ -0,0 +1,3 @@
+export default validate
+
+declare function validate(object: any): void

package/src/geometries/path2/validate.js

@@ -0,0 +1,41 @@
+const vec2 = require('../../maths/vec2')
+const isA = require('./isA')
+
+/**
+ * Determine if the given object is a valid path2.
+ * Checks for valid data points, and duplicate points.
+ *
+ * **If the geometry is not valid, an exception will be thrown with details of the geometry error.**
+ *
+ * @param {Object} object - the object to interrogate
+ * @throws {Error} error if the geometry is not valid
+ * @alias module:modeling/geometries/path2.validate
+ */
+const validate = (object) => {
+  if (!isA(object)) {
+    throw new Error('invalid path2 structure')
+  }
+
+  // check for duplicate points
+  if (object.points.length > 1) {
+    for (let i = 0; i < object.points.length; i++) {
+      if (vec2.equals(object.points[i], object.points[(i + 1) % object.points.length])) {
+        throw new Error(`path2 duplicate points ${object.points[i]}`)
+      }
+    }
+  }
+
+  // check for infinity, nan
+  object.points.forEach((point) => {
+    if (!point.every(Number.isFinite)) {
+      throw new Error(`path2 invalid point ${point}`)
+    }
+  })
+
+  // check transforms
+  if (!object.transforms.every(Number.isFinite)) {
+    throw new Error(`path2 invalid transforms ${object.transforms}`)
+  }
+}
+
+module.exports = validate

package/src/geometries/poly2/arePointsInside.js

@@ -23,41 +23,6 @@ const arePointsInside = (points, polygon) => {
   return sum === points.length ? 1 : 0
 }
 
-/*
- * Determine if the given point is inside the polygon.
- *
- * @see http://geomalgorithms.com/a03-_inclusion.html
- * @param {Array} point - an array with X and Y values
- * @param {Array} polygon - a list of points, where each point is an array with X and Y values
- * @return {Integer} 1 if the point is inside, 0 if outside
- */
-const isPointInsideOld = (point, polygon) => {
-  let wn = 0
-  const n = polygon.length
-  const x = point[0]
-  const y = point[1]
-  for (let i = 0; i < polygon.length; i++) {
-    const p1 = polygon[i]
-    const p2 = polygon[(i + 1) % n]
-    if (x !== p1[0] && y !== p1[1] && x !== p2[0] && y !== p2[1]) { // no overlap of points
-      if (p1[1] <= y) {
-        if (p2[1] > y) { // upward crossing
-          if (isLeft(p1, p2, point) > 0) { // point left of edge
-            wn++
-          }
-        }
-      } else {
-        if (p2[1] <= y) { // downward crossing
-          if (isLeft(p1, p2, point) < 0) { // point right of edge
-            wn--
-          }
-        }
-      }
-    }
-  }
-  return wn === 0 ? 1 : 0
-}
-
 /*
  * Determine if the given point is inside the polygon.
  *

package/src/geometries/poly2/arePointsInside.test.js

@@ -12,7 +12,7 @@ test('poly2: arePointsInside() should return proper values', (t) => {
   t.is(obs, 0)
 
   polygon = create([[0, 0], [5, 0], [5, 5], [0, 5]])
-  // points overlaping points
+  // points overlapping points
   obs = arePointsInside([[0, 0]], polygon)
   t.is(obs, 0)
   obs = arePointsInside([[5, 0]], polygon)

package/src/geometries/poly2/index.js

@@ -2,6 +2,12 @@
  * Represents a 2D polygon consisting of a list of ordered vertices.
  * @see {@link poly2} for data structure information.
  * @module modeling/geometries/poly2
+ *
+ * @example
+ * poly2.create([[0,0], [4,0], [4,3]])
+ *
+ * @example
+ * {"vertices": [[0,0], [4,0], [4,3]]}
  */
 module.exports = {
   arePointsInside: require('./arePointsInside'),

package/src/geometries/poly3/index.d.ts

@@ -13,6 +13,7 @@ export { default as plane } from './plane'
 export { default as toPoints } from './toPoints'
 export { default as toString } from './toString'
 export { default as transform } from './transform'
+export { default as validate } from './validate'
 
 export { default as Poly3 } from './type'
 export as namespace poly3

package/src/geometries/poly3/index.js

@@ -1,7 +1,13 @@
 /**
- * Represents a convex 3D polygon consisting of a list of vertices.
+ * Represents a convex 3D polygon consisting of a list of ordered vertices.
  * @see {@link poly3} for data structure information.
  * @module modeling/geometries/poly3
+ *
+ * @example
+ * poly3.create([[0,0,0], [4,0,0], [4,3,12]])
+ *
+ * @example
+ * {"vertices": [[0,0,0], [4,0,0], [4,3,12]]}
  */
 module.exports = {
   clone: require('./clone'),
@@ -18,5 +24,6 @@ module.exports = {
   plane: require('./plane'),
   toPoints: require('./toPoints'),
   toString: require('./toString'),
-  transform: require('./transform')
+  transform: require('./transform'),
+  validate: require('./validate')
 }

package/src/geometries/poly3/invert.js

@@ -1,3 +1,4 @@
+const plane = require('../../maths/plane')
 const create = require('./create')
 
 /**
@@ -9,7 +10,12 @@ const create = require('./create')
  */
 const invert = (polygon) => {
   const vertices = polygon.vertices.slice().reverse()
-  return create(vertices)
+  const inverted = create(vertices)
+  if (polygon.plane) {
+    // Flip existing plane to save recompute
+    inverted.plane = plane.flip(plane.create(), polygon.plane)
+  }
+  return inverted
 }
 
 module.exports = invert