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

package/src/geometries/path2/validate.js

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

package/src/geometries/path3/applyTransforms.js

@@ -11,7 +11,7 @@ import * as vec3 from '../../maths/vec3/index.js'
  * @function
  *
  * @example
- * geometry = applyTransforms(geometry)
+ * geometry = path3.applyTransforms(geometry)
  */
 export const applyTransforms = (geometry) => {
   if (mat4.isIdentity(geometry.transforms)) return geometry

package/src/geometries/path3/close.js

@@ -7,8 +7,10 @@ import * as vec3 from '../../maths/vec3/index.js'
  *
  * @param {Path3} geometry - the path to close
  * @returns {Path3} a new path
- * @function
- * @alias module:modeling/geometries/path3.close
+ * @alias module:modeling/path3.close
+ *
+ * @example
+ * const newPath = path3.close(oldPath)
  */
 export const close = (geometry) => {
   if (geometry.isClosed) return geometry

package/src/geometries/path3/concat.js

@@ -13,11 +13,10 @@ import { toVertices } from './toVertices.js'
  *
  * @param {...Path3} paths - the paths to concatenate
  * @returns {Path3} a new path
- * @function
- * @alias module:modeling/geometries/path3.concat
+ * @alias module:modeling/path3.concat
  *
  * @example
- * let newPath = concat(fromVertices({}, [[1, 2, 3]]), fromVertices({}, [[4, 5, 6]]))
+ * let newPath = path3.concat(path3.fromVertices({}, [[1, 2, 3]]), path3.fromVertices({}, [[4, 5, 6]]))
  */
 export const concat = (...paths) => {
   // Only the last path can be closed, producing a closed path.

package/src/geometries/path3/create.js

@@ -1,30 +1,14 @@
 import * as mat4 from '../../maths/mat4/index.js'
 
-/**
- * Represents a 3D geometry consisting of a list of ordered vertices.
- *
- * @typedef {Object} Path3
- * @property {Array} vertices - list of ordered vertices
- * @property {boolean} isClosed - true if the path is closed where start and end vertices are the same
- * @property {Mat4} transforms - transforms to apply to the vertices, see transform()
- *
- * @example
- * {
- *   vertices: [[0,0,0], [4,0,0], [4,3,0]],
- *   isClosed: true,
- *   transforms: [1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1],
- * }
- */
-
 /**
  * Create an empty, open path.
  *
+ * @param {Array} [vertices] - a list of vertices of which to create the path
  * @returns {Path3} a new path
- * @function
- * @alias module:modeling/geometries/path3.create
+ * @alias module:modeling/path3.create
  *
  * @example
- * let pathA = create()
- * let pathB = create([[0,0,0], [4,0,0], [4,3,0]])
+ * let pathA = path3.create()
+ * let pathB = path3.create([[0,0,0], [4,0,0], [4,3,0]])
  */
 export const create = (vertices = []) => ({ vertices: vertices, isClosed: false, transforms: mat4.create() })

package/src/geometries/path3/equals.js

@@ -10,8 +10,10 @@ import { toVertices } from './toVertices.js'
  * @param {Path3} a - the first path to compare
  * @param {Path3} b - the second path to compare
  * @returns {boolean}
- * @function
- * @alias module:modeling/geometries/path3.equals
+ * @alias module:modeling/path3.equals
+ *
+ * @example
+ * if (path3.equals(pathA, pathB)) { ... }
  */
 export const equals = (a, b) => {
   if (a.isClosed !== b.isClosed) {

package/src/geometries/path3/fromVertices.js

@@ -15,11 +15,10 @@ import { create } from './create.js'
  * @param {boolean} [options.closed=false] - if the path should be open or closed
  * @param {Array} vertices - array of vertices (3D) from which to create the path
  * @returns {Path3} a new path
- * @function
- * @alias module:modeling/geometries/path3.fromVertices
+ * @alias module:modeling/path3.fromVertices
  *
  * @example
- * my newPath = fromVertices({closed: true}, [[10, 10, 10], [-10, 10, -10]])
+ * my newPath = path3.fromVertices({closed: true}, [[10, 10, 10], [-10, 10, -10]])
  */
 export const fromVertices = (options, vertices) => {
   const defaults = { closed: false }

package/src/geometries/path3/index.js

@@ -2,12 +2,28 @@
  * Represents a 3D geometry consisting of a list of ordered vertices.
  *
  * @see {@link Path3} for data structure information.
- * @module modeling/geometries/path3
+ * @module modeling/path3
  *
  * @example
  * import { path3 } from '@jscad/modeling'
  * let myShape = path3.fromVertices({ closed: true }, [[0,0,0], [4,0,0], [4,3,0]])
  */
+
+/**
+ * @typedef {Object} Path3
+ * @property {Array} vertices - list of ordered vertices
+ * @property {boolean} isClosed - true if the path is closed where start and end vertices are the same
+ * @property {Mat4} transforms - transforms to apply to the vertices, see transform()
+ *
+ * @example
+ * // data structure
+ * {
+ *   vertices: [[0,0,0], [4,0,0], [4,3,0]],
+ *   isClosed: true,
+ *   transforms: [1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1],
+ * }
+ */
+
 export { close } from './close.js'
 export { concat } from './concat.js'
 export { create } from './create.js'

package/src/geometries/path3/isA.js

@@ -3,8 +3,10 @@
  *
  * @param {Object} object - the object to interrogate
  * @returns {boolean} true if the object matches a path3
- * @function
- * @alias module:modeling/geometries/path3.isA
+ * @alias module:modeling/path3.isA
+ *
+ * @example
+ * if (path3.isA(geometry)) { ... }
  */
 export const isA = (object) => {
   if (object && typeof object === 'object') {

package/src/geometries/path3/reverse.js

@@ -5,11 +5,10 @@
  *
  * @param {Path3} geometry - the path to reverse
  * @returns {Path3} a new path
- * @function
- * @alias module:modeling/geometries/path3.reverse
+ * @alias module:modeling/path3.reverse
  *
  * @example
- * let newPath = reverse(path)
+ * let newPath = path3.reverse(oldPath)
  */
 export const reverse = (geometry) => {
   // NOTE: this only updates the order of the vertices

package/src/geometries/path3/toString.js

@@ -7,11 +7,10 @@ import { toVertices } from './toVertices.js'
  *
  * @param {path} geometry - the path
  * @returns {string} a representative string
- * @function
- * @alias module:modeling/geometries/path3.toString
+ * @alias module:modeling/path3.toString
  *
  * @example
- * console.out(toString(path))
+ * console.out(path3.toString(geometry))
  */
 export const toString = (geometry) => {
   const vertices = toVertices(geometry)

package/src/geometries/path3/toVertices.js

@@ -7,10 +7,9 @@ import { applyTransforms } from './applyTransforms.js'
  *
  * @param {Path3} geometry - the geometry
  * @returns {Array} an array of vertices
- * @function
- * @alias module:modeling/geometries/path3.toVertices
+ * @alias module:modeling/path3.toVertices
  *
  * @example
- * let sharedVertices = toVertices(path)
+ * let sharedVertices = path3.toVertices(geometry)
  */
 export const toVertices = (geometry) => applyTransforms(geometry).vertices

package/src/geometries/path3/transform.js

@@ -9,11 +9,10 @@ import * as mat4 from '../../maths/mat4/index.js'
  * @param {Mat4} matrix - the matrix to transform with
  * @param {Path3} geometry - the geometry to transform
  * @returns {Path3} a new path
- * @function
- * @alias module:modeling/geometries/path3.transform
+ * @alias module:modeling/path3.transform
  *
  * @example
- * let newPath = transform(fromZRotation(TAU / 8), path)
+ * let newPath = path3.transform(mat4.fromZRotation(TAU / 8), oldPath)
  */
 export const transform = (matrix, geometry) => {
   const transforms = mat4.multiply(mat4.create(), matrix, geometry.transforms)

package/src/geometries/path3/validate.js

@@ -4,14 +4,17 @@ import { isA } from './isA.js'
 
 /**
  * Determine if the given object is a valid path3.
+ *
  * Checks for valid vertices, 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
- * @function
- * @alias module:modeling/geometries/path3.validate
+ * @alias module:modeling/path3.validate
+ *
+ * @example
+ * path3.vaidate(geometry)
  */
 export const validate = (object) => {
   if (!isA(object)) {

package/src/geometries/poly2/arePointsInside.js

@@ -7,7 +7,10 @@ import { reverse } from './reverse.js'
  * @param {Array} points - a list of points, where each point is an array with X and Y values
  * @param {Poly2} polygon - a 2D polygon
  * @return {number} 1 if all points are inside, 0 if some or none are inside
- * @alias module:modeling/geometries/poly2.arePointsInside
+ * @alias module:modeling/poly2.arePointsInside
+ *
+ * @example
+ * if (poly2.arePointsInside([[0,0], [4,0], [4,3]], geometry) { ... }
  */
 export const arePointsInside = (points, polygon) => {
   if (points.length === 0) return 0 // nothing to check

package/src/geometries/poly2/clone.js

@@ -3,6 +3,9 @@
  *
  * @param {Poly2} polygon - polygon to clone
  * @returns {Poly2} a new polygon
- * @alias module:modeling/geometries/poly2.clone
+ * @alias module:modeling/poly2.clone
+ *
+ * @example
+ * const newPoly = poly2.clone(oldPoly)
  */
 export const clone = (polygon) => Object.assign({}, polygon)

package/src/geometries/poly2/create.js

@@ -1,18 +1,11 @@
-/**
- * Represents a 2D polygon consisting of a list of ordered points
- * which is closed between start and end points.
- * @see https://en.wikipedia.org/wiki/Polygon
- * @property {Array} points - list of ordered points (2D)
- */
-
 /**
  * Creates a new polygon with initial values.
  *
  * @param {Array} [points] - list of points (2D)
  * @returns {Poly2} a new polygon
- * @alias module:modeling/geometries/poly2.create
+ * @alias module:modeling/poly2.create
  *
  * @example
- * let polygon = create([[0,0], [4,0], [4,3]])
+ * let polygon = poly2.create([[0,0], [4,0], [4,3]])
  */
 export const create = (points = []) => ({ points })

package/src/geometries/poly2/index.js

@@ -1,12 +1,24 @@
 /**
  * Represents a 2D polygon consisting of a list of ordered points.
- * @see {@link poly2} for data structure information.
- * @module modeling/geometries/poly2
+ * @see {@link Poly2} for data structure information.
+ * @module modeling/poly2
  *
  * @example
- * import { geometries } from '@jscad/modeling'
- * const p1 = geometries.poly2.create([[0,0], [4,0], [4,3]])
+ * import { poly2 } from '@jscad/modeling'
+ * const p1 = poly2.create([[0,0], [4,0], [4,3]])
  */
+
+/**
+ * @typedef {Object} Poly2
+ * @property {Array} points - list of ordered points (2D)
+ *
+ * @example
+ * // data structure
+ * {
+ *   points: [[0,0], [4,0], [4,3]],
+ * }
+ */
+
 export { arePointsInside } from './arePointsInside.js'
 export { clone } from './clone.js'
 export { create } from './create.js'

package/src/geometries/poly2/isA.js

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

package/src/geometries/poly2/isConvex.js

@@ -1,8 +1,12 @@
 /**
  * Check whether the given polygon is convex.
+ *
  * @param {Poly2} polygon - the polygon to interrogate
  * @returns {Boolean} true if convex
- * @alias module:modeling/geometries/poly2.isConvex
+ * @alias module:modeling/poly2.isConvex
+ *
+ * @example
+ * if (poly2.isConvex(geometry)) { ... }
  */
 export const isConvex = (polygon) => {
   const numPoints = polygon.points.length

package/src/geometries/poly2/isSimple.js

@@ -3,9 +3,13 @@ import { intersect } from '../../maths/utils/intersect.js'
 /**
  * Check whether the given polygon is simple, i.e. does not intersect itself.
  * @see https://en.wikipedia.org/wiki/Simple_polygon
+ *
  * @param {Poly2} polygon - the polygon to interrogate
  * @returns {Boolean} true if simple
- * @alias module:modeling/geometries/poly2.isSimple
+ * @alias module:modeling/poly2.isSimple
+ *
+ * @example
+ * if (poly2.isSimple(geometry)) { ... }
  */
 export const isSimple = (polygon) => {
   const numPoints = polygon.points.length

package/src/geometries/poly2/measureArea.js

@@ -5,6 +5,9 @@ import { area } from '../../maths/utils/area.js'
  *
  * @param {Poly2} polygon - the polygon to measure
  * @return {number} the area of the polygon
- * @alias module:modeling/geometries/poly2.measureArea
+ * @alias module:modeling/poly2.measureArea
+ *
+ * @example
+ * const area = poly2.measureArea(geometry)
  */
 export const measureArea = (polygon) => area(polygon.points)

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,19 +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 = []) => ({ 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