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

package/src/geometries/poly2/measureBoundingBox.js

@@ -1,9 +1,14 @@
 import * as vec2 from '../../maths/vec2/index.js'
 
 /**
+ * Measure the min and max bounds of the given polygon.
+ *
  * @param {Poly2} polygon - the polygon to measure
  * @returns {Array} an array of two vectors (2D);  minimum and maximum coordinates
- * @alias module:modeling/geometries/poly2.measureBoundingBox
+ * @alias module:modeling/poly2.measureBoundingBox
+ *
+ * @example
+ * const bounds = poly2.measureBoundingBox(geometry)
  */
 export const measureBoundingBox = (polygon) => {
   const points = polygon.points

package/src/geometries/poly2/reverse.js

@@ -5,7 +5,10 @@ import { create } from './create.js'
  *
  * @param {Poly2} polygon - the polygon to reverse
  * @returns {Poly2} a new polygon
- * @alias module:modeling/geometries/poly2.reverse
+ * @alias module:modeling/poly2.reverse
+ *
+ * @example
+ * let newPoly = poly2.reverse(oldPoly)
  */
 export const reverse = (polygon) => {
   const points = polygon.points.slice().reverse()

package/src/geometries/poly2/toPoints.js

@@ -1,8 +1,13 @@
 /**
  * Return the given polygon as a list of points.
+ *
  * NOTE: The returned array should not be modified as the points are shared with the geometry.
+ *
  * @param {Poly2} polygon - the polygon
  * @return {Array} list of points (2D)
- * @alias module:modeling/geometries/poly2.toPoints
+ * @alias module:modeling/poly2.toPoints
+ *
+ * @example
+ * const sharedPoints = poly2.toPoints(geometry)
  */
 export const toPoints = (polygon) => polygon.points

package/src/geometries/poly2/toString.js

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

package/src/geometries/poly2/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 {Poly2} polygon - the polygon to transform
  * @returns {Poly2} a new polygon
- * @alias module:modeling/geometries/poly2.transform
+ * @alias module:modeling/poly2.transform
+ *
+ * @example
+ * let newPoly = poly2.transfrom(oldPoly)
  */
 export const transform = (matrix, polygon) => {
   const points = polygon.points.map((point) => vec2.transform(vec2.create(), point, matrix))

package/src/geometries/poly2/validate.js

@@ -5,13 +5,17 @@ import { measureArea } from './measureArea.js'
 
 /**
  * Determine if the given object is a valid polygon.
+ *
  * Checks for valid data structure, convex polygons, and duplicate 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/poly2.validate
+ * @alias module:modeling/poly2.validate
+ *
+ * @example
+ * poly2.validate(geometry)
  */
 export const validate = (object) => {
   if (!isA(object)) {

package/src/geometries/poly3/clone.js

@@ -8,7 +8,10 @@ import { create } from './create.js'
  * @param {Poly3} [out] - receiving polygon
  * @param {Poly3} polygon - polygon to clone
  * @returns {Poly3} a new polygon
- * @alias module:modeling/geometries/poly3.clone
+ * @alias module:modeling/poly3.clone
+ *
+ * @example
+ * const newPoly = poly3.clone(oldPoly)
  */
 export const clone = (...params) => {
   let out

package/src/geometries/poly3/create.js

@@ -1,24 +1,11 @@
-/**
- * Represents a convex 3D polygon. The vertices used to initialize a polygon must
- * be coplanar and form a convex shape. The vertices do not have to be `vec3`
- * instances but they must behave similarly.
- * @property {Array} vertices - list of ordered vertices (3D)
- * @example
- * {"vertices": [[0,0,0], [4,0,0], [4,3,12]]}
- */
-
 /**
  * Creates a new 3D polygon with initial values.
  *
  * @param {Array} [vertices] - a list of vertices (3D)
  * @returns {Poly3} a new polygon
- * @alias module:modeling/geometries/poly3.create
+ * @alias module:modeling/poly3.create
+ *
  * @example
- * const polygon = create([[1, 0], [0, 1], [0, 0]])
+ * const polygon = poly3.create([[1, 0], [0, 1], [0, 0]])
  */
-export const create = (vertices) => {
-  if (vertices === undefined || vertices.length < 3) {
-    vertices = [] // empty contents
-  }
-  return { vertices }
-}
+export const create = (vertices = []) => ({ vertices })

package/src/geometries/poly3/fromVerticesAndPlane.js

@@ -2,11 +2,13 @@ import { create } from './create.js'
 
 /**
  * Create a polygon from the given vertices and plane.
+ *
  * NOTE: No checks are performed on the parameters.
+ *
  * @param {Array} vertices - list of vertices (3D)
  * @param {Plane} plane - plane of the polygon
  * @returns {Poly3} a new polygon
- * @alias module:modeling/geometries/poly3.fromVerticesAndPlane
+ * @alias module:modeling/poly3.fromVerticesAndPlane
  */
 export const fromVerticesAndPlane = (vertices, plane) => {
   const poly = create(vertices)

package/src/geometries/poly3/index.js

@@ -1,12 +1,27 @@
 /**
  * Represents a convex 3D polygon consisting of a list of ordered vertices.
- * @see {@link poly3} for data structure information.
- * @module modeling/geometries/poly3
+ *
+ * The vertices used to initialize a polygon must be coplanar and form a convex shape.
+ *
+ * @see {@link Poly3} for data structure information.
+ * @module modeling/poly3
+ *
+ * @example
+ * import { poly3 } from '@jscad/modeling'
+ * const polygon = poly3.create([[0,0,0], [4,0,0], [4,3,12]])
+ */
+
+/**
+ * @typedef {Object} Poly3
+ * @property {Array} vertices - list of ordered vertices (3D)
  *
  * @example
- * import { geometries } from '@jscad/modeling'
- * const polygon = geometries.poly3.create([[0,0,0], [4,0,0], [4,3,12]])
+ * // data structure
+ * {
+ *   vertices: [[0,0,0], [4,0,0], [4,3,12]]
+ * }
  */
+
 export { clone } from './clone.js'
 export { create } from './create.js'
 export { fromVerticesAndPlane } from './fromVerticesAndPlane.js'

package/src/geometries/poly3/invert.js

@@ -7,7 +7,10 @@ import { create } from './create.js'
  *
  * @param {Poly3} polygon - the polygon to invert
  * @returns {Poly3} a new poly3
- * @alias module:modeling/geometries/poly3.invert
+ * @alias module:modeling/poly3.invert
+ *
+ * @example
+ * const newPoly = poly3.invert(oldPoly)
  */
 export const invert = (polygon) => {
   const vertices = polygon.vertices.slice().reverse()

package/src/geometries/poly3/isA.js

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

package/src/geometries/poly3/isConvex.js

@@ -3,9 +3,13 @@ import * as vec3 from '../../maths/vec3/index.js'
 
 /**
  * Check whether the given polygon is convex.
+ *
  * @param {Poly3} polygon - the polygon to interrogate
  * @returns {Boolean} true if convex
- * @alias module:modeling/geometries/poly3.isConvex
+ * @alias module:modeling/poly3.isConvex
+ *
+ * @example
+ * if (poly3.isConvex(geometry)) { ... }
  */
 export const isConvex = (polygon) => areVerticesConvex(polygon.vertices)
 

package/src/geometries/poly3/measureArea.js

@@ -3,9 +3,13 @@ import { plane } from './plane.js'
 /**
  * Measure the area of the given polygon.
  * @see 2000 softSurfer http://geomalgorithms.com
+ *
  * @param {Poly3} polygon - the polygon to measure
  * @return {number} area of the polygon
- * @alias module:modeling/geometries/poly3.measureArea
+ * @alias module:modeling/poly3.measureArea
+ *
+ * @example
+ * const area = poly3.measureArea(polyA)
  */
 export const measureArea = (polygon) => {
   const n = polygon.vertices.length

package/src/geometries/poly3/measureBoundingBox.js

@@ -5,7 +5,10 @@ import * as vec3 from '../../maths/vec3/index.js'
  *
  * @param {Poly3} polygon - the polygon to measure
  * @returns {Array} an array of two vectors (3D);  minimum and maximum coordinates
- * @alias module:modeling/geometries/poly3.measureBoundingBox
+ * @alias module:modeling/poly3.measureBoundingBox
+ *
+ * @example
+ * const bounds = poly3.measureBoundingBox(polyA)
  */
 export const measureBoundingBox = (polygon) => {
   const vertices = polygon.vertices

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