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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jscad/modeling",
-  "version": "3.0.3-alpha.0",
+  "version": "3.0.4-alpha.0",
   "description": "Constructive Solid Geometry (CSG) Library for JSCAD",
   "homepage": "https://openjscad.xyz/",
   "repository": "https://github.com/jscad/OpenJSCAD.org",
@@ -58,11 +58,10 @@
     "access": "public"
   },
   "devDependencies": {
-    "@rollup/plugin-terser": "^0.4.3",
-    "ava": "^4.3.3",
-    "c8": "^8.0.0",
-    "rollup": "^2.79.1",
-    "rollup-plugin-banner": "^0.2.1"
+    "@rollup/plugin-terser": "^0.4.0",
+    "ava": "^6.3.0",
+    "c8": "^10.1.0",
+    "rollup": "^4.52.0"
   },
-  "gitHead": "b0a83db054ec02ccddd9e19e51f86bf30f72a69e"
+  "gitHead": "1de52a2b7b6bd31134fd0b72a2842f31ecf8f237"
 }

package/rollup.config.js

@@ -1,21 +1,25 @@
-import banner from 'rollup-plugin-banner'
+import * as fs from 'fs'
+
 import terser from '@rollup/plugin-terser'
 
+const {name, version, license} = JSON.parse(fs.readFileSync('package.json'))
+
 export default {
   input: 'src/index.js',
   output: [
     {
       file: 'dist/jscad-modeling.min.js',
       format: 'umd',
-      name: 'jscadModeling'
+      name: 'jscadModeling',
+      banner: `/*! ${name} V${version} (${license}) */`
     },
     {
       file: 'dist/jscad-modeling.es.js',
-      format: 'es'
+      format: 'es',
+      banner: `/*! ${name} V${version} (${license}) */`
     }
   ],
   plugins: [
-    banner('<%= pkg.description %>\n@module <%= pkg.name %>\n@version <%= pkg.version %>\n@license <%= pkg.license %>'),
     terser({ compress: { module: true }, mangle: false, format: { comments: 'some' } })
   ]
 }

package/src/curves/bezier/arcLengthToT.js

@@ -20,7 +20,7 @@ import { lengths } from './lengths.js'
  * @param {number} [options.segments=100] the number of segments to use when approximating the curve length.
  * @param {object} bezier a bezier curve.
  * @returns a number in the [0, 1] interval or NaN if the arcLength is negative or greater than the total length of the curve.
