@jscad/modeling 2.11.1 → 3.0.0-alpha.0

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

@@ -0,0 +1,17 @@
+import test from 'ava'
+
+import { create, clone } from './index.js'
+
+import { comparePoints } from '../../../test/helpers/index.js'
+
+test('poly2: clone() should return a new poly2 with same values', (t) => {
+  const org1 = create()
+  const ret1 = clone(org1)
+  t.true(comparePoints(ret1.points, org1.points))
+  t.not(ret1, org1)
+
+  const org2 = create([[1, 1], [-1, 1], [-1, -1], [1, -1]])
+  const ret2 = clone(org2)
+  t.true(comparePoints(ret2.points, org2.points))
+  t.not(ret2, org2)
+})

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

@@ -1,6 +1,4 @@
-import Poly2 from './type'
-import Vec2 from '../../maths/vec2/type'
+import type { Poly2 } from './type.d.ts'
+import type { Vec2 } from '../../maths/vec2/type.d.ts'
 
-export default create
-
-declare function create(vertices?: Array<Vec2>): Poly2
+export function create(points?: Array<Vec2>): Poly2

package/src/geometries/poly2/create.js

@@ -1,24 +1,23 @@
 /**
- * Represents a convex 2D polygon consisting of a list of ordered vertices.
- * @typedef {Object} poly2
- * @property {Array} vertices - list of ordered vertices (2D)
+ * Represents a 2D polygon consisting of a list of ordered points
+ * which is closed between start and end points.
+ * @see https://en.wikipedia.org/wiki/Polygon
+ * @property {Array} points - list of ordered points (2D)
  */
 
 /**
  * Creates a new polygon with initial values.
  *
- * @param {Array} [vertices] - list of vertices (2D)
- * @returns {poly2} a new polygon
+ * @param {Array} [points] - list of points (2D)
+ * @returns {Poly2} a new polygon
  * @alias module:modeling/geometries/poly2.create
  *
  * @example
- * let polygon = create()
+ * let polygon = create([[0,0], [4,0], [4,3]])
  */
