bezier-spline-eval

A lightweight, high-performance TypeScript library for evaluating cubic and quadratic Bézier splines, finding their extents (bounding box), and calculating inflection points. Built with gl-matrix for performance and zero allocations during calculations.

Perfect for graphics applications, UI development, game development, and any other case where you need to analyze Bézier curves.

Features

• ✅ Cubic and Quadratic Bézier Splines: Full support for both common curve types.
• ✅ N-Dimensional: Works with points of any dimension (e.g., 2D, 3D).
• ✅ Evaluation: Find the position on a curve at any t value.
• ✅ Extents: Calculate the precise axis-aligned bounding box.
• ✅ Critical Points: Find t values for maxima, minima, and inflections.
• ✅ Performant: Uses gl-matrix under the hood.
• ✅ TypeScript Native: Fully typed for a great developer experience.
• ✅ Modern: Outputs ES Modules and UMD bundles.

Installation

npm install bezier-spline-eval

Usage

Here’s a quick example of how to use the library.

import { CubicSpline, QuadraticSpline } from 'bezier-spline-eval';

// --- Quadratic Example (e.g., SVG 'Q' command) ---

const quadraticPoints = [[0, 0], [100, 200], [200, 0]];
const quadSpline = new QuadraticSpline(quadraticPoints);

// Get the point at the halfway mark
const midPoint = quadSpline.evaluate(0.5); // [100, 100]

// Get the bounding box of the curve
const quadExtents = quadSpline.extents();
// quadExtents will be [[0, 0], [200, 100]]

console.log('Quadratic midpoint:', midPoint);
console.log('Quadratic extents:', quadExtents);


// --- Cubic Example (e.g., SVG 'C' command) ---

const cubicPoints = [[0, 0], [50, 200], [150, -200], [200, 0]];
const cubicSpline = new CubicSpline(cubicPoints);

// Find the t-value of the peak height
const criticalPoints = cubicSpline.curveMaximaMinimaT();
const yCriticalT = criticalPoints[1][0]; // ~0.31

// Get the peak point on the curve
const peakPoint = cubicSpline.evaluate(yCriticalT);

// Get the bounding box
const cubicExtents = cubicSpline.extents();

console.log('Cubic peak point:', peakPoint);
console.log('Cubic extents:', cubicExtents);

API

new QuadraticSpline(points: Point[])

Creates a quadratic spline instance. points must be an array of 3 points, where each point is an array of numbers (e.g., [x, y]).

new CubicSpline(points: Point[])

Creates a cubic spline instance. points must be an array of 4 points.

Instance Methods

• .evaluate(t: number | number[]): Point | Point[] Calculates the point(s) on the curve for the given t value(s) (from 0 to 1).

• .extents(): [Point, Point] | null Returns the bounding box of the curve as a tuple [minPoint, maxPoint].

• .extremes(): Point[] Returns an array of all points on the curve that define its extents (i.e., the start/end points and all critical points).

• .curveMaximaMinimaT(): Record<number, number[]> Returns a dictionary where keys are dimension indices and values are arrays of t values where that dimension's derivative is zero.

• .curveInflectionT(): Record<number, number[]> (CubicSpline only) Returns a dictionary of t values where the curve has an inflection point in that dimension.

Development

To work on this project locally:

1. Clone the repository
2. Install dependencies: npm install
3. Run tests: npm test
4. Build the library: npm run build

This project uses Vite for building and Vitest for testing.

License

MIT