toosoon-utils 4.0.6 → 4.1.0

package/lib/constants.d.ts

@@ -1,8 +1,10 @@
 export declare const EPSILON = 1e-10;
 export declare const PI: number;
 export declare const TWO_PI: number;
+export declare const TAU: number;
 export declare const HALF_PI: number;
 export declare const QUARTER_PI: number;
+export declare const TAU_EPSILON: number;
 export declare const W3CX11: {
     aliceblue: number;
     antiquewhite: number;

package/lib/constants.js

@@ -3,9 +3,11 @@
 // *********************
 export const EPSILON = 1e-10;
 export const PI = Math.PI;
-export const TWO_PI = Math.PI * 2;
-export const HALF_PI = Math.PI / 2;
-export const QUARTER_PI = Math.PI / 4;
+export const TWO_PI = PI * 2;
+export const TAU = PI * 2;
+export const HALF_PI = PI / 2;
+export const QUARTER_PI = PI / 4;
+export const TAU_EPSILON = TAU - EPSILON;
 // *********************
 // Colors
 // *********************

package/lib/extras/_wip/pool.d.ts

@@ -0,0 +1,56 @@
+export type PoolSettings = {
+    max?: number;
+};
+export declare const defaultSettings: Required<PoolSettings>;
+type PoolItem = {
+    setup?: () => void;
+    reset?: () => void;
+    dispose?: () => void;
+};
+/**
+ * Abstract class for manipulating pool items
+ *
+ * @exports
+ * @class Pool
+ */
+export default abstract class Pool<I extends PoolItem> {
+    items: I[];
+    pool: I[];
+    settings: Required<PoolSettings>;
+    constructor(settings?: PoolSettings);
+    /**
+     * Abstract method to implement custom item creation
+     *
+     * @returns {PoolItem}
+     */
+    protected abstract create(): I;
+    /**
+     * Add an item to the active items
+     *
+     * @param {PoolItem} item Item to add to the active items
+     */
+    protected add(item: I): void;
+    /**
+     * Remove an item from the active items
+     *
+     * @param {PoolItem} item Item to remove from the active items
+     */
+    protected remove(item: I): void;
+    /**
+     * Return an item from pool or create a new one
+     *
+     * @returns {PoolItem|undefined}
+     */
+    get(): I | undefined;
+    /**
+     * Release an item from the active items and add it to the pool
+     *
+     * @param {PoolItem} item Item to release
+     */
+    release(item: I): void;
+    /**
+     * Dispose all items
+     */
+    dispose(): void;
+}
+export {};

package/lib/extras/_wip/pool.js

@@ -0,0 +1,67 @@
+// *********************
+// WIP
+// *********************
+export const defaultSettings = {
+    max: Infinity
+};
+/**
+ * Abstract class for manipulating pool items
+ *
+ * @exports
+ * @class Pool
+ */
+export default class Pool {
+    items = [];
+    pool = [];
+    settings = { ...defaultSettings };
+    constructor(settings = { ...defaultSettings }) {
+        this.settings = Object.assign(this.settings, settings);
+    }
+    /**
+     * Add an item to the active items
+     *
+     * @param {PoolItem} item Item to add to the active items
+     */
+    add(item) {
+        this.items.push(item);
+    }
+    /**
+     * Remove an item from the active items
+     *
+     * @param {PoolItem} item Item to remove from the active items
+     */
+    remove(item) {
+        this.items = this.items.filter((_item) => _item !== item);
+    }
+    /**
+     * Return an item from pool or create a new one
+     *
+     * @returns {PoolItem|undefined}
+     */
+    get() {
+        if (this.items.length >= this.settings.max)
+            return;
+        const item = this.pool.pop() ?? this.create();
+        item.setup?.();
+        this.add(item);
+        return item;
+    }
+    /**
+     * Release an item from the active items and add it to the pool
+     *
+     * @param {PoolItem} item Item to release
+     */
+    release(item) {
+        this.pool.push(item);
+        item.reset?.();
+        this.remove(item);
+    }
+    /**
+     * Dispose all items
+     */
+    dispose() {
+        [...this.items, ...this.pool].forEach((item) => item.dispose?.());
+        this.items = [];
+        this.pool = [];
+    }
+}

package/lib/{classes/color-scale.d.ts → extras/color-scale/ColorScale.d.ts}

@@ -1,4 +1,4 @@
-import type { ColorRepresentation } from '../types';
+import type { ColorRepresentation } from '../../types';
 export type ColorScaleSettings = {
     colorSpace: 'rgb';
 } | {

package/lib/{classes/color-scale.js → extras/color-scale/ColorScale.js}

@@ -1,5 +1,5 @@
-import { lerp, triLerp } from '../maths';
-import { hclToRgb, hsbToRgb, hslToRgb, normalizeColor, rgbToHcl, rgbToHsb, rgbToHsl } from '../colors';
+import { lerp, triLerp } from '../../maths';
+import { hclToRgb, hsbToRgb, hslToRgb, normalizeColor, rgbToHcl, rgbToHsb, rgbToHsl } from '../../colors';
 export const defaultSettings = {
     colorSpace: 'rgb'
 };

package/lib/extras/curves/ArcCurve.d.ts

@@ -0,0 +1,19 @@
+import EllipseCurve from './EllipseCurve';
+/**
+ * Utility class for manipulating Arc curves
+ *
+ * @exports
+ * @class ArcCurve
+ * @extends Curve
+ */
+export default class ArcCurve extends EllipseCurve {
+    /**
+     * @param {number} cx X-axis coordinate of the center of the circle
+     * @param {number} cy Y-axis coordinate of the center of the circle
+     * @param {number} radius Radius of the circle
+     * @param {number} [startAngle] Rotation angle of the arc (in radians)
+     * @param {number} [endAngle]   Rotation angle of the arc (in radians)
+     * @param {boolean} [counterclockwise] Flag indicating the direction of the arc
+     */
+    constructor(cx: number, cy: number, radius: number, startAngle?: number, endAngle?: number, counterclockwise?: boolean);
+}

package/lib/extras/curves/ArcCurve.js

@@ -0,0 +1,21 @@
+import EllipseCurve from './EllipseCurve';
+/**
+ * Utility class for manipulating Arc curves
+ *
+ * @exports
+ * @class ArcCurve
+ * @extends Curve
+ */
+export default class ArcCurve extends EllipseCurve {
+    /**
+     * @param {number} cx X-axis coordinate of the center of the circle
+     * @param {number} cy Y-axis coordinate of the center of the circle
+     * @param {number} radius Radius of the circle
+     * @param {number} [startAngle] Rotation angle of the arc (in radians)
+     * @param {number} [endAngle]   Rotation angle of the arc (in radians)
+     * @param {boolean} [counterclockwise] Flag indicating the direction of the arc
+     */
+    constructor(cx, cy, radius, startAngle, endAngle, counterclockwise) {
+        super(cx, cy, radius, radius, 0, startAngle, endAngle, counterclockwise);
+    }
+}

package/lib/extras/curves/CatmulRomCurve.d.ts

@@ -0,0 +1,62 @@
+import type { Point } from 'src/types';
+import Curve from './Curve';
+/**
+ * Utility class for manipulating Catmull-Rom curves
+ *
+ * @exports
+ * @class CatmullRomCurve
+ * @extends Curve
+ */
+export default class CatmullRomCurve extends Curve {
+    readonly type: string;
+    /**
+     * X-axis coordinate of the start point
+     */
+    x1: number;
+    /**
+     * Y-axis coordinate of the start point
+     */
+    y1: number;
+    /**
+     * X-axis coordinate of the first control point
+     */
+    cp1x: number;
+    /**
+     * Y-axis coordinate of the first control point
+     */
+    cp1y: number;
+    /**
+     * X-axis coordinate of the second control point
+     */
+    cp2x: number;
+    /**
+     * Y-axis coordinate of the second control point
+     */
+    cp2y: number;
+    /**
+     * X-axis coordinate of the end point
+     */
+    x2: number;
+    /**
+     * Y-axis coordinate of the end point
+     */
+    y2: number;
+    /**
+     * @param {number} x1   X-axis coordinate of the start point
+     * @param {number} y1   Y-axis coordinate of the start point
+     * @param {number} cp1x X-axis coordinate of the first control point
+     * @param {number} cp1y Y-axis coordinate of the first control point
+     * @param {number} cp2x X-axis coordinate of the second control point
+     * @param {number} cp2y Y-axis coordinate of the second control point
+     * @param {number} x2   X-axis coordinate of the end point
+     * @param {number} y2   Y-axis coordinate of the end point
+     */
+    constructor(x1: number, y1: number, cp1x: number, cp1y: number, cp2x: number, cp2y: number, x2: number, y2: number);
+    /**
+     * Interpolate a point on the Catmull-Rom curve
+     *
+     * @param {number} t Normalized time value to interpolate
+     * @returns {Point} Interpolated coordinates on the curve
+     */
+    getPoint(t: number): Point;
+}

package/lib/extras/curves/CatmulRomCurve.js

@@ -0,0 +1,75 @@
+import { catmullRom } from 'src/geometry';
+import Curve from './Curve';
+/**
+ * Utility class for manipulating Catmull-Rom curves
+ *
+ * @exports
+ * @class CatmullRomCurve
+ * @extends Curve
+ */
+export default class CatmullRomCurve extends Curve {
+    type = 'CatmullRomCurve';
+    /**
+     * X-axis coordinate of the start point
+     */
+    x1;
+    /**
+     * Y-axis coordinate of the start point
+     */
+    y1;
+    /**
+     * X-axis coordinate of the first control point
+     */
+    cp1x;
+    /**
+     * Y-axis coordinate of the first control point
+     */
+    cp1y;
+    /**
+     * X-axis coordinate of the second control point
+     */
+    cp2x;
+    /**
+     * Y-axis coordinate of the second control point
+     */
+    cp2y;
+    /**
+     * X-axis coordinate of the end point
+     */
+    x2;
+    /**
+     * Y-axis coordinate of the end point
+     */
+    y2;
+    /**
+     * @param {number} x1   X-axis coordinate of the start point
+     * @param {number} y1   Y-axis coordinate of the start point
+     * @param {number} cp1x X-axis coordinate of the first control point
+     * @param {number} cp1y Y-axis coordinate of the first control point
+     * @param {number} cp2x X-axis coordinate of the second control point
+     * @param {number} cp2y Y-axis coordinate of the second control point
+     * @param {number} x2   X-axis coordinate of the end point
+     * @param {number} y2   Y-axis coordinate of the end point
+     */
+    constructor(x1, y1, cp1x, cp1y, cp2x, cp2y, x2, y2) {
+        super();
+        this.x1 = x1;
+        this.y1 = y1;
+        this.cp1x = cp1x;
+        this.cp1y = cp1y;
+        this.cp2x = cp2x;
+        this.cp2y = cp2y;
+        this.x2 = x2;
+        this.y2 = y2;
+    }
+    /**
+     * Interpolate a point on the Catmull-Rom curve
+     *
+     * @param {number} t Normalized time value to interpolate
+     * @returns {Point} Interpolated coordinates on the curve
+     */
+    getPoint(t) {
+        const point = catmullRom(t, this.x1, this.y1, this.cp1x, this.cp1y, this.cp2x, this.cp2y, this.x2, this.y2);
+        return point;
+    }
+}

package/lib/extras/curves/CubicBezierCurve.d.ts

@@ -0,0 +1,62 @@
+import type { Point } from 'src/types';
+import Curve from './Curve';
+/**
+ * Utility class for manipulating Cubic Bézier curves
+ *
+ * @exports
+ * @class CubicBezierCurve
+ * @extends Curve
+ */
+export default class CubicBezierCurve extends Curve {
+    readonly type: string;
+    /**
+     * X-axis coordinate of the start point
+     */
+    x1: number;
+    /**
+     * Y-axis coordinate of the start point
+     */
+    y1: number;
+    /**
+     * X-axis coordinate of the first control point
+     */
+    cp1x: number;
+    /**
+     * Y-axis coordinate of the first control point
+     */
+    cp1y: number;
+    /**
+     * X-axis coordinate of the second control point
+     */
+    cp2x: number;
+    /**
+     * Y-axis coordinate of the second control point
+     */
+    cp2y: number;
+    /**
+     * X-axis coordinate of the end point
+     */
+    x2: number;
+    /**
+     * Y-axis coordinate of the end point
+     */
+    y2: number;
+    /**
+     * @param {number} x1   X-axis coordinate of the start point
+     * @param {number} y1   Y-axis coordinate of the start point
+     * @param {number} cp1x X-axis coordinate of the first control point
+     * @param {number} cp1y Y-axis coordinate of the first control point
+     * @param {number} cp2x X-axis coordinate of the second control point
+     * @param {number} cp2y Y-axis coordinate of the second control point
+     * @param {number} x2   X-axis coordinate of the end point
+     * @param {number} y2   Y-axis coordinate of the end point
+     */
+    constructor(x1: number, y1: number, cp1x: number, cp1y: number, cp2x: number, cp2y: number, x2: number, y2: number);
+    /**
+     * Interpolate a point on the Cubic Bézier curve
+     *
+     * @param {number} t Normalized time value to interpolate
+     * @returns {Point} Interpolated coordinates on the curve
+     */
+    getPoint(t: number): Point;
+}

package/lib/extras/curves/CubicBezierCurve.js

@@ -0,0 +1,75 @@
+import { cubicBezier } from 'src/geometry';
+import Curve from './Curve';
+/**
+ * Utility class for manipulating Cubic Bézier curves
+ *
+ * @exports
+ * @class CubicBezierCurve
+ * @extends Curve
+ */
+export default class CubicBezierCurve extends Curve {
+    type = 'CubicBezierCurve';
+    /**
+     * X-axis coordinate of the start point
+     */
+    x1;
+    /**
+     * Y-axis coordinate of the start point
+     */
+    y1;
+    /**
+     * X-axis coordinate of the first control point
+     */
+    cp1x;
+    /**
+     * Y-axis coordinate of the first control point
+     */
+    cp1y;
+    /**
+     * X-axis coordinate of the second control point
+     */
+    cp2x;
+    /**
+     * Y-axis coordinate of the second control point
+     */
+    cp2y;
+    /**
+     * X-axis coordinate of the end point
+     */
+    x2;
+    /**
+     * Y-axis coordinate of the end point
+     */
+    y2;
+    /**
+     * @param {number} x1   X-axis coordinate of the start point
+     * @param {number} y1   Y-axis coordinate of the start point
+     * @param {number} cp1x X-axis coordinate of the first control point
+     * @param {number} cp1y Y-axis coordinate of the first control point
+     * @param {number} cp2x X-axis coordinate of the second control point
+     * @param {number} cp2y Y-axis coordinate of the second control point
+     * @param {number} x2   X-axis coordinate of the end point
+     * @param {number} y2   Y-axis coordinate of the end point
+     */
+    constructor(x1, y1, cp1x, cp1y, cp2x, cp2y, x2, y2) {
+        super();
+        this.x1 = x1;
+        this.y1 = y1;
+        this.cp1x = cp1x;
+        this.cp1y = cp1y;
+        this.cp2x = cp2x;
+        this.cp2y = cp2y;
+        this.x2 = x2;
+        this.y2 = y2;
+    }
+    /**
+     * Interpolate a point on the Cubic Bézier curve
+     *
+     * @param {number} t Normalized time value to interpolate
+     * @returns {Point} Interpolated coordinates on the curve
+     */
+    getPoint(t) {
+        const point = cubicBezier(t, this.x1, this.y1, this.cp1x, this.cp1y, this.cp2x, this.cp2y, this.x2, this.y2);
+        return point;
+    }
+}

package/lib/extras/curves/Curve.d.ts

@@ -0,0 +1,95 @@
+import type { Point } from 'src/types';
+/**
+ * Utility abstract class for manipulating curves
+ *
+ * @exports
+ * @class Curve
+ * @abstract
+ */
+export default abstract class Curve {
+    readonly type: string;
+    /**
+     * Amount of divisions when calculating the cumulative segment lengths of a curve
+     */
+    arcLengthDivisions: number;
+    /**
+     * Must be set to `true` if the curve parameters have changed
+     */
+    needsUpdate: boolean;
+    protected _cacheArcLengths: number[];
+    /**
+     * Interpolate a point on the curve
+     *
+     * @abstract
+     * @param {number} t Normalized time value to interpolate
+     * @returns {Point} Interpolated coordinates on the curve
+     */
+    abstract getPoint(t: number): Point;
+    /**
+     * Interpolate a point on the curve
+     *
+     * @param {number} u Normalized position value to interpolate
+     * @returns {Point} Interpolated coordinates on the curve
+     */
+    getPointAt(u: number): Point;
+    /**
+     * Compute the curve shape into an array of points
+     *
+     * @param {number} [divisions=5] Number of divisions
+     * @returns {Point[]}
+     */
+    getPoints(divisions?: number): Point[];
+    /**
+     * Compute the curve shape into an array of equi-spaced points across the entire curve
+     *
+     * @param {number} [divisions=5] Number of divisions
+     * @returns {Point[]}
+     */
+    getSpacedPoints(divisions?: number): Point[];
+    /**
+     * Compute the total arc length of the curve
+     *
+     * @returns {number}
+     */
+    getLength(): number;
+    /**
+     * Compute the cumulative segment lengths of the curve
+     *
+     * @param {number} [divisions=this.arcLengthDivisions] Number of divisions
+     * @returns {number[]}
+     */
+    getLengths(divisions?: number): number[];
+    /**
+     * Update the cached cumulative segment lengths
+     */
+    updateArcLengths(): void;
+    /**
+     * Re-map a normalized position value into normalized time
+     *
+     * @param {number} u 								 Normalized position value to interpolate
+     * @param {number} [targetArcLength] Distance on the curve
+     * @returns {number} Updated interpolation value
+     */
+    getUtoTmapping(u: number, targetArcLength?: number): number;
+    /**
+     * Compute an unit vector tangent for the given normalized time value
+     *
+     * @param {number} t Normalized time value
+     * @returns {[number, number]} Tangent vector
+     */
+    getTangent(t: number): Point;
+    /**
+     * Compute an unit vector tangent for the given normalized position value
+     *
+     * @param {number} u Normalized position value
+     * @returns {[number, number]} Tangent vector
+     */
+    getTangentAt(u: number): [number, number];
+    /**
+     * Static method to check if given points are defining a closed curve
+     *
+     * @param {Point[]} points Points to check
+     * @returns {boolean} True if the curve is closed, false otherwise
+     */
+    static isClosed(points: Point[]): boolean;
+}