@jbroll/jscad-modeling 2.12.7

package/src/operations/transforms/align.test.js

@@ -0,0 +1,96 @@
+const test = require('ava')
+
+const { comparePoints } = require('../../../test/helpers')
+const { geom3 } = require('../../geometries')
+const { measureBoundingBox, measureAggregateBoundingBox } = require('../../measurements')
+const { cube } = require('../../primitives')
+
+const { align } = require('./index')
+
+test('align: single object returns geometry unchanged if all axes are none', (t) => {
+  const original = cube({ size: 4, center: [10, 10, 10] })
+  const aligned = align({ modes: ['none', 'none', 'none'] }, original)
+  const bounds = measureBoundingBox(aligned)
+  const expectedBounds = [[8, 8, 8], [12, 12, 12]]
+  t.notThrows(() => geom3.validate(aligned))
+  t.true(comparePoints(bounds, expectedBounds), 'Bounding box was not as expected. Result: ' + JSON.stringify(bounds))
+})
+
+test('align: single objects returns geometry aligned, different modes on each axis', (t) => {
+  const original = cube({ size: 4, center: [10, 10, 10] })
+  const aligned = align({ modes: ['center', 'min', 'max'] }, original)
+  const bounds = measureBoundingBox(aligned)
+  const expectedBounds = [[-2, 0, -4], [2, 4, 0]]
+  t.notThrows(() => geom3.validate(aligned))
+  t.true(comparePoints(bounds, expectedBounds), 'Bounding box was not as expected. Result: ' + JSON.stringify(bounds))
+})
+
+test('align: unfilled modes and relativeTo arrays return results with expected values', (t) => {
+  const original = cube({ size: 4, center: [10, 10, 10] })
+  const aligned = align({ modes: ['center'], relativeTo: [0] }, original)
+  const bounds = measureBoundingBox(aligned)
+  const expectedBounds = [[-2, 8, 8], [2, 12, 12]]
+  t.notThrows(() => geom3.validate(aligned))
+  t.true(comparePoints(bounds, expectedBounds), 'Bounding box was not as expected. Result: ' + JSON.stringify(bounds))
+})
+
+test('align: multiple objects grouped returns geometry aligned, different modes on each axis', (t) => {
+  const original = [
+    cube({ size: 4, center: [10, 10, 10] }),
+    cube({ size: 2, center: [4, 4, 4] })
+  ]
+  const aligned = align({ modes: ['center', 'min', 'max'], relativeTo: [6, -10, 0], grouped: true }, original)
+  const bounds = measureAggregateBoundingBox(aligned)
+  const expectedBounds = [[1.5, -10, -9], [10.5, -1, 0]]
+  t.notThrows(() => geom3.validate(aligned[0]))
+  t.notThrows(() => geom3.validate(aligned[1]))
+  t.true(comparePoints(bounds, expectedBounds), 'Bounding box was not as expected. Result: ' + JSON.stringify(bounds))
+})
+
+test('align: multiple objects ungrouped returns geometry aligned, different modes on each axis', (t) => {
+  const original = [
+    cube({ size: 4, center: [10, 10, 10] }),
+    cube({ size: 2, center: [4, 4, 4] })
+  ]
+  const aligned = align({ modes: ['center', 'min', 'max'], relativeTo: [30, 30, 30] }, original)
+  const bounds = measureAggregateBoundingBox(aligned)
+  const expectedBounds = [[28, 30, 26], [32, 34, 30]]
+  t.notThrows(() => geom3.validate(aligned[0]))
+  t.notThrows(() => geom3.validate(aligned[1]))
+  t.true(comparePoints(bounds, expectedBounds), 'Bounding box was not as expected. Result: ' + JSON.stringify(bounds))
+})
+
+test('align: multiple objects grouped, relativeTo is nulls, returns geometry unchanged', (t) => {
+  const original = [
+    cube({ size: 4, center: [10, 10, 10] }),
+    cube({ size: 2, center: [4, 4, 4] })
+  ]
+  const aligned = align({ modes: ['center', 'min', 'max'], relativeTo: [null, null, null], grouped: true }, original)
+  const bounds = measureAggregateBoundingBox(aligned)
+  const expectedBounds = [[3, 3, 3], [12, 12, 12]]
+  t.notThrows(() => geom3.validate(aligned[0]))
+  t.notThrows(() => geom3.validate(aligned[1]))
+  t.true(comparePoints(bounds, expectedBounds), 'Bounding box was not as expected. Result: ' + JSON.stringify(bounds))
+})
+
+test('align: multiple objects ungrouped, relativeTo is nulls, returns geometry aligned to group bounds', (t) => {
+  const original = [
+    cube({ size: 2, center: [4, 4, 4] }),
+    cube({ size: 4, center: [10, 10, 10] })
+  ]
+  const aligned = align({ modes: ['center', 'min', 'max'], relativeTo: [null, null, null], grouped: false }, original)
+  const bounds = measureAggregateBoundingBox(aligned)
+  const expectedBounds = [[5.5, 3, 8], [9.5, 7, 12]]
+  t.notThrows(() => geom3.validate(aligned[0]))
+  t.notThrows(() => geom3.validate(aligned[1]))
+  t.true(comparePoints(bounds, expectedBounds), 'Bounding box was not as expected. Result: ' + JSON.stringify(bounds))
+})
+
+test('align: throws errors on bad options', (t) => {
+  const aCube = cube({ size: 4, center: [10, 10, 10] })
+  t.throws(() => align({ grouped: 3 }, aCube), { instanceOf: Error })
+  t.throws(() => align({ relativeTo: [3, 4, 9, 12] }, aCube), { instanceOf: Error })
+  t.throws(() => align({ relativeTo: [3, 4, 'dog'] }, aCube), { instanceOf: Error })
+  t.throws(() => align({ modes: ['center', 'max', 'james'] }, aCube), { instanceOf: Error })
+  t.throws(() => align({ modes: ['center', 'max', 'min', 'none'] }, aCube), { instanceOf: Error })
+})

