@jscad/modeling 3.0.0-alpha.0 → 3.0.2-alpha.0

package/src/operations/booleans/trees/PolygonTreeNode.js

@@ -6,6 +6,9 @@ import * as poly3 from '../../../geometries/poly3/index.js'
 
 import { splitPolygonByPlane } from './splitPolygonByPlane.js'
 
+// cached values to boost performance
+const splitResult = { type: 0, front: null, back: null }
+
 // # class PolygonTreeNode
 // This class manages hierarchical splits of polygons.
 // At the top is a root node which does not hold a polygon, only child PolygonTreeNodes.
@@ -13,72 +16,72 @@ import { splitPolygonByPlane } from './splitPolygonByPlane.js'
 // The polygons can be in different planes.
 // splitByPlane() splits a node by a plane. If the plane intersects the polygon,
 // two new child nodes are created holding the split polygon.
-// getPolygons() retrieves the polygons from the tree. If for PolygonTreeNode the polygon is split but
+// getPolygons() retrieves the polygons from the node. If for PolygonTreeNode the polygon is split but
 // the two split parts (child nodes) are still intact, then the unsplit polygon is returned.
 // This ensures that we can safely split a polygon into many fragments. If the fragments are untouched,
 // getPolygons() will return the original unsplit polygon instead of the fragments.
