@jbroll/jscad-modeling 2.12.7

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

@@ -0,0 +1,261 @@
+const { EPS } = require('../../../maths/constants')
+
+const vec3 = require('../../../maths/vec3')
+
+const poly3 = require('../../../geometries/poly3')
+
+const splitPolygonByPlane = require('./splitPolygonByPlane')
+
+// # 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.
+// Below that are zero or more 'top' nodes; each holds a polygon.
+// 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 splitted polygon.
+// getPolygons() retrieves the polygons from the tree. 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
+// since they are no longer intact.
+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
+  }
+
+  // fill the tree 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 splitted polygons
+    if (!this.isRootNode()) {
+      throw new Error('Assertion failed')
+    }
+    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
+
+      // 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)
+
+      // invalidate the parent's polygon, and of all parents above it:
+      this.parent.recursivelyInvalidatePolygon()
+    }
+  }
+
+  isRemoved () {
+    return this.removed
+  }
+
+  isRootNode () {
+    return !this.parent
+  }
+
+  // invert all polygons in the tree. Call on the root node
+  invert () {
+    if (!this.isRootNode()) throw new Error('Assertion failed') // can only call this on the root node
+    this.invertSub()
+  }
+
+  getPolygon () {
+    if (!this.polygon) throw new Error('Assertion failed') // doesn't have a polygon, which means that it has been broken down
+    return this.polygon
+  }
+
+  getPolygons (result) {
+    let children = [this]
+    const queue = [children]
+    let i, j, l, node
+    for (i = 0; i < queue.length; ++i) { // queue size can change in loop, don't cache length
+      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:
+          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)
+        }
+      }
+    }
+  }
+
+  // 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) {
+      const queue = [this.children]
+      let i
+      let j
+      let l
+      let node
+      let nodes
+      for (i = 0; i < queue.length; i++) { // queue.length can increase, do not cache
+        nodes = queue[i]
+        for (j = 0, l = nodes.length; j < l; j++) { // ok to cache length
+          node = nodes[j]
+          if (node.children.length > 0) {
+            queue.push(node.children)
+          } else {
+            // no children. Split the polygon:
+            node._splitByPlane(plane, coplanarfrontnodes, coplanarbacknodes, frontnodes, backnodes)
+          }
+        }
+      }
+    } else {
+      this._splitByPlane(plane, coplanarfrontnodes, coplanarbacknodes, frontnodes, backnodes)
+    }
+  }
+
+  // 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
+
+          case 1:
+            // coplanar back:
+            coplanarbacknodes.push(this)
+            break
+
+          case 2:
+            // front:
+            frontnodes.push(this)
+            break
+
+          case 3:
+            // back:
+            backnodes.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
+        }
+      }
+    }
+  }
+
+  // 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
+  // returns the newly created child
+  addChild (polygon) {
+    const newchild = new PolygonTreeNode(this, polygon)
+    this.children.push(newchild)
+    return newchild
+  }
+
+  invertSub () {
+    let children = [this]
+    const queue = [children]
+    let i, j, l, node
+    for (i = 0; i < queue.length; i++) {
+      children = queue[i]
+      for (j = 0, l = children.length; j < l; j++) {
+        node = children[j]
+        if (node.polygon) {
+          node.polygon = poly3.invert(node.polygon)
+        }
+        if (node.children.length > 0) queue.push(node.children)
+      }
+    }
+  }
+
+  // private method
+  // remove the polygon from the node, and all parent nodes above it
+  // called to invalidate parents of removed nodes
+  recursivelyInvalidatePolygon () {
+    this.polygon = null
+    if (this.parent) {
+      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 = []
+      }
+    }
+  }
+
+  toString () {
+    let result = ''
+    let children = [this]
+    const queue = [children]
+    let i, j, l, node
+    for (i = 0; i < queue.length; ++i) { // queue size can change in loop, don't cache length
+      children = queue[i]
+      const prefix = ' '.repeat(i)
+      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) {
+          result += `\n ${prefix}polygon: ${node.polygon.vertices}\n`
+        } else {
+          result += '\n'
+        }
+        if (node.children.length > 0) queue.push(node.children)
+      }
+    }
+    return result
+  }
+}
+
+module.exports = PolygonTreeNode

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

