toosoon-utils 4.0.5 → 4.1.0

package/lib/extras/curves/PathSVG.js

@@ -0,0 +1,135 @@
+import { EPSILON, PI, TWO_PI, TAU_EPSILON } from 'src/constants';
+import { toDegrees } from 'src/geometry';
+import PolylineCurve from './PolylineCurve';
+import CatmullRomCurve from './CatmulRomCurve';
+import SplineCurve from './SplineCurve';
+import EllipseCurve from './EllipseCurve';
+import ArcCurve from './ArcCurve';
+import Path from './Path';
+/**
+ * Utility class for manipulating connected curves and generating SVG path
+ *
+ * It works by serializing 2D Canvas API to SVG path data
+ *
+ * @exports
+ * @class PathSVG
+ * @extends Path
+ */
+export default class PathSVG extends Path {
+    /**
+     * Resolution used for Catmul-Rom curve and Spline curve approximations
+     */
+    curveResolution;
+    constructor({ curveResolution = 10 }) {
+        super();
+        this.curveResolution = curveResolution;
+    }
+    _commands = ``;
+    moveTo(x, y) {
+        super.moveTo(x, y);
+        this._write(`M${x},${y}`);
+        return this;
+    }
+    lineTo(x, y) {
+        super.lineTo(x, y);
+        this._writeLineTo(x, y);
+        return this;
+    }
+    polylineTo(points) {
+        super.polylineTo(points);
+        points.forEach(([x, y]) => this._writeLineTo(x, y));
+        return this;
+    }
+    // public arcTo(x1: number, y1: number, x2: number, y2: number, radius: number): this {
+    //   super.arcTo(x1, y1, x2, y2, radius);
+    //   return this;
+    // }
+    quadraticCurveTo(cpx, cpy, x2, y2) {
+        super.quadraticCurveTo(cpx, cpy, x2, y2);
+        this._write(`Q${cpx},${cpy},${x2},${y2}`);
+        return this;
+    }
+    bezierCurveTo(cp1x, cp1y, cp2x, cp2y, x2, y2) {
+        super.bezierCurveTo(cp1x, cp1y, cp2x, cp2y, x2, y2);
+        this._write(`C${cp1x},${cp1y},${cp2x},${cp2y},${x2},${y2}`);
+        return this;
+    }
+    catmulRomCurveTo(cp1x, cp1y, cp2x, cp2y, x2, y2) {
+        super.catmulRomCurveTo(cp1x, cp1y, cp2x, cp2y, x2, y2);
+        const curve = this.curves[this.curves.length - 1];
+        if (curve instanceof CatmullRomCurve) {
+            curve.getSpacedPoints(curve.getLength() * this.curveResolution).forEach(([x, y]) => this._writeLineTo(x, y));
+        }
+        return this;
+    }
+    splineTo(points) {
+        super.splineTo(points);
+        const curve = this.curves[this.curves.length - 1];
+        if (curve instanceof SplineCurve) {
+            curve.getSpacedPoints(curve.getLength() * this.curveResolution).forEach(([x, y]) => this._writeLineTo(x, y));
+        }
+        return this;
+    }
+    ellipse(cx, cy, rx, ry, rotation = 0, startAngle = 0, endAngle = TWO_PI, counterclockwise) {
+        super.ellipse(cx, cy, rx, ry, rotation, startAngle, endAngle, counterclockwise);
+        const curve = this.curves[this.curves.length - 1];
+        if (curve instanceof EllipseCurve) {
+            this._writeArc(cx, cy, rx, ry, rotation, startAngle, endAngle, counterclockwise);
+        }
+        return this;
+    }
+    arc(cx, cy, radius, startAngle, endAngle, counterclockwise) {
+        super.arc(cx, cy, radius, startAngle, endAngle, counterclockwise);
+        const curve = this.curves[this.curves.length - 1];
+        if (curve instanceof ArcCurve) {
+            this._writeArc(cx, cy, radius, radius, 0, startAngle, endAngle, counterclockwise);
+        }
+        return this;
+    }
+    rect(x, y, width, height) {
+        super.rect(x, y, width, height);
+        const curve = this.curves[this.curves.length - 1];
+        if (curve instanceof PolylineCurve) {
+            curve.points?.forEach(([x, y]) => this._writeLineTo(x, y));
+        }
+        return this;
+    }
+    closePath() {
+        super.closePath();
+        this._write(`Z`);
+        return this;
+    }
+    _writeLineTo(x, y) {
+        this._write(`L${x},${y}`);
+    }
+    _writeArc(cx, cy, rx, ry, rotation = 0, startAngle = 0, endAngle = TWO_PI, counterclockwise) {
+        let deltaAngle = counterclockwise ? startAngle - endAngle : endAngle - startAngle;
+        if (deltaAngle < 0)
+            deltaAngle = (deltaAngle % TWO_PI) + TWO_PI;
+        const xAxisRotation = toDegrees(rotation);
+        const largeArcFlag = deltaAngle >= PI ? 1 : 0;
+        const sweepFlag = counterclockwise ? 0 : 1;
+        if (deltaAngle > TAU_EPSILON) {
+            const dx = Math.cos(startAngle) * rx;
+            const dy = Math.sin(startAngle) * ry;
+            this._write(`A${rx},${ry},${xAxisRotation},1,${sweepFlag},${cx - dx},${cy - dy}`);
+            this._write(`A${rx},${ry},${xAxisRotation},1,${sweepFlag},${cx + dx},${cy + dy}`);
+        }
+        else if (deltaAngle > EPSILON) {
+            const dx = Math.cos(endAngle) * rx;
+            const dy = Math.sin(endAngle) * ry;
+            this._write(`A${rx},${ry},${xAxisRotation},${largeArcFlag},${sweepFlag},${cx + dx},${cy + dy}`);
+        }
+    }
+    _write(command) {
+        this._commands += `${command}`;
+    }
+    /**
+     * Return SVG path data string
+     *
+     * @returns {string}
+     */
+    toString() {
+        return this._commands;
+    }
+}

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

