@jbroll/jscad-modeling 2.12.7

package/src/curves/bezier/lengths.js

@@ -0,0 +1,56 @@
+const valueAt = require('./valueAt')
+
+/**
+ * Divides the bezier curve into line segments and returns the cumulative length of those segments as an array.
+ * Utility function used to calculate the curve's approximate length and determine the equivalence between arc length and time.
+ *
+ * @example
+ * const b = bezier.create([[0, 0], [0, 10]]);
+ * const totalLength = lengths(100, b).pop(); // the last element of the array is the curve's approximate length
+ *
+ * @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.
+ */
+const lengths = (segments, bezier) => {
+  let sum = 0
+  const lengths = [0]
+  let previous = valueAt(0, bezier)
+  for (let index = 1; index <= segments; index++) {
+    const current = valueAt(index / segments, bezier)
+    sum += distanceBetween(current, previous)
+    lengths.push(sum)
+    previous = current
+  }
+  return lengths
+}
+
+/**
+ * Calculates the Euclidean distance between two n-dimensional points.
+ *
+ * @example
+ * const distance = distanceBetween([0, 0], [0, 10]); // calculate distance between 2D points
+ * console.log(distance); // output 10
+ *
+ * @param {Array} a - first operand.
+ * @param {Array} b - second operand.
+ * @returns {Number} - distance.
+ */
+const distanceBetween = (a, b) => {
+  if (Number.isFinite(a) && Number.isFinite(b)) {
+    return Math.abs(a - b)
+  } else if (Array.isArray(a) && Array.isArray(b)) {
+    if (a.length !== b.length) {
+      throw new Error('The operands must have the same number of dimensions.')
+    }
+    let sum = 0
+    for (let i = 0; i < a.length; i++) {
+      sum += (b[i] - a[i]) * (b[i] - a[i])
+    }
+    return Math.sqrt(sum)
+  } else {
+    throw new Error('The operands must be of the same type, either number or array.')
+  }
+}
+
+module.exports = lengths

package/src/curves/bezier/lengths.test.js

@@ -0,0 +1,78 @@
+const test = require('ava')
+
+const { bezier } = require('../index')
+const lengths = require('./lengths')
+
+const { nearlyEqual } = require('../../../test/helpers/index')
+
+test('calculate lengths for a 1D linear bezier with numeric control points', (t) => {
+  const bezierCurve = bezier.create([0, 10])
+  const result = lengths(100, bezierCurve)
+  t.is(result.length, 101) // with the default number of segments (100) the length of the array should be 101
+  nearlyEqual(t, result[0], 0, 0.0001) // first element is always 0
+  nearlyEqual(t, result[50], 5, 0.0001) // the mid element contains half the curve length
+  nearlyEqual(t, result[100], 10, 0.0001) // the last element of the array contains the entire curve length
+})
+
+test('calculate lengths for a 1D linear bezier with array control points', (t) => {
+  const bezierCurve = bezier.create([[0], [10]])
+  const result = lengths(100, bezierCurve)
+  t.is(result.length, 101)
+  nearlyEqual(t, result[0], 0, 0.0001)
+  nearlyEqual(t, result[50], 5, 0.0001)
+  nearlyEqual(t, result[100], 10, 0.0001)
+})
+
+test('calculate lengths for a 2D linear bezier', (t) => {
+  const bezierCurve = bezier.create([[0, 0], [10, 10]])
+  const result = lengths(100, bezierCurve)
+  t.is(result.length, 101)
+  nearlyEqual(t, result[0], 0, 0.0001)
+  nearlyEqual(t, result[50], 7.0710, 0.0001)
+  nearlyEqual(t, result[100], 14.1421, 0.0001)
+})
+
+test('calculate lengths for a 2D quadratic (3 control points) bezier', (t) => {
+  const bezierCurve = bezier.create([[0, 0], [0, 10], [10, 10]])
+  const result = lengths(100, bezierCurve)
+  t.is(result.length, 101)
+  nearlyEqual(t, result[0], 0, 0.0001)
+  nearlyEqual(t, result[50], 8.1160, 0.0001)
+  nearlyEqual(t, result[100], 16.2320, 0.0001)
+})
+
+test('calculate lengths for a 2D cubic (4 control points) bezier', (t) => {
+  const bezierCurve = bezier.create([[0, 0], [0, 10], [10, 10], [10, 0]])
+  const result = lengths(100, bezierCurve)
+  t.is(result.length, 101)
+  nearlyEqual(t, result[0], 0, 0.0001)
+  nearlyEqual(t, result[50], 9.9996, 0.0001)
+  nearlyEqual(t, result[100], 19.9992, 0.0001)
+})
+
+test('calculate lengths for a 3D linear bezier', (t) => {
+  const bezierCurve = bezier.create([[0, 0, 0], [10, 10, 10]])
+  const result = lengths(100, bezierCurve)
+  t.is(result.length, 101)
+  nearlyEqual(t, result[0], 0, 0.0001)
+  nearlyEqual(t, result[50], 8.6602, 0.0001)
+  nearlyEqual(t, result[100], 17.3205, 0.0001)
+})
+
+test('calculate lengths for a 3D quadratic (3 control points) bezier', (t) => {
+  const bezierCurve = bezier.create([[0, 0, 0], [5, 5, 5], [0, 0, 10]])
+  const result = lengths(100, bezierCurve)
+  t.is(result.length, 101)
+  nearlyEqual(t, result[0], 0, 0.0001)
+  nearlyEqual(t, result[50], 6.3562, 0.0001)
+  nearlyEqual(t, result[100], 12.7125, 0.0001)
+})
+
+test('calculate lengths for a 3D cubic (4 control points) bezier', (t) => {
+  const bezierCurve = bezier.create([[0, 0, 0], [5, 5, 5], [0, 0, 10], [-5, -5, 5]])
+  const result = lengths(100, bezierCurve)
+  t.is(result.length, 101)
+  nearlyEqual(t, result[0], 0, 0.0001)
+  nearlyEqual(t, result[50], 7.7617, 0.0001)
+  nearlyEqual(t, result[100], 17.2116, 0.0001)
+})