- * @alias module:modeling/curves/bezier.arcLengthToT
+ * @alias module:modeling/bezier.arcLengthToT
  */
 export const arcLengthToT = (options, bezier) => {
   const defaults = {

package/src/curves/bezier/create.js

@@ -23,7 +23,7 @@
  *
  * @param {Array} points An array with at least 2 elements of either all numbers, or all arrays of numbers that are the same size.
  * @returns {bezier} a new bezier data object
- * @alias module:modeling/curves/bezier.create
+ * @alias module:modeling/bezier.create
  */
 export const create = (points) => {
   if (!Array.isArray(points)) throw new Error('Bezier points must be a valid array/')

package/src/curves/bezier/index.js

@@ -1,14 +1,14 @@
 /**
  * Represents a bezier easing function.
  * @see {@link bezier} for data structure information.
- * @module modeling/curves/bezier
+ * @module modeling/bezier
+ *
  * @example
- * import { curves } from '@jscad/modeling'
- * const { bezier } = curves
+ * import { bezier } from '@jscad/modeling'
  */
+export { arcLengthToT } from './arcLengthToT.js'
 export { create } from './create.js'
-export { valueAt } from './valueAt.js'
-export { tangentAt } from './tangentAt.js'
-export { lengths } from './lengths.js'
 export { length } from './length.js'
-export { arcLengthToT } from './arcLengthToT.js'
+export { lengths } from './lengths.js'
+export { tangentAt } from './tangentAt.js'
+export { valueAt } from './valueAt.js'

package/src/curves/bezier/length.js

@@ -11,6 +11,6 @@ import { lengths } from './lengths.js'
  * @param {number} segments the number of segments to use when approximating the curve length.
  * @param {object} bezier a bezier curve.
  * @returns an approximation of the curve's length.
- * @alias module:modeling/curves/bezier.length
+ * @alias module:modeling/bezier.length
  */
 export const length = (segments, bezier) => lengths(segments, bezier)[segments]

package/src/curves/bezier/lengths.js

@@ -11,6 +11,7 @@ import { valueAt } from './valueAt.js'
  * @param {number} segments the number of segments to use when approximating the curve length.
  * @param {object} bezier a bezier curve.
  * @returns an array containing the cumulative length of the segments.
+ * @alias module:modeling/bezier.lengths
  */
 export const lengths = (segments, bezier) => {
   let sum = 0
@@ -25,7 +26,7 @@ export const lengths = (segments, bezier) => {
   return lengths
 }
 
-/**
+/*
  * Calculates the Euclidean distance between two n-dimensional points.
  *
  * @example

package/src/curves/bezier/tangentAt.js

@@ -10,7 +10,7 @@
  * @param {number} t : the position of which to calculate the bezier's tangent value; 0 < t < 1
  * @param {object} bezier : an array with at least 2 elements of either all numbers, or all arrays of numbers that are the same size.
  * @return {array | number} the tangent at the requested position.
- * @alias module:modeling/curves/bezier.tangentAt
+ * @alias module:modeling/bezier.tangentAt
  */
 export const tangentAt = (t, bezier) => {
   if (t < 0 || t > 1) {

package/src/curves/bezier/valueAt.js

@@ -11,7 +11,7 @@
  * @param {number} t : the position of which to calculate the value; 0 < t < 1
  * @param {object} bezier : a Bézier curve created with bezier.create().
  * @returns {array | number} the value at the requested position.
- * @alias module:modeling/curves/bezier.valueAt
+ * @alias module:modeling/bezier.valueAt
  */
 export const valueAt = (t, bezier) => {
   if (t < 0 || t > 1) {

package/src/curves/index.js

@@ -1,8 +1,8 @@
 /**
  * Curves are n-dimensional mathematical constructs that define a path from vertex 0 to vertex 1.
- * @module modeling/curves
+ * @alias module:modeling.curves
+ *
  * @example
- * import { curves } from '@jscad/modeling'
- * const { bezier } = curves
+ * import { bezier } from '@jscad/modeling'
  */
 export * as bezier from './bezier/index.js'

package/src/geometries/geom2/applyTransforms.js

@@ -3,12 +3,14 @@ import * as vec2 from '../../maths/vec2/index.js'
 
 /*
  * Apply the transforms of the given geometry.
+ *
  * NOTE: This function must be called BEFORE exposing any data. See toOutlines().
+ *
  * @param {Geom2} geometry - the geometry to transform
  * @returns {Geom2} the given geometry
  *
  * @example
- * geometry = applyTransforms(geometry)
+ * const geometry = geom2.applyTransforms(geometry)
  */
 export const applyTransforms = (geometry) => {
   if (mat4.isIdentity(geometry.transforms)) return geometry

package/src/geometries/geom2/clone.js

@@ -1,7 +1,11 @@
 /**
  * Performs a shallow clone of the given geometry.
+ *
  * @param {Geom2} geometry - the geometry to clone
  * @returns {Geom2} new geometry
- * @alias module:modeling/geometries/geom2.clone
+ * @alias module:modeling/geom2.clone
+ *
+ * @example
+ * const geometry = geom2.clone(geometry)
  */
 export const clone = (geometry) => Object.assign({}, geometry)

package/src/geometries/geom2/create.js

@@ -1,24 +1,14 @@
 import * as mat4 from '../../maths/mat4/index.js'
 
-/**
- * Represents a 2D geometry consisting of outlines, where each outline is an ordered list of points.
- * @property {Array} outlines - list of polygon outlines
- * @property {Mat4} transforms - transforms to apply to the geometry, see transform()
- * @example
- * // data structure
- * {
- *   "outlines": [[[-1,-1],[1,-1],[1,1],[-1,1]]],
- *   "transforms": [1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1]
- * }
- */
-
 /**
  * Create a new 2D geometry composed of polygon outlines.
+ *
  * @param {Array} [outlines] - list of outlines where each outline is an array of points
  * @returns {Geom2} a new geometry
- * @alias module:modeling/geometries/geom2.create
+ * @alias module:modeling/geom2.create
+ *
  * @example
- * let myShape = create([ [[-1,-1], [1,-1], [1,1], [-1,1]] ])
+ * let myShape = geom2.create([ [[-1,-1], [1,-1], [1,1], [-1,1]] ])
  */
 export const create = (outlines = []) => ({
   outlines,

package/src/geometries/geom2/fromSides.js

@@ -26,7 +26,7 @@ const toSharedPoints = (sides) => {
  */
 const toPointMap = (sides) => {
   const pointMap = new Map()
-  // first map to edges with shared vertices
+  // first map to edges with shared points
   const edges = toSharedPoints(sides)
   // construct adjacent edges map
   edges.forEach((edge) => {
@@ -41,11 +41,13 @@ const toPointMap = (sides) => {
 
 /**
  * Create a new 2D geometry from a list of sides.
+ *
  * @param {Array} sides - list of sides to create outlines from
  * @returns {Geom2} a new geometry
+ * @alias module:modeling/geom2.fromSides
  *
  * @example
- * let geometry = fromSides([[[0, 0], [1, 0]], [[1, 0], [1, 1]], [[1, 1], [0, 0]]])
+ * let geometry = geom2.fromSides([[[0, 0], [1, 0]], [[1, 0], [1, 1]], [[1, 1], [0, 0]]])
  */
 export const fromSides = (sides) => {
   const pointMap = toPointMap(sides) // {point: [edges]}

package/src/geometries/geom2/index.js

@@ -1,12 +1,28 @@
 /**
  * Represents a 2D geometry consisting of outlines, where each outline is an ordered list of points.
- * The outline is always closed between the first and last points.
- * @see {@link geom2} for data structure information.
- * @module modeling/geometries/geom2
+ *
+ * Each outline is always closed between the first and last points.
+ *
+ * @see {@link Geom2} for data structure information.
+ * @module modeling/geom2
+ *
+ * @example
+ * import { geom2 } from '@jscad/modeling'
+ * let myShape = geom2.create([ [[-1,-1], [1,-1], [1,1], [-1,1]] ])
+ */
+
+/**
+ * @typedef Geom2
+ * @type {Object}
+ * @property {Array} outlines - list of outlines, each outline is an ordered list of points
+ * @property {Mat4} transforms - transforms to apply to the polygons, see transform()
  *
  * @example
- * import { geometries } from '@jscad/modeling'
- * let myShape = geometries.geom2.create([ [[-1,-1], [1,-1], [1,1], [-1,1]] ])
+ * // data structure
+ * {
+ *   "outlines": [[[-1,-1],[1,-1],[1,1],[-1,1]]],
+ *   "transforms": [1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1]
+ * }
  */
 export { clone } from './clone.js'
 export { create } from './create.js'

package/src/geometries/geom2/isA.js

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

package/src/geometries/geom2/reverse.js

@@ -3,13 +3,15 @@ import { toOutlines } from './toOutlines.js'
 
 /**
  * Reverses the given geometry so that the outline points are flipped in the opposite order.
+ *
  * This swaps the left (interior) and right (exterior) edges.
+ *
  * @param {Geom2} geometry - the geometry to reverse
  * @returns {Geom2} the new reversed geometry
- * @alias module:modeling/geometries/geom2.reverse
+ * @alias module:modeling/geom2.reverse
  *
  * @example
- * let newGeometry = reverse(geometry)
+ * let newGeometry = geom2.reverse(geometry)
  */
 export const reverse = (geometry) => {
   const outlines = toOutlines(geometry)

package/src/geometries/geom2/toOutlines.js

@@ -2,9 +2,10 @@ import { applyTransforms } from './applyTransforms.js'
 
 /**
  * Create the outline(s) of the given geometry.
+ *
  * @param {Geom2} geometry - geometry to create outlines from
  * @returns {Array} an array of outlines, where each outline is an array of ordered points
- * @alias module:modeling/geometries/geom2.toOutlines
+ * @alias module:modeling/geom2.toOutlines
  *
  * @example
  * let geometry = subtract(rectangle({size: [5, 5]}), rectangle({size: [3, 3]}))

package/src/geometries/geom2/toPoints.js

@@ -2,14 +2,17 @@ import { toOutlines } from './toOutlines.js'
 
 /**
  * Produces an array of points from the given geometry.
+ *
  * The returned array should not be modified as the points are shared with the geometry.
+ *
  * NOTE: The points returned do NOT define an order. Use toOutlines() for ordered points.
+ *
  * @param {Geom2} geometry - the geometry
  * @returns {Array} an array of points
- * @alias module:modeling/geometries/geom2.toPoints
+ * @alias module:modeling/geom2.toPoints
  *
  * @example
- * let sharedPoints = toPoints(geometry)
+ * let sharedPoints = geom2.toPoints(geometry)
  */
 export const toPoints = (geometry) => {
   const points = []

package/src/geometries/geom2/toSides.js

@@ -2,14 +2,15 @@ import { toOutlines } from './toOutlines.js'
 
 /**
  * Produces an array of sides from the given geometry.
- * The returned array should not be modified as the data is shared with the geometry.
+ *
  * NOTE: The sides returned do NOT define an order. Use toOutlines() for ordered points.
+ *
  * @param {Geom2} geometry - the geometry
  * @returns {Array} an array of sides
- * @alias module:modeling/geometries/geom2.toSides
+ * @alias module:modeling/geom2.toSides
  *
  * @example
- * let sharedSides = toSides(geometry)
+ * let sharedSides = geom2.toSides(geometry)
  */
 export const toSides = (geometry) => {
   const sides = []

package/src/geometries/geom2/toString.js

@@ -4,12 +4,13 @@ import { toOutlines } from './toOutlines.js'
 
 /**
  * Create a string representing the contents of the given geometry.
+ *
  * @param {Geom2} geometry - the geometry
  * @returns {string} a representative string
- * @alias module:modeling/geometries/geom2.toString
+ * @alias module:modeling/geom2.toString
  *
  * @example
- * console.out(toString(geometry))
+ * console.out(geom2.toString(geometry))
  */
 export const toString = (geometry) => {
   const outlines = toOutlines(geometry)

package/src/geometries/geom2/transform.js

@@ -4,15 +4,17 @@ import { reverse } from './reverse.js'
 
 /**
  * Transform the given geometry using the given matrix.
+ *
  * This is a lazy transform of the outlines, as this function only adjusts the transforms.
  * The transforms are applied when accessing the outlines via toOutlines().
+ *
  * @param {Mat4} matrix - the matrix to transform with
  * @param {Geom2} geometry - the geometry to transform
  * @returns {Geom2} a new geometry
- * @alias module:modeling/geometries/geom2.transform
+ * @alias module:modeling/geom2.transform
  *
  * @example
- * let newGeometry = transform(fromZRotation(TAU / 4), geometry)
+ * let newGeometry = geom2.transform(fromZRotation(TAU / 4), geometry)
  */
 export const transform = (matrix, geometry) => {
   const transforms = mat4.multiply(mat4.create(), matrix, geometry.transforms)

package/src/geometries/geom2/validate.js

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

package/src/geometries/geom3/clone.js

@@ -1,7 +1,11 @@
 /**
  * Performs a shallow clone of the given geometry.
+ *
  * @param {Geom3} geometry - the geometry to clone
  * @returns {Geom3} a new geometry
- * @alias module:modeling/geometries/geom3.clone
+ * @alias module:modeling/geom3.clone
+ *
+ * @example
+ * let clone = geom3.clone(geometry)
  */
 export const clone = (geometry) => Object.assign({}, geometry)

package/src/geometries/geom3/create.js

@@ -1,27 +1,13 @@
 import * as mat4 from '../../maths/mat4/index.js'
 
-/**
- * Represents a 3D geometry consisting of a list of polygons.
- * @property {Array} polygons - list of polygons, each polygon containing three or more vertices
- * @property {Mat4} transforms - transforms to apply to the polygons, see transform()
- * @example
- * {
- *   "polygons": [
- *     {"vertices": [[-1,-1,-1], [-1,-1,1], [-1,1,1], [-1,1,-1]]},
- *     {"vertices": [[1,-1,-1], [1,1,-1], [1,1,1], [1,-1,1]]},
- *     {"vertices": [[-1,-1,-1], [1,-1,-1], [1,-1,1], [-1,-1,1]]},
- *     {"vertices": [[-1,1,-1], [-1,1,1], [1,1,1], [1,1,-1]]},
- *     {"vertices": [[-1,-1,-1], [-1,1,-1], [1,1,-1], [1,-1,-1]]},
- *     {"vertices": [[-1,-1,1], [1,-1,1], [1,1,1], [-1,1,1]]}
- *   ],
- *   "transforms": [1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1],
- * }
- */
-
 /**
  * Create a new 3D geometry composed of the given polygons.
+ *
  * @param {Array} [polygons] - list of polygons, or undefined
  * @returns {Geom3} a new geometry
- * @alias module:modeling/geometries/geom3.create
+ * @alias module:modeling/geom3.create
+ *
+ * @example
+ * let geometry = geom3.create()
  */
 export const create = (polygons = []) => ({ polygons, transforms: mat4.create() })

package/src/geometries/geom3/fromVertices.js

@@ -8,9 +8,21 @@ import { create } from './create.js'
  * The list of vertices should contain sub-arrays, each defining a single polygon of vertices.
  * In addition, the vertices should follow the right-hand rule for rotation in order to
  * define an external facing polygon.
+ *
  * @param {Array} listOfLists - list of lists, where each list is a set of vertices to construct a polygon
  * @returns {Geom3} a new geometry
- * @alias module:modeling/geometries/geom3.fromVertices
+ * @alias module:modeling/geom3.fromVertices
+ *
+ * @example
+ * let vertices = [
+ *   [[-1,-1,-1], [-1,-1,1], [-1,1,1], [-1,1,-1]],
+ *   [[1,-1,-1], [1,1,-1], [1,1,1], [1,-1,1]],
+ *   [[-1,-1,-1], [1,-1,-1], [1,-1,1], [-1,-1,1]]
+ *   [[-1,1,-1], [-1,1,1], [1,1,1], [1,1,-1]],
+ *   [[-1,-1,-1], [-1,1,-1], [1,1,-1], [1,-1,-1]],
+ *   [[-1,-1,1], [1,-1,1], [1,1,1], [-1,1,1]]
+ * ]
+ * let geometry = geom3.fromVertices(vertices)
  */
 export const fromVertices = (listOfLists) => {
   if (!Array.isArray(listOfLists)) {

package/src/geometries/geom3/fromVerticesConvex.js

@@ -7,7 +7,7 @@ import * as poly3 from '../poly3/index.js'
  *
  * @param {Array} uniqueVertices - list of vertices to construct convex 3D geometry
  * @returns {geom3} a new geometry
- * @alias module:modeling/geometries/geom3.fromVerticesConvex
+ * @alias module:modeling/geom3.fromVerticesConvex
  */
 export const fromVerticesConvex = (uniqueVertices) => {
   if (!Array.isArray(uniqueVertices)) {

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

@@ -4,6 +4,7 @@ export { fromVertices } from './fromVertices.js'
 export { fromVerticesConvex } from './fromVerticesConvex.js'
 export { invert } from './invert.js'
 export { isA } from './isA.js'
+export { isConvex } from './isConvex.js'
 export { toPolygons } from './toPolygons.js'
 export { toString } from './toString.js'
 export { toVertices } from './toVertices.js'

package/src/geometries/geom3/index.js

@@ -1,11 +1,12 @@
 /**
  * Represents a 3D geometry consisting of a list of polygons.
- * @see {@link geom3} for data structure information.
- * @module modeling/geometries/geom3
+ *
+ * @see {@link Geom3} for data structure information
+ * @module modeling/geom3
  *
  * @example
- * import { geometries } from '@jscad/modeling'
- * const myShape = geometries.geom3.fromVertices([
+ * import { geom3 } from '@jscad/modeling'
+ * const myShape = geom3.fromVertices([
  *   [[-1,-1,-1], [-1,-1,1], [-1,1,1], [-1,1,-1]],
  *   [[1,-1,-1], [1,1,-1], [1,1,1], [1,-1,1]],
  *   [[-1,-1,-1], [1,-1,-1], [1,-1,1], [-1,-1,1]]
@@ -14,12 +15,33 @@
  *   [[-1,-1,1], [1,-1,1], [1,1,1], [-1,1,1]]
  * ])
  */
+
+/**
+ * @typedef Geom3
+ * @type {Object}
+ * @property {Array} polygons - list of polygons, each polygon containing three or more vertices
+ * @property {Mat4} transforms - transforms to apply to the polygons, see transform()
+ *
+ * @example
+ * {
+ *   "polygons": [
+ *     {"vertices": [[-1,-1,-1], [-1,-1,1], [-1,1,1], [-1,1,-1]]},
+ *     {"vertices": [[1,-1,-1], [1,1,-1], [1,1,1], [1,-1,1]]},
+ *     {"vertices": [[-1,-1,-1], [1,-1,-1], [1,-1,1], [-1,-1,1]]},
+ *     {"vertices": [[-1,1,-1], [-1,1,1], [1,1,1], [1,1,-1]]},
+ *     {"vertices": [[-1,-1,-1], [-1,1,-1], [1,1,-1], [1,-1,-1]]},
+ *     {"vertices": [[-1,-1,1], [1,-1,1], [1,1,1], [-1,1,1]]}
+ *   ],
+ *   "transforms": [1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1],
+ * }
+ */
 export { clone } from './clone.js'
 export { create } from './create.js'
 export { fromVertices } from './fromVertices.js'
 export { fromVerticesConvex } from './fromVerticesConvex.js'
 export { invert } from './invert.js'
 export { isA } from './isA.js'
+export { isConvex } from './isConvex.js'
 export { toPolygons } from './toPolygons.js'
 export { toString } from './toString.js'
 export { toVertices } from './toVertices.js'

package/src/geometries/geom3/invert.js

@@ -5,9 +5,13 @@ import { toPolygons } from './toPolygons.js'
 
 /**
  * Invert the given geometry, transposing solid and empty space.
+ *
  * @param {Geom3} geometry - the geometry to invert
  * @returns {Geom3} a new geometry
- * @alias module:modeling/geometries/geom3.invert
+ * @alias module:modeling/geom3.invert
+ *
+ * @example
+ * let inverted = geom3.invert(geometry)
  */
 export const invert = (geometry) => {
   const polygons = toPolygons(geometry)

package/src/geometries/geom3/isA.js

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

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

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