feat(modeling): new geometry for 3D paths (path3)

Author: z3dev

jsdoc.json

@@ -10,6 +10,7 @@
       "packages/modeling/src/geometries/geom2",
       "packages/modeling/src/geometries/geom3",
       "packages/modeling/src/geometries/path2",
+      "packages/modeling/src/geometries/path3",
       "packages/modeling/src/geometries/poly2",
       "packages/modeling/src/geometries/poly3",
       "packages/modeling/src/geometries/slice",

packages/modeling/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() })

packages/modeling/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'

packages/modeling/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'

packages/modeling/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() })

packages/modeling/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
+}

packages/modeling/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))
+})

packages/modeling/src/geometries/path3/close.d.ts

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

packages/modeling/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
+}

packages/modeling/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
+})