package/src/operations/transforms/center.d.ts

@@ -0,0 +1,24 @@
+import { Geometry } from '../../geometries/types'
+import Vec3 from '../../maths/vec3/type'
+import RecursiveArray from '../../utils/recursiveArray'
+
+export interface CenterOptions {
+  axes?: [boolean, boolean, boolean]
+  relativeTo?: Vec3
+}
+
+export function center<T extends Geometry>(options: CenterOptions, geometry: T): T
+export function center<T extends Geometry>(options: CenterOptions, ...geometries: RecursiveArray<T>): Array<T>
+export function center(options: CenterOptions, ...geometries: RecursiveArray<Geometry>): Array<Geometry>
+
+export function centerX<T extends Geometry>(geometry: T): T
+export function centerX<T extends Geometry>(...geometries: RecursiveArray<T>): Array<T>
+export function centerX(...geometries: RecursiveArray<Geometry>): Array<Geometry>
+
+export function centerY<T extends Geometry>(geometry: T): T
+export function centerY<T extends Geometry>(...geometries: RecursiveArray<T>): Array<T>
+export function centerY(...geometries: RecursiveArray<Geometry>): Array<Geometry>
+
+export function centerZ<T extends Geometry>(geometry: T): T
+export function centerZ<T extends Geometry>(...geometries: RecursiveArray<T>): Array<T>
+export function centerZ(...geometries: RecursiveArray<Geometry>): Array<Geometry>

package/src/operations/transforms/center.js