package/src/curves/bezier/tangentAt.d.ts

@@ -0,0 +1,5 @@
+import Bezier from './type'
+
+export default tangentAt
+
+declare function tangentAt(t: number, bezier: Bezier): Array<number> | number

package/src/curves/bezier/tangentAt.js

@@ -0,0 +1,45 @@
+/**
+ * Calculates the tangent at a specific position along a bezier easing curve.
+ * For multidimensional curves, the tangent is the slope of each dimension at that point.
+ * See the example called extrudeAlongPath.js
+ *
+ * @example
+ * const b = bezier.create([[0,0,0], [0,5,10], [10,0,-5], [10,10,10]]) // a cubic 3 dimensional easing curve that can generate position arrays for modelling
+ * let tangent = bezier.tangentAt(t, b)
+ *
+ * @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
+ */
+const tangentAt = (t, bezier) => {
+  if (t < 0 || t > 1) {
+    throw new Error('Bezier tangentAt() input must be between 0 and 1')
+  }
+  if (bezier.pointType === 'float_single') {
+    return bezierTangent(bezier, bezier.points, t)
+  } else {
+    const result = []
+    for (let i = 0; i < bezier.dimensions; i++) {
+      const singleDimensionPoints = []
+      for (let j = 0; j < bezier.points.length; j++) {
+        singleDimensionPoints.push(bezier.points[j][i])
+      }
+      result.push(bezierTangent(bezier, singleDimensionPoints, t))
+    }
+    return result
+  }
+}
+
+const bezierTangent = function (bezier, p, t) {
+  // from https://pages.mtu.edu/~shene/COURSES/cs3621/NOTES/spline/Bezier/bezier-der.html
+  const n = p.length - 1
+  let result = 0
+  for (let i = 0; i < n; i++) {
+    const q = n * (p[i + 1] - p[i])
+    result += bezier.tangentPermutations[i] * Math.pow(1 - t, n - 1 - i) * Math.pow(t, i) * q
+  }
+  return result
+}
+
+module.exports = tangentAt

package/src/curves/bezier/tangentAt.test.js

