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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jscad/modeling",
-  "version": "3.0.2-alpha.0",
+  "version": "3.0.3-alpha.0",
   "description": "Constructive Solid Geometry (CSG) Library for JSCAD",
   "homepage": "https://openjscad.xyz/",
   "repository": "https://github.com/jscad/OpenJSCAD.org",
@@ -64,5 +64,5 @@
     "rollup": "^2.79.1",
     "rollup-plugin-banner": "^0.2.1"
   },
-  "gitHead": "ac80d1a7cb0a8efb21aff9193d4a8bccb6e31f1c"
+  "gitHead": "b0a83db054ec02ccddd9e19e51f86bf30f72a69e"
 }

package/src/colors/colorize.test.js

@@ -36,7 +36,7 @@ test('color (rgba on objects)', (t) => {
 
 test('color (rgba on geometry)', (t) => {
   const obj0 = geom2.create([[[0, 0], [1, 0], [0, 1]]])
-  const obj1 = geom3.fromPoints([[[0, 0, 0], [1, 0, 0], [1, 0, 1]]])
+  const obj1 = geom3.fromVertices([[[0, 0, 0], [1, 0, 0], [1, 0, 1]]])
   const obj2 = path2.fromPoints({ closed: true }, [[0, 0], [1, 0], [1, 1]])
   const obj3 = poly3.create([[0, 0, 0], [1, 0, 0], [1, 1, 0]])
 

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

@@ -1,14 +1,12 @@
 export { clone } from './clone.js'
 export { create } from './create.js'
 export { fromSides } from './fromSides.js'
-export { fromCompactBinary } from './fromCompactBinary.js'
 export { isA } from './isA.js'
 export { reverse } from './reverse.js'
 export { toOutlines } from './toOutlines.js'
 export { toPoints } from './toPoints.js'
 export { toSides } from './toSides.js'
 export { toString } from './toString.js'
-export { toCompactBinary } from './toCompactBinary.js'
 export { transform } from './transform.js'
 export { validate } from './validate.js'
 

package/src/geometries/geom2/index.js

@@ -11,13 +11,11 @@
 export { clone } from './clone.js'
 export { create } from './create.js'
 export { fromSides } from './fromSides.js'
-export { fromCompactBinary } from './fromCompactBinary.js'
 export { isA } from './isA.js'
 export { reverse } from './reverse.js'
 export { toOutlines } from './toOutlines.js'
 export { toPoints } from './toPoints.js'
 export { toSides } from './toSides.js'
 export { toString } from './toString.js'
-export { toCompactBinary } from './toCompactBinary.js'
 export { transform } from './transform.js'
 export { validate } from './validate.js'

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

@@ -1,6 +1,6 @@
 import test from 'ava'
 
-import { fromPoints } from './index.js'
+import { fromVertices } from './index.js'
 
 import { applyTransforms } from './applyTransforms.js'
 
@@ -15,7 +15,7 @@ test('applyTransforms: Updates a geom3 with transformed polygons', (t) => {
     isRetesselated: false,
     transforms: [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]
   }
-  const geometry = fromPoints(vertices)
+  const geometry = fromVertices(vertices)
   const updated = applyTransforms(geometry)
   t.is(geometry, updated)
   t.true(comparePolygons(updated.polygons[0], expected.polygons[0]))

package/src/geometries/geom3/clone.test.js

@@ -1,6 +1,6 @@
 import test from 'ava'
 
-import { clone, create, fromPoints } from './index.js'
+import { clone, create, fromVertices } from './index.js'
 
 import { comparePolygons, compareVectors } from '../../../test/helpers/index.js'
 
@@ -23,7 +23,7 @@ test('clone: Creates a clone of a populated geom3', (t) => {
     ],
     transforms: [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]
   }
-  const geometry = fromPoints(vertices)
+  const geometry = fromVertices(vertices)
   const another = clone(geometry)
   t.not(another, geometry)
   t.true(comparePolygons(another.polygons[0], expected.polygons[0]))

package/src/geometries/geom3/create.js

@@ -24,12 +24,4 @@ import * as mat4 from '../../maths/mat4/index.js'
  * @returns {Geom3} a new geometry
  * @alias module:modeling/geometries/geom3.create
  */
-export const create = (polygons) => {
-  if (polygons === undefined) {
-    polygons = [] // empty contents
-  }
-  return {
-    polygons,
-    transforms: mat4.create()
-  }
-}
+export const create = (polygons = []) => ({ polygons, transforms: mat4.create() })

package/src/geometries/geom3/{fromPoints.d.ts → fromVertices.d.ts}

@@ -1,4 +1,4 @@
 import type { Geom3 } from './type.d.ts'
 import type { Vec3 } from '../../maths/vec3/type.d.ts'
 
-export function fromPoints(points: Array<Array<Vec3>>): Geom3
+export function fromVertices(vertices: Array<Array<Vec3>>): Geom3

package/src/geometries/geom3/{fromPoints.js → fromVertices.js}

@@ -4,14 +4,15 @@ import { create } from './create.js'
 
 /**
  * Construct a new 3D geometry from a list of vertices.
+ *
  * 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.fromPoints
+ * @alias module:modeling/geometries/geom3.fromVertices
  */
-export const fromPoints = (listOfLists) => {
+export const fromVertices = (listOfLists) => {
   if (!Array.isArray(listOfLists)) {
     throw new Error('the given vertices must be an array')
   }

package/src/geometries/geom3/{fromPoints.test.js → fromVertices.test.js}

@@ -1,10 +1,10 @@
 import test from 'ava'
 
-import { fromPoints } from './index.js'
+import { fromVertices } from './index.js'
 
 import { comparePolygons, compareVectors } from '../../../test/helpers/index.js'
 
-test('fromPoints: Creates a populated geom3', (t) => {
+test('fromVertices: Creates a populated geom3', (t) => {
   const vertices = [[[0, 0, 0], [1, 0, 0], [1, 0, 1]]]
   const expected = {
     polygons: [
@@ -13,12 +13,12 @@ test('fromPoints: Creates a populated geom3', (t) => {
     isRetesselated: false,
     transforms: [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]
   }
-  const obs = fromPoints(vertices)
+  const obs = fromVertices(vertices)
   t.true(comparePolygons(obs.polygons[0], expected.polygons[0]))
   t.true(compareVectors(obs.transforms, expected.transforms))
 })
 
-test('fromPoints: throws for improper vertices', (t) => {
-  t.throws(() => fromPoints(), { instanceOf: Error })
-  t.throws(() => fromPoints(0, 0, 0), { instanceOf: Error })
+test('fromVertices: throws for improper vertices', (t) => {
+  t.throws(() => fromVertices(), { instanceOf: Error })
+  t.throws(() => fromVertices(0, 0, 0), { instanceOf: Error })
 })

package/src/geometries/geom3/{fromPointsConvex.d.ts → fromVerticesConvex.d.ts}

@@ -1,4 +1,4 @@
 import type { Geom3 } from './type.d.ts'
 import type { Vec3 } from '../../maths/vec3/type.d.ts'
 
-export function fromPointsConvex(points: Array<Array<Vec3>>): Geom3
+export function fromVerticesConvex(vertices: Array<Array<Vec3>>): Geom3

package/src/geometries/geom3/fromVerticesConvex.js

@@ -0,0 +1,25 @@
+import { runner } from '../../operations/hulls/quickhull/index.js'
+import { create } from './create.js'
+import * as poly3 from '../poly3/index.js'
+
+/**
+ * Construct a new convex 3D geometry from a list of unique vertices.
+ *
+ * @param {Array} uniqueVertices - list of vertices to construct convex 3D geometry
+ * @returns {geom3} a new geometry
+ * @alias module:modeling/geometries/geom3.fromVerticesConvex
+ */
+export const fromVerticesConvex = (uniqueVertices) => {
+  if (!Array.isArray(uniqueVertices)) {
+    throw new Error('the given vertices must be an array')
+  }
+
+  const faces = runner(uniqueVertices, { skipTriangulation: true })
+
+  const polygons = faces.map((face) => {
+    const vertices = face.map((index) => uniqueVertices[index])
+    return poly3.create(vertices)
+  })
+
+  return create(polygons)
+}

package/src/geometries/geom3/{fromPointsConvex.test.js → fromVerticesConvex.test.js}

@@ -1,8 +1,8 @@
 import test from 'ava'
 
-import { fromPointsConvex, validate } from './index.js'
+import { fromVerticesConvex, validate } from './index.js'
 
-test('fromPointsConvex (uniquePoints)', (t) => {
+test('fromVerticesConvex (uniqueVertices)', (t) => {
   const out = []
   for (let x = -9; x <= 9; ++x) {
     for (let y = -9; y <= 9; ++y) {
@@ -14,7 +14,7 @@ test('fromPointsConvex (uniquePoints)', (t) => {
     }
   }
 
-  const obs = fromPointsConvex(out)
+  const obs = fromVerticesConvex(out)
   validate(obs)
   t.is(obs.polygons.length, 170)
   t.true(obs.polygons.every((f) => ([3, 4, 8, 9].indexOf(f.vertices.length) !== -1)))

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

@@ -1,14 +1,12 @@
 export { clone } from './clone.js'
 export { create } from './create.js'
-export { fromPoints } from './fromPoints.js'
-export { fromPointsConvex } from './fromPointsConvex.js'
-export { fromCompactBinary } from './fromCompactBinary.js'
+export { fromVertices } from './fromVertices.js'
+export { fromVerticesConvex } from './fromVerticesConvex.js'
 export { invert } from './invert.js'
 export { isA } from './isA.js'
-export { toPoints } from './toPoints.js'
 export { toPolygons } from './toPolygons.js'
 export { toString } from './toString.js'
-export { toCompactBinary } from './toCompactBinary.js'
+export { toVertices } from './toVertices.js'
 export { transform } from './transform.js'
 export { validate } from './validate.js'
 

package/src/geometries/geom3/index.js

@@ -5,7 +5,7 @@
  *
  * @example
  * import { geometries } from '@jscad/modeling'
- * const myShape = geometries.geom3.fromPoints([
+ * const myShape = geometries.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]]
@@ -16,14 +16,12 @@
  */
 export { clone } from './clone.js'
 export { create } from './create.js'
-export { fromPoints } from './fromPoints.js'
-export { fromPointsConvex } from './fromPointsConvex.js'
-export { fromCompactBinary } from './fromCompactBinary.js'
+export { fromVertices } from './fromVertices.js'
+export { fromVerticesConvex } from './fromVerticesConvex.js'
 export { invert } from './invert.js'
 export { isA } from './isA.js'
-export { toPoints } from './toPoints.js'
 export { toPolygons } from './toPolygons.js'
 export { toString } from './toString.js'
-export { toCompactBinary } from './toCompactBinary.js'
+export { toVertices } from './toVertices.js'
 export { transform } from './transform.js'
 export { validate } from './validate.js'

package/src/geometries/geom3/invert.test.js

@@ -1,6 +1,6 @@
 import test from 'ava'
 
-import { invert, create, fromPoints } from './index.js'
+import { invert, create, fromVertices } from './index.js'
 
 import { comparePolygons, compareVectors } from '../../../test/helpers/index.js'
 
@@ -23,7 +23,7 @@ test('invert: Creates a invert of a populated geom3', (t) => {
     ],
     transforms: [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]
   }
-  const geometry = fromPoints(vertices)
+  const geometry = fromVertices(vertices)
   const another = invert(geometry)
   t.not(another, geometry)
   t.true(comparePolygons(another.polygons[0], expected.polygons[0]))

package/src/geometries/geom3/isA.test.js

@@ -1,10 +1,10 @@
 import test from 'ava'
 
-import { isA, create, fromPoints } from './index.js'
+import { isA, create, fromVertices } from './index.js'
 
 test('isA: identifies created geom3', (t) => {
   const p1 = create()
-  const p2 = fromPoints([[[0, 0, 0], [1, 0, 0], [1, 0, 1]]])
+  const p2 = fromVertices([[[0, 0, 0], [1, 0, 0], [1, 0, 1]]])
   t.true(isA(p1))
   t.true(isA(p2))
 })

package/src/geometries/geom3/toString.test.js

@@ -1,6 +1,6 @@
 import test from 'ava'
 
-import { create, fromPoints, toString } from './index.js'
+import { create, fromVertices, toString } from './index.js'
 
 test('toString: serialize empty geom3 into a string', (t) => {
   const geometry = create()
@@ -10,7 +10,7 @@ test('toString: serialize empty geom3 into a string', (t) => {
 })
 
 test('toString: serialize geom3 into a string', (t) => {
-  const geometry = fromPoints([[[0, 0, 3], [0, 1, 3], [2, 0, 3]]])
+  const geometry = fromVertices([[[0, 0, 3], [0, 1, 3], [2, 0, 3]]])
   const result = toString(geometry)
   const expected = 'geom3 (1 polygons):\n  poly3: [[0.0000000, 0.0000000, 3.0000000], [0.0000000, 1.0000000, 3.0000000], [2.0000000, 0.0000000, 3.0000000]]\n'
   t.is(result, expected)

package/src/geometries/geom3/{toPoints.d.ts → toVertices.d.ts}

@@ -1,4 +1,4 @@
 import type { Geom3 } from './type.d.ts'
 import type { Vec3 } from '../../maths/vec3/type.d.ts'
 
-export function toPoints(geometry: Geom3): Array<Array<Vec3>>
+export function toVertices(geometry: Geom3): Array<Array<Vec3>>

package/src/geometries/geom3/{toPoints.js → toVertices.js}

@@ -4,12 +4,13 @@ import { toPolygons } from './toPolygons.js'
 
 /**
  * Return the given geometry as a list of points, after applying transforms.
+ *
  * The returned array should not be modified as the points are shared with the geometry.
  * @param {Geom3} geometry - the geometry
  * @return {Array} list of points, where each sub-array represents a polygon
- * @alias module:modeling/geometries/geom3.toPoints
+ * @alias module:modeling/geometries/geom3.toVertices
  */
-export const toPoints = (geometry) => {
+export const toVertices = (geometry) => {
   const polygons = toPolygons(geometry)
   return polygons.map((polygon) => poly3.toVertices(polygon))
 }

package/src/geometries/geom3/{toPoints.test.js → toVertices.test.js}

@@ -1,17 +1,17 @@
 import test from 'ava'
 
-import { toPoints, fromPoints, toString } from './index.js'
+import { toVertices, fromVertices, toString } from './index.js'
 
 import { comparePolygonsAsPoints } from '../../../test/helpers/index.js'
 
-test('toPoints: Creates an array of vertices from a populated geom3', (t) => {
+test('toVertices: Creates an array of vertices from a populated geom3', (t) => {
   const vertices = [[[0, 0, 0], [1, 0, 0], [1, 0, 1]]]
-  const geometry = fromPoints(vertices)
+  const geometry = fromVertices(vertices)
 
   toString(geometry)
 
   const expected = [[[0, 0, 0], [1, 0, 0], [1, 0, 1]]]
-  const vertexList = toPoints(geometry)
+  const vertexList = toVertices(geometry)
   t.deepEqual(vertexList, expected)
   t.true(comparePolygonsAsPoints(vertexList, expected))
 

package/src/geometries/geom3/transform.test.js

@@ -2,7 +2,7 @@ import test from 'ava'
 
 import { mat4 } from '../../maths/index.js'
 
-import { transform, fromPoints, toPolygons } from './index.js'
+import { transform, fromVertices, toPolygons } from './index.js'
 
 import { comparePolygons, compareVectors } from '../../../test/helpers/index.js'
 
@@ -20,7 +20,7 @@ test('transform: Adjusts the transforms of a populated geom3', (t) => {
     ],
     transforms: [0, 1, 0, 0, -1, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]
   }
-  const geometry = fromPoints(vertices)
+  const geometry = fromVertices(vertices)
   let another = transform(rotate90, geometry)
   t.not(geometry, another)
   t.true(comparePolygons(another.polygons[0], expected.polygons[0]))

package/src/geometries/geom3/validate.test.js

@@ -1,7 +1,7 @@
 import test from 'ava'
 
 import * as vec3 from '../../maths/vec3/index.js'
-import { fromPoints, validate } from './index.js'
+import { fromVertices, validate } from './index.js'
 
 // tetrahedron
 const a = vec3.fromValues(-1, -1, 1)
@@ -11,16 +11,16 @@ const d = vec3.fromValues(1, 1, 1)
 
 test('validate: allow valid geom3', (t) => {
   // simplest valid geometry
-  const geometry = fromPoints([[a, b, c], [d, b, a], [d, a, c], [c, b, d]])
+  const geometry = fromVertices([[a, b, c], [d, b, a], [d, a, c], [c, b, d]])
   t.notThrows(() => validate(geometry))
 })
 
 test('validate: throw exception for nan', (t) => {
-  const geometry = fromPoints([[a, b, c], [d, b, a], [d, a, c], [c, b, [1, 1, NaN]]])
+  const geometry = fromVertices([[a, b, c], [d, b, a], [d, a, c], [c, b, [1, 1, NaN]]])
   t.throws(() => validate(geometry))
 })
 
 test('validate: throw exception for infinity', (t) => {
-  const geometry = fromPoints([[a, b, c], [d, b, a], [d, a, c], [c, b, [1, 1, Infinity]]])
+  const geometry = fromVertices([[a, b, c], [d, b, a], [d, a, c], [c, b, [1, 1, Infinity]]])
   t.throws(() => validate(geometry))
 })

package/src/geometries/index.d.ts

@@ -1,6 +1,7 @@
 export * as geom2 from './geom2/index.js'
 export * as geom3 from './geom3/index.js'
 export * as path2 from './path2/index.js'
+export * as path3 from './path3/index.js'
 export * as poly2 from './poly2/index.js'
 export * as poly3 from './poly3/index.js'
 export * as slice from './slice/index.js'

package/src/geometries/index.js

@@ -16,6 +16,7 @@
 export * as geom2 from './geom2/index.js'
 export * as geom3 from './geom3/index.js'
 export * as path2 from './path2/index.js'
+export * as path3 from './path3/index.js'
 export * as poly2 from './poly2/index.js'
 export * as poly3 from './poly3/index.js'
 export * as slice from './slice/index.js'

package/src/geometries/path2/create.js

@@ -21,13 +21,4 @@ import * as mat4 from '../../maths/mat4/index.js'
  * @example
  * let newPath = 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/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

@@ -16,11 +16,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/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 = 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,31 @@
+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
+ * @function
+ * @alias module:modeling/geometries/path3.close
+ */
+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,36 @@
+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
+ * @function
+ * @alias module:modeling/geometries/path3.concat
+ *
+ * @example
+ * let newPath = concat(fromVertices({}, [[1, 2, 3]]), 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)
+}