toosoon-utils 4.0.6 → 4.1.0

package/lib/extras/curves/Curve.js

@@ -0,0 +1,174 @@
+import { distance, isCoincident } from 'src/geometry';
+/**
+ * Utility abstract class for manipulating curves
+ *
+ * @exports
+ * @class Curve
+ * @abstract
+ */
+export default class Curve {
+    type = 'Curve';
+    /**
+     * Amount of divisions when calculating the cumulative segment lengths of a curve
+     */
+    arcLengthDivisions = 200;
+    /**
+     * Must be set to `true` if the curve parameters have changed
+     */
+    needsUpdate = false;
+    _cacheArcLengths = [];
+    /**
+     * Interpolate a point on the curve
+     *
+     * @param {number} u Normalized position value to interpolate
+     * @returns {Point} Interpolated coordinates on the curve
+     */
+    getPointAt(u) {
+        const t = this.getUtoTmapping(u);
+        return this.getPoint(t);
+    }
+    /**
+     * Compute the curve shape into an array of points
+     *
+     * @param {number} [divisions=5] Number of divisions
+     * @returns {Point[]}
+     */
+    getPoints(divisions = 10) {
+        const points = [];
+        for (let i = 0; i <= divisions; i++) {
+            points.push(this.getPoint(i / divisions));
+        }
+        return points;
+    }
+    /**
+     * 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 = 10) {
+        const points = [];
+        for (let i = 0; i <= divisions; i++) {
+            points.push(this.getPointAt(i / divisions));
+        }
+        return points;
+    }
+    /**
+     * Compute the total arc length of the curve
+     *
+     * @returns {number}
+     */
+    getLength() {
+        const lengths = this.getLengths();
+        return lengths[lengths.length - 1];
+    }
+    /**
+     * Compute the cumulative segment lengths of the curve
+     *
+     * @param {number} [divisions=this.arcLengthDivisions] Number of divisions
+     * @returns {number[]}
+     */
+    getLengths(divisions = this.arcLengthDivisions) {
+        if (this._cacheArcLengths.length === divisions + 1 && !this.needsUpdate) {
+            return this._cacheArcLengths;
+        }
+        this.needsUpdate = false;
+        const lengths = [0];
+        let currentPoint;
+        let lastPoint = this.getPoint(0);
+        let sum = 0;
+        for (let i = 1; i <= divisions; i++) {
+            currentPoint = this.getPoint(i / divisions);
+            sum += distance(...currentPoint, ...lastPoint);
+            lengths.push(sum);
+            lastPoint = currentPoint;
+        }
+        this._cacheArcLengths = lengths;
+        return lengths;
+    }
+    /**
+     * Update the cached cumulative segment lengths
+     */
+    updateArcLengths() {
+        this.needsUpdate = true;
+        this.getLengths();
+    }
+    /**
+     * 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, targetArcLength) {
+        const arcLengths = this.getLengths();
+        let i = 0;
+        const length = arcLengths.length;
+        targetArcLength = targetArcLength ?? u * arcLengths[length - 1];
+        let low = 0;
+        let high = length - 1;
+        let comparison;
+        while (low < high) {
+            i = Math.floor(low + (high - low) / 2);
+            comparison = arcLengths[i] - targetArcLength;
+            if (comparison < 0) {
+                low = i + 1;
+            }
+            else if (comparison > 0) {
+                high = i - 1;
+            }
+            else {
+                high = i;
+                break;
+            }
+        }
+        i = high;
+        if (arcLengths[i] === targetArcLength) {
+            return i / (length - 1);
+        }
+        const lengthBefore = arcLengths[i];
+        const lengthAfter = arcLengths[i + 1];
+        const segmentLength = lengthAfter - lengthBefore;
+        const segmentFraction = (targetArcLength - lengthBefore) / segmentLength;
+        const t = (i + segmentFraction) / (length - 1);
+        return t;
+    }
+    /**
+     * Compute an unit vector tangent for the given normalized time value
+     *
+     * @param {number} t Normalized time value
+     * @returns {[number, number]} Tangent vector
+     */
+    getTangent(t) {
+        const delta = 0.0001;
+        let t1 = Math.max(0, t - delta);
+        let t2 = Math.min(1, t + delta);
+        const p1 = this.getPoint(t1);
+        const p2 = this.getPoint(t2);
+        let x = p2[0] - p1[0];
+        let y = p2[1] - p1[1];
+        const length = Math.sqrt(x * x + y * y);
+        x /= length;
+        y /= length;
+        return [x, y];
+    }
+    /**
+     * Compute an unit vector tangent for the given normalized position value
+     *
+     * @param {number} u Normalized position value
+     * @returns {[number, number]} Tangent vector
+     */
+    getTangentAt(u) {
+        const t = this.getUtoTmapping(u);
+        return this.getTangent(t);
+    }
+    /**
+     * 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) {
+        return points.length > 1 && !isCoincident(...points[0], ...points[points.length - 1]);
+    }
+}

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

@@ -0,0 +1,63 @@
+import type { Point } from 'src/types';
+import Curve from './Curve';
+/**
+ * Utility class for manipulating Ellipse curves
+ *
+ * @exports
+ * @class EllipseCurve
+ * @extends Curve
+ */
+export default class EllipseCurve extends Curve {
+    readonly type: string;
+    /**
+     * X-axis coordinate of the center of the ellipse
+     */
+    cx: number;
+    /**
+     * Y-axis coordinate of the center of the ellipse
+     */
+    cy: number;
+    /**
+     * X-radius of the ellipse
+     */
+    rx: number;
+    /**
+     * Y-radius of the ellipse
+     */
+    ry: number;
+    /**
+     * Rotation angle of the ellipse (in radians), counterclockwise from the positive X-axis
+     */
+    rotation?: number;
+    /**
+     * Start angle of the arc (in radians)
+     */
+    startAngle?: number;
+    /**
+     * End angle of the arc (in radians)
+     */
+    endAngle?: number;
+    /**
+     * Flag indicating the direction of the arc
+     */
+    counterclockwise?: boolean;
+    /**
+     * @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]   Rotation angle of the ellipse (in radians), counterclockwise from the positive X-axis
+     * @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, rx: number, ry: number, rotation?: number, startAngle?: number, endAngle?: number, counterclockwise?: boolean);
+    /**
+     * Interpolate a point on the Ellipse curve
+     *
+     * @abstract
+     * @param {number} t Normalized time value to interpolate
+     * @returns {Point} Interpolated coordinates on the curve
+     */
+    getPoint(t: number): Point;
+}

package/lib/extras/curves/EllipseCurve.js

@@ -0,0 +1,76 @@
+import { ellipse } from 'src/geometry';
+import Curve from './Curve';
+/**
+ * Utility class for manipulating Ellipse curves
+ *
+ * @exports
+ * @class EllipseCurve
+ * @extends Curve
+ */
+export default class EllipseCurve extends Curve {
+    type = 'EllipseCurve';
+    /**
+     * X-axis coordinate of the center of the ellipse
+     */
+    cx;
+    /**
+     * Y-axis coordinate of the center of the ellipse
+     */
+    cy;
+    /**
+     * X-radius of the ellipse
+     */
+    rx;
+    /**
+     * Y-radius of the ellipse
+     */
+    ry;
+    /**
+     * Rotation angle of the ellipse (in radians), counterclockwise from the positive X-axis
+     */
+    rotation;
+    /**
+     * Start angle of the arc (in radians)
+     */
+    startAngle;
+    /**
+     * End angle of the arc (in radians)
+     */
+    endAngle;
+    /**
+     * Flag indicating the direction of the arc
+     */
+    counterclockwise;
+    /**
+     * @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]   Rotation angle of the ellipse (in radians), counterclockwise from the positive X-axis
+     * @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, rx, ry, rotation, startAngle, endAngle, counterclockwise) {
+        super();
+        this.cx = cx;
+        this.cy = cy;
+        this.rx = rx;
+        this.ry = ry;
+        this.rotation = rotation;
+        this.startAngle = startAngle;
+        this.endAngle = endAngle;
+        this.counterclockwise = counterclockwise;
+    }
+    /**
+     * Interpolate a point on the Ellipse curve
+     *
+     * @abstract
+     * @param {number} t Normalized time value to interpolate
+     * @returns {Point} Interpolated coordinates on the curve
+     */
+    getPoint(t) {
+        const point = ellipse(t, this.cx, this.cy, this.rx, this.ry, this.rotation, this.startAngle, this.endAngle, this.counterclockwise);
+        return point;
+    }
+}

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

@@ -0,0 +1,51 @@
+import type { Point } from 'src/types';
+import Curve from './Curve';
+/**
+ * Utility class for manipulating lines
+ *
+ * @exports
+ * @class LineCurve
+ * @extends Curve
+ */
+export default class LineCurve 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 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} x2 X-axis coordinate of the end point
+     * @param {number} y2 Y-axis coordinate of the end point
+     */
+    constructor(x1: number, y1: number, x2: number, y2: number);
+    /**
+     * Interpolate a point on the line
+     *
+     * @param {number} t Normalized time value to interpolate
+     * @returns {Point} Interpolated coordinates on the line
+     */
+    getPoint(t: number): Point;
+    getPointAt(u: number): Point;
+    /**
+     * 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): [number, number];
+    getTangentAt(u: number): [number, number];
+}

package/lib/extras/curves/LineCurve.js

@@ -0,0 +1,71 @@
+import { line } from 'src/geometry';
+import Curve from './Curve';
+/**
+ * Utility class for manipulating lines
+ *
+ * @exports
+ * @class LineCurve
+ * @extends Curve
+ */
+export default class LineCurve extends Curve {
+    type = 'LineCurve';
+    /**
+     * X-axis coordinate of the start point
+     */
+    x1;
+    /**
+     * Y-axis coordinate of the start point
+     */
+    y1;
+    /**
+     * 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} x2 X-axis coordinate of the end point
+     * @param {number} y2 Y-axis coordinate of the end point
+     */
+    constructor(x1, y1, x2, y2) {
+        super();
+        this.x1 = x1;
+        this.y1 = y1;
+        this.x2 = x2;
+        this.y2 = y2;
+    }
+    /**
+     * Interpolate a point on the line
+     *
+     * @param {number} t Normalized time value to interpolate
+     * @returns {Point} Interpolated coordinates on the line
+     */
+    getPoint(t) {
+        const point = line(t, this.x1, this.y1, this.x2, this.y2);
+        return point;
+    }
+    getPointAt(u) {
+        return this.getPoint(u);
+    }
+    /**
+     * Compute an unit vector tangent for the given normalized time value
+     *
+     * @param {number} t Normalized time value
+     * @returns {[number, number]} Tangent vector
+     */
+    getTangent(t) {
+        let x = this.x2 - this.x1;
+        let y = this.y2 - this.y1;
+        const length = Math.sqrt(x * x + y * y);
+        x /= length;
+        y /= length;
+        return [x, y];
+    }
+    getTangentAt(u) {
+        return this.getTangent(u);
+    }
+}

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