@@ -0,0 +1,63 @@
+const test = require('ava')
+
+const { bezier } = require('../index')
+
+test('Linear bezier (straight line between two points)', (t) => {
+  const straightLine = bezier.create([10, 20])
+  t.is(bezier.tangentAt(0, straightLine), 10)
+  t.is(bezier.tangentAt(0.5, straightLine), 10)
+  t.is(bezier.tangentAt(1, straightLine), 10)
+})
+
+test('bezier with non-numbers throws error', (t) => {
+  t.throws(() => bezier.create(['what', 20]), { instanceOf: Error })
+})
+
+test('quadratic bezier (3 control points)', (t) => {
+  const OneDCurve = bezier.create([0, 10, 20])
+  t.is(bezier.tangentAt(0, OneDCurve), 20)
+  t.is(bezier.tangentAt(0.5, OneDCurve), 20)
+  t.is(bezier.tangentAt(1, OneDCurve), 20)
+})
+
+test('quadratic bezier (3 control points, non symmetric)', (t) => {
+  const OneDCurve = bezier.create([0, 0, 20])
+  t.is(bezier.tangentAt(0, OneDCurve), 0)
+  t.is(bezier.tangentAt(0.5, OneDCurve), 20)
+  t.is(bezier.tangentAt(1, OneDCurve), 40)
+})
+
+test('quadratic bezier (4 control points)', (t) => {
+  const OneDCurve = bezier.create([0, 0, 20, 20])
+  t.is(bezier.tangentAt(0, OneDCurve), 0)
+  t.is(bezier.tangentAt(0.5, OneDCurve), 30)
+  t.is(bezier.tangentAt(1, OneDCurve), 0)
+})
+
+test('bezier with numbers and array of numbers throws error', (t) => {
+  t.throws(() => bezier.create([[0, 5, 10], 20]), { instanceOf: Error })
+})
+
+test('bezier with array of numbers of different size throws error', (t) => {
+  t.throws(() => bezier.create([[0, 5, 10], [20, 0]]), { instanceOf: Error })
+})
+
+test('quadratic bezier one dimension, 3 control points', (t) => {
+  const OneDCurve = bezier.create([[0], [10], [20]])
+  t.deepEqual(bezier.tangentAt(0, OneDCurve), [20])
+  t.deepEqual(bezier.tangentAt(0.5, OneDCurve), [20])
+  t.deepEqual(bezier.tangentAt(1, OneDCurve), [20])
+})
+
+test('quadratic bezier 2 dimensions, 3 control points', (t) => {
+  const TwoDCurve = bezier.create([[0, 10], [30, 10], [60, 20]])
+  t.deepEqual(bezier.tangentAt(0, TwoDCurve), [60, 0])
+  t.deepEqual(bezier.tangentAt(0.5, TwoDCurve), [60, 10])
+  t.deepEqual(bezier.tangentAt(1, TwoDCurve), [60, 20])
+})
+
+test('bezier throws error when t is not between 0 and 1', (t) => {
+  const straightLine = bezier.create([0, 20])
+  t.throws(() => bezier.tangentAt(-2, straightLine), { instanceOf: Error })
+  t.throws(() => bezier.tangentAt(1.1, straightLine), { instanceOf: Error })
+})

package/src/curves/bezier/type.d.ts

@@ -0,0 +1,9 @@
+export default Bezier
+
+declare interface Bezier {
+  points: Array<number> | Array<Array<number>>
+  pointType: string
+  dimensions: number
+  permutations: Array<number>
+  tangentPermutations: Array<number>
+}

package/src/curves/bezier/valueAt.d.ts

@@ -0,0 +1,5 @@
+import Bezier from './type'
+
+export default valueAt
+
+declare function valueAt(t: number, bezier: Bezier): Array<number> | number

package/src/curves/bezier/valueAt.js

@@ -0,0 +1,44 @@
+/**
+ * Calculates the value at a specific position along a bezier easing curve.
+ * For multidimensional curves, the tangent is the slope of each dimension at that point.
+ * See the example called extrudeAlongPath.js to see this in use.
+ * Math and explanation comes from {@link https://www.freecodecamp.org/news/nerding-out-with-bezier-curves-6e3c0bc48e2f/}
+ *
+ * @example
+ * const b = bezier.create([0,0,0], [0,5,10], [10,0,-5], [10,10,10]]) // a cubic 3 dimensional easing curve that can generate position arrays for modelling
+ * let position = bezier.valueAt(t,b) // where 0 < t < 1
+ *
+ * @param {number} t : the position of which to calculate the value; 0 < t < 1
+ * @param {Object} bezier : a bezier curve created with bezier.create().
+ * @returns {array | number} the value at the requested position.
+ * @alias module:modeling/curves/bezier.valueAt
+ */
+const valueAt = (t, bezier) => {
+  if (t < 0 || t > 1) {
+    throw new Error('Bezier valueAt() input must be between 0 and 1')
+  }
+  if (bezier.pointType === 'float_single') {
+    return bezierFunction(bezier, bezier.points, t)
+  } else {
+    const result = []
+    for (let i = 0; i < bezier.dimensions; i++) {
+      const singleDimensionPoints = []
+      for (let j = 0; j < bezier.points.length; j++) {
+        singleDimensionPoints.push(bezier.points[j][i])
+      }
+      result.push(bezierFunction(bezier, singleDimensionPoints, t))
+    }
+    return result
+  }
+}
+
+const bezierFunction = function (bezier, p, t) {
+  const n = p.length - 1
+  let result = 0
+  for (let i = 0; i <= n; i++) {
+    result += bezier.permutations[i] * Math.pow(1 - t, n - i) * Math.pow(t, i) * p[i]
+  }
+  return result
+}
+
+module.exports = valueAt