@@ -0,0 +1,50 @@
+const Node = require('./Node')
+const PolygonTreeNode = require('./PolygonTreeNode')
+
+// # class Tree
+// This is the root of a BSP tree.
+// This separate class for the root of the tree in order to hold the PolygonTreeNode root.
+// The actual tree is kept in this.rootnode
+class Tree {
+  constructor (polygons) {
+    this.polygonTree = new PolygonTreeNode()
+    this.rootnode = new Node(null)
+    if (polygons) this.addPolygons(polygons)
+  }
+
+  invert () {
+    this.polygonTree.invert()
+    this.rootnode.invert()
+  }
+
+  // Remove all polygons in this BSP tree that are inside the other BSP tree
+  // `tree`.
+  clipTo (tree, alsoRemovecoplanarFront = false) {
+    this.rootnode.clipTo(tree, alsoRemovecoplanarFront)
+  }
+
+  allPolygons () {
+    const result = []
+    this.polygonTree.getPolygons(result)
+    return result
+  }
+
+  addPolygons (polygons) {
+    const polygontreenodes = new Array(polygons.length)
+    for (let i = 0; i < polygons.length; i++) {
+      polygontreenodes[i] = this.polygonTree.addChild(polygons[i])
+    }
+    this.rootnode.addPolygonTreeNodes(polygontreenodes)
+  }
+
+  clear () {
+    this.polygonTree.clear()
+  }
+
+  toString () {
+    const result = 'Tree: ' + this.polygonTree.toString('')
+    return result
+  }
+}
+
+module.exports = Tree

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

@@ -0,0 +1,3 @@
+module.exports = {
+  Tree: require('./Tree')
+}

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

@@ -0,0 +1,15 @@
+const vec3 = require('../../../maths/vec3')
+
+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
+
+  vec3.scale(direction, direction, lambda)
+  vec3.add(direction, p1, direction)
+  return direction
+}
+
+module.exports = splitLineSegmentByPlane

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

@@ -0,0 +1,119 @@
+const { EPS } = require('../../../maths/constants')
+
+const plane = require('../../../maths/plane')
+const vec3 = require('../../../maths/vec3')
+
+const poly3 = require('../../../geometries/poly3')
+
+const splitLineSegmentByPlane = require('./splitLineSegmentByPlane')
+
+const EPS_SQUARED = EPS * EPS
+
+// Remove consecutive duplicate vertices from a polygon vertex list.
+// Compares last vertex to first to handle wraparound.
+// Returns a new array (does not modify input).
+const removeConsecutiveDuplicates = (vertices) => {
+  if (vertices.length < 3) return vertices
+  const result = []
+  let prevvertex = vertices[vertices.length - 1]
+  for (let i = 0; i < vertices.length; i++) {
+    const vertex = vertices[i]
+    if (vec3.squaredDistance(vertex, prevvertex) >= EPS_SQUARED) {
+      result.push(vertex)
+    }
+    prevvertex = vertex
+  }
+  return result
+}
+
+// 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
+const splitPolygonByPlane = (splane, polygon) => {
+  const result = {
+    type: null,
+    front: null,
+    back: null
+  }
+  // cache in local lets (speedup):
+  const vertices = polygon.vertices
+  const numvertices = vertices.length
+  const pplane = poly3.plane(polygon)
+  if (plane.equals(pplane, splane)) {
+    result.type = 0
+  } else {
+    let hasfront = false
+    let hasback = false
+    const vertexIsBack = []
+    const MINEPS = -EPS
+    for (let i = 0; i < numvertices; i++) {
+      const t = vec3.dot(splane, vertices[i]) - splane[3]
+      const isback = (t < MINEPS)
+      vertexIsBack.push(isback)
+      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) {
+      result.type = 2
+    } else if (!hasfront) {
+      result.type = 3
+    } else {
+      // spanning
+      result.type = 4
+      const frontvertices = []
+      const backvertices = []
+      let isback = vertexIsBack[0]
+      for (let vertexindex = 0; vertexindex < numvertices; vertexindex++) {
+        const vertex = vertices[vertexindex]
+        let nextvertexindex = vertexindex + 1
+        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)
+          }
+        } else {
+          // line segment intersects plane:
+          const nextpoint = vertices[nextvertexindex]
+          const intersectionpoint = splitLineSegmentByPlane(splane, vertex, nextpoint)
+          if (isback) {
+            backvertices.push(vertex)
+            backvertices.push(intersectionpoint)
+            frontvertices.push(intersectionpoint)
+          } else {
+            frontvertices.push(vertex)
+            frontvertices.push(intersectionpoint)
+            backvertices.push(intersectionpoint)
+          }
+        }
+        isback = nextisback
+      } // for vertexindex
+      // remove consecutive duplicate vertices
+      const backFiltered = removeConsecutiveDuplicates(backvertices)
+      const frontFiltered = removeConsecutiveDuplicates(frontvertices)
+      if (frontFiltered.length >= 3) {
+        result.front = poly3.fromPointsAndPlane(frontFiltered, pplane)
+      }
+      if (backFiltered.length >= 3) {
+        result.back = poly3.fromPointsAndPlane(backFiltered, pplane)
+      }
+    }
+  }
+  return result
+}
+
+module.exports = splitPolygonByPlane

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

