@jbroll/jscad-modeling 2.12.7 → 2.13.0

package/src/operations/minkowski/minkowskiSum.js

@@ -0,0 +1,223 @@
+const flatten = require('../../utils/flatten')
+
+const geom3 = require('../../geometries/geom3')
+const poly3 = require('../../geometries/poly3')
+
+const hullPoints3 = require('../hulls/hullPoints3')
+const union = require('../booleans/union')
+
+const isConvex = require('./isConvex')
+
+/**
+ * Compute the Minkowski sum of two 3D geometries.
+ *
+ * The Minkowski sum A ⊕ B is the set of all points a + b where a ∈ A and b ∈ B.
+ * Geometrically, this "inflates" geometry A by the shape of geometry B.
+ *
+ * Common use cases:
+ * - Offset a solid by a sphere to round all edges and corners
+ * - Offset a solid by a cube to create chamfered edges
+ * - Collision detection (if Minkowski sum contains origin, shapes overlap)
+ *
+ * For best performance, use convex geometries. Non-convex geometries are supported
+ * when the second operand is convex, but require decomposition and are slower.
+ *
+ * @param {...Object} geometries - two geom3 geometries (second should be convex for non-convex first)
+ * @returns {geom3} new 3D geometry representing the Minkowski sum
+ * @alias module:modeling/operations/minkowski.minkowskiSum
+ *
+ * @example
+ * const { primitives, minkowski } = require('@jscad/modeling')
+ * const cube = primitives.cuboid({ size: [10, 10, 10] })
+ * const sphere = primitives.sphere({ radius: 2, segments: 16 })
+ * const rounded = minkowski.minkowskiSum(cube, sphere)
+ */
+const minkowskiSum = (...geometries) => {
+  geometries = flatten(geometries)
+
+  if (geometries.length < 2) {
+    throw new Error('minkowskiSum requires at least two geometries')
+  }
+
+  if (geometries.length > 2) {
+    throw new Error('minkowskiSum currently supports exactly two geometries')
+  }
+
+  const [geomA, geomB] = geometries
+
+  if (!geom3.isA(geomA) || !geom3.isA(geomB)) {
+    throw new Error('minkowskiSum requires geom3 geometries')
+  }
+
+  const aConvex = isConvex(geomA)
+  const bConvex = isConvex(geomB)
+
+  // Fast path: both convex
+  if (aConvex && bConvex) {
+    return minkowskiSumConvex(geomA, geomB)
+  }
+
+  // Non-convex A + convex B: decompose A into tetrahedra
+  if (!aConvex && bConvex) {
+    return minkowskiSumNonConvexConvex(geomA, geomB)
+  }
+
+  // Convex A + non-convex B: swap operands (Minkowski sum is commutative)
+  if (aConvex && !bConvex) {
+    return minkowskiSumNonConvexConvex(geomB, geomA)
+  }
+
+  // Both non-convex: not yet supported
+  throw new Error('minkowskiSum of two non-convex geometries is not yet supported')
+}
+
+/**
+ * Compute Minkowski sum of non-convex A with convex B.
+ *
+ * Decomposes A into tetrahedra, computes Minkowski sum of each with B,
+ * then unions all results.
+ */
+const minkowskiSumNonConvexConvex = (geomA, geomB) => {
+  const tetrahedra = decomposeIntoTetrahedra(geomA)
+
+  if (tetrahedra.length === 0) {
+    return geom3.create()
+  }
+
+  // Compute Minkowski sum for each tetrahedron
+  const parts = tetrahedra.map((tet) => minkowskiSumConvex(tet, geomB))
+
+  // Union all parts
+  if (parts.length === 1) {
+    return parts[0]
+  }
+
+  return union(parts)
+}
+
+/**
+ * Decompose a geom3 into tetrahedra using fan triangulation from centroid.
+ * Each resulting tetrahedron is guaranteed to be convex.
+ */
+const decomposeIntoTetrahedra = (geometry) => {
+  const polygons = geom3.toPolygons(geometry)
+
+  if (polygons.length === 0) {
+    return []
+  }
+
+  // Compute centroid of the geometry
+  const centroid = computeCentroid(geometry)
+
+  const tetrahedra = []
+
+  // For each polygon, create tetrahedra from centroid to each triangle
+  for (let i = 0; i < polygons.length; i++) {
+    const vertices = polygons[i].vertices
+
+    // Fan triangulate the polygon and create tetrahedra
+    for (let j = 1; j < vertices.length - 1; j++) {
+      const v0 = vertices[0]
+      const v1 = vertices[j]
+      const v2 = vertices[j + 1]
+
+      // Create tetrahedron from centroid and triangle
+      const tetPolygons = createTetrahedronPolygons(centroid, v0, v1, v2)
+      tetrahedra.push(geom3.create(tetPolygons))
+    }
+  }
+
+  return tetrahedra
+}
+
+/**
+ * Create the 4 triangular faces of a tetrahedron.
+ */
+const createTetrahedronPolygons = (p0, p1, p2, p3) => {
+  // Tetrahedron has 4 faces, each a triangle
+  // We need to ensure consistent winding (outward-facing normals)
+  return [
+    poly3.create([p0, p2, p1]), // base seen from p3
+    poly3.create([p0, p1, p3]), // face opposite p2
+    poly3.create([p1, p2, p3]), // face opposite p0
+    poly3.create([p2, p0, p3])  // face opposite p1
+  ]
+}
+
+/**
+ * Compute the centroid of a geom3.
+ */
+const computeCentroid = (geometry) => {
+  const vertices = extractUniqueVertices(geometry)
+
+  if (vertices.length === 0) {
+    return [0, 0, 0]
+  }
+
+  let x = 0, y = 0, z = 0
+  for (let i = 0; i < vertices.length; i++) {
+    x += vertices[i][0]
+    y += vertices[i][1]
+    z += vertices[i][2]
+  }
+
+  const n = vertices.length
+  return [x / n, y / n, z / n]
+}
+
+/**
+ * Compute Minkowski sum of two convex polyhedra.
+ *
+ * For convex polyhedra, the Minkowski sum equals the convex hull of
+ * all pairwise vertex sums. This is O(n*m) for n and m vertices,
+ * plus the cost of the convex hull algorithm.
+ */
+const minkowskiSumConvex = (geomA, geomB) => {
+  const pointsA = extractUniqueVertices(geomA)
+  const pointsB = extractUniqueVertices(geomB)
+
+  if (pointsA.length === 0 || pointsB.length === 0) {
+    return geom3.create()
+  }
+
+  // Compute all pairwise sums
+  const summedPoints = []
+  for (let i = 0; i < pointsA.length; i++) {
+    const a = pointsA[i]
+    for (let j = 0; j < pointsB.length; j++) {
+      const b = pointsB[j]
+      summedPoints.push([a[0] + b[0], a[1] + b[1], a[2] + b[2]])
+    }
+  }
+
+  // Compute convex hull of the summed points
+  const hullPolygons = hullPoints3(summedPoints)
+
+  return geom3.create(hullPolygons)
+}
+
+/**
+ * Extract unique vertices from a geom3.
+ * Uses a Set with string keys for deduplication.
+ */
+const extractUniqueVertices = (geometry) => {
+  const found = new Set()
+  const unique = []
+
+  const polygons = geom3.toPolygons(geometry)
+  for (let i = 0; i < polygons.length; i++) {
+    const vertices = polygons[i].vertices
+    for (let j = 0; j < vertices.length; j++) {
+      const v = vertices[j]
+      const key = `${v[0]},${v[1]},${v[2]}`
+      if (!found.has(key)) {
+        found.add(key)
+        unique.push(v)
+      }
+    }
+  }
+
+  return unique
+}
+
+module.exports = minkowskiSum