package/src/curves/bezier/valueAt.test.js

@@ -0,0 +1,63 @@
+const test = require('ava')
+
+const { bezier } = require('../index')
+
+test('Linear bezier (straight line between two points)', (t) => {
+  const straightLine = bezier.create([10, 20])
+  t.is(bezier.valueAt(0, straightLine), 10)
+  t.is(bezier.valueAt(0.5, straightLine), 15)
+  t.is(bezier.valueAt(1, straightLine), 20)
+})
+
+test('bezier with non-numbers throws error', (t) => {
+  t.throws(() => bezier.create(['what', 20]), { instanceOf: Error })
+})
+
+test('quadratic bezier (3 control points)', (t) => {
+  const OneDCurve = bezier.create([0, 10, 20])
+  t.is(bezier.valueAt(0, OneDCurve), 0)
+  t.is(bezier.valueAt(0.5, OneDCurve), 10)
+  t.is(bezier.valueAt(1, OneDCurve), 20)
+})
+
+test('quadratic bezier (3 control points, non symmetric)', (t) => {
+  const OneDCurve = bezier.create([0, 0, 20])
+  t.is(bezier.valueAt(0, OneDCurve), 0)
+  t.is(bezier.valueAt(0.5, OneDCurve), 5)
+  t.is(bezier.valueAt(1, OneDCurve), 20)
+})
+
+test('quadratic bezier (4 control points)', (t) => {
+  const OneDCurve = bezier.create([0, 0, 20, 20])
+  t.is(bezier.valueAt(0, OneDCurve), 0)
+  t.is(bezier.valueAt(0.5, OneDCurve), 10)
+  t.is(bezier.valueAt(1, OneDCurve), 20)
+})
+
+test('bezier with numbers and array of numbers throws error', (t) => {
+  t.throws(() => bezier.create([[0, 5, 10], 20]), { instanceOf: Error })
+})
+
+test('bezier with array of numbers of different size throws error', (t) => {
+  t.throws(() => bezier.create([[0, 5, 10], [20, 0]]), { instanceOf: Error })
+})
+
+test('quadratic bezier one dimension, 3 control points', (t) => {
+  const OneDCurve = bezier.create([[0], [10], [20]])
+  t.deepEqual(bezier.valueAt(0, OneDCurve), [0])
+  t.deepEqual(bezier.valueAt(0.5, OneDCurve), [10])
+  t.deepEqual(bezier.valueAt(1, OneDCurve), [20])
+})
+
+test('quadratic bezier 2 dimensions, 3 control points', (t) => {
+  const TwoDCurve = bezier.create([[0, 10], [30, 10], [60, 20]])
+  t.deepEqual(bezier.valueAt(0, TwoDCurve), [0, 10])
+  t.deepEqual(bezier.valueAt(0.5, TwoDCurve), [30, 12.5])
+  t.deepEqual(bezier.valueAt(1, TwoDCurve), [60, 20])
+})
+
+test('bezier throws error when t is not between 0 and 1', (t) => {
+  const straightLine = bezier.create([0, 20])
+  t.throws(() => bezier.valueAt(-2, straightLine), { instanceOf: Error })
+  t.throws(() => bezier.valueAt(1.1, straightLine), { instanceOf: Error })
+})

package/src/curves/index.d.ts

@@ -0,0 +1,3 @@
+export * as bezier from './bezier'
+
+export as namespace curves

package/src/curves/index.js

@@ -0,0 +1,9 @@
+/**
+ * Curves are n-dimensional mathematical constructs that define a path from point 0 to point 1.
+ * @module modeling/curves
+ * @example
+ * const { bezier } = require('@jscad/modeling').curves
+ */
+module.exports = {
+  bezier: require('./bezier')
+}