@@ -0,0 +1,132 @@
+const test = require('ava')
+
+const { poly3 } = require('../../../geometries')
+const plane = require('../../../maths/plane')
+
+const splitPolygonByPlane = require('./splitPolygonByPlane')
+
+test('splitPolygonByPlane: test coplanar-front polygon returns type 0.', (t) => {
+  // Polygon in XY plane at z=0
+  const polygon = poly3.create([[0, 0, 0], [1, 0, 0], [1, 1, 0], [0, 1, 0]])
+  // Plane is also XY plane at z=0, normal pointing up
+  const splane = plane.fromPoints(plane.create(), [0, 0, 0], [1, 0, 0], [1, 1, 0])
+
+  const result = splitPolygonByPlane(splane, polygon)
+  t.is(result.type, 0) // coplanar-front
+  t.is(result.front, null)
+  t.is(result.back, null)
+})
+
+test('splitPolygonByPlane: test polygon entirely in front returns type 2.', (t) => {
+  // Polygon at z=5
+  const polygon = poly3.create([[0, 0, 5], [1, 0, 5], [1, 1, 5], [0, 1, 5]])
+  // Plane at z=0
+  const splane = [0, 0, 1, 0] // normal (0,0,1), w=0
+
+  const result = splitPolygonByPlane(splane, polygon)
+  t.is(result.type, 2) // front
+  t.is(result.front, null)
+  t.is(result.back, null)
+})
+
+test('splitPolygonByPlane: test polygon entirely in back returns type 3.', (t) => {
+  // Polygon at z=-5
+  const polygon = poly3.create([[0, 0, -5], [1, 0, -5], [1, 1, -5], [0, 1, -5]])
+  // Plane at z=0
+  const splane = [0, 0, 1, 0] // normal (0,0,1), w=0
+
+  const result = splitPolygonByPlane(splane, polygon)
+  t.is(result.type, 3) // back
+  t.is(result.front, null)
+  t.is(result.back, null)
+})
+
+test('splitPolygonByPlane: test spanning polygon returns type 4 with front and back.', (t) => {
+  // Polygon spanning z=0 plane (from z=-1 to z=1)
+  const polygon = poly3.create([[0, 0, -1], [1, 0, -1], [1, 0, 1], [0, 0, 1]])
+  // Plane at z=0
+  const splane = [0, 0, 1, 0] // normal (0,0,1), w=0
+
+  const result = splitPolygonByPlane(splane, polygon)
+  t.is(result.type, 4) // spanning
+  t.not(result.front, null)
+  t.not(result.back, null)
+
+  // Front polygon should have z >= 0
+  const frontPoints = poly3.toPoints(result.front)
+  t.true(frontPoints.length >= 3)
+  frontPoints.forEach((p) => {
+    t.true(p[2] >= -1e-5, `front point z=${p[2]} should be >= 0`)
+  })
+
+  // Back polygon should have z <= 0
+  const backPoints = poly3.toPoints(result.back)
+  t.true(backPoints.length >= 3)
+  backPoints.forEach((p) => {
+    t.true(p[2] <= 1e-5, `back point z=${p[2]} should be <= 0`)
+  })
+})
+
+test('splitPolygonByPlane: test duplicate vertices are removed from split result.', (t) => {
+  // Create a polygon that when split would produce duplicate vertices
+  // Triangle with one vertex on the plane
+  const polygon = poly3.create([[0, 0, 0], [1, 0, 1], [1, 0, -1]])
+  // Plane at z=0
+  const splane = [0, 0, 1, 0]
+
+  const result = splitPolygonByPlane(splane, polygon)
+  t.is(result.type, 4) // spanning
+
+  // Verify no consecutive duplicate vertices in front
+  if (result.front) {
+    const frontPoints = poly3.toPoints(result.front)
+    for (let i = 0; i < frontPoints.length; i++) {
+      const curr = frontPoints[i]
+      const next = frontPoints[(i + 1) % frontPoints.length]
+      const dx = curr[0] - next[0]
+      const dy = curr[1] - next[1]
+      const dz = curr[2] - next[2]
+      const distSq = dx * dx + dy * dy + dz * dz
+      t.true(distSq > 1e-10, 'front polygon should not have duplicate consecutive vertices')
+    }
+  }
+
+  // Verify no consecutive duplicate vertices in back
+  if (result.back) {
+    const backPoints = poly3.toPoints(result.back)
+    for (let i = 0; i < backPoints.length; i++) {
+      const curr = backPoints[i]
+      const next = backPoints[(i + 1) % backPoints.length]
+      const dx = curr[0] - next[0]
+      const dy = curr[1] - next[1]
+      const dz = curr[2] - next[2]
+      const distSq = dx * dx + dy * dy + dz * dz
+      t.true(distSq > 1e-10, 'back polygon should not have duplicate consecutive vertices')
+    }
+  }
+})
+
+test('splitPolygonByPlane: test complex spanning polygon splits correctly.', (t) => {
+  // Hexagon spanning the XY plane
+  const polygon = poly3.create([
+    [1, 0, -1],
+    [0.5, 0.866, -1],
+    [-0.5, 0.866, 1],
+    [-1, 0, 1],
+    [-0.5, -0.866, 1],
+    [0.5, -0.866, -1]
+  ])
+  // Plane at z=0
+  const splane = [0, 0, 1, 0]
+
+  const result = splitPolygonByPlane(splane, polygon)
+  t.is(result.type, 4) // spanning
+  t.not(result.front, null)
+  t.not(result.back, null)
+
+  // Both resulting polygons should be valid (at least 3 vertices)
+  const frontPoints = poly3.toPoints(result.front)
+  const backPoints = poly3.toPoints(result.back)
+  t.true(frontPoints.length >= 3, 'front polygon should have at least 3 vertices')
+  t.true(backPoints.length >= 3, 'back polygon should have at least 3 vertices')
+})

