@jscad/modeling 2.12.7 → 2.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jscad/modeling",
-  "version": "2.12.7",
+  "version": "2.13.0",
   "description": "Constructive Solid Geometry (CSG) Library for JSCAD",
   "homepage": "https://openjscad.xyz/",
   "repository": "https://github.com/jscad/OpenJSCAD.org",
@@ -61,5 +61,5 @@
     "nyc": "15.1.0",
     "uglifyify": "5.0.2"
   },
-  "gitHead": "138ee568542545f27629166bd93fff653cc3c26d"
+  "gitHead": "602bb2a3a2c2c7c21315e2801804dd1ec0cbd3f8"
 }

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

@@ -5,6 +5,7 @@ export { default as fromPoints } from './fromPoints'
 export { default as fromCompactBinary } from './fromCompactBinary'
 export { default as invert } from './invert'
 export { default as isA } from './isA'
+export { isConvex } from './isConvex'
 export { default as toPoints } from './toPoints'
 export { default as toPolygons } from './toPolygons'
 export { default as toString } from './toString'

package/src/geometries/geom3/index.js

@@ -28,6 +28,7 @@ module.exports = {
   fromCompactBinary: require('./fromCompactBinary'),
   invert: require('./invert'),
   isA: require('./isA'),
+  isConvex: require('./isConvex'),
   toPoints: require('./toPoints'),
   toPolygons: require('./toPolygons'),
   toString: require('./toString'),

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

@@ -0,0 +1,3 @@
+import type Geom3 from './type'
+
+export function isConvex(geometry: Geom3): boolean

package/src/geometries/geom3/isConvex.js

@@ -0,0 +1,68 @@
+const { EPS } = require('../../maths/constants')
+const vec3 = require('../../maths/vec3')
+
+const geom3 = require('./isA')
+const toPolygons = require('./toPolygons')
+const poly3 = require('../poly3')
+
+/**
+ * Test if a 3D geometry is convex.
+ *
+ * A polyhedron is convex if every vertex lies on or behind every face plane
+ * (i.e., on the interior side of the plane).
+ *
+ * @param {geom3} geometry - the geometry to test
+ * @returns {boolean} true if the geometry is convex
+ * @alias module:modeling/geometries/geom3.isConvex
+ *
+ * @example
+ * const { geom3, primitives } = require('@jscad/modeling')
+ * const cube = primitives.cuboid({ size: [10, 10, 10] })
+ * console.log(geom3.isConvex(cube)) // true
+ */
+const isConvex = (geometry) => {
+  if (!geom3(geometry)) {
+    throw new Error('isConvex requires a geom3 geometry')
+  }
+
+  const polygons = toPolygons(geometry)
+
+  if (polygons.length === 0) {
+    return true // Empty geometry is trivially convex
+  }
+
+  // Collect all unique vertices
+  const vertices = []
+  const found = new Set()
+  for (let i = 0; i < polygons.length; i++) {
+    const verts = polygons[i].vertices
+    for (let j = 0; j < verts.length; j++) {
+      const v = verts[j]
+      const key = `${v[0]},${v[1]},${v[2]}`
+      if (!found.has(key)) {
+        found.add(key)
+        vertices.push(v)
+      }
+    }
+  }
+
+  // For each face plane, check that all vertices are on or behind it
+  for (let i = 0; i < polygons.length; i++) {
+    const plane = poly3.plane(polygons[i])
+
+    for (let j = 0; j < vertices.length; j++) {
+      const v = vertices[j]
+      // Distance from point to plane: dot(normal, point) - w
+      const distance = vec3.dot(plane, v) - plane[3]
+
+      // If any vertex is in front of any face (positive distance), not convex
+      if (distance > EPS) {
+        return false
+      }
+    }
+  }
+
+  return true
+}
+
+module.exports = isConvex

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

@@ -0,0 +1,45 @@
+const test = require('ava')
+
+const { geometries, primitives, booleans } = require('../../index')
+const { geom3 } = geometries
+
+test('isConvex: throws for non-geom3 input', (t) => {
+  t.throws(() => geom3.isConvex('invalid'), { message: /requires a geom3/ })
+  t.throws(() => geom3.isConvex(null), { message: /requires a geom3/ })
+})
+
+test('isConvex: empty geometry is convex', (t) => {
+  const empty = geom3.create()
+  t.true(geom3.isConvex(empty))
+})
+
+test('isConvex: cuboid is convex', (t) => {
+  const cube = primitives.cuboid({ size: [10, 10, 10] })
+  t.true(geom3.isConvex(cube))
+})
+
+test('isConvex: sphere is convex', (t) => {
+  const sph = primitives.sphere({ radius: 5, segments: 16 })
+  t.true(geom3.isConvex(sph))
+})
+
+test('isConvex: cylinder is convex', (t) => {
+  const cyl = primitives.cylinderElliptic({ height: 10, startRadius: [3, 3], endRadius: [3, 3], segments: 16 })
+  t.true(geom3.isConvex(cyl))
+})
+
+test('isConvex: cube with hole is not convex', (t) => {
+  const cube = primitives.cuboid({ size: [10, 10, 10] })
+  const hole = primitives.cuboid({ size: [4, 4, 20] }) // Hole through the cube
+
+  const withHole = booleans.subtract(cube, hole)
+  t.false(geom3.isConvex(withHole))
+})
+
+test('isConvex: L-shaped solid is not convex', (t) => {
+  const big = primitives.cuboid({ size: [10, 10, 10], center: [0, 0, 0] })
+  const corner = primitives.cuboid({ size: [6, 6, 12], center: [3, 3, 0] })
+
+  const lShape = booleans.subtract(big, corner)
+  t.false(geom3.isConvex(lShape))
+})

package/src/geometries/path2/appendArc.js

@@ -120,7 +120,7 @@ const appendArc = (options, geometry) => {
     }
 
     // Ok, we have the center point and angle range (from theta1, deltatheta radians) so we can create the ellipse
-    let numsteps = Math.ceil(Math.abs(deltatheta) / TAU * segments) + 1
+    let numsteps = Math.floor(segments * (Math.abs(deltatheta) / TAU))
     if (numsteps < 1) numsteps = 1
     for (let step = 1; step < numsteps; step++) {
       const theta = theta1 + step / numsteps * deltatheta

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

@@ -22,47 +22,43 @@ test('appendArc: appending to a path produces a new path', (t) => {
   const p2 = fromPoints({}, [[27, -22], [27, -3]])
   obs = appendArc({ endpoint: [12, -22], radius: [15, -20] }, p2)
   pts = toPoints(obs)
-  t.is(pts.length, 7)
+  t.is(pts.length, 5)
 
   // test segments
   obs = appendArc({ endpoint: [12, -22], radius: [15, -20], segments: 64 }, p2)
   pts = toPoints(obs)
-  t.is(pts.length, 19)
+  t.is(pts.length, 17)
 
   // test clockwise
   obs = appendArc({ endpoint: [12, -22], radius: [15, -20], clockwise: true }, p2)
   pts = toPoints(obs)
   let exp = [
-    [27, -22],
-    [27, -3],
-    [26.086451657912605, -8.941047736250177],
-    [23.87938869625451, -14.243872270248309],
-    [20.58174906029909, -18.420882475791835],
-    [16.49674848226545, -21.0880050920699],
-    [11.999999999999998, -22]
+  [ 27, -22 ],
+  [ 27, -3 ],
+  [ 24.7485593841743, -12.579008396887021 ],
+  [ 19.29019838402471, -19.492932330409836 ],
+  [ 12, -22 ]
   ]
-  t.is(pts.length, 7)
+  t.is(pts.length, 5)
   t.true(comparePoints(pts, exp))
 
   // test large
   obs = appendArc({ endpoint: [12, -22], radius: [15, -20], large: true }, p2)
   pts = toPoints(obs)
-  t.is(pts.length, 16)
+  t.is(pts.length, 14)
 
   // test xaxisrotation
   obs = appendArc({ endpoint: [12, -22], radius: [15, -20], xaxisrotation: TAU / 4 }, p2)
   pts = toPoints(obs)
   exp = [
-    [27, -22],
-    [27, -3],
-    [21.830323320631795, -4.401628923214028],
-    [17.364704977487236, -6.805886946199115],
-    [13.940501387124588, -10.031143708098092],
-    [11.816394990371812, -13.833746263211978],
-    [11.15285201325494, -17.926425912558045],
-    [12, -22.000000000000004]
+  [ 27, -22 ],
+  [ 27, -3 ],
+  [ 19.486852090983938, -5.488140907400943 ],
+  [ 13.940501387124588, -10.031143708098092 ],
+  [ 11.296247566821858, -15.862906638006239 ],
+  [ 12, -22 ]
   ]
-  t.is(pts.length, 8)
+  t.is(pts.length, 6)
   t.true(comparePoints(pts, exp))
 
   // test small arc between far points

package/src/index.d.ts

@@ -11,6 +11,7 @@ export * as booleans from './operations/booleans'
 export * as expansions from './operations/expansions'
 export * as extrusions from './operations/extrusions'
 export * as hulls from './operations/hulls'
+export * as minkowski from './operations/minkowski'
 export * as modifiers from './operations/modifiers'
 export * as transforms from './operations/transforms'
 

package/src/index.js

@@ -12,6 +12,7 @@ module.exports = {
   expansions: require('./operations/expansions'),
   extrusions: require('./operations/extrusions'),
   hulls: require('./operations/hulls'),
+  minkowski: require('./operations/minkowski'),
   modifiers: require('./operations/modifiers'),
   transforms: require('./operations/transforms')
 }

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

@@ -1,4 +1,5 @@
 export { default as intersect } from './intersect'
+export { minkowskiSum as minkowski } from '../minkowski/minkowskiSum'
 export { default as subtract } from './subtract'
 export { default as union } from './union'
 export { default as scission } from './scission'

package/src/operations/booleans/index.js

@@ -8,6 +8,7 @@
  */
 module.exports = {
   intersect: require('./intersect'),
+  minkowski: require('../minkowski/minkowskiSum'),
   scission: require('./scission'),
   subtract: require('./subtract'),
   union: require('./union')

package/src/operations/extrusions/extrudeRectangular.test.js

@@ -15,7 +15,7 @@ test('extrudeRectangular (defaults)', (t) => {
   let obs = extrudeRectangular({ }, geometry1)
   let pts = geom3.toPoints(obs)
   t.notThrows(() => geom3.validate(obs))
-  t.is(pts.length, 44)
+  t.is(pts.length, 36)
 
   obs = extrudeRectangular({ }, geometry2)
   pts = geom3.toPoints(obs)
@@ -30,7 +30,7 @@ test('extrudeRectangular (chamfer)', (t) => {
   let obs = extrudeRectangular({ corners: 'chamfer' }, geometry1)
   let pts = geom3.toPoints(obs)
   t.notThrows(() => geom3.validate(obs))
-  t.is(pts.length, 60)
+  t.is(pts.length, 48)
 
   obs = extrudeRectangular({ corners: 'chamfer' }, geometry2)
   pts = geom3.toPoints(obs)
@@ -45,7 +45,7 @@ test('extrudeRectangular (segments = 8, round)', (t) => {
   let obs = extrudeRectangular({ segments: 8, corners: 'round' }, geometry1)
   let pts = geom3.toPoints(obs)
   t.notThrows(() => geom3.validate(obs))
-  t.is(pts.length, 84)
+  t.is(pts.length, 72)
 
   obs = extrudeRectangular({ segments: 8, corners: 'round' }, geometry2)
   pts = geom3.toPoints(obs)

package/src/operations/minkowski/index.d.ts

@@ -0,0 +1 @@
+export { minkowskiSum } from './minkowskiSum'

package/src/operations/minkowski/index.js

@@ -0,0 +1,17 @@
+/**
+ * Minkowski sum operations for 3D geometries.
+ *
+ * The Minkowski sum of two shapes A and B is the set of all points that are
+ * the sum of a point in A and a point in B. This is useful for:
+ * - Offsetting/inflating shapes (using a sphere creates rounded edges)
+ * - Collision detection (shapes collide iff their Minkowski difference contains origin)
+ * - Motion planning and swept volumes
+ *
+ * @module modeling/minkowski
+ * @example
+ * const { minkowskiSum } = require('@jscad/modeling').minkowski
+ * const rounded = minkowskiSum(cube, sphere)
+ */
+module.exports = {
+  minkowskiSum: require('./minkowskiSum')
+}

package/src/operations/minkowski/minkowskiSum.d.ts

@@ -0,0 +1,4 @@
+import type { Geom3 } from '../../geometries/types'
+
+export function minkowskiSum(geometryA: Geom3, geometryB: Geom3): Geom3
+export function minkowskiSum(...geometries: Geom3[]): Geom3

package/src/operations/minkowski/minkowskiSum.js

@@ -0,0 +1,224 @@
+const flatten = require('../../utils/flatten')
+
+const geom3 = require('../../geometries/geom3')
+const poly3 = require('../../geometries/poly3')
+
+const hullPoints3 = require('../hulls/hullPoints3')
+const unionGeom3 = require('../booleans/unionGeom3')
+
+/**
+ * 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/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 exactly two geometries')
+  }
+
+  const [geomA, geomB] = geometries
+
+  if (!geom3.isA(geomA) || !geom3.isA(geomB)) {
+    throw new Error('minkowskiSum requires geom3 geometries')
+  }
+
+  const aConvex = geom3.isConvex(geomA)
+  const bConvex = geom3.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 using internal unionGeom3
+  if (parts.length === 1) {
+    return parts[0]
+  }
+
+  return unionGeom3(parts)
+}
+
+/**
+ * Decompose a geom3 into tetrahedra using face-local apex points.
+ * Each resulting tetrahedron is guaranteed to be convex.
+ *
+ * Unlike centroid-based decomposition, this approach works correctly for
+ * shapes where the centroid is outside the geometry (e.g., torus, U-shapes).
+ * Each polygon gets its own apex point, offset inward along its normal.
+ */
+const decomposeIntoTetrahedra = (geometry) => {
+  const polygons = geom3.toPolygons(geometry)
+
+  if (polygons.length === 0) {
+    return []
+  }
+
+  const tetrahedra = []
+
+  // For each polygon, compute a face-local apex and create tetrahedra
+  for (let i = 0; i < polygons.length; i++) {
+    const polygon = polygons[i]
+    const vertices = polygon.vertices
+
+    // Compute polygon center
+    let cx = 0, cy = 0, cz = 0
+    for (let k = 0; k < vertices.length; k++) {
+      cx += vertices[k][0]
+      cy += vertices[k][1]
+      cz += vertices[k][2]
+    }
+    cx /= vertices.length
+    cy /= vertices.length
+    cz /= vertices.length
+
+    // Get polygon plane (normal + offset)
+    const plane = poly3.plane(polygon)
+    const nx = plane[0], ny = plane[1], nz = plane[2]
+
+    // Offset inward along negative normal to create face-local apex
+    // The normal points outward, so we go in the negative direction
+    // Use a small offset - the actual distance doesn't matter much
+    // as long as the apex is on the interior side of the face
+    const offset = 0.1
+    const apex = [ // Vertex used as apex in tetrahedron polygons below
+      cx - nx * offset,
+      cy - ny * offset,
+      cz - nz * offset
+    ]
+
+    // Fan triangulate the polygon and create tetrahedra from apex
+    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 apex and triangle
+      const tetPolygons = createTetrahedronPolygons(apex, 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 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