@@ -0,0 +1,90 @@
+const flatten = require('../../utils/flatten')
+
+const geom2 = require('../../geometries/geom2')
+const geom3 = require('../../geometries/geom3')
+const path2 = require('../../geometries/path2')
+
+const measureBoundingBox = require('../../measurements/measureBoundingBox')
+
+const { translate } = require('./translate')
+
+const centerGeometry = (options, object) => {
+  const defaults = {
+    axes: [true, true, true],
+    relativeTo: [0, 0, 0]
+  }
+  const { axes, relativeTo } = Object.assign({}, defaults, options)
+
+  const bounds = measureBoundingBox(object)
+  const offset = [0, 0, 0]
+  if (axes[0]) offset[0] = relativeTo[0] - (bounds[0][0] + ((bounds[1][0] - bounds[0][0]) / 2))
+  if (axes[1]) offset[1] = relativeTo[1] - (bounds[0][1] + ((bounds[1][1] - bounds[0][1]) / 2))
+  if (axes[2]) offset[2] = relativeTo[2] - (bounds[0][2] + ((bounds[1][2] - bounds[0][2]) / 2))
+  return translate(offset, object)
+}
+
+/**
+ * Center the given objects using the given options.
+ * @param {Object} options - options for centering
+ * @param {Array} [options.axes=[true,true,true]] - axis of which to center, true or false
+ * @param {Array} [options.relativeTo=[0,0,0]] - relative point of which to center the objects
+ * @param {...Object} objects - the objects to center
+ * @return {Object|Array} the centered object, or a list of centered objects
+ * @alias module:modeling/transforms.center
+ *
+ * @example
+ * let myshape = center({axes: [true,false,false]}, sphere()) // center about the X axis
+ */
+const center = (options, ...objects) => {
+  const defaults = {
+    axes: [true, true, true],
+    relativeTo: [0, 0, 0]
+  // TODO: Add additional 'methods' of centering: midpoint, centroid
+  }
+  const { axes, relativeTo } = Object.assign({}, defaults, options)
+
+  objects = flatten(objects)
+  if (objects.length === 0) throw new Error('wrong number of arguments')
+  if (relativeTo.length !== 3) throw new Error('relativeTo must be an array of length 3')
+
+  options = { axes, relativeTo }
+
+  const results = objects.map((object) => {
+    if (path2.isA(object)) return centerGeometry(options, object)
+    if (geom2.isA(object)) return centerGeometry(options, object)
+    if (geom3.isA(object)) return centerGeometry(options, object)
+    return object
+  })
+  return results.length === 1 ? results[0] : results
+}
+
+/**
+ * Center the given objects about the X axis.
+ * @param {...Object} objects - the objects to center
+ * @return {Object|Array} the centered object, or a list of centered objects
+ * @alias module:modeling/transforms.centerX
+ */
+const centerX = (...objects) => center({ axes: [true, false, false] }, objects)
+
+/**
+ * Center the given objects about the Y axis.
+ * @param {...Object} objects - the objects to center
+ * @return {Object|Array} the centered object, or a list of centered objects
+ * @alias module:modeling/transforms.centerY
+ */
+const centerY = (...objects) => center({ axes: [false, true, false] }, objects)
+
+/**
+ * Center the given objects about the Z axis.
+ * @param {...Object} objects - the objects to center
+ * @return {Object|Array} the centered object, or a list of centered objects
+ * @alias module:modeling/transforms.centerZ
+ */
+const centerZ = (...objects) => center({ axes: [false, false, true] }, objects)
+
+module.exports = {
+  center,
+  centerX,
+  centerY,
+  centerZ
+}

package/src/operations/transforms/center.test.js