@@ -0,0 +1,27 @@
+import type { Point } from 'src/types';
+import Curve from './Curve';
+/**
+ * Utility class for manipulating Polyline curves
+ *
+ * @exports
+ * @class PolylineCurve
+ * @extends Curve
+ */
+export default class PolylineCurve extends Curve {
+    readonly type: string;
+    /**
+     * Array of points defining the curve
+     */
+    points: Point[];
+    /**
+     * @param {Point[]} [points] Array of points defining the curve
+     */
+    constructor(points?: Point[]);
+    /**
+     * Interpolate a point on the Spline curve
+     *
+     * @param {number} t Normalized time value to interpolate
+     * @returns {Point} Interpolated coordinates on the curve
+     */
+    getPoint(t: number): Point;
+}

package/lib/extras/curves/PolylineCurve.js

@@ -0,0 +1,39 @@
+import { line } from 'src/geometry';
+import Curve from './Curve';
+/**
+ * Utility class for manipulating Polyline curves
+ *
+ * @exports
+ * @class PolylineCurve
+ * @extends Curve
+ */
+export default class PolylineCurve extends Curve {
+    type = 'PolylineCurve';
+    /**
+     * Array of points defining the curve
+     */
+    points = [];
+    /**
+     * @param {Point[]} [points] Array of points defining the curve
+     */
+    constructor(points = []) {
+        super();
+        this.points = points;
+    }
+    /**
+     * Interpolate a point on the Spline curve
+     *
+     * @param {number} t Normalized time value to interpolate
+     * @returns {Point} Interpolated coordinates on the curve
+     */
+    getPoint(t) {
+        const points = this.points;
+        const p = (points.length - 1) * t;
+        const index = Math.floor(p);
+        const weight = p - index;
+        const p1 = points[index === 0 ? index : index - 1];
+        const p2 = points[index];
+        const point = line(weight, ...p1, ...p2);
+        return point;
+    }
+}

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

