frenet-serret-frames

Compute rotation minimizing (Bishop) or Frenet-Serret frames for a path of 3D positions.

Installation

npm install frenet-serret-frames

Features

• Bishop frames (default): rotation minimizing frames, also known as parallel transport frames, computed with the double reflection method. Minimal twist around the path, suited for sweeping tubes and ribbons.
• Frenet frames: normal pointing towards the centre of curvature. Flips at inflection points; straight parts take the nearest frame.
• Seamless closed paths: the mismatch at the seam is spread along the arc length.
• Constraints: initialNormal, finalNormal on open paths, and an additional twist spread along the arc length.
• Any layout: flat or nested positions, normals and binormals out in the same layout, written into provided arrays.
• Robust: duplicated points, straight lines and reversed tangents handled without flips.

Usage

import frenetSerretFrames from "frenet-serret-frames";
import { squirclePath } from "primitive-geometry";

const geometry = squirclePath();
frenetSerretFrames(geometry, {
  closed: false,
  mode: "bishop",
  initialNormal: null,
  finalNormal: null,
  twist: 0,
});
console.log(geometry);
// {
//   positions: Float32Array [x, y, z, x, y, z, ...],
//   cells: [[a, b, c, ...]],
//   tangents: Float32Array [x, y, z, x, y, z, ...],
//   normals: Float32Array [x, y, z, x, y, z, ...],
//   binormals: Float32Array [x, y, z, x, y, z, ...],
// }

API

Functions

Typedefs

frenetSerretFrames(geometry, [options]) ⇒ SimplicialComplexWithTNB

Compute rotation minimizing (Bishop) or Frenet-Serret frames for a path of 3D positions.

Kind: global function See

• Frenet–Serret formulas
• Computation of Rotation Minimizing Frames (Wang et al. 2008)

| Param | Type | Default | | --------- | ---------------------------------------------------- | --------------- | | geometry | SimplicialComplex | | | [options] | Options | {} |

SimplicialComplex : object

Geometry definition.

Kind: global typedef Properties

| Name | Type | | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | positions | module:pex-math~TypedArray | Array.<number> | Array.<module:pex-math~Vec3> | | [tangents] | module:pex-math~TypedArray | Array.<number> | Array.<module:pex-math~Vec3> | | [normals] | module:pex-math~TypedArray | Array.<number> | Array.<module:pex-math~Vec3> | | [binormals] | module:pex-math~TypedArray | Array.<number> | Array.<module:pex-math~Vec3> | | [uvs] | module:pex-math~TypedArray | Array.<number> | Array.<module:pex-math~Vec2> | | [cells] | Uint8Array | Uint16Array | Uint32Array | Array | Array.<module:pex-math~Vec3> |

SimplicialComplexWithTNB : object

Geometry definition augmented with tangents, normals and binormals.

Kind: global typedef Properties

| Name | Type | | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | positions | module:pex-math~TypedArray | Array.<number> | Array.<module:pex-math~Vec3> | | tangents | module:pex-math~TypedArray | Array.<number> | Array.<module:pex-math~Vec3> | | normals | module:pex-math~TypedArray | Array.<number> | Array.<module:pex-math~Vec3> | | binormals | module:pex-math~TypedArray | Array.<number> | Array.<module:pex-math~Vec3> | | [uvs] | module:pex-math~TypedArray | Array.<number> | Array.<module:pex-math~Vec2> | | [cells] | Uint8Array | Uint16Array | Uint32Array | Array | Array.<module:pex-math~Vec3> |

Options : object

Options for frames computation. All optional.

Kind: global typedef Properties

| Name | Type | Default | Description | | --------------- | ------------------------------------------------------------------ | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | [closed] | boolean | false | Specify if the path is closed. | | [mode] | "bishop" | "frenet" | "bishop" | Frame type: - "bishop": rotation minimizing (parallel transport) frames, computed with the double reflection method. Twist free, suited for sweeping. - "frenet": normal pointing towards the curvature centre. Flips at inflection points and is undefined on straight parts, where the nearest frame is transported instead. | | [initialNormal] | module:pex-math~Vec3 | | Specify a starting normal for "bishop" frames, made orthogonal to the first tangent. Defaults to a coordinate axis not aligned with the first tangent, also used when the initial normal is parallel to it. | | [finalNormal] | module:pex-math~Vec3 | | Specify an ending normal for "bishop" frames of open paths, made orthogonal to the last tangent. Reached with the smallest rotation, spread along the arc length. Ignored when parallel to the last tangent. | | [twist] | number | 0 | Additional rotation of "bishop" frames around the tangent, in radians, spread along the arc length from the first frame to the last. Closed paths and paths with a final normal need a multiple of 2π to keep their end frame, or of π when the sign of the normal doesn't matter (eg. flat ribbons). |

License

MIT. See license file.