@@ -0,0 +1,128 @@
+const test = require('ava')
+
+const { comparePoints, comparePolygonsAsPoints } = require('../../../test/helpers')
+
+const { geom2, geom3, path2 } = require('../../geometries')
+
+const { center, centerX, centerY, centerZ } = require('./index')
+
+test('center: centering of a path2 produces expected changes to points', (t) => {
+  const geometry = path2.fromPoints({}, [[5, 0], [0, 3], [-1, 0]])
+
+  // center about X
+  let centered = center({ axes: [true, false, false] }, geometry)
+  let pts = path2.toPoints(centered)
+  const exp = [[3, 0], [-2, 3], [-3, 0]]
+  t.notThrows(() => path2.validate(centered))
+  t.true(comparePoints(pts, exp))
+
+  centered = centerX(geometry)
+  pts = path2.toPoints(centered)
+  t.notThrows(() => path2.validate(centered))
+  t.true(comparePoints(pts, exp))
+})
+
+test('center: centering of a geom2 produces expected changes to points', (t) => {
+  const geometry = geom2.fromPoints([[0, 0], [10, 0], [0, 10]])
+
+  // center about Y
+  let centered = center({ axes: [false, true, false] }, geometry)
+  let pts = geom2.toPoints(centered)
+  const exp = [[0, -5], [10, -5], [0, 5]]
+  t.notThrows(() => geom2.validate(centered))
+  t.true(comparePoints(pts, exp))
+
+  centered = centerY(geometry)
+  pts = geom2.toPoints(centered)
+  t.notThrows(() => geom2.validate(centered))
+  t.true(comparePoints(pts, exp))
+})
+
+test('center: centering of a geom3 produces expected changes to polygons', (t) => {
+  const points = [
+    [[-2, -7, -12], [-2, -7, 18], [-2, 13, 18], [-2, 13, -12]],
+    [[8, -7, -12], [8, 13, -12], [8, 13, 18], [8, -7, 18]],
+    [[-2, -7, -12], [8, -7, -12], [8, -7, 18], [-2, -7, 18]],
+    [[-2, 13, -12], [-2, 13, 18], [8, 13, 18], [8, 13, -12]],
+    [[-2, -7, -12], [-2, 13, -12], [8, 13, -12], [8, -7, -12]],
+    [[-2, -7, 18], [8, -7, 18], [8, 13, 18], [-2, 13, 18]]
+  ]
+  const geometry = geom3.fromPoints(points)
+
+  // center about X
+  let centered = center({ axes: [true, false, false] }, geometry)
+  let pts = geom3.toPoints(centered)
+  let exp = [
+    [[-5, -7, -12], [-5, -7, 18], [-5, 13, 18], [-5, 13, -12]],
+    [[5, -7, -12], [5, 13, -12], [5, 13, 18], [5, -7, 18]],
+    [[-5, -7, -12], [5, -7, -12], [5, -7, 18], [-5, -7, 18]],
+    [[-5, 13, -12], [-5, 13, 18], [5, 13, 18], [5, 13, -12]],
+    [[-5, -7, -12], [-5, 13, -12], [5, 13, -12], [5, -7, -12]],
+    [[-5, -7, 18], [5, -7, 18], [5, 13, 18], [-5, 13, 18]]
+  ]
+  t.notThrows(() => geom3.validate(centered))
+  t.true(comparePolygonsAsPoints(pts, exp))
+
+  centered = centerX(geometry)
+  pts = geom3.toPoints(centered)
+  t.notThrows(() => geom3.validate(centered))
+  t.true(comparePolygonsAsPoints(pts, exp))
+
+  // center about Y
+  centered = center({ axes: [false, true, false] }, geometry)
+  pts = geom3.toPoints(centered)
+  exp = [
+    [[-2, -10, -12], [-2, -10, 18], [-2, 10, 18], [-2, 10, -12]],
+    [[8, -10, -12], [8, 10, -12], [8, 10, 18], [8, -10, 18]],
+    [[-2, -10, -12], [8, -10, -12], [8, -10, 18], [-2, -10, 18]],
+    [[-2, 10, -12], [-2, 10, 18], [8, 10, 18], [8, 10, -12]],
+    [[-2, -10, -12], [-2, 10, -12], [8, 10, -12], [8, -10, -12]],
+    [[-2, -10, 18], [8, -10, 18], [8, 10, 18], [-2, 10, 18]]
+  ]
+  t.notThrows(() => geom3.validate(centered))
+  t.true(comparePolygonsAsPoints(pts, exp))
+
+  centered = centerY(geometry)
+  pts = geom3.toPoints(centered)
+  t.notThrows(() => geom3.validate(centered))
+  t.true(comparePolygonsAsPoints(pts, exp))
+
+  // center about Z
+  centered = center({ axes: [false, false, true] }, geometry)
+  pts = geom3.toPoints(centered)
+  exp = [
+    [[-2, -7, -15], [-2, -7, 15], [-2, 13, 15], [-2, 13, -15]],
+    [[8, -7, -15], [8, 13, -15], [8, 13, 15], [8, -7, 15]],
+    [[-2, -7, -15], [8, -7, -15], [8, -7, 15], [-2, -7, 15]],
+    [[-2, 13, -15], [-2, 13, 15], [8, 13, 15], [8, 13, -15]],
+    [[-2, -7, -15], [-2, 13, -15], [8, 13, -15], [8, -7, -15]],
+    [[-2, -7, 15], [8, -7, 15], [8, 13, 15], [-2, 13, 15]]
+  ]
+  t.notThrows(() => geom3.validate(centered))
+  t.true(comparePolygonsAsPoints(pts, exp))
+
+  centered = centerZ(geometry)
+  pts = geom3.toPoints(centered)
+  t.notThrows(() => geom3.validate(centered))
+  t.true(comparePolygonsAsPoints(pts, exp))
+})
+
+test('center: centering of multiple objects produces expected changes', (t) => {
+  const junk = 'hello'
+  const geometry1 = path2.fromPoints({}, [[-5, 5], [5, 5], [-5, -5], [10, -5]])
+  const geometry2 = geom2.fromPoints([[-5, -5], [0, 5], [10, -5]])
+
+  const centered = center({ axes: [true, true, false], relativeTo: [10, 15, 0] }, junk, geometry1, geometry2)
+
+  t.is(centered[0], junk)
+
+  const pts1 = path2.toPoints(centered[1])
+  const exp1 = [[2.5, 20], [12.5, 20], [2.5, 10], [17.5, 10]]
+  t.notThrows(() => path2.validate(centered[1]))
+  t.true(comparePoints(pts1, exp1))
+
+  const pts2 = geom2.toPoints(centered[2])
+  const exp2 = [[2.5, 10], [7.5, 20], [17.5, 10]]
+  t.notThrows(() => geom2.validate(centered[2]))
+  t.true(comparePoints(pts2, exp2))
+})