@@ -0,0 +1,52 @@
+import type { Point } from 'src/types';
+import Curve from './Curve';
+/**
+ * Utility class for manipulating Quadratic Bézier curves
+ *
+ * @exports
+ * @class QuadraticBezierCurve
+ * @extends Curve
+ */
+export default class QuadraticBezierCurve 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 control point
+     */
+    cpx: number;
+    /**
+     * Y-axis coordinate of the control point
+     */
+    cpy: 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} cpx X-axis coordinate of the control point
+     * @param {number} cpy Y-axis coordinate of the 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, cpx: number, cpy: number, x2: number, y2: number);
+    /**
+     * Interpolate a point on the Quadratic 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/QuadraticBezierCurve.js

@@ -0,0 +1,63 @@
+import { quadraticBezier } from 'src/geometry';
+import Curve from './Curve';
+/**
+ * Utility class for manipulating Quadratic Bézier curves
+ *
+ * @exports
+ * @class QuadraticBezierCurve
+ * @extends Curve
+ */
+export default class QuadraticBezierCurve extends Curve {
+    type = 'QuadraticBezierCurve';
+    /**
+     *  X-axis coordinate of the start point
+     */
+    x1;
+    /**
+     *  Y-axis coordinate of the start point
+     */
+    y1;
+    /**
+     * X-axis coordinate of the control point
+     */
+    cpx;
+    /**
+     * Y-axis coordinate of the control point
+     */
+    cpy;
+    /**
+     *  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} cpx X-axis coordinate of the control point
+     * @param {number} cpy Y-axis coordinate of the 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, cpx, cpy, x2, y2) {
+        super();
+        this.x1 = x1;
+        this.y1 = y1;
+        this.cpx = cpx;
+        this.cpy = cpy;
+        this.x2 = x2;
+        this.y2 = y2;
+    }
+    /**
+     * Interpolate a point on the Quadratic Bézier curve
+     *
+     * @param {number} t Normalized time value to interpolate
+     * @returns {Point} Interpolated coordinates on the curve
+     */
+    getPoint(t) {
+        const point = quadraticBezier(t, this.x1, this.y1, this.cpx, this.cpy, this.x2, this.y2);
+        return point;
+    }
+}

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

@@ -0,0 +1,24 @@
+import type { Point } from 'src/types';
+import Curve from './Curve';
+/**
+ * Utility class for manipulating Spline curves
+ *
+ * @exports
+ * @class SplineCurve
+ * @extends Curve
+ */
+export default class SplineCurve extends Curve {
+    readonly type: string;
+    points: Point[];
+    /**
+     * @param {Point[]} [points] Array of points defining the curve
+     */
+    constructor(points?: Point[]);
+    /**
+     * Interpolate a point on the Spline curve
+     *
+     * @param {number} t Normalized time value to interpolate
+     * @returns {Point} Interpolated coordinates on the curve
+     */
+    getPoint(t: number): Point;
+}

package/lib/extras/curves/SplineCurve.js

@@ -0,0 +1,38 @@
+import { catmullRom } from 'src/geometry';
+import Curve from './Curve';
+/**
+ * Utility class for manipulating Spline curves
+ *
+ * @exports
+ * @class SplineCurve
+ * @extends Curve
+ */
+export default class SplineCurve extends Curve {
+    type = 'SplineCurve';
+    points = [];
+    /**
+     * @param {Point[]} [points] Array of points defining the curve
+     */
+    constructor(points = []) {
+        super();
+        this.points = points;
+    }
+    /**
+     * Interpolate a point on the Spline curve
+     *
+     * @param {number} t Normalized time value to interpolate
+     * @returns {Point} Interpolated coordinates on the curve
+     */
+    getPoint(t) {
+        const points = this.points;
+        const p = (points.length - 1) * t;
+        const index = Math.floor(p);
+        const weight = p - index;
+        const p1 = points[index === 0 ? index : index - 1];
+        const cp1 = points[index];
+        const cp2 = points[index > points.length - 2 ? points.length - 1 : index + 1];
+        const p2 = points[index > points.length - 3 ? points.length - 1 : index + 2];
+        const point = catmullRom(weight, ...p1, ...cp1, ...cp2, ...p2);
+        return point;
+    }
+}

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

@@ -0,0 +1,12 @@
+export { default as Curve } from './Curve';
+export { default as LineCurve } from './LineCurve';
+export { default as PolylineCurve } from './PolylineCurve';
+export { default as QuadraticBezierCurve } from './QuadraticBezierCurve';
+export { default as CubicBezierCurve } from './CubicBezierCurve';
+export { default as CatmulRomCurve } from './CatmulRomCurve';
+export { default as SplineCurve } from './SplineCurve';
+export { default as EllipseCurve } from './EllipseCurve';
+export { default as ArcCurve } from './ArcCurve';
+export { default as PathCurve } from './PathCurve';
+export { default as Path } from './Path';
+export { default as PathSVG } from './PathSVG';

package/lib/extras/curves/index.js

