frenet-serret-frames 2.1.0 → 3.0.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+# [3.0.0](https://github.com/dmnsgn/frenet-serret-frames/compare/v2.1.0...v3.0.0) (2023-07-31)
+
+
+### Features
+
+* add typed array support ([d766f7c](https://github.com/dmnsgn/frenet-serret-frames/commit/d766f7c1beafcd23130d95f4bc6faa591ae07f10))
+
+
+### BREAKING CHANGES
+
+* use pex-math
+* use geometry as first argument
+* return augmented geometry and not frames
+
+
+
 # [2.1.0](https://github.com/dmnsgn/frenet-serret-frames/compare/v2.0.1...v2.1.0) (2021-10-02)
 
 

package/README.md

@@ -2,15 +2,15 @@
 
 [![npm version](https://img.shields.io/npm/v/frenet-serret-frames)](https://www.npmjs.com/package/frenet-serret-frames)
 [![stability-stable](https://img.shields.io/badge/stability-stable-green.svg)](https://www.npmjs.com/package/frenet-serret-frames)
-[![npm minzipped size](https://img.shields.io/bundlephobia/minzip/frenet-serret-frames)](https://www.npmjs.com/package/frenet-serret-frames)
-[![dependencies](https://img.shields.io/david/dmnsgn/frenet-serret-frames)](https://github.com/dmnsgn/frenet-serret-frames/blob/main/package.json)
+[![npm minzipped size](https://img.shields.io/bundlephobia/minzip/frenet-serret-frames)](https://bundlephobia.com/package/frenet-serret-frames)
+[![dependencies](https://img.shields.io/librariesio/release/npm/frenet-serret-frames)](https://github.com/dmnsgn/frenet-serret-frames/blob/main/package.json)
 [![types](https://img.shields.io/npm/types/frenet-serret-frames)](https://github.com/microsoft/TypeScript)
 [![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-fa6673.svg)](https://conventionalcommits.org)
 [![styled with prettier](https://img.shields.io/badge/styled_with-Prettier-f8bc45.svg?logo=prettier)](https://github.com/prettier/prettier)
 [![linted with eslint](https://img.shields.io/badge/linted_with-ES_Lint-4B32C3.svg?logo=eslint)](https://github.com/eslint/eslint)
 [![license](https://img.shields.io/github/license/dmnsgn/frenet-serret-frames)](https://github.com/dmnsgn/frenet-serret-frames/blob/main/LICENSE.md)
 
-Compute Frenet-Serret frames for a path of 3D points and tangents.
+Compute Frenet-Serret frames for a geometry of 3D positions and optionally provided tangents.
 
 [![paypal](https://img.shields.io/badge/donate-paypal-informational?logo=paypal)](https://paypal.me/dmnsgn)
 [![coinbase](https://img.shields.io/badge/donate-coinbase-informational?logo=coinbase)](https://commerce.coinbase.com/checkout/56cbdf28-e323-48d8-9c98-7019e72c97f3)
@@ -45,8 +45,8 @@ const frames = frenetSerretFrames(path, tangents, {
 ## Functions
 
 <dl>
-<dt><a href="#frenetSerretFrames">frenetSerretFrames(points, tangents, [options])</a> ⇒ <code><a href="#Frame">Array.&lt;Frame&gt;</a></code></dt>
-<dd><p>Compute Frenet-Serret frames for a path of 3D points and tangents</p>
+<dt><a href="#frenetSerretFrames">frenetSerretFrames(geometry, [options])</a> ⇒ <code><a href="#SimplicialComplexWithTNB">SimplicialComplexWithTNB</a></code></dt>
+<dd><p>Compute Frenet-Serret frames for a geometry of 3D positions and optionally provided tangents.</p>
 </dd>
 </dl>
 
@@ -55,40 +55,78 @@ const frames = frenetSerretFrames(path, tangents, {
 <dl>
 <dt><a href="#vec3">vec3</a> : <code>Array.&lt;number&gt;</code></dt>
 <dd></dd>
-<dt><a href="#Options">Options</a> : <code>Object</code></dt>
+<dt><a href="#SimplicialComplex">SimplicialComplex</a> : <code>object</code></dt>
+<dd><p>Geometry definition.</p>
+</dd>
+<dt><a href="#SimplicialComplexWithTNB">SimplicialComplexWithTNB</a> : <code>object</code></dt>
+<dd><p>Geometry definition augmented with tangent, normals and binormals.</p>
+</dd>
+<dt><a href="#Options">Options</a> : <code>object</code></dt>
 <dd><p>Options for frames computation. All optional.</p>
 </dd>
-<dt><a href="#Frame">Frame</a> : <code>Object</code></dt>
-<dd></dd>
 </dl>
 
 <a name="frenetSerretFrames"></a>
 
-## frenetSerretFrames(points, tangents, [options]) ⇒ [<code>Array.&lt;Frame&gt;</code>](#Frame)
+## frenetSerretFrames(geometry, [options]) ⇒ [<code>SimplicialComplexWithTNB</code>](#SimplicialComplexWithTNB)
 
-Compute Frenet-Serret frames for a path of 3D points and tangents
+Compute Frenet-Serret frames for a geometry of 3D positions and optionally provided tangents.
 
-**Kind**: global function  
+**Kind**: global function
 **See**: [Frenet–Serret formulas](https://en.wikipedia.org/wiki/Frenet%E2%80%93Serret_formulas)
 
-| Param     | Type                                     | Default         | Description                                                             |
-| --------- | ---------------------------------------- | --------------- | ----------------------------------------------------------------------- |
-| points    | [<code>Array.&lt;vec3&gt;</code>](#vec3) |                 | Array of 3D points [x, y, z].                                           |
-| tangents  | [<code>Array.&lt;vec3&gt;</code>](#vec3) |                 | Array of 3D points [x, y, z] corresponding to the tangents of the path. |
-| [options] | [<code>Options</code>](#Options)         | <code>{}</code> |                                                                         |
+| Param     | Type                                                 | Default         |
+| --------- | ---------------------------------------------------- | --------------- |
+| geometry  | [<code>SimplicialComplex</code>](#SimplicialComplex) |                 |
+| [options] | [<code>Options</code>](#Options)                     | <code>{}</code> |
 
 <a name="vec3"></a>
 
 ## vec3 : <code>Array.&lt;number&gt;</code>
 
-**Kind**: global typedef  
+**Kind**: global typedef
+<a name="SimplicialComplex"></a>
+
+## SimplicialComplex : <code>object</code>
+
+Geometry definition.
+
+**Kind**: global typedef
+**Properties**
+
+| Name       | Type                                                                                                                        |
+| ---------- | --------------------------------------------------------------------------------------------------------------------------- |
+| positions  | <code>Float32Array</code> \| [<code>Array.&lt;vec3&gt;</code>](#vec3)                                                       |
+| [tangents] | <code>Float32Array</code> \| [<code>Array.&lt;vec3&gt;</code>](#vec3)                                                       |
+| [normals]  | <code>Float32Array</code> \| [<code>Array.&lt;vec3&gt;</code>](#vec3)                                                       |
+| [uvs]      | <code>Float32Array</code> \| [<code>Array.&lt;vec3&gt;</code>](#vec3)                                                       |
+| [cells]    | <code>Uint8Array</code> \| <code>Uint16Array</code> \| <code>Uint32Array</code> \| [<code>Array.&lt;vec3&gt;</code>](#vec3) |
+
+<a name="SimplicialComplexWithTNB"></a>
+
+## SimplicialComplexWithTNB : <code>object</code>
+
+Geometry definition augmented with tangent, normals and binormals.
+
+**Kind**: global typedef
+**Properties**
+
+| Name      | Type                                                                                                                        |
+| --------- | --------------------------------------------------------------------------------------------------------------------------- |
+| positions | <code>Float32Array</code> \| [<code>Array.&lt;vec3&gt;</code>](#vec3)                                                       |
+| tangents  | <code>Float32Array</code> \| [<code>Array.&lt;vec3&gt;</code>](#vec3)                                                       |
+| normals   | <code>Float32Array</code> \| [<code>Array.&lt;vec3&gt;</code>](#vec3)                                                       |
+| binormals | <code>Float32Array</code> \| [<code>Array.&lt;vec3&gt;</code>](#vec3)                                                       |
+| [uvs]     | <code>Float32Array</code> \| [<code>Array.&lt;vec3&gt;</code>](#vec3)                                                       |
+| [cells]   | <code>Uint8Array</code> \| <code>Uint16Array</code> \| <code>Uint32Array</code> \| [<code>Array.&lt;vec3&gt;</code>](#vec3) |
+
 <a name="Options"></a>
 
-## Options : <code>Object</code>
+## Options : <code>object</code>
 
 Options for frames computation. All optional.
 
-**Kind**: global typedef  
+**Kind**: global typedef
 **Properties**
 
 | Name            | Type                       | Default            | Description                                                                                          |
@@ -96,20 +134,6 @@ Options for frames computation. All optional.
 | [closed]        | <code>boolean</code>       | <code>false</code> | Specify is the path is closed.                                                                       |
 | [initialNormal] | [<code>vec3</code>](#vec3) | <code></code>      | Specify a starting normal for the frames. Default to the direction of the minimum tangent component. |
 
-<a name="Frame"></a>
-
-## Frame : <code>Object</code>
-
-**Kind**: global typedef  
-**Properties**
-
-| Name     | Type                       |
-| -------- | -------------------------- |
-| position | [<code>vec3</code>](#vec3) |
-| normal   | [<code>vec3</code>](#vec3) |
-| binormal | [<code>vec3</code>](#vec3) |
-| tangent  | [<code>vec3</code>](#vec3) |
-
 <!-- api-end -->
 
 ## License

package/index.js

@@ -1,132 +1,147 @@
-import { vec3, quat } from "gl-matrix";
-import clamp from "clamp";
-
-/**
- * @typedef {number[]} vec3
- */
-
-/**
- * @typedef {Object} Options Options for frames computation. All optional.
- * @property {boolean} [closed=false] Specify is the path is closed.
- * @property {vec3} [initialNormal=null] Specify a starting normal for the frames. Default to the direction of the minimum tangent component.
- */
-
-/**
- * @typedef {Object} Frame
- * @property {vec3} position
- * @property {vec3} normal
- * @property {vec3} binormal
- * @property {vec3} tangent
- */
+import { avec3, vec3, quat, utils } from "pex-math";
+import computePathTangents from "path-tangents";
 
 const X_UP = [1, 0, 0];
 const Y_UP = [0, 1, 0];
 const Z_UP = [0, 0, 1];
 
 /**
- * Compute Frenet-Serret frames for a path of 3D points and tangents
+ * Compute Frenet-Serret frames for a geometry of 3D positions and optionally provided tangents.
  *
- * @param {vec3[]} points Array of 3D points [x, y, z].
- * @param {vec3[]} tangents Array of 3D points [x, y, z] corresponding to the tangents of the path.
- * @param {Options} [options={}]
- * @returns {Frame[]}
+ * @param {import("./types.js").SimplicialComplex} geometry
+ * @param {import("./types.js").Options} [options={}]
+ * @returns {import("./types.js").SimplicialComplexWithTNB}
  *
  * @see [Frenet–Serret formulas]{@link https://en.wikipedia.org/wiki/Frenet%E2%80%93Serret_formulas}
  */
-function frenetSerretFrames(points, tangents, options) {
+function frenetSerretFrames(geometry, options) {
+  const isTypedArray = !Array.isArray(geometry.positions);
+
   // Extends options
-  const { closed = false, initialNormal = null } = {
-    ...options,
-  };
+  const { closed = false, initialNormal = null } = { ...options };
 
-  const frames = [];
-  const v = vec3.create();
+  const size = geometry.positions.length / (isTypedArray ? 3 : 1);
+  geometry.tangents ||= computePathTangents(geometry.positions, closed);
+  geometry.normals ||= isTypedArray ? new Float32Array(size * 3) : [];
+  geometry.binormals ||= isTypedArray ? new Float32Array(size * 3) : [];
 
-  // Compute initial frame
-  let tangent = tangents[0];
-  let normal = initialNormal || vec3.create();
+  let v = vec3.create();
 
-  const atx = Math.abs(tangent[0]);
-  const aty = Math.abs(tangent[1]);
-  const atz = Math.abs(tangent[2]);
+  // Compute initial frame
+  let tangent = isTypedArray
+    ? geometry.tangents.slice(0, 3)
+    : geometry.tangents[0];
+  let normal;
+
+  if (initialNormal) {
+    normal = [...initialNormal];
+  } else {
+    const atx = Math.abs(tangent[0]);
+    const aty = Math.abs(tangent[1]);
+    const atz = Math.abs(tangent[2]);
 
-  if (!initialNormal) {
     if (aty > atx && aty >= atz) {
-      vec3.cross(v, tangent, X_UP);
+      v = vec3.cross([...tangent], X_UP);
     } else if (atz > atx && atz >= aty) {
-      vec3.cross(v, tangent, Y_UP);
+      v = vec3.cross([...tangent], Y_UP);
     } else {
-      vec3.cross(v, tangent, Z_UP);
+      v = vec3.cross([...tangent], Z_UP);
     }
 
-    vec3.cross(normal, tangent, v);
-    vec3.normalize(normal, normal);
+    normal = vec3.normalize(vec3.cross([...tangent], v));
   }
 
-  let binormal = vec3.cross(vec3.create(), tangent, normal);
-  vec3.normalize(binormal, binormal);
+  let binormal = vec3.normalize(vec3.cross([...tangent], normal));
 
-  frames.push({
-    position: [...points[0]],
-    normal: vec3.clone(normal),
-    binormal: vec3.clone(binormal),
-    tangent: vec3.clone(tangent),
-  });
+  if (isTypedArray) {
+    geometry.normals.set(normal);
+    geometry.binormals.set(binormal);
+  } else {
+    geometry.normals.push(normal);
+    geometry.binormals.push(binormal);
+  }
 
   // Compute the rest of the frames
   const rotation = quat.create();
-  let previousTangent;
+  let previousTangent = vec3.create();
+
+  for (let i = 1; i < size; i++) {
+    if (isTypedArray) {
+      avec3.set(previousTangent, 0, geometry.tangents, i - 1);
+      avec3.set(tangent, 0, geometry.tangents, i);
+    } else {
+      previousTangent = geometry.tangents[i - 1];
+      tangent = geometry.tangents[i];
+    }
 
-  for (let i = 1; i < points.length; i++) {
-    const position = points[i];
-    previousTangent = tangents[i - 1];
-    tangent = tangents[i];
-    normal = vec3.clone(normal);
-    binormal = vec3.clone(binormal);
+    normal = vec3.copy(normal);
+    binormal = vec3.copy(binormal);
 
-    vec3.cross(v, previousTangent, tangent);
+    v = vec3.cross([...previousTangent], tangent);
 
     if (vec3.length(v) > Number.EPSILON) {
-      vec3.normalize(v, v);
+      vec3.normalize(v);
 
-      let theta = Math.acos(clamp(vec3.dot(previousTangent, tangent), -1, 1));
-      quat.setAxisAngle(rotation, v, theta);
-      vec3.transformQuat(normal, normal, rotation);
+      const theta = Math.acos(
+        utils.clamp(vec3.dot(previousTangent, tangent), -1, 1),
+      );
+      quat.fromAxisAngle(rotation, v, theta);
+      vec3.multQuat(normal, rotation);
+    }
+    binormal = vec3.cross([...tangent], normal);
+
+    if (isTypedArray) {
+      avec3.set(geometry.normals, i, normal, 0);
+      avec3.set(geometry.binormals, i, binormal, 0);
+    } else {
+      geometry.normals.push(normal);
+      geometry.binormals.push(binormal);
     }
-    vec3.cross(binormal, tangent, normal);
-
-    frames.push({
-      position: [...position],
-      normal: vec3.clone(normal),
-      binormal: vec3.clone(binormal),
-      tangent: vec3.clone(tangent),
-    });
   }
 
   if (closed) {
-    const firstNormal = frames[0].normal;
-    const lastNormal = frames[frames.length - 1].normal;
-
-    let theta = Math.acos(clamp(vec3.dot(firstNormal, lastNormal), 0, 1));
-    theta /= frames.length - 1;
-
-    if (
-      vec3.dot(
-        vec3.clone(tangents[0]),
-        vec3.cross(v, firstNormal, lastNormal)
-      ) > 0
-    ) {
+    const firstNormal = isTypedArray
+      ? geometry.normals.slice(0, 3)
+      : geometry.normals[0];
+    const lastNormal = isTypedArray
+      ? geometry.normals.slice(-3)
+      : geometry.normals.at(-1);
+    const firstTangent = isTypedArray
+      ? geometry.tangents.slice(0, 3)
+      : geometry.tangents[0];
+
+    let theta = Math.acos(
+      utils.clamp(vec3.dot(firstNormal, lastNormal), -1, 1),
+    );
+    theta /= size - 1;
+
+    if (vec3.dot(firstTangent, vec3.cross([...firstNormal], lastNormal)) > 0) {
       theta = -theta;
     }
 
-    frames.forEach(({ normal, binormal, tangent }, index) => {
-      quat.setAxisAngle(rotation, tangent, theta * index);
-      vec3.transformQuat(normal, normal, rotation);
-      vec3.cross(binormal, tangent, normal);
-    });
+    for (let i = 0; i < size; i++) {
+      if (isTypedArray) {
+        avec3.set(tangent, 0, geometry.tangents, i);
+        avec3.set(normal, 0, geometry.normals, i);
+        avec3.set(binormal, 0, geometry.binormals, i);
+
+        quat.fromAxisAngle(rotation, tangent, theta * i);
+        vec3.multQuat(normal, rotation);
+        binormal = vec3.cross([...tangent], normal);
+
+        avec3.set(geometry.normals, i, normal, 0);
+        avec3.set(geometry.binormals, i, binormal, 0);
+      } else {
+        const tangent = geometry.tangents[i];
+        const normal = geometry.normals[i];
+        quat.fromAxisAngle(rotation, tangent, theta * i);
+        vec3.multQuat(normal, rotation);
+        geometry.binormals[i] = vec3.cross([...tangent], normal);
+      }
+    }
   }
 
-  return frames;
+  return geometry;
 }
 
 export default frenetSerretFrames;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "frenet-serret-frames",
-  "version": "2.1.0",
-  "description": "Compute Frenet-Serret frames for a path of 3D points and tangents.",
+  "version": "3.0.0",
+  "description": "Compute Frenet-Serret frames for a geometry of 3D positions and optionally provided tangents.",
   "keywords": [
     "path",
     "spline",
@@ -33,20 +33,17 @@
   "main": "index.js",
   "types": "types/index.d.ts",
   "dependencies": {
-    "clamp": "^1.0.1",
-    "gl-matrix": "^3.3.0"
+    "pex-math": "^4.0.0-alpha.3"
   },
   "devDependencies": {
-    "assert": "^2.0.0",
-    "core-js": "^3.14.0",
-    "es-module-shims": "^0.10.7",
-    "path-tangents": "^2.0.1",
-    "pex-cam": "^2.8.0",
-    "pex-context": "^2.10.4",
-    "tweakpane": "^3.0.2"
+    "es-module-shims": "^1.8.0",
+    "path-tangents": "^3.0.0",
+    "pex-cam": "^3.0.0-alpha.1",
+    "pex-context": "^3.0.0-alpha.7",
+    "tweakpane": "^3.1.10"
   },
   "engines": {
-    "node": ">=15.0.0",
-    "npm": ">=7.0.0"
+    "node": ">=18.0.0",
+    "npm": ">=8.6.0"
   }
 }

package/types/index.d.ts

@@ -1,33 +1,11 @@
 export default frenetSerretFrames;
-export type vec3 = number[];
 /**
- * Options for frames computation. All optional.
- */
-export type Options = {
-    /**
-     * Specify is the path is closed.
-     */
-    closed?: boolean;
-    /**
-     * Specify a starting normal for the frames. Default to the direction of the minimum tangent component.
-     */
-    initialNormal?: vec3;
-};
-export type Frame = {
-    position: vec3;
-    normal: vec3;
-    binormal: vec3;
-    tangent: vec3;
-};
-/**
- * Compute Frenet-Serret frames for a path of 3D points and tangents
+ * Compute Frenet-Serret frames for a geometry of 3D positions and optionally provided tangents.
  *
- * @param {vec3[]} points Array of 3D points [x, y, z].
- * @param {vec3[]} tangents Array of 3D points [x, y, z] corresponding to the tangents of the path.
- * @param {Options} [options={}]
- * @returns {Frame[]}
+ * @param {import("./types.js").SimplicialComplex} geometry
+ * @param {import("./types.js").Options} [options={}]
+ * @returns {import("./types.js").SimplicialComplexWithTNB}
  *
  * @see [Frenet–Serret formulas]{@link https://en.wikipedia.org/wiki/Frenet%E2%80%93Serret_formulas}
  */
-declare function frenetSerretFrames(points: vec3[], tangents: vec3[], options?: Options): Frame[];
-import { vec3 } from "gl-matrix";
+declare function frenetSerretFrames(geometry: import("./types.js").SimplicialComplex, options?: import("./types.js").Options): import("./types.js").SimplicialComplexWithTNB;

package/types/types.d.ts

@@ -0,0 +1,35 @@
+export type vec3 = number[];
+/**
+ * Geometry definition.
+ */
+export type SimplicialComplex = {
+    positions: Float32Array | vec3[];
+    tangents?: Float32Array | vec3[];
+    normals?: Float32Array | vec3[];
+    uvs?: Float32Array | vec3[];
+    cells?: (Uint8Array | Uint16Array | Uint32Array | vec3[]);
+};
+/**
+ * Geometry definition augmented with tangent, normals and binormals.
+ */
+export type SimplicialComplexWithTNB = {
+    positions: Float32Array | vec3[];
+    tangents: Float32Array | vec3[];
+    normals: Float32Array | vec3[];
+    binormals: Float32Array | vec3[];
+    uvs?: Float32Array | vec3[];
+    cells?: (Uint8Array | Uint16Array | Uint32Array | vec3[]);
+};
+/**
+ * Options for frames computation. All optional.
+ */
+export type Options = {
+    /**
+     * Specify is the path is closed.
+     */
+    closed?: boolean;
+    /**
+     * Specify a starting normal for the frames. Default to the direction of the minimum tangent component.
+     */
+    initialNormal?: vec3;
+};

package/types.js

@@ -0,0 +1,30 @@
+/**
+ * @typedef {number[]} vec3
+ */
+
+/**
+ * @typedef {object} SimplicialComplex Geometry definition.
+ * @property {Float32Array | vec3[]} positions
+ * @property {Float32Array | vec3[]} [tangents]
+ * @property {Float32Array | vec3[]} [normals]
+ * @property {Float32Array | vec3[]} [uvs]
+ * @property {(Uint8Array | Uint16Array | Uint32Array | vec3[])} [cells]
+ */
+
+/**
+ * @typedef {object} SimplicialComplexWithTNB Geometry definition augmented with tangent, normals and binormals.
+ * @property {Float32Array | vec3[]} positions
+ * @property {Float32Array | vec3[]} tangents
+ * @property {Float32Array | vec3[]} normals
+ * @property {Float32Array | vec3[]} binormals
+ * @property {Float32Array | vec3[]} [uvs]
+ * @property {(Uint8Array | Uint16Array | Uint32Array | vec3[])} [cells]
+ */
+
+/**
+ * @typedef {object} Options Options for frames computation. All optional.
+ * @property {boolean} [closed=false] Specify is the path is closed.
+ * @property {vec3} [initialNormal=null] Specify a starting normal for the frames. Default to the direction of the minimum tangent component.
+ */
+
+export {};