package/src/operations/transforms/index.d.ts

@@ -0,0 +1,9 @@
+export { default as align, AlignOptions } from './align'
+export * from './center'
+export * from './mirror'
+export * from './rotate'
+export * from './scale'
+export * from './transform'
+export * from './translate'
+
+export as namespace transforms

package/src/operations/transforms/index.js

@@ -0,0 +1,37 @@
+/**
+ * All shapes (primitives or the results of operations) can be transformed, such as scaled or rotated.
+ * In all cases, the function returns the results, and never changes the original shapes.
+ * @module modeling/transforms
+ * @example
+ * const { center, rotateX, translate } = require('@jscad/modeling').transforms
+ */
+module.exports = {
+  align: require('./align'),
+
+  center: require('./center').center,
+  centerX: require('./center').centerX,
+  centerY: require('./center').centerY,
+  centerZ: require('./center').centerZ,
+
+  mirror: require('./mirror').mirror,
+  mirrorX: require('./mirror').mirrorX,
+  mirrorY: require('./mirror').mirrorY,
+  mirrorZ: require('./mirror').mirrorZ,
+
+  rotate: require('./rotate').rotate,
+  rotateX: require('./rotate').rotateX,
+  rotateY: require('./rotate').rotateY,
+  rotateZ: require('./rotate').rotateZ,
+
+  scale: require('./scale').scale,
+  scaleX: require('./scale').scaleX,
+  scaleY: require('./scale').scaleY,
+  scaleZ: require('./scale').scaleZ,
+
+  transform: require('./transform'),
+
+  translate: require('./translate').translate,
+  translateX: require('./translate').translateX,
+  translateY: require('./translate').translateY,
+  translateZ: require('./translate').translateZ
+}

package/src/operations/transforms/mirror.d.ts

@@ -0,0 +1,24 @@
+import { Geometry } from '../../geometries/types'
+import { Vec3 } from '../../maths/types'
+import RecursiveArray from '../../utils/recursiveArray'
+
+export interface MirrorOptions {
+  origin?: Vec3
+  normal?: Vec3
+}
+
+export function mirror<T extends Geometry>(options: MirrorOptions, geometry: T): T
+export function mirror<T extends Geometry>(options: MirrorOptions, ...geometries: RecursiveArray<T>): Array<T>
+export function mirror(options: MirrorOptions, ...geometries: RecursiveArray<Geometry>): Array<Geometry>
+
+export function mirrorX<T extends Geometry>(geometry: T): T
+export function mirrorX<T extends Geometry>(...geometries: RecursiveArray<T>): Array<T>
+export function mirrorX(...geometries: RecursiveArray<Geometry>): Array<Geometry>
+
+export function mirrorY<T extends Geometry>(geometry: T): T
+export function mirrorY<T extends Geometry>(...geometries: RecursiveArray<T>): Array<T>
+export function mirrorY(...geometries: RecursiveArray<Geometry>): Array<Geometry>
+
+export function mirrorZ<T extends Geometry>(geometry: T): T
+export function mirrorZ<T extends Geometry>(...geometries: RecursiveArray<T>): Array<T>
+export function mirrorZ(...geometries: RecursiveArray<Geometry>): Array<Geometry>

package/src/operations/transforms/mirror.js

