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

package/src/geometries/path2/appendBezier.js

@@ -7,22 +7,24 @@ import { toPoints } from './toPoints.js'
 
 /**
  * Append a series of points to the given geometry that represent a Bézier curve.
+ *
  * The Bézier curve starts at the last point in the given geometry, and ends at the last control point.
  * The other control points are intermediate control points to transition the curve from start to end points.
  * The first control point may be null to ensure a smooth transition occurs. In this case,
  * the second to last point of the given geometry is mirrored into the control points of the Bézier curve.
  * In other words, the trailing gradient of the geometry matches the new gradient of the curve.
+ *
  * @param {object} options - options for construction
  * @param {Array} options.controlPoints - list of control points (2D) for the Bézier curve
  * @param {number} [options.segments=16] - number of segments per 360 rotation
  * @param {Path2} geometry - the path of which to append points
  * @returns {Path2} a new path with the appended points
- * @alias module:modeling/geometries/path2.appendBezier
+ * @alias module:modeling/path2.appendBezier
  *
  * @example
- * let myShape = fromPoints({}, [[10,-20]])
- * myShape = appendBezier({controlPoints: [[10,-10],[25,-10],[25,-20]]}, myShape);
- * myShape = appendBezier({controlPoints: [null, [25,-30],[40,-30],[40,-20]]}, myShape)
+ * let myShape = path2.fromPoints({}, [[10,-20]])
+ * myShape = path2.appendBezier({controlPoints: [[10,-10],[25,-10],[25,-20]]}, myShape);
+ * myShape = path2.appendBezier({controlPoints: [null, [25,-30],[40,-30],[40,-20]]}, myShape)
  */
 export const appendBezier = (options, geometry) => {
   const defaults = {

package/src/geometries/path2/appendPoints.js

@@ -3,11 +3,13 @@ import { create } from './create.js'
 
 /**
  * Append the given list of points to the end of the given geometry.
+ *
  * @param {Array} points - the points (2D) to append to the given path
  * @param {Path2} geometry - the given path
  * @returns {Path2} a new path with the appended points
- * @alias module:modeling/geometries/path2.appendPoints
+ * @alias module:modeling/path2.appendPoints
+ *
  * @example
- * let newPath = appendPoints([[3, 4], [4, 5]], oldPath)
+ * let newPath = path2.appendPoints([[3, 4], [4, 5]], oldPath)
  */
 export const appendPoints = (points, geometry) => concat(geometry, create(points))

package/src/geometries/path2/applyTransforms.js

@@ -3,9 +3,12 @@ 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 toPoints.
+ *
  * @param {path} geometry - the geometry to transform
  * @returns {path} the given geometry
+ *
  * @example
  * geometry = applyTransforms(geometry)
  */

package/src/geometries/path2/clone.js

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

package/src/geometries/path2/close.js

@@ -6,9 +6,13 @@ import { clone } from './clone.js'
 
 /**
  * Close the given geometry.
+ *
  * @param {Path2} geometry - the path to close
  * @returns {Path2} a new path
- * @alias module:modeling/geometries/path2.close
+ * @alias module:modeling/path2.close
+ *
+ * @example
+ * let newPath = path2.close(oldPath)
  */
 export const close = (geometry) => {
   if (geometry.isClosed) return geometry

package/src/geometries/path2/concat.js

@@ -10,12 +10,13 @@ import { toPoints } from './toPoints.js'
  * A concatenation of zero paths is an empty, open path.
  * A concatenation of one closed path to a series of open paths produces a closed path.
  * A concatenation of a path to a closed path is an error.
+ *
  * @param {...Path2} paths - the paths to concatenate
  * @returns {Path2} a new path
- * @alias module:modeling/geometries/path2.concat
+ * @alias module:modeling/path2.concat
  *
  * @example
- * let newPath = concat(fromPoints({}, [[1, 2]]), fromPoints({}, [[3, 4]]))
+ * let newPath = path2.concat(path2.fromPoints({}, [[1, 2]]), path2.fromPoints({}, [[3, 4]]))
  */
 export const concat = (...paths) => {
   // Only the last path can be closed, producing a closed path.

package/src/geometries/path2/create.js

@@ -1,33 +1,13 @@
 import * as mat4 from '../../maths/mat4/index.js'
 
-/**
- * Represents a 2D geometry consisting of a list of ordered points.
- * @property {Array} points - list of ordered points
- * @property {boolean} isClosed - true if the path is closed where start and end points are the same
- * @property {Mat4} transforms - transforms to apply to the points, see transform()
- * @example
- * {
- *   "points": [[0,0], [4,0], [4,3]],
- *   "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} [points] - a list of points of which to create the path
  * @returns {Path2} a new path
- * @alias module:modeling/geometries/path2.create
+ * @alias module:modeling/path2.create
  *
  * @example
- * let newPath = create()
+ * let newPath = path2.create()
  */
-export const create = (points) => {
-  if (points === undefined) {
-    points = []
-  }
-  return {
-    points: points,
-    isClosed: false,
-    transforms: mat4.create()
-  }
-}
+export const create = (points = []) => ({ points: points, isClosed: false, transforms: mat4.create() })

package/src/geometries/path2/equals.js

@@ -3,13 +3,18 @@ import * as vec2 from '../../maths/vec2/index.js'
 import { toPoints } from './toPoints.js'
 
 /**
-  * Determine if the given paths are equal.
-  * For closed paths, this includes equality under point order rotation.
-  * @param {Path2} a - the first path to compare
-  * @param {Path2} b - the second path to compare
-  * @returns {Boolean}
-  * @alias module:modeling/geometries/path2.equals
-  */
+ * Determine if the given paths are equal.
+ *
+ * For closed paths, this includes equality under point order rotation.
+ *
+ * @param {Path2} a - the first path to compare
+ * @param {Path2} b - the second path to compare
+ * @returns {Boolean}
+ * @alias module:modeling/path2.equals
+ *
+ * @example
+ * if (path2.equals(pathA, pathB)) { ... }
+ */
 export const equals = (a, b) => {
   if (a.isClosed !== b.isClosed) {
     return false

package/src/geometries/path2/fromPoints.js

@@ -7,16 +7,18 @@ import { create } from './create.js'
 
 /**
  * Create a new path from the given points.
+ *
  * The points must be provided an array of points,
  * where each point is an array of two numbers.
+ *
  * @param {object} options - options for construction
  * @param {boolean} [options.closed=false] - if the path should be open or closed
  * @param {Array} points - array of points (2D) from which to create the path
  * @returns {Path2} a new path
- * @alias module:modeling/geometries/path2.fromPoints
+ * @alias module:modeling/path2.fromPoints
  *
- * @example:
- * my newPath = fromPoints({closed: true}, [[10, 10], [-10, 10]])
+ * @example
+ * my newPath = path2.fromPoints({closed: true}, [[10, 10], [-10, 10]])
  */
 export const fromPoints = (options, points) => {
   const defaults = { closed: false }

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

@@ -7,12 +7,10 @@ export { concat } from './concat.js'
 export { create } from './create.js'
 export { equals } from './equals.js'
 export { fromPoints, FromPointsOptions } from './fromPoints.js'
-export { fromCompactBinary } from './fromCompactBinary.js'
 export { isA } from './isA.js'
 export { reverse } from './reverse.js'
 export { toPoints } from './toPoints.js'
 export { toString } from './toString.js'
-export { toCompactBinary } from './toCompactBinary.js'
 export { transform } from './transform.js'
 export { validate } from './validate.js'
 

package/src/geometries/path2/index.js

@@ -1,11 +1,28 @@
 /**
  * Represents a 2D geometry consisting of a list of ordered points.
- * @see {@link path2} for data structure information.
- * @module modeling/geometries/path2
+ *
+ * @see {@link Path2} for data structure information.
+ * @module modeling/path2
+ *
+ * @example
+ * import { path2 } from '@jscad/modeling'
+ * let myShape = path2.fromPoints({ closed: true }, [[0,0], [4,0], [4,3]])
+ */
+
+/**
+ * @typedef Path2
+ * @type {Object}
+ * @property {Array} points - list of ordered points
+ * @property {boolean} isClosed - true if the path is closed where start and end points are the same
+ * @property {Mat4} transforms - transforms to apply to the points, see transform()
  *
  * @example
- * import { geometries } from '@jscad/modeling'
- * let myShape = geometries.path2.fromPoints({ closed: true }, [[0,0], [4,0], [4,3]])
+ * // data structure
+ * {
+ *   "points": [[0,0], [4,0], [4,3]],
+ *   "isClosed": true,
+ *   "transforms": [1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1],
+ * }
  */
 export { appendArc } from './appendArc.js'
 export { appendBezier } from './appendBezier.js'
@@ -16,11 +33,9 @@ export { concat } from './concat.js'
 export { create } from './create.js'
 export { equals } from './equals.js'
 export { fromPoints } from './fromPoints.js'
-export { fromCompactBinary } from './fromCompactBinary.js'
 export { isA } from './isA.js'
 export { reverse } from './reverse.js'
 export { toPoints } from './toPoints.js'
 export { toString } from './toString.js'
-export { toCompactBinary } from './toCompactBinary.js'
 export { transform } from './transform.js'
 export { validate } from './validate.js'

package/src/geometries/path2/isA.js

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

package/src/geometries/path2/reverse.js

@@ -2,13 +2,15 @@ import { clone } from './clone.js'
 
 /**
  * Reverses the path so that the points are in the opposite order.
+ *
  * This swaps the left (interior) and right (exterior) edges.
+ *
  * @param {Path2} geometry - the path to reverse
  * @returns {Path2} a new path
- * @alias module:modeling/geometries/path2.reverse
+ * @alias module:modeling/path2.reverse
  *
  * @example
- * let newPath = reverse(myPath)
+ * let newPath = path2.reverse(oldPath)
  */
 export const reverse = (geometry) => {
   // NOTE: this only updates the order of the points

package/src/geometries/path2/toPoints.js

@@ -2,12 +2,14 @@ import { applyTransforms } from './applyTransforms.js'
 
 /**
  * Produces an array of points from the given geometry.
- * The returned array should not be modified as the data is shared with the geometry.
+ *
+ * NOTE: The returned array should not be modified as the data is shared with the geometry.
+ *
  * @param {Path2} geometry - the geometry
  * @returns {Array} an array of points
- * @alias module:modeling/geometries/path2.toPoints
+ * @alias module:modeling/path2.toPoints
  *
  * @example
- * let sharedPoints = toPoints(geometry)
+ * let sharedPoints = path2.toPoints(geometry)
  */
 export const toPoints = (geometry) => applyTransforms(geometry).points

package/src/geometries/path2/toString.js

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

package/src/geometries/path2/transform.js

@@ -2,15 +2,17 @@ import * as mat4 from '../../maths/mat4/index.js'
 
 /**
  * Transform the given geometry using the given matrix.
+ *
  * This is a lazy transform of the points, as this function only adjusts the transforms.
  * The transforms are applied when accessing the points via toPoints().
+ *
  * @param {Mat4} matrix - the matrix to transform with
  * @param {Path2} geometry - the geometry to transform
  * @returns {Path2} a new path
- * @alias module:modeling/geometries/path2.transform
+ * @alias module:modeling/path2.transform
  *
  * @example
- * let newPath = transform(fromZRotation(TAU / 8), path)
+ * let newPath = path2.transform(mat4.fromZRotation(TAU / 8), path)
  */
 export const transform = (matrix, geometry) => {
   const transforms = mat4.multiply(mat4.create(), matrix, geometry.transforms)

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

@@ -0,0 +1,22 @@
+import * as mat4 from '../../maths/mat4/index.js'
+import * as vec3 from '../../maths/vec3/index.js'
+
+/*
+ * Apply the transforms of the given geometry.
+ *
+ * NOTE: This function must be called BEFORE exposing any data. See toVertices.
+ *
+ * @param {Path3} geometry - the geometry to transform
+ * @returns {Path3} the given geometry
+ * @function
+ *
+ * @example
+ * geometry = path3.applyTransforms(geometry)
+ */
+export const applyTransforms = (geometry) => {
+  if (mat4.isIdentity(geometry.transforms)) return geometry
+
+  geometry.vertices = geometry.vertices.map((vertex) => vec3.transform(vec3.create(), vertex, geometry.transforms))
+  geometry.transforms = mat4.create()
+  return geometry
+}

package/src/geometries/path3/applyTransforms.test.js

@@ -0,0 +1,28 @@
+import test from 'ava'
+
+import { fromVertices } from './index.js'
+
+import { applyTransforms } from './applyTransforms.js'
+
+import { comparePoints, compareVectors } from '../../../test/helpers/index.js'
+
+test('applyTransforms: Updates a populated path with transformed points', (t) => {
+  const vertices = [[0, 0, 0], [1, 0, 0], [0, 1, 0]]
+  const expected = {
+    vertices: [[0, 0, 0], [1, 0, 0], [0, 1, 0]],
+    isClosed: false,
+    transforms: [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]
+  }
+  const geometry = fromVertices({}, vertices)
+  const updated = applyTransforms(geometry)
+  t.is(geometry, updated)
+  t.true(comparePoints(updated.vertices, expected.vertices))
+  t.false(updated.isClosed)
+  t.true(compareVectors(updated.transforms, expected.transforms))
+
+  const updated2 = applyTransforms(updated)
+  t.is(updated, updated2)
+  t.true(comparePoints(updated2.vertices, expected.vertices))
+  t.false(updated2.isClosed)
+  t.true(compareVectors(updated2.transforms, expected.transforms))
+})

package/src/geometries/path3/close.d.ts

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

package/src/geometries/path3/close.js

@@ -0,0 +1,33 @@
+import { EPS } from '../../maths/constants.js'
+
+import * as vec3 from '../../maths/vec3/index.js'
+
+/**
+ * Close the given geometry.
+ *
+ * @param {Path3} geometry - the path to close
+ * @returns {Path3} a new path
+ * @alias module:modeling/path3.close
+ *
+ * @example
+ * const newPath = path3.close(oldPath)
+ */
+export const close = (geometry) => {
+  if (geometry.isClosed) return geometry
+
+  const cloned = Object.assign({}, geometry)
+  cloned.isClosed = true
+
+  if (cloned.vertices.length > 1) {
+    // make sure the paths are formed properly
+    const vertices = cloned.vertices
+    const p0 = vertices[0]
+    let pn = vertices[vertices.length - 1]
+    while (vec3.distance(p0, pn) < (EPS * EPS)) {
+      vertices.pop()
+      if (vertices.length === 1) break
+      pn = vertices[vertices.length - 1]
+    }
+  }
+  return cloned
+}

package/src/geometries/path3/close.test.js

@@ -0,0 +1,43 @@
+import test from 'ava'
+
+import { close, create, fromVertices } from './index.js'
+
+test('close: closes an empty path', (t) => {
+  const p1 = create()
+  t.false(p1.isClosed)
+
+  const p2 = close(p1)
+  t.true(p2.isClosed)
+  t.not(p1, p2)
+
+  const p3 = close(p2)
+  t.true(p3.isClosed)
+  t.is(p2, p3)
+})
+
+test('close: closes various paths', (t) => {
+  let p1 = create()
+  p1 = close(p1)
+  t.true(p1.isClosed)
+  t.is(0, p1.vertices.length)
+
+  let p2 = fromVertices({ closed: false }, [])
+  p2 = close(p2)
+  t.true(p2.isClosed)
+  t.is(0, p2.vertices.length)
+
+  let p3 = fromVertices({ closed: true }, [[0, 0, 0]])
+  p3 = close(p3)
+  t.true(p3.isClosed)
+  t.is(1, p3.vertices.length)
+
+  let p4 = fromVertices({ closed: true }, [[0, 0, 0], [0, 0, 0]])
+  p4 = close(p4)
+  t.true(p4.isClosed)
+  t.is(1, p4.vertices.length) // the last point is removed
+
+  let p5 = fromVertices({ closed: true }, [[0, 0, 0], [1, 1, 0], [0, 0, 0]])
+  p5 = close(p5)
+  t.true(p5.isClosed)
+  t.is(2, p5.vertices.length) // the last point is removed
+})

package/src/geometries/path3/concat.d.ts

@@ -0,0 +1,3 @@
+import type { Path3 } from './type.d.ts'
+
+export function concat(...paths: Array<Path3>): Path3

package/src/geometries/path3/concat.js

@@ -0,0 +1,35 @@
+import { equals } from '../../maths/vec3/index.js'
+
+import { fromVertices } from './fromVertices.js'
+import { toVertices } from './toVertices.js'
+
+/**
+ * Concatenate the given paths.
+ *
+ * If both contain the same vertex at the junction, merge it into one.
+ * A concatenation of zero paths is an empty, open path.
+ * A concatenation of one closed path to a series of open paths produces a closed path.
+ * A concatenation of a path to a closed path is an error.
+ *
+ * @param {...Path3} paths - the paths to concatenate
+ * @returns {Path3} a new path
+ * @alias module:modeling/path3.concat
+ *
+ * @example
+ * 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.
+  let isClosed = false
+  let vertices = []
+  paths.forEach((path, i) => {
+    const tmp = toVertices(path).slice()
+    if (vertices.length > 0 && tmp.length > 0 && equals(tmp[0], vertices[vertices.length - 1])) tmp.shift()
+    if (tmp.length > 0 && isClosed) {
+      throw new Error(`Cannot concatenate to a closed path; check the ${i}th path`)
+    }
+    isClosed = path.isClosed
+    vertices = vertices.concat(tmp)
+  })
+  return fromVertices({ closed: isClosed }, vertices)
+}

package/src/geometries/path3/concat.test.js

@@ -0,0 +1,35 @@
+import test from 'ava'
+
+import { concat, equals, fromVertices } from './index.js'
+
+test('concat: no paths produces an empty open path', (t) => {
+  t.true(equals(concat(), fromVertices({ closed: false }, [])))
+})
+
+test('concat: empty paths produces an empty open path', (t) => {
+  t.true(equals(concat(fromVertices({}, []), fromVertices({}, [])), fromVertices({ closed: false }, [])))
+})
+
+test('concat: many open paths produces a open path', (t) => {
+  const p1 = fromVertices({ closed: false }, [[0, 0, 0]])
+  const p2 = fromVertices({ closed: false }, [[1, 1, 0]])
+  const p3 = fromVertices({ closed: false }, [[1, 1, 0], [3, 3, 0]])
+
+  const result = concat(p1, p2, p3)
+  t.true(equals(result, fromVertices({}, [[0, 0, 0], [1, 1, 0], [3, 3, 0]])))
+  t.is(p1.vertices.length, 1)
+  t.is(p2.vertices.length, 1)
+  t.is(p3.vertices.length, 2)
+})
+
+test('concat: an open path and a closed path produces a closed path', (t) => {
+  t.true(equals(concat(fromVertices({ closed: false }, [[0, 0, 0]]),
+    fromVertices({ closed: true }, [[1, 1, 0]])),
+  fromVertices({ closed: true }, [[0, 0, 0], [1, 1, 0]])))
+})
+
+test('concat: a closed path and an open path throws an error', (t) => {
+  const p1 = fromVertices({ closed: true }, [[0, 0, 0]])
+  const p2 = fromVertices({ closed: false }, [[1, 1, 0]])
+  t.throws(() => concat(p1, p2), { message: 'Cannot concatenate to a closed path; check the 1th path' })
+})

package/src/geometries/path3/create.d.ts

@@ -0,0 +1,4 @@
+import type { Path3 } from './type.d.ts'
+import type { Vec3 } from '../../maths/vec3/type.d.ts'
+
+export function create(vertices?: Array<Vec3>): Path3

package/src/geometries/path3/create.js

@@ -0,0 +1,14 @@
+import * as mat4 from '../../maths/mat4/index.js'
+
+/**
+ * Create an empty, open path.
+ *
+ * @param {Array} [vertices] - a list of vertices of which to create the path
+ * @returns {Path3} a new path
+ * @alias module:modeling/path3.create
+ *
+ * @example
+ * 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/create.test.js

@@ -0,0 +1,8 @@
+import test from 'ava'
+
+import { create, equals, fromVertices } from './index.js'
+
+test('create: Creates an empty path', (t) => {
+  t.true(equals(create(), fromVertices({ closed: false }, [])))
+  t.true(equals(create([[0, 0, 0], [1, 1, 1]]), fromVertices({ closed: false }, [[0, 0, 0], [1, 1, 1]])))
+})

package/src/geometries/path3/equals.d.ts

@@ -0,0 +1,3 @@
+import type { Path3 } from './type.d.ts'
+
+export function equals(a: Path3, b: Path3): boolean