package/src/geometries/geom2/applyTransforms.js

@@ -0,0 +1,26 @@
+const mat4 = require('../../maths/mat4')
+const vec2 = require('../../maths/vec2')
+
+/*
+ * Apply the transforms of the given geometry.
+ * NOTE: This function must be called BEFORE exposing any data. See toSides().
+ * @param {geom2} geometry - the geometry to transform
+ * @returns {geom2} the given geometry
+ *
+ * @example
+ * geometry = applyTransforms(geometry)
+ */
+const applyTransforms = (geometry) => {
+  if (mat4.isIdentity(geometry.transforms)) return geometry
+
+  // apply transforms to each side
+  geometry.sides = geometry.sides.map((side) => {
+    const p0 = vec2.transform(vec2.create(), side[0], geometry.transforms)
+    const p1 = vec2.transform(vec2.create(), side[1], geometry.transforms)
+    return [p0, p1]
+  })
+  geometry.transforms = mat4.create()
+  return geometry
+}
+
+module.exports = applyTransforms

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

@@ -0,0 +1,21 @@
+const test = require('ava')
+
+const { fromPoints } = require('./index')
+
+const applyTransforms = require('./applyTransforms')
+
+test('applyTransforms: Updates a populated geom2 with transformed sides', (t) => {
+  const points = [[0, 0], [1, 0], [0, 1]]
+  const expected = {
+    sides: [[[0, 1], [0, 0]], [[0, 0], [1, 0]], [[1, 0], [0, 1]]],
+    transforms: [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]
+  }
+  const geometry = fromPoints(points)
+  const updated = applyTransforms(geometry)
+  t.is(geometry, updated)
+  t.deepEqual(updated, expected)
+
+  const updated2 = applyTransforms(updated)
+  t.is(updated, updated2)
+  t.deepEqual(updated, expected)
+})

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

@@ -0,0 +1,5 @@
+import Geom2 from './type'
+
+export default clone
+
+declare function clone(geometry: Geom2): Geom2

package/src/geometries/geom2/clone.js

@@ -0,0 +1,9 @@
+/**
+ * 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
+ */
+const clone = (geometry) => Object.assign({}, geometry)
+
+module.exports = clone

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

@@ -0,0 +1,26 @@
+const test = require('ava')
+
+const { clone, create, fromPoints } = require('./index')
+
+test('clone: Creates a clone on an empty geom2', (t) => {
+  const expected = {
+    sides: [],
+    transforms: [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]
+  }
+  const geometry = create()
+  const another = clone(geometry)
+  t.not(another, geometry)
+  t.deepEqual(another, expected)
+})
+
+test('clone: Creates a clone of a complete geom2', (t) => {
+  const points = [[0, 0], [1, 0], [0, 1]]
+  const expected = {
+    sides: [[[0, 1], [0, 0]], [[0, 0], [1, 0]], [[1, 0], [0, 1]]],
+    transforms: [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]
+  }
+  const geometry = fromPoints(points)
+  const another = clone(geometry)
+  t.not(another, geometry)
+  t.deepEqual(another, expected)
+})

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

@@ -0,0 +1,6 @@
+import Geom2 from './type'
+import Vec2 from '../../maths/vec2/type'
+
+export default create
+
+declare function create(sides?: Array<[Vec2, Vec2]>): Geom2

package/src/geometries/geom2/create.js

@@ -0,0 +1,26 @@
+const mat4 = require('../../maths/mat4')
+
+/**
+ * Represents a 2D geometry consisting of a list of sides.
+ * @typedef {Object} geom2
+ * @property {Array} sides - list of sides, each side containing two points
+ * @property {mat4} transforms - transforms to apply to the sides, see transform()
+ */
+
+/**
+ * Create a new 2D geometry composed of unordered sides (two connected points).
+ * @param {Array} [sides] - list of sides where each side is an array of two points
+ * @returns {geom2} a new geometry
+ * @alias module:modeling/geometries/geom2.create
+ */
+const create = (sides) => {
+  if (sides === undefined) {
+    sides = [] // empty contents
+  }
+  return {
+    sides: sides,
+    transforms: mat4.create()
+  }
+}
+
+module.exports = create

package/src/geometries/geom2/create.test.js