@@ -0,0 +1,164 @@
+import { Point } from 'src/types';
+import PathCurve from './PathCurve';
+/**
+ * Utility class for manipulating connected curves
+ *
+ * It works by providing methods for creating curves similar to the 2D Canvas API
+ *
+ *
+ * @exports
+ * @class CurvePath
+ * @extends PathCurve
+ */
+export default class Path extends PathCurve {
+    /**
+     * Path current offset
+     */
+    currentPosition: Point;
+    /**
+     * Create a path from the given list of points
+     *
+     * @param {Point[]} points Array of points defining the path
+     * @param {Point[]} type   Type of curve used for creating the path
+     * @return {this}
+     */
+    setFromPoints(points: Point[], type?: 'lines' | 'polyline' | 'spline'): this;
+    /**
+     * Move {@link Path#currentPosition} to the coordinates specified by `x` and `y`
+     *
+     * @param {number} x X-axis coordinate of the point
+     * @param {number} y Y-axis coordinate of the point
+     * @return {this}
+     */
+    moveTo(x: number, y: number): this;
+    /**
+     * Draw a line from the current position to the position specified by `x` and `y`
+     * Add an instance of {@link LineCurve} to the path
+     *
+     * @param {number} x X-axis coordinate of the point
+     * @param {number} y Y-axis coordinate of the point
+     * @return {this}
+     */
+    lineTo(x: number, y: number): this;
+    /**
+     * Draw a Polyline curve from the current position through the given points
+     * Add an instance of {@link PolylineCurve} to the path
+     *
+     * @param {Point[]} points Array of points defining the curve
+     * @returns {this}
+     */
+    polylineTo(points: Point[]): this;
+    /**
+     * Draw an Arc curve from the current position, tangential to the 2 segments created by both control points
+     * Add an instance of {@link ArcCurve} to the path
+     *
+     * @param {number} x1 X-axis coordinate of the first control point
+     * @param {number} y1 Y-axis coordinate of the first control point
+     * @param {number} x2 X-axis coordinate of the second control point
+     * @param {number} y2 Y-axis coordinate of the second control point
+     * @param {number} radius Arc radius (Must be non-negative)
+     * @returns {this}
+     */
+    arcTo(x1: number, y1: number, x2: number, y2: number, radius: number): this;
+    /**
+     * Draw a Quadratic Bézier curve from the current position to the end point specified by `x` and `y`, using the control point specified by `cpx` and `cpy`
+     * Add an instance of {@link QuadraticBezierCurve} to the path
+     *
+     * @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
+     * @return {this}
+     */
+    quadraticCurveTo(cpx: number, cpy: number, x2: number, y2: number): this;
+    /**
+     * Draw a Cubic Bézier curve from the current position to the end point specified by `x` and `y`, using the control point specified by (`cp1x`, `cp1y`) and (`cp2x`, `cp2y`)
+     * Add an instance of {@link CubicBezierCurve} to the path
+     *
+     * @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
+     * @return {this}
+     */
+    bezierCurveTo(cp1x: number, cp1y: number, cp2x: number, cp2y: number, x2: number, y2: number): this;
+    /**
+     * Draw a Catmul-Rom curve from the current position to the end point specified by `x` and `y`, using the control points specified by (`cp1x`, `cp1y`) and (`cp2x`, `cp2y`)
+     * Add an instance of {@link CatmullRomCurve} to the path
+     *
+     * @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
+     * @return {this}
+     */
+    catmulRomCurveTo(cp1x: number, cp1y: number, cp2x: number, cp2y: number, x2: number, y2: number): this;
+    /**
+     * Draw a Spline curve from the current position through the given points
+     * Add an instance of {@link SplineCurve} to the path
+     *
+     * @param {Point[]} points Array of points defining the curve
+     * @return {this}
+     */
+    splineTo(points: Point[]): this;
+    /**
+     * Draw an Ellispe curve which is centered at (`cx`, `cy`) position
+     * Add an instance of {@link EllipseCurve} to the path
+     *
+     * @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} rx X-radius of the ellipse
+     * @param {number} ry Y-radius of the ellipse
+     * @param {number} [rotation] 	Rotation angle of the ellipse (in radians), counterclockwise from the positive X-axis
+     * @param {number} [startAngle] Start angle of the arc (in radians)
+     * @param {number} [endAngle]   End angle of the arc (in radians)
+     * @param {boolean} [counterclockwise] Flag indicating the direction of the arc
+     * @return {this}
+     */
+    ellipse(cx: number, cy: number, rx: number, ry: number, rotation?: number, startAngle?: number, endAngle?: number, counterclockwise?: boolean): this;
+    /**
+     * Draw an Arc curve which is centered at (`cx`, `cy`) position
+     * Add an instance of {@link ArcCurve} to the path
+     *
+     * @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] Flag indicating the direction of the arc
+     * @return {this}
+     */
+    arc(cx: number, cy: number, radius: number, startAngle?: number, endAngle?: number, counterclockwise?: boolean): this;
+    /**
+     * Draw a rectangular path from the start position specified by `x` and `y` to the end position using `width` and `height`
+     * Add an instance of {@link PolylineCurve} to the path
+     *
+     * @param {number} x 		  X-axis coordinate of the rectangle starting point
+     * @param {number} y      Y-axis coordinate of the rectangle starting point
+     * @param {number} width	Rectangle width (Positive values are to the right and negative to the left)
+     * @param {number} height Rectangle height (Positive values are down, and negative are up)
+     * @return {this}
+     */
+    rect(x: number, y: number, width: number, height: number): this;
+    /**
+     * Draw a rounded rectangular path from the start position specified by `x` and `y` to the end position using `width` and `height`
+     *
+     * @param {number} x 		  X-axis coordinate of the rectangle starting point
+     * @param {number} y      Y-axis coordinate of the rectangle starting point
+     * @param {number} width	Rectangle width (Positive values are to the right and negative to the left)
+     * @param {number} height Rectangle height (Positive values are down, and negative are up)
+     * @param {number|number[]} radius Radius of the circular arc to be used for the corners of the rectangle
+     * @return {this}
+     */
+    roundRect(x: number, y: number, width: number, height: number, radius: number | number[]): this;
+    /**
+     * Add a line curve to close the curve path
+     * Add an instance of {@link LineCurve} to the path
+     */
+    closePath(): this;
+    private _setCurrentPosition;
+}