-const create = (vertices) => {
-  if (vertices === undefined || vertices.length < 3) {
-    vertices = [] // empty contents
+export const create = (points) => {
+  if (points === undefined || points.length < 3) {
+    points = [] // empty contents
   }
-  return { vertices: vertices }
+  return { points }
 }
-
-module.exports = create

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

@@ -1,13 +1,13 @@
-const test = require('ava')
+import test from 'ava'
 
-const { create } = require('./index')
+import { create } from './index.js'
 
 test('poly2: create() should return a poly2 with initial values', (t) => {
   let obs = create()
-  let exp = { vertices: [] }
+  let exp = { points: [] }
   t.deepEqual(obs, exp)
 
   obs = create([[1, 1], [2, 2], [3, 3]])
-  exp = { vertices: [[1, 1], [2, 2], [3, 3]] }
+  exp = { points: [[1, 1], [2, 2], [3, 3]] }
   t.deepEqual(obs, exp)
 })

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

@@ -1,7 +1,15 @@
-export { default as arePointsInside } from './arePointsInside'
-export { default as create } from './create'
-export { default as flip } from './flip'
-export { default as measureArea } from './measureArea'
+export { arePointsInside } from './arePointsInside.js'
+export { clone } from './clone.js'
+export { create } from './create.js'
+export { isA } from './isA.js'
+export { isConvex } from './isConvex.js'
+export { isSimple } from './isSimple.js'
+export { measureArea } from './measureArea.js'
+export { measureBoundingBox } from './measureBoundingBox.js'
+export { reverse } from './reverse.js'
+export { toPoints } from './toPoints.js'
+export { toString } from './toString.js'
+export { transform } from './transform.js'
+export { validate } from './validate.js'
 
-export { default as Poly2 } from './type'
-export as namespace poly2
+export type { Poly2 } from './type.d.ts'

package/src/geometries/poly2/index.js

@@ -1,17 +1,22 @@
 /**
- * Represents a 2D polygon consisting of a list of ordered vertices.
+ * Represents a 2D polygon consisting of a list of ordered points.
  * @see {@link poly2} for data structure information.
  * @module modeling/geometries/poly2
  *
  * @example
- * poly2.create([[0,0], [4,0], [4,3]])
- *
- * @example
- * {"vertices": [[0,0], [4,0], [4,3]]}
+ * import { geometries } from '@jscad/modeling'
+ * const p1 = geometries.poly2.create([[0,0], [4,0], [4,3]])
  */
-module.exports = {
-  arePointsInside: require('./arePointsInside'),
-  create: require('./create'),
-  flip: require('./flip'),
-  measureArea: require('./measureArea')
-}
+export { arePointsInside } from './arePointsInside.js'
+export { clone } from './clone.js'
+export { create } from './create.js'
+export { isA } from './isA.js'
+export { isConvex } from './isConvex.js'
+export { isSimple } from './isSimple.js'
+export { measureArea } from './measureArea.js'
+export { measureBoundingBox } from './measureBoundingBox.js'
+export { reverse } from './reverse.js'
+export { toPoints } from './toPoints.js'
+export { toString } from './toString.js'
+export { transform } from './transform.js'
+export { validate } from './validate.js'

package/src/geometries/poly2/isA.d.ts

@@ -0,0 +1,3 @@
+import type { Poly2 } from './type.d.ts'
+
+export function isA(object: any): object is Poly2

package/src/geometries/poly2/isA.js

@@ -0,0 +1,16 @@
+/**
+ * Determine if the given object is a 2D polygon.
+ * @param {object} object - the object to interrogate
+ * @returns {Boolean} true if the object matches a poly2
+ * @alias module:modeling/geometries/poly2.isA
+ */
+export const isA = (object) => {
+  if (object && typeof object === 'object') {
+    if ('points' in object) {
+      if (Array.isArray(object.points)) {
+        return true
+      }
+    }
+  }
+  return false
+}

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

@@ -0,0 +1,30 @@
+import test from 'ava'
+
+import * as geom2 from '../geom2/index.js'
+import * as geom3 from '../geom3/index.js'
+import * as poly3 from '../poly3/index.js'
+import { isA, create } from './index.js'
+
+test('isA: identifies created poly2', (t) => {
+  const p1 = create()
+  const p2 = create([[0, 0], [1, 0], [1, 1]])
+  t.true(isA(p1))
+  t.true(isA(p2))
+})
+
+test('isA: identifies non poly2', (t) => {
+  const p1 = null
+  const p2 = {}
+  const p3 = { points: 1 }
+  const p4 = { vertices: 1 }
+  const p5 = geom2.create()
+  const p6 = geom3.create()
+  const p7 = poly3.create()
+  t.false(isA(p1))
+  t.false(isA(p2))
+  t.false(isA(p3))
+  t.false(isA(p4))
+  t.false(isA(p5))
+  t.false(isA(p6))
+  t.false(isA(p7))
+})

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

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

package/src/geometries/poly2/isConvex.js

@@ -0,0 +1,37 @@
+/**
+ * Check whether the given polygon is convex.
+ * @param {Poly2} polygon - the polygon to interrogate
+ * @returns {Boolean} true if convex
+ * @alias module:modeling/geometries/poly2.isConvex
+ */
+export const isConvex = (polygon) => {
+  const numPoints = polygon.points.length
+  if (numPoints > 2) {
+    const points = polygon.points
+    let prev = 0
+    let curr = 0
+    for (let i = 0; i < numPoints; i++) {
+      curr = crossBetweenSegments(points[i], points[(i + 1) % numPoints], points[(i + 2) % numPoints])
+      if (curr !== 0) {
+        // sum angle of crosses, looking for a change in direction
+        if (curr * prev < 0) {
+          return false
+        }
+        prev = curr
+      }
+    }
+  }
+  return true
+}
+
+/*
+ * Calculate cross product between two consecutive line segments; p1 -> p2, p2 -> p3.
+ */
+const crossBetweenSegments = (p1, p2, p3) => {
+  const X1 = p2[0] - p1[0]
+  const Y1 = p2[1] - p1[1]
+  const X2 = p3[0] - p1[0]
+  const Y2 = p3[1] - p1[1]
+
+  return (X1 * Y2 - Y1 * X2)
+}

package/src/geometries/poly2/isConvex.test.js

@@ -0,0 +1,27 @@
+import test from 'ava'
+
+import { isConvex, create } from './index.js'
+
+test('poly2: isConvex() should return correct values', (t) => {
+  const ply1 = create()
+  t.true(isConvex(ply1))
+
+  const ply2 = create([[0, 0], [1, 0], [1, 1]])
+  t.true(isConvex(ply2))
+
+  // Counterclockwise
+  const ply3 = create([[5, 5], [5, -5], [-5, -5], [-5, 5]])
+  t.true(isConvex(ply3))
+
+  // Clockwise
+  const ply4 = create([[5, 5], [-5, 5], [-5, -5], [5, -5]])
+  t.true(isConvex(ply4))
+
+  // CCW With V-side
+  const ply5 = create([[5, 5], [5, -5], [0, 0], [-5, -5], [-5, 5]])
+  t.false(isConvex(ply5))
+
+  // STAR
+  const ply6 = create([[0, 0], [5, 5], [5, -5], [0, 0], [-5, -5], [-5, 5]])
+  t.false(isConvex(ply6))
+})

package/src/geometries/poly2/isSimple.d.ts

@@ -0,0 +1,3 @@
+import type { Poly2 } from './type.d.ts'
+
+export function isSimple(polygon: Poly2): boolean

package/src/geometries/poly2/isSimple.js

@@ -0,0 +1,38 @@
+import { intersect } from '../../maths/utils/intersect.js'
+
+/**
+ * Check whether the given polygon is simple, i.e. does not intersect itself.
+ * @see https://en.wikipedia.org/wiki/Simple_polygon
+ * @param {Poly2} polygon - the polygon to interrogate
+ * @returns {Boolean} true if simple
+ * @alias module:modeling/geometries/poly2.isSimple
+ */
+export const isSimple = (polygon) => {
+  const numPoints = polygon.points.length
+  if (numPoints < 3) return false // only polygons with an areas are simple
+
+  if (numPoints === 3) return true // triangles are simple
+
+  const points = polygon.points
+
+  // proof one: there are N unique points
+  const found = new Set()
+  points.forEach((v) => found.add(v.toString()))
+  if (found.size !== numPoints) return false
+
+  // proof two: line segments do not cross
+  for (let i = 0; i < numPoints; i++) {
+    for (let j = i + 2; j < numPoints; j++) {
+      const k = (j + 1) % numPoints
+      if (i !== k) {
+        const s0 = points[i]
+        const s1 = points[(i + 1) % numPoints]
+        const z0 = points[j]
+        const z1 = points[k]
+        const ip = intersect(s0, s1, z0, z1)
+        if (ip) return false
+      }
+    }
+  }
+  return true
+}

package/src/geometries/poly2/isSimple.test.js

@@ -0,0 +1,31 @@
+import test from 'ava'
+
+import { isSimple, create } from './index.js'
+
+test('poly2: isSimple() should return correct values', (t) => {
+  const ply1 = create()
+  t.false(isSimple(ply1))
+
+  const ply2 = create([[0, 0], [1, 0], [1, 1]])
+  t.true(isSimple(ply2))
+
+  // Clockwise
+  const ply3 = create([[5, 5], [5, -5], [-5, -5], [-5, 5]])
+  t.true(isSimple(ply3))
+
+  // Counterclockwise
+  const ply4 = create([[5, 5], [-5, 5], [-5, -5], [5, -5]])
+  t.true(isSimple(ply4))
+
+  // CW With V-side
+  const ply5 = create([[5, 5], [5, -5], [0, 0], [-5, -5], [-5, 5]])
+  t.true(isSimple(ply5))
+
+  // STAR
+  const ply6 = create([[0, 0], [5, 5], [5, -5], [0, 0], [-5, -5], [-5, 5]])
+  t.false(isSimple(ply6))
+
+  // CROSSING
+  const ply7 = create([[5, 5], [5, -5], [-5, 5], [-5, -5]])
+  t.false(isSimple(ply7))
+})

package/src/geometries/poly2/measureArea.d.ts

@@ -1,5 +1,3 @@
-import Poly2 from './type'
+import type { Poly2 } from './type.d.ts'
 
-export default measureArea
-
-declare function measureArea(polygon: Poly2): number
+export function measureArea(polygon: Poly2): number

package/src/geometries/poly2/measureArea.js

@@ -1,12 +1,10 @@
+import { area } from '../../maths/utils/area.js'
+
 /**
  * Measure the area under the given polygon.
  *
- * @param {poly2} polygon - the polygon to measure
- * @return {Number} the area of the polygon
+ * @param {Poly2} polygon - the polygon to measure
+ * @return {number} the area of the polygon
  * @alias module:modeling/geometries/poly2.measureArea
  */
-const area = require('../../maths/utils/area')
-
-const measureArea = (polygon) => area(polygon.vertices)
-
-module.exports = measureArea
+export const measureArea = (polygon) => area(polygon.points)

package/src/geometries/poly2/measureArea.test.js

@@ -1,6 +1,6 @@
-const test = require('ava')
+import test from 'ava'
 
-const { measureArea, create } = require('./index')
+import { measureArea, create } from './index.js'
 
 test('poly2: measureArea() should return correct values', (t) => {
   const ply1 = create()

package/src/geometries/poly2/measureBoundingBox.d.ts

@@ -0,0 +1,4 @@
+import type { Poly2 } from './type.d.ts'
+import type { Vec2 } from '../../maths/vec2/type.d.ts'
+
+export function measureBoundingBox(polygon: Poly2): [Vec2, Vec2]

package/src/geometries/poly2/measureBoundingBox.js

@@ -0,0 +1,18 @@
+import * as vec2 from '../../maths/vec2/index.js'
+
+/**
+ * @param {Poly2} polygon - the polygon to measure
+ * @returns {Array} an array of two vectors (2D);  minimum and maximum coordinates
+ * @alias module:modeling/geometries/poly2.measureBoundingBox
+ */
+export const measureBoundingBox = (polygon) => {
+  const points = polygon.points
+  const numPoints = points.length
+  const min = numPoints === 0 ? vec2.create() : vec2.clone(points[0])
+  const max = vec2.clone(min)
+  for (let i = 1; i < numPoints; i++) {
+    vec2.min(min, min, points[i])
+    vec2.max(max, max, points[i])
+  }
+  return [min, max]
+}

package/src/geometries/poly2/measureBoundingBox.test.js

@@ -0,0 +1,71 @@
+import test from 'ava'
+
+import * as mat4 from '../../maths/mat4/index.js'
+
+import { compareVectors } from '../../../test/helpers/index.js'
+
+import { measureBoundingBox, create, transform } from './index.js'
+
+test('poly2: measureBoundingBox() should return correct values', (t) => {
+  let ply1 = create()
+  let exp1 = [[0, 0], [0, 0]]
+  let ret1 = measureBoundingBox(ply1)
+  t.true(compareVectors(ret1[0], exp1[0]))
+  t.true(compareVectors(ret1[1], exp1[1]))
+
+  // simple triangle
+  let ply2 = create([[0, 0], [0, 10], [10, 0]])
+  let exp2 = [[0, 0], [10, 10]]
+  let ret2 = measureBoundingBox(ply2)
+  t.true(compareVectors(ret2[0], exp2[0]))
+  t.true(compareVectors(ret2[1], exp2[1]))
+
+  // simple square
+  let ply3 = create([[0, 0], [10, 0], [10, 10], [0, 10]])
+  let exp3 = [[0, 0], [10, 10]]
+  let ret3 = measureBoundingBox(ply3)
+  t.true(compareVectors(ret3[0], exp3[0]))
+  t.true(compareVectors(ret3[1], exp3[1]))
+
+  // V-shape
+  const points = [
+    [3, 0],
+    [5, 0],
+    [8, 2],
+    [6, 5],
+    [8, 6],
+    [5, 6],
+    [5, 2],
+    [2, 5],
+    [1, 3],
+    [3, 3]
+  ]
+  let ply4 = create(points)
+  let exp4 = [[1, 0], [8, 6]]
+  let ret4 = measureBoundingBox(ply4)
+  t.true(compareVectors(ret4[0], exp4[0]))
+  t.true(compareVectors(ret4[1], exp4[1]))
+
+  // rotated to various angles
+  const rotation = mat4.fromZRotation(mat4.create(), (45 * 0.017453292519943295))
+  ply1 = transform(rotation, ply1)
+  ply2 = transform(rotation, ply2)
+  ply3 = transform(rotation, ply3)
+  ply4 = transform(rotation, ply4)
+  ret1 = measureBoundingBox(ply1)
+  ret2 = measureBoundingBox(ply2)
+  ret3 = measureBoundingBox(ply3)
+  ret4 = measureBoundingBox(ply4)
+  exp1 = [[0, 0], [0, 0]]
+  t.true(compareVectors(ret1[0], exp1[0]))
+  t.true(compareVectors(ret1[1], exp1[1]))
+  exp2 = [[-7.071067811865475, 0], [7.0710678118654755, 7.0710678118654755]]
+  t.true(compareVectors(ret2[0], exp2[0]))
+  t.true(compareVectors(ret2[1], exp2[1]))
+  exp3 = [[-7.071067811865475, 0], [7.0710678118654755, 14.142135623730951]]
+  t.true(compareVectors(ret3[0], exp3[0]))
+  t.true(compareVectors(ret3[1], exp3[1]))
+  exp4 = [[-2.121320343559642, 2.1213203435596424], [4.242640687119286, 9.899494936611665]]
+  t.true(compareVectors(ret4[0], exp4[0]))
+  t.true(compareVectors(ret4[1], exp4[1]))
+})

package/src/geometries/poly2/reverse.d.ts

@@ -0,0 +1,3 @@
+import type { Poly2 } from './type.d.ts'
+
+export function reverse(polygon: Poly2): Poly2

package/src/geometries/poly2/reverse.js

@@ -0,0 +1,13 @@
+import { create } from './create.js'
+
+/**
+ * Reverse the direction of points in the given polygon, rotating the opposite direction.
+ *
+ * @param {Poly2} polygon - the polygon to reverse
+ * @returns {Poly2} a new polygon
+ * @alias module:modeling/geometries/poly2.reverse
+ */
+export const reverse = (polygon) => {
+  const points = polygon.points.slice().reverse()
+  return create(points)
+}

package/src/geometries/poly2/reverse.test.js

@@ -0,0 +1,27 @@
+import test from 'ava'
+
+import { create, reverse, toPoints } from './index.js'
+
+import { comparePoints } from '../../../test/helpers/index.js'
+
+test('reverse: reverses a populated poly2', (t) => {
+  const points = [[0, 0], [1, 0], [0, 1]]
+  const expected = { points: [[0, 1], [1, 0], [0, 0]] }
+  const geometry = create(points)
+  const another = reverse(geometry)
+  t.not(geometry, another)
+  t.true(comparePoints(another.points, expected.points))
+})
+
+test('reverse: does not modify input poly2', (t) => {
+  const points = [[0, 0], [1, 0], [0, 1]]
+  // expected:
+  const forward = [[0, 0], [1, 0], [0, 1]]
+  const backward = [[0, 1], [1, 0], [0, 0]]
+
+  const geometry = create(points)
+  const another = reverse(geometry)
+  t.not(geometry, another)
+  t.true(comparePoints(toPoints(geometry), forward))
+  t.true(comparePoints(toPoints(another), backward))
+})

package/src/geometries/poly2/toPoints.d.ts

@@ -0,0 +1,4 @@
+import type { Poly2 } from './type.d.ts'
+import type { Vec2 } from '../../maths/vec2/type.d.ts'
+
+export function toPoints(polygon: Poly2): Array<Vec2>

package/src/geometries/poly2/toPoints.js

@@ -0,0 +1,8 @@
+/**
+ * Return the given polygon as a list of points.
+ * NOTE: The returned array should not be modified as the points are shared with the geometry.
+ * @param {Poly2} polygon - the polygon
+ * @return {Array} list of points (2D)
+ * @alias module:modeling/geometries/poly2.toPoints
+ */
+export const toPoints = (polygon) => polygon.points

package/src/geometries/poly2/toPoints.test.js

@@ -0,0 +1,18 @@
+import test from 'ava'
+
+import { create, toPoints } from './index.js'
+
+import { comparePoints } from '../../../test/helpers/index.js'
+
+test('toPoints: creates an empty array of points from an empty poly2', (t) => {
+  const geometry = create()
+  const points = toPoints(geometry)
+  t.deepEqual(points, [])
+})
+
+test('toPoints: creates an array of points from a populated poly2', (t) => {
+  const geometry = create([[0, 0], [1, 0], [0, 1]])
+  const expected = [[0, 0], [1, 0], [0, 1]]
+  const points = toPoints(geometry)
+  t.true(comparePoints(points, expected))
+})

package/src/geometries/poly2/toString.d.ts

@@ -0,0 +1,3 @@
+import type { Poly2 } from './type.d.ts'
+
+export function toString(polygon: Poly2): string

package/src/geometries/poly2/toString.js

@@ -0,0 +1,9 @@
+import * as vec2 from '../../maths/vec2/index.js'
+
+/**
+ * Convert the given polygon to a readable string.
+ * @param {Poly2} polygon - the polygon to convert
+ * @return {String} the string representation
+ * @alias module:modeling/geometries/poly2.toString
+ */
+export const toString = (polygon) => `poly2: [${polygon.points.map(vec2.toString).join(', ')}]`

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

@@ -0,0 +1,10 @@
+import test from 'ava'
+
+import { create, toString } from './index.js'
+
+test('toString: serialize poly2 into a string', (t) => {
+  const geometry = create([[0, 0], [0, 1], [2, 0]])
+  const result = toString(geometry)
+  const expected = 'poly2: [[0.0000000, 0.0000000], [0.0000000, 1.0000000], [2.0000000, 0.0000000]]'
+  t.is(result, expected)
+})

package/src/geometries/poly2/transform.d.ts

@@ -0,0 +1,4 @@
+import type { Poly2 } from './type.d.ts'
+import type { Mat4 } from '../../maths/mat4/type.d.ts'
+
+export function transform(matrix: Mat4, polygon: Poly2): Poly2

package/src/geometries/poly2/transform.js

@@ -0,0 +1,20 @@
+import * as mat4 from '../../maths/mat4/index.js'
+import * as vec2 from '../../maths/vec2/index.js'
+
+import { create } from './create.js'
+
+/**
+ * Transform the given polygon using the given matrix.
+ * @param {Mat4} matrix - the matrix to transform with
+ * @param {Poly2} polygon - the polygon to transform
+ * @returns {Poly2} a new polygon
+ * @alias module:modeling/geometries/poly2.transform
+ */
+export const transform = (matrix, polygon) => {
+  const points = polygon.points.map((point) => vec2.transform(vec2.create(), point, matrix))
+  if (mat4.isMirroring(matrix)) {
+    // reverse the order to preserve the orientation
+    points.reverse()
+  }
+  return create(points)
+}