@@ -0,0 +1,78 @@
+const flatten = require('../../utils/flatten')
+
+const mat4 = require('../../maths/mat4')
+const plane = require('../../maths/plane')
+
+const geom2 = require('../../geometries/geom2')
+const geom3 = require('../../geometries/geom3')
+const path2 = require('../../geometries/path2')
+
+/**
+ * Mirror the given objects using the given options.
+ * @param {Object} options - options for mirror
+ * @param {Array} [options.origin=[0,0,0]] - the origin of the plane
+ * @param {Array} [options.normal=[0,0,1]] - the normal vector of the plane
+ * @param {...Object} objects - the objects to mirror
+ * @return {Object|Array} the mirrored object, or a list of mirrored objects
+ * @alias module:modeling/transforms.mirror
+ *
+ * @example
+ * let myshape = mirror({normal: [0,0,10]}, cube({center: [0,0,15], radius: [20, 25, 5]}))
+ */
+const mirror = (options, ...objects) => {
+  const defaults = {
+    origin: [0, 0, 0],
+    normal: [0, 0, 1] // Z axis
+  }
+  const { origin, normal } = Object.assign({}, defaults, options)
+
+  objects = flatten(objects)
+  if (objects.length === 0) throw new Error('wrong number of arguments')
+
+  const planeOfMirror = plane.fromNormalAndPoint(plane.create(), normal, origin)
+  // verify the plane, i.e. check that the given normal was valid
+  if (Number.isNaN(planeOfMirror[0])) {
+    throw new Error('the given origin and normal do not define a proper plane')
+  }
+
+  const matrix = mat4.mirrorByPlane(mat4.create(), planeOfMirror)
+
+  const results = objects.map((object) => {
+    if (path2.isA(object)) return path2.transform(matrix, object)
+    if (geom2.isA(object)) return geom2.transform(matrix, object)
+    if (geom3.isA(object)) return geom3.transform(matrix, object)
+    return object
+  })
+  return results.length === 1 ? results[0] : results
+}
+
+/**
+ * Mirror the given objects about the X axis.
+ * @param {...Object} objects - the objects to mirror
+ * @return {Object|Array} the mirrored object, or a list of mirrored objects
+ * @alias module:modeling/transforms.mirrorX
+ */
+const mirrorX = (...objects) => mirror({ normal: [1, 0, 0] }, objects)
+
+/**
+ * Mirror the given objects about the Y axis.
+ * @param {...Object} objects - the geometries to mirror
+ * @return {Object|Array} the mirrored object, or a list of mirrored objects
+ * @alias module:modeling/transforms.mirrorY
+ */
+const mirrorY = (...objects) => mirror({ normal: [0, 1, 0] }, objects)
+
+/**
+ * Mirror the given objects about the Z axis.
+ * @param {...Object} objects - the geometries to mirror
+ * @return {Object|Array} the mirrored object, or a list of mirrored objects
+ * @alias module:modeling/transforms.mirrorZ
+ */
+const mirrorZ = (...objects) => mirror({ normal: [0, 0, 1] }, objects)
+
+module.exports = {
+  mirror,
+  mirrorX,
+  mirrorY,
+  mirrorZ
+}

package/src/operations/transforms/mirror.test.js