@@ -0,0 +1,12 @@
+export { default as Curve } from './Curve';
+export { default as LineCurve } from './LineCurve';
+export { default as PolylineCurve } from './PolylineCurve';
+export { default as QuadraticBezierCurve } from './QuadraticBezierCurve';
+export { default as CubicBezierCurve } from './CubicBezierCurve';
+export { default as CatmulRomCurve } from './CatmulRomCurve';
+export { default as SplineCurve } from './SplineCurve';
+export { default as EllipseCurve } from './EllipseCurve';
+export { default as ArcCurve } from './ArcCurve';
+export { default as PathCurve } from './PathCurve';
+export { default as Path } from './Path';
+export { default as PathSVG } from './PathSVG';

package/lib/{classes/frame-rate.js → extras/frame-rate/FrameRate.js}

@@ -1,4 +1,4 @@
-import { now } from '../functions';
+import { now } from '../../functions';
 /**
  * Utility class for controlling FPS calls
  *

package/lib/geometry.d.ts

@@ -1,4 +1,4 @@
-import type { Vector3 } from './types';
+import type { Point, Point3 } from './types';
 /**
  * Convert a radians value into degrees
  *
@@ -26,8 +26,8 @@ export declare function angle(x1: number, y1: number, x2: number, y2: number): n
 /**
  * Find the closest angle between to angles
  *
- * @param {number} source Source angle in radians
- * @param {number} target Target angle in radians
+ * @param {number} source Source angle (in radians)
+ * @param {number} target Target angle (in radians)
  * @returns {number} Closest angle
  */
 export declare function closestAngle(source: number, target: number): number;
@@ -55,54 +55,114 @@ export declare function diagonal(width: number, height: number): number;
  * @param  {number} radius  Radius of the sphere
  * @param  {number} phi     Polar angle from the y (up) axis     : [0, PI]
  * @param  {number} theta   Equator angle around the y (up) axis : [0, 2*PI]
- * @param  {Vector3} target Target vector
- * @returns {Vector3}
+ * @param  {Point3} target Target 3D point
+ * @returns {Point3}
  */
-export declare function radToSphere(radius: number, phi: number, theta: number, target?: Vector3): Vector3;
+export declare function radToSphere(radius: number, phi: number, theta: number, target?: Point3): Point3;
 /**
- * Interpolate a point on an elliptical arc Cubic Bézier curve
+ * Interpolate a point on a line
+ *
+ * @param {number} t  Normalized time value to interpolate
+ * @param {number} x1 X-axis coordinate of the start point
+ * @param {number} y1 Y-axis coordinate of the start point
+ * @param {number} x2 X-axis coordinate of the end point
+ * @param {number} y2 Y-axis coordinate of the end point
+ * @returns {Point} Interpolated coordinates on the line
+ */
+export declare function line(t: number, x1: number, y1: number, x2: number, y2: number): Point;
+/**
+ * Interpolate a point on a Quadratic Bézier curve
+ *
+ * @param {number} t   Normalized time value to interpolate
+ * @param {number} x1  X-axis coordinate of the start point
+ * @param {number} y1  Y-axis coordinate of the start point
+ * @param {number} cpx X-axis coordinate of the control point
+ * @param {number} cpy Y-axis coordinate of the control point
+ * @param {number} x2  X-axis coordinate of the end point
+ * @param {number} y2  Y-axis coordinate of the end point
+ * @returns {Point} Interpolated coordinates on the curve
+ */
+export declare function quadraticBezier(t: number, x1: number, y1: number, cpx: number, cpy: number, x2: number, y2: number): Point;
+/**
+ * Interpolate a point on a Cubic Bézier curve
  *
  * @param {number} t    Normalized time value to interpolate
  * @param {number} x1   X-axis coordinate of the start point
  * @param {number} y1   Y-axis coordinate of the start point
- * @param {number} cpx1 X-axis coordinate of the first control point
- * @param {number} cpy1 Y-axis coordinate of the first control point
- * @param {number} cpx2 X-axis coordinate of the second control point
- * @param {number} cpy2 Y-axis coordinate of the second control 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
- * @returns {[number, number]} Interpolated coordinates on the curve
+ * @returns {Point} Interpolated coordinates on the curve
  */