package/src/operations/minkowski/minkowskiSum.test.js

@@ -0,0 +1,161 @@
+const test = require('ava')
+
+const { geom3 } = require('../../geometries')
+const { cuboid, sphere } = require('../../primitives')
+const { measureBoundingBox } = require('../../measurements')
+const { subtract } = require('../booleans')
+
+const minkowskiSum = require('./minkowskiSum')
+const isConvex = require('./isConvex')
+
+test('minkowskiSum: throws for non-geom3 inputs', (t) => {
+  t.throws(() => minkowskiSum('invalid', cuboid()), { message: /requires geom3/ })
+  t.throws(() => minkowskiSum(cuboid(), 'invalid'), { message: /requires geom3/ })
+})
+
+test('minkowskiSum: throws for less than two geometries', (t) => {
+  t.throws(() => minkowskiSum(), { message: /requires at least two/ })
+  t.throws(() => minkowskiSum(cuboid()), { message: /requires at least two/ })
+})
+
+test('minkowskiSum: throws for more than two geometries', (t) => {
+  t.throws(() => minkowskiSum(cuboid(), cuboid(), cuboid()), { message: /exactly two/ })
+})
+
+test('minkowskiSum: cube + cube produces correct bounds', (t) => {
+  // Cube1: size 10 (±5 from origin)
+  // Cube2: size 4 (±2 from origin)
+  // Minkowski sum should be size 14 (±7 from origin)
+  const cube1 = cuboid({ size: [10, 10, 10] })
+  const cube2 = cuboid({ size: [4, 4, 4] })
+
+  const result = minkowskiSum(cube1, cube2)
+
+  t.true(geom3.isA(result))
+
+  const bounds = measureBoundingBox(result)
+  // Allow small tolerance for floating point
+  t.true(Math.abs(bounds[0][0] - (-7)) < 0.001)
+  t.true(Math.abs(bounds[0][1] - (-7)) < 0.001)
+  t.true(Math.abs(bounds[0][2] - (-7)) < 0.001)
+  t.true(Math.abs(bounds[1][0] - 7) < 0.001)
+  t.true(Math.abs(bounds[1][1] - 7) < 0.001)
+  t.true(Math.abs(bounds[1][2] - 7) < 0.001)
+})
+
+test('minkowskiSum: cube + sphere produces correct bounds', (t) => {
+  // Cube: size 10 (±5 from origin)
+  // Sphere: radius 2
+  // Minkowski sum should be ±7 from origin
+  const cube = cuboid({ size: [10, 10, 10] })
+  const sph = sphere({ radius: 2, segments: 16 })
+
+  const result = minkowskiSum(cube, sph)
+
+  t.true(geom3.isA(result))
+
+  const bounds = measureBoundingBox(result)
+  // Allow small tolerance
+  t.true(Math.abs(bounds[0][0] - (-7)) < 0.1)
+  t.true(Math.abs(bounds[1][0] - 7) < 0.1)
+})
+
+test('minkowskiSum: sphere + sphere produces correct bounds', (t) => {
+  // Sphere1: radius 3
+  // Sphere2: radius 2
+  // Minkowski sum should be a sphere-like shape with radius ~5
+  const sph1 = sphere({ radius: 3, segments: 16 })
+  const sph2 = sphere({ radius: 2, segments: 16 })
+
+  const result = minkowskiSum(sph1, sph2)
+
+  t.true(geom3.isA(result))
+
+  const bounds = measureBoundingBox(result)
+  // Should be approximately ±5
+  t.true(Math.abs(bounds[0][0] - (-5)) < 0.2)
+  t.true(Math.abs(bounds[1][0] - 5) < 0.2)
+})
+
+test('minkowskiSum: empty geometry returns empty', (t) => {
+  const empty = geom3.create()
+  const cube = cuboid({ size: [10, 10, 10] })
+
+  const result = minkowskiSum(empty, cube)
+
+  t.true(geom3.isA(result))
+  t.is(geom3.toPolygons(result).length, 0)
+})
+
+test('minkowskiSum: result is convex', (t) => {
+  const cube = cuboid({ size: [10, 10, 10] })
+  const sph = sphere({ radius: 2, segments: 12 })
+
+  const result = minkowskiSum(cube, sph)
+
+  t.true(isConvex(result))
+})
+
+// Non-convex tests
+
+test('minkowskiSum: non-convex + convex produces valid geometry', (t) => {
+  // Create L-shaped non-convex geometry
+  const big = cuboid({ size: [10, 10, 10] })
+  const corner = cuboid({ size: [6, 6, 12], center: [3, 3, 0] })
+  const lShape = subtract(big, corner)
+
+  t.false(isConvex(lShape))
+
+  const sph = sphere({ radius: 1, segments: 8 })
+
+  const result = minkowskiSum(lShape, sph)
+
+  t.true(geom3.isA(result))
+  t.true(geom3.toPolygons(result).length > 0)
+})
+
+test('minkowskiSum: non-convex + convex produces correct bounds', (t) => {
+  // Cube with hole through it
+  const cube = cuboid({ size: [10, 10, 10] })
+  const hole = cuboid({ size: [4, 4, 20] })
+  const cubeWithHole = subtract(cube, hole)
+
+  t.false(isConvex(cubeWithHole))
+
+  // Offset by sphere of radius 1
+  const sph = sphere({ radius: 1, segments: 8 })
+  const result = minkowskiSum(cubeWithHole, sph)
+
+  const bounds = measureBoundingBox(result)
+
+  // Original cube is ±5, plus sphere radius 1 = ±6
+  t.true(Math.abs(bounds[0][0] - (-6)) < 0.2)
+  t.true(Math.abs(bounds[1][0] - 6) < 0.2)
+})
+
+test('minkowskiSum: convex + non-convex swaps operands', (t) => {
+  // Minkowski sum is commutative, so A⊕B = B⊕A
+  const cube = cuboid({ size: [10, 10, 10] })
+  const hole = cuboid({ size: [4, 4, 20] })
+  const cubeWithHole = subtract(cube, hole)
+
+  const sph = sphere({ radius: 1, segments: 8 })
+
+  // convex + non-convex should work (swaps internally)
+  const result = minkowskiSum(sph, cubeWithHole)
+
+  t.true(geom3.isA(result))
+  t.true(geom3.toPolygons(result).length > 0)
+})
+
+test('minkowskiSum: throws for two non-convex geometries', (t) => {
+  const cube1 = cuboid({ size: [10, 10, 10] })
+  const hole1 = cuboid({ size: [4, 4, 20] })
+  const nonConvex1 = subtract(cube1, hole1)
+
+  const cube2 = cuboid({ size: [8, 8, 8] })
+  const hole2 = cuboid({ size: [3, 3, 16] })
+  const nonConvex2 = subtract(cube2, hole2)
+
+  t.throws(() => minkowskiSum(nonConvex1, nonConvex2), { message: /two non-convex/ })
+})