@@ -0,0 +1,158 @@
+const test = require('ava')
+
+const { comparePoints, comparePolygonsAsPoints } = require('../../../test/helpers')
+
+const { measureArea } = require('../../measurements')
+
+const { geom2, geom3, path2 } = require('../../geometries')
+
+const { mirror, mirrorX, mirrorY, mirrorZ } = require('./index')
+
+test('mirror: mirroring of path2 about X/Y produces expected changes to points', (t) => {
+  const geometry = path2.fromPoints({}, [[-5, 5], [5, 5], [-5, -5], [10, -5]])
+
+  // mirror about X
+  let mirrored = mirror({ normal: [1, 0, 0] }, geometry)
+  let obs = path2.toPoints(mirrored)
+  let exp = [[5, 5], [-5, 5], [5, -5], [-10, -5]]
+  t.notThrows(() => path2.validate(mirrored))
+  t.true(comparePoints(obs, exp))
+
+  mirrored = mirrorX(geometry)
+  obs = path2.toPoints(mirrored)
+  t.notThrows(() => path2.validate(mirrored))
+  t.true(comparePoints(obs, exp))
+
+  // mirror about Y
+  mirrored = mirror({ normal: [0, 1, 0] }, geometry)
+  obs = path2.toPoints(mirrored)
+  exp = [[-5, -5], [5, -5], [-5, 5], [10, 5]]
+  t.notThrows(() => path2.validate(mirrored))
+  t.true(comparePoints(obs, exp))
+
+  mirrored = mirrorY(geometry)
+  obs = path2.toPoints(mirrored)
+  t.notThrows(() => path2.validate(mirrored))
+  t.true(comparePoints(obs, exp))
+})
+
+test('mirror: mirroring of geom2 about X/Y produces expected changes to points', (t) => {
+  const geometry = geom2.fromPoints([[-5, -5], [0, 5], [10, -5]])
+
+  // mirror about X
+  let mirrored = mirror({ normal: [1, 0, 0] }, geometry)
+  let obs = geom2.toPoints(mirrored)
+  let exp = [[0, 5], [5, -5], [-10, -5]]
+  t.notThrows(() => geom2.validate(mirrored))
+  t.is(measureArea(mirrored), measureArea(geometry))
+  t.true(comparePoints(obs, exp))
+
+  mirrored = mirrorX(geometry)
+  obs = geom2.toPoints(mirrored)
+  t.notThrows(() => geom2.validate(mirrored))
+  t.is(measureArea(mirrored), measureArea(geometry))
+  t.true(comparePoints(obs, exp))
+
+  // mirror about Y
+  mirrored = mirror({ normal: [0, 1, 0] }, geometry)
+  obs = geom2.toPoints(mirrored)
+  exp = [[0, -5], [-5, 5], [10, 5]]
+  t.notThrows(() => geom2.validate(mirrored))
+  t.is(measureArea(mirrored), measureArea(geometry))
+  t.true(comparePoints(obs, exp))
+
+  mirrored = mirrorY(geometry)
+  obs = geom2.toPoints(mirrored)
+  t.notThrows(() => geom2.validate(mirrored))
+  t.is(measureArea(mirrored), measureArea(geometry))
+  t.true(comparePoints(obs, exp))
+})
+
+test('mirror: mirroring of geom3 about X/Y/Z produces expected changes to polygons', (t) => {
+  const points = [
+    [[-2, -7, -12], [-2, -7, 18], [-2, 13, 18], [-2, 13, -12]],
+    [[8, -7, -12], [8, 13, -12], [8, 13, 18], [8, -7, 18]],
+    [[-2, -7, -12], [8, -7, -12], [8, -7, 18], [-2, -7, 18]],
+    [[-2, 13, -12], [-2, 13, 18], [8, 13, 18], [8, 13, -12]],
+    [[-2, -7, -12], [-2, 13, -12], [8, 13, -12], [8, -7, -12]],
+    [[-2, -7, 18], [8, -7, 18], [8, 13, 18], [-2, 13, 18]]
+  ]
+  const geometry = geom3.fromPoints(points)
+
+  // mirror about X
+  let mirrored = mirror({ normal: [1, 0, 0] }, geometry)
+  let obs = geom3.toPoints(mirrored)
+  let exp = [
+    [[2, 13, -12], [2, 13, 18], [2, -7, 18], [2, -7, -12]],
+    [[-8, -7, 18], [-8, 13, 18], [-8, 13, -12], [-8, -7, -12]],
+    [[2, -7, 18], [-8, -7, 18], [-8, -7, -12], [2, -7, -12]],
+    [[-8, 13, -12], [-8, 13, 18], [2, 13, 18], [2, 13, -12]],
+    [[-8, -7, -12], [-8, 13, -12], [2, 13, -12], [2, -7, -12]],
+    [[2, 13, 18], [-8, 13, 18], [-8, -7, 18], [2, -7, 18]]
+  ]
+  t.notThrows(() => geom3.validate(mirrored))
+  t.true(comparePolygonsAsPoints(obs, exp))
+  t.deepEqual(obs, exp)
+
+  mirrored = mirrorX(geometry)
+  obs = geom3.toPoints(mirrored)
+  t.notThrows(() => geom3.validate(mirrored))
+  t.true(comparePolygonsAsPoints(obs, exp))
+
+  // mirror about Y
+  mirrored = mirror({ normal: [0, 1, 0] }, geometry)
+  obs = geom3.toPoints(mirrored)
+  exp = [
+    [[-2, -13, -12], [-2, -13, 18], [-2, 7, 18], [-2, 7, -12]],
+    [[8, 7, 18], [8, -13, 18], [8, -13, -12], [8, 7, -12]],
+    [[-2, 7, 18], [8, 7, 18], [8, 7, -12], [-2, 7, -12]],
+    [[8, -13, -12], [8, -13, 18], [-2, -13, 18], [-2, -13, -12]],
+    [[8, 7, -12], [8, -13, -12], [-2, -13, -12], [-2, 7, -12]],
+    [[-2, -13, 18], [8, -13, 18], [8, 7, 18], [-2, 7, 18]]
+  ]
+  t.notThrows(() => geom3.validate(mirrored))
+  t.true(comparePolygonsAsPoints(obs, exp))
+
+  mirrored = mirrorY(geometry)
+  obs = geom3.toPoints(mirrored)
+  t.notThrows(() => geom3.validate(mirrored))
+  t.true(comparePolygonsAsPoints(obs, exp))
+
+  // mirror about Z
+  mirrored = mirror({ normal: [0, 0, 1] }, geometry)
+  obs = geom3.toPoints(mirrored)
+  exp = [
+    [[-2, 13, 12], [-2, 13, -18], [-2, -7, -18], [-2, -7, 12]],
+    [[8, -7, -18], [8, 13, -18], [8, 13, 12], [8, -7, 12]],
+    [[-2, -7, -18], [8, -7, -18], [8, -7, 12], [-2, -7, 12]],
+    [[8, 13, 12], [8, 13, -18], [-2, 13, -18], [-2, 13, 12]],
+    [[8, -7, 12], [8, 13, 12], [-2, 13, 12], [-2, -7, 12]],
+    [[-2, 13, -18], [8, 13, -18], [8, -7, -18], [-2, -7, -18]]
+  ]
+  t.notThrows(() => geom3.validate(mirrored))
+  t.true(comparePolygonsAsPoints(obs, exp))
+
+  mirrored = mirrorZ(geometry)
+  obs = geom3.toPoints(mirrored)
+  t.notThrows(() => geom3.validate(mirrored))
+  t.true(comparePolygonsAsPoints(obs, exp))
+})
+
+test('mirror: mirroring of multiple objects produces an array of mirrored objects', (t) => {
+  const junk = 'hello'
+  const geometry1 = path2.fromPoints({}, [[-5, 5], [5, 5], [-5, -5], [10, -5]])
+  const geometry2 = geom2.fromPoints([[-5, -5], [0, 5], [10, -5]])
+
+  const mirrored = mirror({ normal: [0, 1, 0] }, junk, geometry1, geometry2)
+  t.is(mirrored[0], junk)
+
+  let obs = path2.toPoints(mirrored[1])
+  let exp = [[-5, -5], [5, -5], [-5, 5], [10, 5]]
+  t.notThrows(() => path2.validate(mirrored[1]))
+  t.true(comparePoints(obs, exp))
+
+  obs = geom2.toPoints(mirrored[2])
+  exp = [[0, -5], [-5, 5], [10, 5]]
+  t.notThrows(() => geom2.validate(mirrored[2]))
+  t.true(comparePoints(obs, exp))
+})

