@jscad/modeling 3.0.3-alpha.0 → 3.0.4-alpha.0

package/src/geometries/poly3/measureBoundingSphere.js

@@ -1,5 +1,3 @@
-import * as vec4 from '../../maths/vec4/index.js'
-
 const cache = new WeakMap()
 
 /**
@@ -8,7 +6,10 @@ const cache = new WeakMap()
  * @param {Vec4} out - receiving vector
  * @param {Poly3} polygon - the polygon to measure
  * @returns {Vec4} the computed bounding sphere; center vertex (3D) and radius
- * @alias module:modeling/geometries/poly3.measureBoundingSphere
+ * @alias module:modeling/poly3.measureBoundingSphere
+ *
+ * @example
+ * const bounds = poly2.measureBoundingSphere(polyA)
  */
 export const measureBoundingSphere = (out, polygon) => {
   const vertices = polygon.vertices

package/src/geometries/poly3/measureSignedVolume.js

@@ -2,12 +2,17 @@ import * as vec3 from '../../maths/vec3/index.js'
 
 /**
  * Measure the signed volume of the given polygon, which must be convex.
+ *
  * The volume is that formed by the tetrahedron connected to the axis [0,0,0],
  * and will be positive or negative based on the rotation of the vertices.
  * @see http://chenlab.ece.cornell.edu/Publication/Cha/icip01_Cha.pdf
+ *
  * @param {Poly3} polygon - the polygon to measure
  * @return {number} volume of the polygon
- * @alias module:modeling/geometries/poly3.measureSignedVolume
+ * @alias module:modeling/poly3.measureSignedVolume
+ *
+ * @example
+ * const volume = poly3.measureSignedVolumne(polyA)
  */
 export const measureSignedVolume = (polygon) => {
   let signedVolume = 0

package/src/geometries/poly3/plane.js

@@ -1,5 +1,11 @@
 import * as mplane from '../../maths/plane/index.js'
 
+/**
+ * Determine the plane of the given polygon.
+ *
+ * @param {Poly3} polygon - the polygon of which to fetch the plane
+ * @alias module:modeling/poly3.plane
+ */
 export const plane = (polygon) => {
   if (!polygon.plane) {
     polygon.plane = mplane.fromPoints(mplane.create(), ...polygon.vertices)

package/src/geometries/poly3/toString.js

@@ -2,8 +2,12 @@ import * as vec3 from '../../maths/vec3/index.js'
 
 /**
  * Convert the given polygon to a readable string.
+ *
  * @param {Poly3} polygon - the polygon to convert
  * @return {String} the string representation
- * @alias module:modeling/geometries/poly3.toString
+ * @alias module:modeling/poly3.toString
+ *
+ * @example
+ * console.log(poly3.toString(polyA))
  */
 export const toString = (polygon) => `poly3: [${polygon.vertices.map(vec3.toString).join(', ')}]`

package/src/geometries/poly3/toVertices.js

@@ -1,8 +1,13 @@
 /**
  * Return the given polygon as a list of vertices.
+ *
  * NOTE: The returned array should not be modified as the vertices are shared with the geometry.
+ *
  * @param {Poly3} polygon - the polygon
  * @return {Array} list of vertices (3D)
- * @alias module:modeling/geometries/poly3.toVertices
+ * @alias module:modeling/poly3.toVertices
+ *
+ * @example
+ * const sharedVertices = poly3.toVertices(polyA)
  */
 export const toVertices = (polygon) => polygon.vertices

package/src/geometries/poly3/transform.js

@@ -5,10 +5,14 @@ import { create } from './create.js'
 
 /**
  * Transform the given polygon using the given matrix.
+ *
  * @param {Mat4} matrix - the matrix to transform with
  * @param {Poly3} polygon - the polygon to transform
  * @returns {Poly3} a new polygon
- * @alias module:modeling/geometries/poly3.transform
+ * @alias module:modeling/poly3.transform
+ *
+ * @example
+ * const newPoly = poly3.transform(oldPoly)
  */
 export const transform = (matrix, polygon) => {
   const vertices = polygon.vertices.map((vertex) => vec3.transform(vec3.create(), vertex, matrix))

package/src/geometries/poly3/validate.js

@@ -9,13 +9,17 @@ import { plane } from './plane.js'
 
 /**
  * Determine if the given object is a valid polygon.
+ *
  * Checks for valid data structure, convex polygons, and duplicate vertices.
  *
- * **If the geometry is not valid, an exception will be thrown with details of the geometry error.**
+ * **NOTE: If the geometry is not valid, an exception will be thrown with details of the geometry error.**
  *
  * @param {object} object - the object to interrogate
  * @throws {Error} error if the geometry is not valid
- * @alias module:modeling/geometries/poly3.validate
+ * @alias module:modeling/poly3.validate
+ *
+ * @example
+ * poly3.validate(geometry)
  */
 export const validate = (object) => {
   if (!isA(object)) {

package/src/geometries/slice/calculatePlane.js

@@ -3,13 +3,13 @@ import * as vec3 from '../../maths/vec3/index.js'
 
 /**
  * Calculate the plane of the given slice.
- * NOTE: The slice (and all vertices) are assumed to be planar from the beginning.
+ *
  * @param {Slice} slice - the slice
  * @returns {Plane} the plane of the slice
- * @alias module:modeling/geometries/slice.calculatePlane
+ * @alias module:modeling/slice.calculatePlane
  *
  * @example
- * let myPlane = calculatePlane(slice)
+ * const plane = slice.calculatePlane(sliceA)
  */
 export const calculatePlane = (slice) => {
   if (slice.contours.length < 1) {

package/src/geometries/slice/clone.js

@@ -4,6 +4,9 @@
  *
  * @param {Slice} slice - slice to clone
  * @returns {Slice} a new slice
- * @alias module:modeling/geometries/slice.clone
+ * @alias module:modeling/slice.clone
+ *
+ * @example
+ * const newSlice = slice.clone(oldSlice)
  */
 export const clone = (slice) => Object.assign({}, slice)

package/src/geometries/slice/create.js

@@ -1,18 +1,13 @@
-/**
- * Represents a 3D geometry consisting of a list of contours,
- * where each contour consists of a list of planar vertices.
- * @property {Array} contours - list of contours, each contour containing a list of 3D vertices
- * @example
- * {"contours": [[[0,0,1], [4,0,1], [4,3,1]]]}
- */
-
 /**
  * Creates a new slice from the given contours.
  *
+ * NOTE: The slice (and all vertices) are assumed to be planar from the beginning.
+ *
  * @param {Array} [contours] - a list of contours, where each contour contains a list of vertices (3D)
  * @returns {Slice} a new slice
- * @alias module:modeling/geometries/slice.create
+ * @alias module:modeling/slice.create
+ *
  * @example
- * const slice = create([ [[0,0,1], [4,0,1], [4,3,1]] ])
+ * const slice = slice.create([ [[0,0,1], [4,0,1], [4,3,1]] ])
  */
 export const create = (contours = []) => ({ contours })

package/src/geometries/slice/equals.js

@@ -2,10 +2,14 @@ import * as vec3 from '../../maths/vec3/index.js'
 
 /**
  * Determine if the given slices have the same contours.
+ *
  * @param {Slice} a - the first slice to compare
  * @param {Slice} b - the second slice to compare
  * @returns {Boolean} true if the slices are equal
- * @alias module:modeling/geometries/slice.equals
+ * @alias module:modeling/slice.equals
+ *
+ * @example
+ * if (slice.equals(sliceA, sliceB)) { ... }
  */
 export const equals = (a, b) => {
   if (a.contours.length !== b.contours.length) {

package/src/geometries/slice/fromGeom2.js

@@ -8,7 +8,7 @@ import { create } from './create.js'
  *
  * @param {object} geometry - the 2D geometry to create a slice from
  * @returns {Slice} a new slice
- * @alias module:modeling/geometries/slice.fromGeom2
+ * @alias module:modeling/slice.fromGeom2
  */
 export const fromGeom2 = (geometry) => {
   // Convert from 2D points to 3D vertices

package/src/geometries/slice/fromVertices.js

@@ -3,11 +3,11 @@ import * as vec3 from '../../maths/vec3/index.js'
 import { create } from './create.js'
 
 /**
- * Create a slice from the given vertices.
+ * Create a slice with a single contour from the given vertices.
  *
  * @param {Array} vertices - list of vertices, where each vertex is either 2D or 3D
  * @returns {Slice} a new slice
- * @alias module:modeling/geometries/slice.fromVertices
+ * @alias module:modeling/slice.fromVertices
  *
  * @example
  * const vertices = [
@@ -15,7 +15,7 @@ import { create } from './create.js'
  *   [0, 10, 3],
  *   [0, 10, 6]
  * ]
- * const slice = fromVertices(vertices)
+ * const slice = slice.fromVertices(vertices)
  */
 export const fromVertices = (vertices) => {
   if (!Array.isArray(vertices)) throw new Error('the given vertices must be an array')

package/src/geometries/slice/index.js

@@ -1,12 +1,27 @@
 /**
  * Represents a 3D geometry consisting of a list of contours, where each contour consists of a list of planar vertices.
- * @see {@link slice} for data structure information.
- * @module modeling/geometries/slice
+ * @see {@link Slice} for data structure information.
+ * @module modeling/slice
  *
  * @example
- * import { geometries } from '@jscad/modeling'
- * const slice = geometries.slice.create([[[0,0,0], [4,0,0], [4,3,12]]])
+ * import { slice } from '@jscad/modeling'
+ * const slice = slice.create([[[0,0,0], [4,0,0], [4,3,12]]])
  */
+
+/**
+ * @typedef Slice
+ * @type {Object}
+ * @property {Array} contours - list of contours, each contour containing a list of 3D vertices
+ *
+ * @example
+ * // data structure
+ * {
+ *   contours: [
+ *     [[0,0,1], [4,0,1], [4,3,1]]
+ *   ]
+ * }
+ */
+
 export { calculatePlane } from './calculatePlane.js'
 export { clone } from './clone.js'
 export { create } from './create.js'

package/src/geometries/slice/isA.js

@@ -1,8 +1,12 @@
 /**
  * Determine if the given object is a slice.
+ *
  * @param {Slice} object - the object to interrogate
  * @returns {Boolean} true if the object matches a slice
- * @alias module:modeling/geometries/slice.isA
+ * @alias module:modeling/slice.isA
+ *
+ * @example
+ * if (slice.isA(geometry)) { ... }
  */
 export const isA = (object) => {
   if (object && typeof object === 'object') {

package/src/geometries/slice/reverse.js

@@ -1,11 +1,14 @@
 import { create } from './create.js'
 
 /**
- * Reverse the edges of the given slice.
+ * Reverse the contours of the given slice.
  *
  * @param {Slice} slice - slice to reverse
  * @returns {Slice} reverse of the slice
- * @alias module:modeling/geometries/slice.reverse
+ * @alias module:modeling/slice.reverse
+ *
+ * @example
+ * const newSlice = slice.reverse(oldSlice)
  */
 export const reverse = (slice) => {
   // reverse each contour

package/src/geometries/slice/toEdges.js

@@ -1,12 +1,14 @@
 /**
  * Produces an array of edges from the given slice.
- * The returned array should not be modified as the data is shared with the slice.
+ *
+ * NOTE: The returned array should not be modified as the data is shared with the slice.
+ *
  * @param {Slice} slice - the slice
  * @returns {Array} an array of edges, each edge contains an array of two vertices (3D)
- * @alias module:modeling/geometries/slice.toEdges
+ * @alias module:modeling/slice.toEdges
  *
  * @example
- * let sharedEdges = toEdges(slice)
+ * let sharedEdges = slice.toEdges(slice)
  */
 export const toEdges = (slice) => {
   const edges = []

package/src/geometries/slice/toPolygons.js

@@ -5,9 +5,13 @@ import { PolygonHierarchy } from './earcut/polygonHierarchy.js'
 
 /**
  * Return a list of polygons which are enclosed by the slice.
+ *
  * @param {Slice} slice - the slice
  * @return {Array} a list of polygons (3D)
- * @alias module:modeling/geometries/slice.toPolygons
+ * @alias module:modeling/slice.toPolygons
+ *
+ * @example
+ * const polygons = slice.toPolygons(sliceA)
  */
 export const toPolygons = (slice) => {
   const hierarchy = new PolygonHierarchy(slice)

package/src/geometries/slice/toString.js

@@ -2,9 +2,13 @@ import * as vec3 from '../../maths/vec3/index.js'
 
 /**
  * Convert the given slice to a readable string.
+ *
  * @param {Slice} slice - the slice
  * @return {String} the string representation
- * @alias module:modeling/geometries/slice.toString
+ * @alias module:modeling/slice.toString
+ *
+ * @example
+ * console.log(slice.toString(sliceA))
  */
 export const toString = (slice) => {
   let result = 'slice (' + slice.contours.length + ' contours):\n[\n'

package/src/geometries/slice/toVertices.js

@@ -1,12 +1,14 @@
 /**
  * Produces an array of vertices from the given slice.
- * The returned array should not be modified as the data is shared with the slice.
+ *
+ * NOTE: The returned array should not be modified as the data is shared with the slice.
+ *
  * @param {Slice} slice - the slice
  * @returns {Array} an array of 3D vertices
- * @alias module:modeling/geometries/slice.toVertices
+ * @alias module:modeling/slice.toVertices
  *
  * @example
- * let sharedVertices = toVertices(slice)
+ * let sharedVertices = slice.toVertices(slice)
  */
 export const toVertices = (slice) => {
   const vertices = []

package/src/geometries/slice/transform.js

@@ -4,14 +4,15 @@ import { create } from './create.js'
 
 /**
  * Transform the given slice using the given matrix.
+ *
  * @param {Mat4} matrix - transform matrix
  * @param {Slice} slice - slice to transform
  * @returns {Slice} the transformed slice
- * @alias module:modeling/geometries/slice.transform
+ * @alias module:modeling/slice.transform
  *
  * @example
- * let matrix = mat4.fromTranslation([1, 2, 3])
- * let newSlice = transform(matrix, oldSlice)
+ * const matrix = mat4.fromTranslation([1, 2, 3])
+ * const newSlice = slice.transform(matrix, oldSlice)
  */
 export const transform = (matrix, slice) => {
   const contours = slice.contours.map((contour) => contour.map((vertex) => vec3.transform(vec3.create(), vertex, matrix)))

package/src/geometries/slice/validate.js

@@ -6,13 +6,14 @@ import { isA } from './isA.js'
 
 /**
  * Determine if the given object is a valid slice.
+ *
  * Checks for valid data points.
  *
- * **If the geometry is not valid, an exception will be thrown with details of the geometry error.**
+ * **NOTE: If the geometry is not valid, an exception will be thrown with details of the geometry error.**
  *
  * @param {object} object - the object to interrogate
  * @throws {Error} error if the geometry is not valid
- * @alias module:modeling/geometries/slice.validate
+ * @alias module:modeling/slice.validate
  */
 export const validate = (object) => {
   if (!isA(object)) {

package/src/index.d.ts

@@ -10,6 +10,7 @@ export { degToRad, flatten, radiusToSegments, radToDeg } from './utils'
 export * as booleans from './operations/booleans'
 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 offsets from './operations/offsets'
 export * as transforms from './operations/transforms'

package/src/index.js

@@ -1,3 +1,6 @@
+/**
+ * @module modeling
+ */
 export * from './colors/index.js'
 export * from './curves/index.js'
 export * from './geometries/index.js'
@@ -10,6 +13,7 @@ export { degToRad, flatten, radiusToSegments, radToDeg } from './utils/index.js'
 export * from './operations/booleans/index.js'
 export * from './operations/extrusions/index.js'
 export * from './operations/hulls/index.js'
+export * from './operations/minkowski/index.js'
 export * from './operations/modifiers/index.js'
 export * from './operations/offsets/index.js'
 export * from './operations/transforms/index.js'

package/src/maths/constants.js

@@ -1,19 +1,21 @@
 /**
  * Epsilon used during determination of near zero distances.
- * This should be 1 / spacialResolution.
- * @default
+ *
+ * @constant
  * @alias module:modeling/maths.EPS
  * @example
- * const { EPS } = maths.constants
+ * import { EPS } from '@jscad/modeling'
  */
 export const EPS = 1e-5
 
 /**
  * Smaller epsilon used for measuring near zero distances.
- * @default
+ *
+ * @constant
+ * @static
  * @alias module:modeling/maths.NEPS
  * @example
- * const { NEPS } = maths.constants
+ * import { NEPS } from '@jscad/modeling'
  */
 export const NEPS = 1e-13
 // NEPS is derived from a series of tests to determine the optimal precision
@@ -22,10 +24,12 @@ export const NEPS = 1e-13
 
 /**
  * The TAU property represents the ratio of the circumference of a circle to its radius.
+ *
  * Approximately 6.28318530717958647692
+ *
+ * @constant
  * @alias module:modeling/maths.TAU
- * @default
  * @example
- * const { TAU } = maths.constants
+ * import { TAU } from '@jscad/modeling'
  */
 export const TAU = Math.PI * 2

package/src/maths/index.js

@@ -1,10 +1,11 @@
 /**
  * Maths are computational units for fundamental Euclidean geometry. All maths operate upon array data structures.
+ *
  * Note: Maths data structures are considered immutable, so never change the contents directly.
  * @see Most computations are based upon the glMatrix library (glmatrix.net)
  * @module modeling/maths
  * @example
- * import { constants, line2, line3, mat4, plane, utils, vec2, vec3, vec4 } from '@jscad/modeling'
+ * import { TAU, line2, line3, mat4, plane, utils, vec2, vec3, vec4 } from '@jscad/modeling'
  */
 export * from './constants.js'
 export * as line2 from './line2/index.js'

package/src/maths/mat4/isOnlyTransformScale.js

@@ -17,7 +17,7 @@ export const isOnlyTransformScale = (matrix) => (
   matrix[15] === 1
 )
 
-/**
+/*
  * @param {number} num
  * @returns {boolean}
  */

package/src/operations/booleans/index.js

@@ -1,8 +1,10 @@
 /**
  * All shapes (primitives or the results of operations) can be passed to boolean functions
  * to perform logical operations, e.g. remove a hole from a board.
+ *
  * In all cases, the function returns the results, and never changes the original shapes.
  * @module modeling/booleans
+ *
  * @example
  * import { intersect, scission, subtract, union } from '@jscad/modeling'
  */

package/src/operations/booleans/intersect.js

@@ -6,7 +6,6 @@ import * as geom3 from '../../geometries/geom3/index.js'
 
 import { intersectGeom2 } from './intersectGeom2.js'
 import { intersectGeom3 } from './intersectGeom3.js'
-
 /**
  * Return a new geometry representing space in both the first geometry and
  * all subsequent geometries.

package/src/operations/booleans/scission.js

@@ -1,7 +1,6 @@
 import * as geom3 from '../../geometries/geom3/index.js'
 
 import { scissionGeom3 } from './scissionGeom3.js'
-
 /**
  * Scission (divide) the given geometry into the component pieces.
  *

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

@@ -4,10 +4,7 @@ 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)
 
-  Number.isNaN(lambda) ? lambda = 0
-    : lambda > 1 ? lambda = 1
-      : lambda < 0 ? lambda = 0
-        : lambda
+  Number.isNaN(lambda) ? lambda = 0 : lambda > 1 ? lambda = 1 : lambda < 0 ? lambda = 0 : lambda
 
   vec3.scale(direction, direction, lambda)
   vec3.add(direction, p1, direction)