@@ -0,0 +1,20 @@
+const test = require('ava')
+
+const { create } = require('./index')
+
+test('create: Creates an empty geom2', (t) => {
+  const expected = {
+    sides: [],
+    transforms: [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]
+  }
+  t.deepEqual(create(), expected)
+})
+
+test('create: Creates a populated geom2', (t) => {
+  const sides = [[[0, 0], [1, 1]]]
+  const expected = {
+    sides: sides,
+    transforms: [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]
+  }
+  t.deepEqual(create(sides), expected)
+})

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

@@ -0,0 +1,5 @@
+import Geom2 from './type'
+
+export default fromCompactBinary
+
+declare function fromCompactBinary(data: Array<number> | Float32Array | Float64Array): Geom2

package/src/geometries/geom2/fromCompactBinary.js

@@ -0,0 +1,32 @@
+const mat4 = require('../../maths/mat4')
+const vec2 = require('../../maths/vec2')
+
+const create = require('./create')
+
+/**
+ * Create a new 2D geometry from the given compact binary data.
+ * @param {Array} data - compact binary data
+ * @returns {geom2} a new geometry
+ * @alias module:modeling/geometries/geom2.fromCompactBinary
+ */
+const fromCompactBinary = (data) => {
+  if (data[0] !== 0) throw new Error('invalid compact binary data')
+
+  const created = create()
+
+  created.transforms = mat4.clone(data.slice(1, 17))
+
+  for (let i = 21; i < data.length; i += 4) {
+    const point0 = vec2.fromValues(data[i + 0], data[i + 1])
+    const point1 = vec2.fromValues(data[i + 2], data[i + 3])
+    created.sides.push([point0, point1])
+  }
+  // transfer known properties, i.e. color
+  if (data[17] >= 0) {
+    created.color = [data[17], data[18], data[19], data[20]]
+  }
+  // TODO: how about custom properties or fields ?
+  return created
+}
+
+module.exports = fromCompactBinary

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

@@ -0,0 +1,6 @@
+import Geom2 from './type'
+import Vec2 from '../../maths/vec2/type'
+
+export default fromPoints
+
+declare function fromPoints(points: Array<Vec2>): Geom2

package/src/geometries/geom2/fromPoints.js

@@ -0,0 +1,35 @@
+const vec2 = require('../../maths/vec2')
+
+const create = require('./create')
+
+/**
+ * Create a new 2D geometry from the given points.
+ * The direction (rotation) of the points is not relevant,
+ * as the points can define a convex or a concave polygon.
+ * The geometry must not self intersect, i.e. the sides cannot cross.
+ * @param {Array} points - list of points in 2D space
+ * @returns {geom2} a new geometry
+ * @alias module:modeling/geometries/geom2.fromPoints
+ */
+const fromPoints = (points) => {
+  if (!Array.isArray(points)) {
+    throw new Error('the given points must be an array')
+  }
+  let length = points.length
+  if (length < 3) {
+    throw new Error('the given points must define a closed geometry with three or more points')
+  }
+  // adjust length if the given points are closed by the same point
+  if (vec2.equals(points[0], points[length - 1])) --length
+
+  const sides = []
+  let prevpoint = points[length - 1]
+  for (let i = 0; i < length; i++) {
+    const point = points[i]
+    sides.push([vec2.clone(prevpoint), vec2.clone(point)])
+    prevpoint = point
+  }
+  return create(sides)
+}
+
+module.exports = fromPoints

package/src/geometries/geom2/fromPoints.test.js

@@ -0,0 +1,22 @@
+const test = require('ava')
+
+const { fromPoints } = require('./index')
+
+test('fromPoints: creates populated geom2', (t) => {
+  const points = [[0, 0], [1, 0], [0, 1]]
+  const expected = {
+    sides: [[[0, 1], [0, 0]], [[0, 0], [1, 0]], [[1, 0], [0, 1]]],
+    transforms: [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]
+  }
+  t.deepEqual(fromPoints(points), expected)
+
+  const points2 = [[0, 0], [1, 0], [0, 1], [0, 0]]
+  t.deepEqual(fromPoints(points2), expected)
+})
+
+test('fromPoints: throws for improper points', (t) => {
+  t.throws(() => fromPoints(), { instanceOf: Error })
+  t.throws(() => fromPoints(0, 0), { instanceOf: Error })
+  t.throws(() => fromPoints([]), { instanceOf: Error })
+  t.throws(() => fromPoints([[0, 0]]), { instanceOf: Error })
+})