package/src/operations/booleans/union.d.ts

@@ -0,0 +1,7 @@
+import { Geom2, Geom3 } from '../../geometries/types'
+import RecursiveArray from '../../utils/recursiveArray'
+
+export default union
+
+declare function union(...geometries: RecursiveArray<Geom2>): Geom2
+declare function union(...geometries: RecursiveArray<Geom3>): Geom3

package/src/operations/booleans/union.js

@@ -0,0 +1,46 @@
+const flatten = require('../../utils/flatten')
+const areAllShapesTheSameType = require('../../utils/areAllShapesTheSameType')
+
+const geom2 = require('../../geometries/geom2')
+const geom3 = require('../../geometries/geom3')
+
+const unionGeom2 = require('./unionGeom2')
+const unionGeom3 = require('./unionGeom3')
+
+/**
+ * Return a new geometry representing the total space in the given geometries.
+ * 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
+ * @alias module:modeling/booleans.union
+ *
+ * @example
+ * let myshape = union(cube({size: 5}), cube({size: 5, center: [3,3,3]}))
+ *
+ * @example
+ * +-------+            +-------+
+ * |       |            |       |
+ * |   A   |            |       |
+ * |    +--+----+   =   |       +----+
+ * +----+--+    |       +----+       |
+ *      |   B   |            |       |
+ *      |       |            |       |
+ *      +-------+            +-------+
+ */
+const union = (...geometries) => {
+  geometries = flatten(geometries)
+  if (geometries.length === 0) throw new Error('wrong number of arguments')
+
+  if (!areAllShapesTheSameType(geometries)) {
+    throw new Error('only unions of the same type are supported')
+  }
+
+  const geometry = geometries[0]
+  // if (path.isA(geometry)) return pathunion(matrix, geometries)
+  if (geom2.isA(geometry)) return unionGeom2(geometries)
+  if (geom3.isA(geometry)) return unionGeom3(geometries)
+  return geometry
+}
+
+module.exports = union