feat(modeling): add Minkowski sum operation for 3D geometries

Author: jbroll

packages/modeling/dist/jscad-modeling.min.js

@@ -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'

packages/modeling/src/geometries/geom3/index.d.ts

@@ -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'),

packages/modeling/src/geometries/geom3/index.js

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

packages/modeling/src/geometries/geom3/isConvex.d.ts

@@ -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

packages/modeling/src/geometries/geom3/isConvex.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))
+})

packages/modeling/src/geometries/geom3/isConvex.test.js

@@ -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'
 

packages/modeling/src/index.d.ts

@@ -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')
 }

packages/modeling/src/index.js

@@ -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'

packages/modeling/src/operations/booleans/index.d.ts

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