package/src/operations/modifiers/reTesselateCoplanarPolygons.js

@@ -40,7 +40,7 @@ const reTesselateCoplanarPolygons = (sourcepolygons) => {
       let miny
       let maxy
       for (let i = 0; i < numvertices; i++) {
-        let pos2d = orthobasis.to2D(poly3d.vertices[i])
+        const pos2d = orthobasis.to2D(poly3d.vertices[i])
         // perform binning of y coordinates: If we have multiple vertices very
         // close to each other, give them the same y coordinate:
         const ycoordinatebin = Math.floor(pos2d[1] * ycoordinateBinningFactor)
@@ -55,7 +55,8 @@ const reTesselateCoplanarPolygons = (sourcepolygons) => {
           newy = pos2d[1]
           ycoordinatebins.set(ycoordinatebin, pos2d[1])
         }
-        pos2d = vec2.fromValues(pos2d[0], newy)
+        // Modify y in place instead of creating new vec2
+        pos2d[1] = newy
         vertices2d.push(pos2d)
         const y = pos2d[1]
         if ((i === 0) || (y < miny)) {
@@ -120,6 +121,7 @@ const reTesselateCoplanarPolygons = (sourcepolygons) => {
     //   at the the left and right side of the polygon
     // Iterate over all polygons that have a corner at this y coordinate:
     const polygonindexeswithcorner = ycoordinatetopolygonindexes.get(ycoordinate)
+    let removeCount = 0 // track removals to filter at end (avoids O(n²) splice)
     for (let activepolygonindex = 0; activepolygonindex < activepolygons.length; ++activepolygonindex) {
       const activepolygon = activepolygons[activepolygonindex]
       const polygonindex = activepolygon.polygonindex
@@ -143,9 +145,9 @@ const reTesselateCoplanarPolygons = (sourcepolygons) => {
         }
         if ((newleftvertexindex !== activepolygon.leftvertexindex) && (newleftvertexindex === newrightvertexindex)) {
           // We have increased leftvertexindex or decreased rightvertexindex, and now they point to the same vertex
-          // This means that this is the bottom point of the polygon. We'll remove it:
-          activepolygons.splice(activepolygonindex, 1)
-          --activepolygonindex
+          // This means that this is the bottom point of the polygon. Mark it for removal:
+          activepolygon._remove = true
+          removeCount++
         } else {
           activepolygon.leftvertexindex = newleftvertexindex
           activepolygon.rightvertexindex = newrightvertexindex
@@ -160,6 +162,10 @@ const reTesselateCoplanarPolygons = (sourcepolygons) => {
         }
       } // if polygon has corner here
     } // for activepolygonindex
+    // Filter out marked polygons in single pass (O(n) instead of O(n²) splice)
+    if (removeCount > 0) {
+      activepolygons = activepolygons.filter((p) => !p._remove)
+    }
     let nextycoordinate
     if (yindex >= ycoordinates.length - 1) {
       // last row, all polygons must be finished here:
@@ -221,14 +227,11 @@ const reTesselateCoplanarPolygons = (sourcepolygons) => {
     for (const activepolygonKey in activepolygons) {
       const activepolygon = activepolygons[activepolygonKey]
 
-      let x = interpolateBetween2DPointsForY(activepolygon.topleft, activepolygon.bottomleft, ycoordinate)
-      const topleft = vec2.fromValues(x, ycoordinate)
-      x = interpolateBetween2DPointsForY(activepolygon.topright, activepolygon.bottomright, ycoordinate)
-      const topright = vec2.fromValues(x, ycoordinate)
-      x = interpolateBetween2DPointsForY(activepolygon.topleft, activepolygon.bottomleft, nextycoordinate)
-      const bottomleft = vec2.fromValues(x, nextycoordinate)
-      x = interpolateBetween2DPointsForY(activepolygon.topright, activepolygon.bottomright, nextycoordinate)
-      const bottomright = vec2.fromValues(x, nextycoordinate)
+      // Inline vec2 creation to avoid function call overhead
+      const topleft = [interpolateBetween2DPointsForY(activepolygon.topleft, activepolygon.bottomleft, ycoordinate), ycoordinate]
+      const topright = [interpolateBetween2DPointsForY(activepolygon.topright, activepolygon.bottomright, ycoordinate), ycoordinate]
+      const bottomleft = [interpolateBetween2DPointsForY(activepolygon.topleft, activepolygon.bottomleft, nextycoordinate), nextycoordinate]
+      const bottomright = [interpolateBetween2DPointsForY(activepolygon.topright, activepolygon.bottomright, nextycoordinate), nextycoordinate]
       const outpolygon = {
         topleft: topleft,
         topright: topright,

package/src/operations/modifiers/reTesselateCoplanarPolygons.test.js

@@ -16,7 +16,7 @@ const rotatePoly3 = (angles, polygon) => {
   return poly3.transform(matrix, polygon)
 }
 
-test.only('retessellateCoplanarPolygons: should merge coplanar polygons', (t) => {
+test('retessellateCoplanarPolygons: should merge coplanar polygons', (t) => {
   const polyA = poly3.create([[-5, -5, 0], [5, -5, 0], [5, 5, 0], [-5, 5, 0]])
   const polyB = poly3.create([[5, -5, 0], [8, 0, 0], [5, 5, 0]])
   const polyC = poly3.create([[-5, 5, 0], [-8, 0, 0], [-5, -5, 0]])
@@ -68,3 +68,38 @@ test.only('retessellateCoplanarPolygons: should merge coplanar polygons', (t) =>
   obs = reTesselateCoplanarPolygons([polyH, polyI, polyJ, polyK, polyL])
   t.is(obs.length, 1)
 })
+
+// Test for mark-and-filter optimization: multiple polygons that reach their
+// bottom point at the same y-coordinate (triggering the removal code path)
+test('retessellateCoplanarPolygons: should correctly handle multiple polygon removals', (t) => {
+  // Create multiple triangular polygons that all end at the same y-coordinate
+  // This exercises the mark-and-filter removal optimization
+  const poly1 = poly3.create([[0, 0, 0], [2, 0, 0], [1, 3, 0]]) // triangle pointing up
+  const poly2 = poly3.create([[3, 0, 0], [5, 0, 0], [4, 3, 0]]) // triangle pointing up
+  const poly3a = poly3.create([[6, 0, 0], [8, 0, 0], [7, 3, 0]]) // triangle pointing up
+
+  // These polygons share the same plane and have vertices at y=0 and y=3
+  // During retessellation, all three will be active and then removed at y=3
+  const obs = reTesselateCoplanarPolygons([poly1, poly2, poly3a])
+
+  // Each triangle should be preserved (they don't overlap)
+  t.is(obs.length, 3)
+
+  // Verify each polygon has 3 vertices (triangles)
+  obs.forEach((polygon) => {
+    t.is(polygon.vertices.length, 3)
+  })
+})
+
+// Test for mark-and-filter with overlapping polygons that get merged
+test('retessellateCoplanarPolygons: should merge adjacent polygons with shared edges', (t) => {
+  // Two adjacent squares sharing an edge at x=5
+  const poly1 = poly3.create([[0, 0, 0], [5, 0, 0], [5, 5, 0], [0, 5, 0]])
+  const poly2 = poly3.create([[5, 0, 0], [10, 0, 0], [10, 5, 0], [5, 5, 0]])
+
+  const obs = reTesselateCoplanarPolygons([poly1, poly2])
+
+  // Should merge into a single rectangle
+  t.is(obs.length, 1)
+  t.is(obs[0].vertices.length, 4) // rectangle has 4 vertices
+})

package/src/operations/modifiers/retessellate.js

@@ -22,8 +22,11 @@ const retessellate = (geometry) => {
   const destPolygons = []
   classified.forEach((group) => {
     if (Array.isArray(group)) {
-      const reTessellateCoplanarPolygons = reTesselateCoplanarPolygons(group)
-      destPolygons.push(...reTessellateCoplanarPolygons)
+      const coplanarPolygons = reTesselateCoplanarPolygons(group)
+      // Use loop instead of spread to avoid stack overflow with large arrays
+      for (let i = 0; i < coplanarPolygons.length; i++) {
+        destPolygons.push(coplanarPolygons[i])
+      }
     } else {
       destPolygons.push(group)
     }