-// remove() removes a polygon from the tree. Once a polygon is removed, the parent polygons are invalidated
+// remove() removes a polygon from the node. Once a polygon is removed, the parent polygons are invalidated
 // since they are no longer intact.
 export class PolygonTreeNode {
   // constructor creates the root node
   constructor (parent, polygon) {
     this.parent = parent
-    this.children = []
     this.polygon = polygon
-    this.removed = false // state of branch or leaf
+    this.children = []
   }
 
-  // fill the tree with polygons. Should be called on the root node only; child nodes must
+  // fill the node with polygons. Should be called on the root node only; child nodes must
   // always be a derivate (split) of the parent node.
   addPolygons (polygons) {
     // new polygons can only be added to root node; children can only be split polygons
-    if (!this.isRootNode()) {
-      throw new Error('Assertion failed')
+    if (!this.isRootNode()) throw new Error('PolygonTreeNode01')
+
+    for (let i = 0; i < polygons.length; i++) {
+      this.addChild(polygons[i])
     }
-    const _this = this
-    polygons.forEach((polygon) => {
-      _this.addChild(polygon)
-    })
   }
 
   // remove a node
   // - the siblings become toplevel nodes
   // - the parent is removed recursively
   remove () {
-    if (!this.removed) {
-      this.removed = true
-      this.polygon = null
+    this.polygon = null
 
-      // remove ourselves from the parent's children list:
-      const parentschildren = this.parent.children
-      const i = parentschildren.indexOf(this)
-      if (i < 0) throw new Error('Assertion failed')
-      parentschildren.splice(i, 1)
+    // remove ourselves from the parent's children list:
+    const parentschildren = this.parent.children
+    const i = parentschildren.indexOf(this)
+    if (i < 0) throw new Error('PolyTreeNode02')
+    parentschildren.splice(i, 1)
 
-      // invalidate the parent's polygon, and of all parents above it:
-      this.parent.recursivelyInvalidatePolygon()
-    }
+    // invalidate the parent's polygon, and of all parents above it:
+    this.parent._recursivelyInvalidatePolygon()
   }
 
-  isRemoved () {
-    return this.removed
+  /*
+   * Can the node be split, either base polygon or children
+   */
+  canSplit () {
+    return this.polygon != null || this.children.length > 0
   }
 
   isRootNode () {
     return !this.parent
   }
 
-  // invert all polygons in the tree. Call on the root node
+  // invert all polygons in the node. Call on the root node
   invert () {
-    if (!this.isRootNode()) throw new Error('Assertion failed') // can only call this on the root node
-    this.invertSub()
+    if (!this.isRootNode()) throw new Error('PolyTreeNode03')
+    this._invertSub()
   }
 
   getPolygon () {
-    if (!this.polygon) throw new Error('Assertion failed') // doesn't have a polygon, which means that it has been broken down
+    if (this.polygon === null) throw new Error('PolyTreeNode04')
     return this.polygon
   }
 
+  /*
+   * Get all polygons from the node, and add to the result
+   */
   getPolygons (result) {
     let children = [this]
     const queue = [children]
@@ -87,23 +90,37 @@ export class PolygonTreeNode {
       children = queue[i]
       for (j = 0, l = children.length; j < l; j++) { // ok to cache length
         node = children[j]
-        if (node.polygon) {
-          // the polygon hasn't been broken yet. We can ignore the children and return our polygon:
+        if (node.polygon !== null) {
+          // the polygon hasn't been broken yet. We can ignore the children and return our polygon
           result.push(node.polygon)
         } else {
-          // our polygon has been split up and broken, so gather all subpolygons from the children
-          if (node.children.length > 0) queue.push(node.children)
+          // our polygon has been split up and broken, so gather all subpolygons
+          if (node.children.length > 0) {
+            queue.push(node.children)
+          }
         }
       }
     }
   }
 
-  // split the node by a plane; add the resulting nodes to the frontNodes and backNodes array
-  // If the plane doesn't intersect the polygon, the 'this' object is added to one of the arrays
-  // If the plane does intersect the polygon, two new child nodes are created for the front and back fragments,
-  //  and added to both arrays.
-  splitByPlane (plane, coplanarFrontNodes, coplanarBackNodes, frontNodes, backNodes) {
-    if (this.children.length) {
+  // NOTE: This version of getPolygons() is much SLOWER.
+  getPolygonsNew (result) {
+    if (this.polygon !== null) {
+      // the polygon hasn't been broken yet, so return the original polygon
+      result.push(this.polygon)
+    } else {
+      // the polygon has been split, so gather all polygons from the children
+      for (let i = 0; i < this.children.length; i++) {
+        const node = this.children[i]
+        node.getPolygons(result)
+      }
+    }
+  }
+
+  // split the node by a plane, adding the resulting nodes to the frontNodes and backNodes array
+  // Also see canSplit()
+  splitByPlaneOld (plane, coplanarfrontnodes, coplanarbacknodes, frontnodes, backnodes) {
+    if (this.children.length > 0) {
       const queue = [this.children]
       let i
       let j
@@ -117,68 +134,90 @@ export class PolygonTreeNode {
           if (node.children.length > 0) {
             queue.push(node.children)
           } else {
-            // no children. Split the polygon:
-            node._splitByPlane(plane, coplanarFrontNodes, coplanarBackNodes, frontNodes, backNodes)
+            if (this.polygon !== null) {
+              // no children. Split the polygon:
+              node._splitByPlane(plane, coplanarfrontnodes, coplanarbacknodes, frontnodes, backnodes)
+            }
           }
         }
       }
     } else {
-      this._splitByPlane(plane, coplanarFrontNodes, coplanarBackNodes, frontNodes, backNodes)
+      if (this.polygon !== null) {
+        this._splitByPlane(plane, coplanarfrontnodes, coplanarbacknodes, frontnodes, backnodes)
+      }
+    }
+  }
+
+  splitByPlane (plane, coplanarFrontNodes, coplanarBackNodes, frontNodes, backNodes) {
+    if (this.children.length > 0) {
+      // the polygon has been split, so split the children by the given plane
+      for (let i = 0; i < this.children.length; i++) {
+        const node = this.children[i]
+        node.splitByPlane(plane, coplanarFrontNodes, coplanarBackNodes, frontNodes, backNodes)
+      }
+    } else {
+      if (this.polygon !== null) {
+        // the polygon hasn't been split, so split this node by the given plane
+        this._splitByPlane(plane, coplanarFrontNodes, coplanarBackNodes, frontNodes, backNodes)
+      }
     }
   }
 
+  // PRIVATE
+  // If the plane doesn't intersect the polygon, the 'this' object is added to one of the arrays
+  // If the plane does intersect the polygon, two new child nodes are created for the front and back fragments,
+  // and added to both arrays.
   // only to be called for nodes with no children
   _splitByPlane (splane, coplanarFrontNodes, coplanarBackNodes, frontNodes, backNodes) {
-    const polygon = this.polygon
-    if (polygon) {
-      const bound = poly3.measureBoundingSphere(polygon)
-      const sphereRadius = bound[3] + EPS // ensure radius is LARGER then polygon
-      const sphereCenter = bound
-      const d = vec3.dot(splane, sphereCenter) - splane[3]
-      if (d > sphereRadius) {
-        frontNodes.push(this)
-      } else if (d < -sphereRadius) {
-        backNodes.push(this)
-      } else {
-        const splitResult = splitPolygonByPlane(splane, polygon)
-        switch (splitResult.type) {
-          case 0:
-            // coplanar front:
-            coplanarFrontNodes.push(this)
-            break
+    // perform a quick check to see the plane is outside the bounds of the polygon
+    const bounds = poly3.measureBoundingSphereAndCache(this.polygon)
+    const sphereRadius = bounds[3] + EPS // ensure radius is LARGER then polygon
+    const d = vec3.dot(splane, bounds) - splane[3]
+    if (d > sphereRadius) {
+      frontNodes.push(this)
+      return
+    } else if (d < -sphereRadius) {
+      backNodes.push(this)
+      return
+    }
 
-          case 1:
-            // coplanar back:
-            coplanarBackNodes.push(this)
-            break
+    // the plane may intersect the polyogn
+    splitPolygonByPlane(splitResult, splane, this.polygon)
+    switch (splitResult.type) {
+      case 0:
+        // coplanar front:
+        coplanarFrontNodes.push(this)
+        break
 
-          case 2:
-            // front:
-            frontNodes.push(this)
-            break
+      case 1:
+        // coplanar back:
+        coplanarBackNodes.push(this)
+        break
 
-          case 3:
-            // back:
-            backNodes.push(this)
-            break
+      case 2:
+        // front:
+        frontNodes.push(this)
+        break
 
-          case 4:
-            // spanning:
-            if (splitResult.front) {
-              const frontNode = this.addChild(splitResult.front)
-              frontNodes.push(frontNode)
-            }
-            if (splitResult.back) {
-              const backNode = this.addChild(splitResult.back)
-              backNodes.push(backNode)
-            }
-            break
+      case 3:
+        // back:
+        backNodes.push(this)
+        break
+
+      case 4:
+        // spanning:
+        if (splitResult.front !== null) {
+          const frontNode = this.addChild(splitResult.front)
+          frontNodes.push(frontNode)
         }
-      }
+        if (splitResult.back !== null) {
+          const backNode = this.addChild(splitResult.back)
+          backNodes.push(backNode)
+        }
+        break
     }
   }
 
-  // PRIVATE methods from here:
   // add child to a node
   // this should be called whenever the polygon is split
   // a child should be created for every fragment of the split polygon
@@ -189,7 +228,9 @@ export class PolygonTreeNode {
     return newChild
   }
 
-  invertSub () {
+  // PRIVATE
+  // See invert()
+  _invertSub () {
     let children = [this]
     const queue = [children]
     let i, j, l, node
@@ -197,7 +238,7 @@ export class PolygonTreeNode {
       children = queue[i]
       for (j = 0, l = children.length; j < l; j++) {
         node = children[j]
-        if (node.polygon) {
+        if (node.polygon !== null) {
           node.polygon = poly3.invert(node.polygon)
         }
         if (node.children.length > 0) queue.push(node.children)
@@ -205,34 +246,40 @@ export class PolygonTreeNode {
     }
   }
 
-  // private method
+  // NOTE: This verison is SLOWER
+  _invertSubNew () {
+    if (this.polygon !== null) {
+      this.polygon = poly3.invert(this.polygon)
+    }
+    for (let i = 0; i < this.children.length; i++) {
+      const node = this.children[i]
+      node._invertSub()
+    }
+  }
+
+  // PRIVATE
   // remove the polygon from the node, and all parent nodes above it
   // called to invalidate parents of removed nodes
-  recursivelyInvalidatePolygon () {
+  _recursivelyInvalidatePolygon () {
     this.polygon = null
-    if (this.parent) {
-      this.parent.recursivelyInvalidatePolygon()
+    if (this.parent !== null) {
+      this.parent._recursivelyInvalidatePolygon()
     }
   }
 
   clear () {
-    let children = [this]
-    const queue = [children]
-    for (let i = 0; i < queue.length; ++i) { // queue size can change in loop, don't cache length
-      children = queue[i]
-      const l = children.length
-      for (let j = 0; j < l; j++) {
-        const node = children[j]
-        if (node.polygon) {
-          node.polygon = null
-        }
-        if (node.parent) {
-          node.parent = null
-        }
-        if (node.children.length > 0) queue.push(node.children)
-        node.children = []
-      }
+    // clear children
+    for (let i = 0; i < this.children.length; i++) {
+      const node = this.children[i]
+      node.clear()
+    }
+    this.children.length = 0
+    // unlink polygon
+    if (this.polygon !== null) {
+      this.polygon = null
     }
+    // unlink parent
+    this.parent = null
   }
 
   toString () {
@@ -246,7 +293,7 @@ export class PolygonTreeNode {
       for (j = 0, l = children.length; j < l; j++) { // ok to cache length
         node = children[j]
         result += `${prefix}PolygonTreeNode (${node.isRootNode()}): ${node.children.length}`
-        if (node.polygon) {
+        if (node.polygon !== null) {
           result += `\n ${prefix}polygon: ${node.polygon.vertices}\n`
         } else {
           result += '\n'

package/src/operations/booleans/trees/Tree.js

@@ -7,7 +7,7 @@ import { PolygonTreeNode } from './PolygonTreeNode.js'
 // The actual tree is kept in this.rootnode
 export class Tree {
   constructor (polygons) {
-    this.polygonTree = new PolygonTreeNode()
+    this.polygonTree = new PolygonTreeNode(null, null)
     this.rootnode = new Node(null)
     if (polygons) this.addPolygons(polygons)
   }
@@ -17,10 +17,9 @@ export class Tree {
     this.rootnode.invert()
   }
 
-  // Remove all polygons in this BSP tree that are inside the other BSP tree
-  // `tree`.
+  // Remove all polygons in this tree that are inside the given tree
   clipTo (tree, alsoRemoveCoplanarFront = false) {
-    this.rootnode.clipTo(tree, alsoRemoveCoplanarFront)
+    this.rootnode.clipTo(tree.rootnode, alsoRemoveCoplanarFront)
   }
 
   allPolygons () {
@@ -37,6 +36,12 @@ export class Tree {
     this.rootnode.addPolygonTreeNodes(polygonTreeNodes)
   }
 
+  // NOTE: This version is SLOWER
+  addPolygonsNew (polygons) {
+    this.polygonTree.addPolygons(polygons)
+    this.rootnode.addPolygonTreeNodes(this.polygonTree.children)
+  }
+
   clear () {
     this.polygonTree.clear()
   }

package/src/operations/booleans/trees/splitLineSegmentByPlane.js

@@ -3,9 +3,11 @@ import * as vec3 from '../../../maths/vec3/index.js'
 export const splitLineSegmentByPlane = (plane, p1, p2) => {
   const direction = vec3.subtract(vec3.create(), p2, p1)
   let lambda = (plane[3] - vec3.dot(plane, p1)) / vec3.dot(plane, direction)
-  if (Number.isNaN(lambda)) lambda = 0
-  if (lambda > 1) lambda = 1
-  if (lambda < 0) lambda = 0
+
+  Number.isNaN(lambda) ? lambda = 0
+    : lambda > 1 ? lambda = 1
+      : lambda < 0 ? lambda = 0
+        : lambda
 
   vec3.scale(direction, direction, lambda)
   vec3.add(direction, p1, direction)

package/src/operations/booleans/trees/splitPolygonByPlane.d.ts

@@ -0,0 +1,33 @@
+import { Poly3 } from '../../../geometries/types';
+import { Plane } from '../../../maths/types';
+
+enum ResType
+{
+    coplanar_front = 0,
+    coplanar_back = 1,
+    front = 2,
+    back = 3,
+    spanning = 4,
+}
+
+
+interface SplitRes
+{
+    type: ResType,
+    front: Poly3,
+    back: Poly3;
+}
+
+// Returns object:
+// .type:
+//   0: coplanar-front
+//   1: coplanar-back
+//   2: front
+//   3: back
+//   4: spanning
+// In case the polygon is spanning, returns:
+// .front: a Polygon3 of the front part
+// .back: a Polygon3 of the back part
+declare function splitPolygonByPlane(plane: Plane, polygon: Poly3): SplitRes;
+
+export default splitPolygonByPlane;

package/src/operations/booleans/trees/splitPolygonByPlane.js

@@ -7,23 +7,27 @@ import * as poly3 from '../../../geometries/poly3/index.js'
 
 import { splitLineSegmentByPlane } from './splitLineSegmentByPlane.js'
 
-// Returns object:
-// .type:
-//   0: coplanar-front
-//   1: coplanar-back
-//   2: front
-//   3: back
-//   4: spanning
-// In case the polygon is spanning, returns:
-// .front: a Polygon3 of the front part
-// .back: a Polygon3 of the back part
-export const splitPolygonByPlane = (splane, polygon) => {
-  const result = {
-    type: null,
-    front: null,
-    back: null
-  }
-  // cache in local lets (speedup):
+/*
+ * Split the given polygon by the given plane.
+ *
+ * @@param (Object} result - object of which to update with the result
+ * @param {Plane} splane - plane to split across
+ * @param {Poly3} ploygon - polygon of which to split
+ * @returns none
+ *
+ * The result is updated in place to improve performance (no allocation)
+ *   result.type:
+ *     0: coplanar-front
+ *     1: coplanar-back
+ *     2: front
+ *     3: back
+ *     4: spanning
+ *
+ * In case the polygon is spanning (4)
+ *   result.front contains null or a ploygon (front part)
+ *   result.back contains null or a polygon (back part)
+ */
+export const splitPolygonByPlane = (result, splane, polygon) => {
   const vertices = polygon.vertices
   const numVertices = vertices.length
   const pplane = poly3.plane(polygon)
@@ -41,17 +45,20 @@ export const splitPolygonByPlane = (splane, polygon) => {
       if (t > EPS) hasFront = true
       if (t < MINEPS) hasBack = true
     }
+
     if ((!hasFront) && (!hasBack)) {
       // all points coplanar
       const t = vec3.dot(splane, pplane)
       result.type = (t >= 0) ? 0 : 1
     } else if (!hasBack) {
+      // points only front of the plane
       result.type = 2
     } else if (!hasFront) {
+      // points only back of the plane
       result.type = 3
     } else {
-      // spanning
-      result.type = 4
+      // points span the plane
+      // split the line segments by the plane
       const frontVertices = []
       const backVertices = []
       let isback = vertexIsBack[0]
@@ -61,14 +68,10 @@ export const splitPolygonByPlane = (splane, polygon) => {
         if (nextVertexIndex >= numVertices) nextVertexIndex = 0
         const nextIsBack = vertexIsBack[nextVertexIndex]
         if (isback === nextIsBack) {
-          // line segment is on one side of the plane:
-          if (isback) {
-            backVertices.push(vertex)
-          } else {
-            frontVertices.push(vertex)
-          }
+          // line segment is on one side of the plane
+          isback ? backVertices.push(vertex) : frontVertices.push(vertex)
         } else {
-          // line segment intersects plane:
+          // line segment spans the plane
           const nextPoint = vertices[nextVertexIndex]
           const intersectionPoint = splitLineSegmentByPlane(splane, vertex, nextPoint)
           if (isback) {
@@ -82,8 +85,9 @@ export const splitPolygonByPlane = (splane, polygon) => {
           }
         }
         isback = nextIsBack
-      } // for vertexIndex
-      // remove duplicate vertices:
+      }
+
+      // remove duplicate vertices
       const EPS_SQUARED = EPS * EPS
       if (backVertices.length >= 3) {
         let prevVertex = backVertices[backVertices.length - 1]
@@ -107,12 +111,13 @@ export const splitPolygonByPlane = (splane, polygon) => {
           prevVertex = vertex
         }
       }
-      if (frontVertices.length >= 3) {
-        result.front = poly3.fromVerticesAndPlane(frontVertices, pplane)
-      }
-      if (backVertices.length >= 3) {
-        result.back = poly3.fromVerticesAndPlane(backVertices, pplane)
-      }
+
+      // assemble the result
+      result.type = 4
+
+      result.front = frontVertices.length >= 3 ? poly3.fromVerticesAndPlane(frontVertices, pplane) : null
+
+      result.back = backVertices.length >= 3 ? poly3.fromVerticesAndPlane(backVertices, pplane) : null
     }
   }
   return result

package/src/operations/booleans/union.js

@@ -1,5 +1,5 @@
 import { areAllShapesTheSameType } from '../../utils/areAllShapesTheSameType.js'
-import { flatten } from '../../utils/flatten.js'
+import { coalesce } from '../../utils/coalesce.js'
 
 import * as geom2 from '../../geometries/geom2/index.js'
 import * as geom3 from '../../geometries/geom3/index.js'
@@ -12,11 +12,11 @@ import { unionGeom3 } from './unionGeom3.js'
  * The given geometries should be of the same type, either geom2 or geom3.
  *
  * @param {...Object} geometries - list of geometries
- * @returns {Geom2|geom3} a new geometry
+ * @returns {Geom2|Geom3} a new geometry
  * @alias module:modeling/booleans.union
  *
  * @example
- * let myshape = union(cube({size: [5,5,5]}), cube({size: [5,5,5], center: [5,5,5]}))
+ * let myshape = union(cube({size: 5}), cube({size: 5, center: [3,3,3]}))
  *
  * @example
  * +-------+            +-------+
@@ -29,9 +29,9 @@ import { unionGeom3 } from './unionGeom3.js'
  *      +-------+            +-------+
  */
 export const union = (...geometries) => {
-  geometries = flatten(geometries)
-  if (geometries.length === 0) throw new Error('union wrong number of arguments')
+  geometries = coalesce(geometries)
 
+  if (geometries.length === 0) return undefined
   if (!areAllShapesTheSameType(geometries)) {
     throw new Error('union arguments must be the same geometry type')
   }

package/src/operations/booleans/union.test.js

@@ -4,11 +4,11 @@ import { geom2, geom3 } from '../../geometries/index.js'
 
 import { union } from './index.js'
 
-test('union error wrong number of arguments', (t) => {
-  const message = 'union wrong number of arguments'
-  t.throws(() => union(), { message })
-  t.throws(() => union([]), { message })
-  t.throws(() => union([[], []]), { message })
+test('union empty arguments', (t) => {
+  t.is(union(), undefined)
+  t.is(union([]), undefined)
+  t.is(union([[], []]), undefined)
+  t.is(union(null, null), undefined)
 })
 
 test('union error different geometry types', (t) => {
@@ -20,6 +20,5 @@ test('union error non-geometries', (t) => {
   const message = 'union unsupported geometry type'
   t.throws(() => union([1, 2, 3], [4, 5, 6]), { message })
   t.throws(() => union([], [123]), { message })
-  t.throws(() => union("one", "two"), { message })
-  t.throws(() => union(null, null), { message })
+  t.throws(() => union('one', 'two'), { message })
 })

package/src/operations/booleans/unionGeom2.js

@@ -1,16 +1,12 @@
-import { flatten } from '../../utils/flatten.js'
-
 import { UNION } from './martinez/operation.js'
 import { boolean } from './martinez/index.js'
 
 /*
  * Return a new 2D geometry representing the total space in the given 2D geometries.
- * @param {...geom2} geometries - list of 2D geometries to union
+ * @param {Geom2[]} geometries - a flat list of 2D geometries to union
  * @returns {Geom2} new 2D geometry
  */
-export const unionGeom2 = (...geometries) => {
-  geometries = flatten(geometries)
-
+export const unionGeom2 = (geometries) => {
   let newGeometry = geometries.shift()
   geometries.forEach((geometry) => {
     newGeometry = boolean(newGeometry, geometry, UNION)