package/src/operations/transforms/rotate.d.ts

@@ -0,0 +1,19 @@
+import { Geometry } from '../../geometries/types'
+import { Vec1, Vec2, Vec3 } from '../../maths/types'
+import RecursiveArray from '../../utils/recursiveArray'
+
+export function rotate<T extends Geometry>(angles: Vec1 | Vec2 | Vec3, geometry: T): T
+export function rotate<T extends Geometry>(angles: Vec1 | Vec2 | Vec3, ...geometries: RecursiveArray<T>): Array<T>
+export function rotate(angles: Vec1 | Vec2 | Vec3, ...geometries: RecursiveArray<Geometry>): Array<Geometry>
+
+export function rotateX<T extends Geometry>(angle: number, geometry: T): T
+export function rotateX<T extends Geometry>(angle: number, ...geometries: RecursiveArray<T>): Array<T>
+export function rotateX(angle: number, ...geometries: RecursiveArray<Geometry>): Array<Geometry>
+
+export function rotateY<T extends Geometry>(angle: number, geometry: T): T
+export function rotateY<T extends Geometry>(angle: number, ...geometries: RecursiveArray<T>): Array<T>
+export function rotateY(angle: number, ...geometries: RecursiveArray<Geometry>): Array<Geometry>
+
+export function rotateZ<T extends Geometry>(angle: number, geometry: T): T
+export function rotateZ<T extends Geometry>(angle: number, ...geometries: RecursiveArray<T>): Array<T>
+export function rotateZ(angle: number, ...geometries: RecursiveArray<Geometry>): Array<Geometry>