-export declare function cubicBezier(t: number, x1: number, y1: number, cpx1: number, cpy1: number, cpx2: number, cpy2: number, x2: number, y2: number): [number, number];
+export declare function cubicBezier(t: number, x1: number, y1: number, cp1x: number, cp1y: number, cp2x: number, cp2y: number, x2: number, y2: number): Point;
 /**
- * Interpolate a point on an elliptical arc Quadratic Bézier curve
+ * Interpolate a point on a Catmull-Rom spline
  *
  * @param {number} t   Normalized time value to interpolate
  * @param {number} x1  X-axis coordinate of the start point
  * @param {number} y1  Y-axis coordinate of the start point
- * @param {number} cpx X-axis coordinate of the control point
- * @param {number} cpy Y-axis coordinate of the control 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
- * @returns {[number, number]} Interpolated coordinates on the curve
+ * @returns {Point} Interpolated coordinates on the spline
  */
-export declare function quadraticBesier(t: number, x1: number, y1: number, cpx: number, cpy: number, x2: number, y2: number): [number, number];
+export declare function catmullRom(t: number, x1: number, y1: number, cp1x: number, cp1y: number, cp2x: number, cp2y: number, x2: number, y2: number): Point;
 /**
  * Interpolate a point on an elliptical arc
  *
- * @param {number} t     Normalized time value to interpolate
- * @param {number} x1    X-axis coordinate of the starting point of the arc
- * @param {number} y1    Y-axis coordinate of the starting point of the arc
- * @param {number} x2    X-axis coordinate of the ending point of the arc
- * @param {number} y2    Y-axis coordinate of the ending point of the arc
- * @param {number} rx    X-radius of the ellipse
- * @param {number} ry    Y-radius of the ellipse
- * @param {number} angle Rotation angle of the ellipse (in radians)
- * @param {boolean} [largeArc=true]  Flag indicating whether to draw the larger of the two possible arcs
- * @param {boolean} [clockwise=true] Flag indicating the direction of the arc
- * @returns {[number, number]} Interpolated coordinates on the arc
- */
-export declare function arc(t: number, x1: number, y1: number, x2: number, y2: number, rx: number, ry: number, angle: number, largeArc?: boolean, clockwise?: boolean): [number, number];
+ * @param {number} t  Normalized time value to interpolate
+ * @param {number} cx X-axis coordinate of the center of the ellipse
+ * @param {number} cy Y-axis coordinate of the center of the ellipse
+ * @param {number} rx X-radius of the ellipse
+ * @param {number} ry Y-radius of the ellipse
+ * @param {number} [rotation=0] Rotation angle of the ellipse (in radians), counterclockwise from the positive X-axis
+ * @param {number} [startAngle=0]  Start angle of the arc (in radians)
+ * @param {number} [endAngle=2*PI] End angle of the arc (in radians)
+ * @param {boolean} [counterclockwise=false] Flag indicating the direction of the arc
+ * @returns {Point} Interpolated coordinates on the arc
+ */
+export declare function ellipse(t: number, cx: number, cy: number, rx: number, ry: number, rotation?: number, startAngle?: number, endAngle?: number, counterclockwise?: boolean): Point;
+/**
+ * Interpolate a point on a circular arc
+ *
+ * @param {number} t  Normalized time value to interpolate
+ * @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] Start angle of the arc (in radians)
+ * @param {number} [endAngle]   End angle of the arc (in radians)
+ * @param {boolean} [counterclockwise=false] Flag indicating the direction of the arc
+ * @returns {Point} Interpolated coordinates on the arc
+ */
+export declare function arc(t: number, cx: number, cy: number, radius: number, startAngle?: number, endAngle?: number, counterclockwise?: boolean): Point;
+/**
+ * Check if two points are coincident
+ *
+ * @param {number} x1 X-axis coordinate of the first point
+ * @param {number} y1 Y-axis coordinate of the first point
+ * @param {number} x2 X-axis coordinate of the second point
+ * @param {number} y2 Y-axis coordinate of the second point
+ * @returns {boolean} True if the two are coincident, false otherwise
+ */
+export declare function isCoincident(x1: number, y1: number, x2: number, y2: number): boolean;
+/**
+ * Check if three points are collinear (aligned on the same line)
+ *
+ * @param {number} x1 X-axis coordinate of the first point
+ * @param {number} y1 Y-axis coordinate of the first point
+ * @param {number} x2 X-axis coordinate of the second point
+ * @param {number} y2 Y-axis coordinate of the second point
+ * @param {number} x3 X-axis coordinate of the third point
+ * @param {number} y3 Y-axis coordinate of the third point
+ * @returns {boolean} True if the three points are collinear, false otherwise
+ */
+export declare function isCollinear(x1: number, y1: number, x2: number, y2: number, x3: number, y3: number): boolean;
 export type FitInput = {
     width: number;
     height: number;