toosoon-utils 4.1.9 → 4.2.0

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

@@ -1,4 +1,4 @@
-import type { Point } from '../../types';
+import { type Vector, Vector2, Vector3 } from '../geometry';
 /**
  * Utility abstract class for manipulating curves
  *
@@ -6,7 +6,7 @@ import type { Point } from '../../types';
  * @class Curve
  * @abstract
  */
-export default abstract class Curve {
+export default abstract class Curve<V extends Vector = Vector2 | Vector3> {
     readonly isCurve = true;
     readonly type: string;
     /**
@@ -19,42 +19,42 @@ export default abstract class Curve {
     needsUpdate: boolean;
     protected _cacheArcLengths: number[];
     /**
-     * Interpolate a point on the curve
+     * Interpolate a point on this curve
      *
      * @abstract
      * @param {number} t Normalized time value to interpolate
-     * @returns {Point} Interpolated coordinates on the curve
+     * @returns {Vector} Interpolated coordinates on this curve
      */
-    abstract getPoint(t: number): Point;
+    abstract getPoint(t: number): V;
     /**
-     * Interpolate a point on the curve
+     * Interpolate a point on this curve
      *
      * @param {number} u Normalized position value to interpolate
-     * @returns {Point} Interpolated coordinates on the curve
+     * @returns {Vector} Interpolated coordinates on this curve
      */
-    getPointAt(u: number): Point;
+    getPointAt(u: number): V;
     /**
-     * Compute the curve shape into an array of points
+     * Compute this curve shape into an array of points
      *
      * @param {number} [divisions=5] Number of divisions
-     * @returns {Point[]}
+     * @returns {Vector[]}
      */
-    getPoints(divisions?: number): Point[];
+    getPoints(divisions?: number): V[];
     /**
-     * Compute the curve shape into an array of equi-spaced points across the entire curve
+     * Compute this curve shape into an array of equi-spaced points across the entire curve
      *
      * @param {number} [divisions=5] Number of divisions
-     * @returns {Point[]}
+     * @returns {Vector[]}
      */
-    getSpacedPoints(divisions?: number): Point[];
+    getSpacedPoints(divisions?: number): V[];
     /**
-     * Compute the total arc length of the curve
+     * Compute the total arc length of this curve
      *
      * @returns {number}
      */
     getLength(): number;
     /**
-     * Compute the cumulative segment lengths of the curve
+     * Compute the cumulative segment lengths of this curve
      *
      * @param {number} [divisions=this.arcLengthDivisions] Number of divisions
      * @returns {number[]}
@@ -68,7 +68,7 @@ export default abstract class Curve {
      * Re-map a normalized position value into normalized time
      *
      * @param {number} u 								 Normalized position value to interpolate
-     * @param {number} [targetArcLength] Distance on the curve
+     * @param {number} [targetArcLength] Distance on this curve
      * @returns {number} Updated interpolation value
      */
     getUtoTmapping(u: number, targetArcLength?: number): number;
@@ -76,21 +76,20 @@ export default abstract class Curve {
      * Compute an unit vector tangent for the given normalized time value
      *
      * @param {number} t Normalized time value
-     * @returns {[number, number]} Tangent vector
+     * @returns {Vector} Tangent vector
      */
-    getTangent(t: number): Point;
+    getTangent(t: number): V;
     /**
      * Compute an unit vector tangent for the given normalized position value
      *
      * @param {number} u Normalized position value
-     * @returns {[number, number]} Tangent vector
+     * @returns {Vector} Tangent vector
      */
-    getTangentAt(u: number): [number, number];
+    getTangentAt(u: number): V;
     /**
-     * Static method to check if given points are defining a closed curve
+     * Check if this curve is closed
      *
-     * @param {Point[]} points Points to check
      * @returns {boolean} True if the curve is closed, false otherwise
      */
-    static isClosed(points: Point[]): boolean;
+    isClosed(): boolean;
 }

package/lib/extras/curves/Curve.js

@@ -1,4 +1,3 @@
-import { distance, isCoincident } from '../../geometry';
 /**
  * Utility abstract class for manipulating curves
  *
@@ -19,20 +18,20 @@ export default class Curve {
     needsUpdate = false;
     _cacheArcLengths = [];
     /**
-     * Interpolate a point on the curve
+     * Interpolate a point on this curve
      *
      * @param {number} u Normalized position value to interpolate
-     * @returns {Point} Interpolated coordinates on the curve
+     * @returns {Vector} Interpolated coordinates on this curve
      */
     getPointAt(u) {
         const t = this.getUtoTmapping(u);
         return this.getPoint(t);
     }
     /**
-     * Compute the curve shape into an array of points
+     * Compute this curve shape into an array of points
      *
      * @param {number} [divisions=5] Number of divisions
-     * @returns {Point[]}
+     * @returns {Vector[]}
      */
     getPoints(divisions = 5) {
         const points = [];
@@ -42,10 +41,10 @@ export default class Curve {
         return points;
     }
     /**
-     * Compute the curve shape into an array of equi-spaced points across the entire curve
+     * Compute this curve shape into an array of equi-spaced points across the entire curve
      *
      * @param {number} [divisions=5] Number of divisions
-     * @returns {Point[]}
+     * @returns {Vector[]}
      */
     getSpacedPoints(divisions = 5) {
         const points = [];
@@ -55,7 +54,7 @@ export default class Curve {
         return points;
     }
     /**
-     * Compute the total arc length of the curve
+     * Compute the total arc length of this curve
      *
      * @returns {number}
      */
@@ -64,7 +63,7 @@ export default class Curve {
         return lengths[lengths.length - 1];
     }
     /**
-     * Compute the cumulative segment lengths of the curve
+     * Compute the cumulative segment lengths of this curve
      *
      * @param {number} [divisions=this.arcLengthDivisions] Number of divisions
      * @returns {number[]}
@@ -80,7 +79,7 @@ export default class Curve {
         let sum = 0;
         for (let i = 1; i <= divisions; i++) {
             currentPoint = this.getPoint(i / divisions);
-            sum += distance(...currentPoint, ...lastPoint);
+            sum += currentPoint.distanceTo(lastPoint);
             lengths.push(sum);
             lastPoint = currentPoint;
         }
@@ -98,7 +97,7 @@ export default class Curve {
      * Re-map a normalized position value into normalized time
      *
      * @param {number} u 								 Normalized position value to interpolate
-     * @param {number} [targetArcLength] Distance on the curve
+     * @param {number} [targetArcLength] Distance on this curve
      * @returns {number} Updated interpolation value
      */
     getUtoTmapping(u, targetArcLength) {
@@ -138,38 +137,32 @@ export default class Curve {
      * Compute an unit vector tangent for the given normalized time value
      *
      * @param {number} t Normalized time value
-     * @returns {[number, number]} Tangent vector
+     * @returns {Vector} Tangent vector
      */
     getTangent(t) {
         const delta = 0.0001;
-        let t1 = Math.max(0, t - delta);
-        let t2 = Math.min(1, t + delta);
+        let t0 = Math.max(0, t - delta);
+        let t1 = Math.min(1, t + delta);
+        const p0 = this.getPoint(t0);
         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];
+        return p1.clone().sub(p0).normalize();
     }
     /**
      * Compute an unit vector tangent for the given normalized position value
      *
      * @param {number} u Normalized position value
-     * @returns {[number, number]} Tangent vector
+     * @returns {Vector} 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
+     * Check if this curve is closed
      *
-     * @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]);
+    isClosed() {
+        return this.getPoint(0).equals(this.getPoint(1));
     }
 }

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

@@ -1,4 +1,5 @@
-import type { Point } from '../../types';
+import type { Point2 } from '../../types';
+import { Vector2 } from '../geometry';
 import Curve from './Curve';
 /**
  * Utility class for manipulating ellipses
@@ -7,7 +8,7 @@ import Curve from './Curve';
  * @class EllipseCurve
  * @extends Curve
  */
-export default class EllipseCurve extends Curve {
+export default class EllipseCurve extends Curve<Vector2> {
     readonly type: string;
     /**
      * X-axis coordinate of the center of the ellipse
@@ -53,11 +54,26 @@ export default class EllipseCurve extends Curve {
      */
     constructor(cx: number, cy: number, rx: number, ry: number, rotation?: number, startAngle?: number, endAngle?: number, counterclockwise?: boolean);
     /**
-     * Interpolate a point on the Ellipse curve
+     * Interpolate a point on this curve
      *
      * @abstract
      * @param {number} t Normalized time value to interpolate
-     * @returns {Point} Interpolated coordinates on the curve
+     * @returns {Vector2} Interpolated coordinates on this curve
      */
-    getPoint(t: number): Point;
+    getPoint(t: number): Vector2;
+    /**
+     * Interpolate a point on an elliptical arc
+     *
+     * @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 {Point2} Interpolated coordinates on the arc
+     */
+    static interpolate(t: number, cx: number, cy: number, rx: number, ry: number, rotation?: number, startAngle?: number, endAngle?: number, counterclockwise?: boolean): Point2;
 }

package/lib/extras/curves/EllipseCurve.js

@@ -1,5 +1,5 @@
-import { TWO_PI } from '../../constants';
-import { ellipse } from '../../geometry';
+import { EPSILON, TWO_PI } from '../../constants';
+import { Vector2 } from '../geometry';
 import Curve from './Curve';
 /**
  * Utility class for manipulating ellipses
@@ -64,14 +64,63 @@ export default class EllipseCurve extends Curve {
         this.counterclockwise = counterclockwise ?? false;
     }
     /**
-     * Interpolate a point on the Ellipse curve
+     * Interpolate a point on this curve
      *
      * @abstract
      * @param {number} t Normalized time value to interpolate
-     * @returns {Point} Interpolated coordinates on the curve
+     * @returns {Vector2} Interpolated coordinates on this 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;
+        return new Vector2(...EllipseCurve.interpolate(t, this.cx, this.cy, this.rx, this.ry, this.rotation, this.startAngle, this.endAngle, this.counterclockwise));
+    }
+    /**
+     * Interpolate a point on an elliptical arc
+     *
+     * @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 {Point2} Interpolated coordinates on the arc
+     */
+    static interpolate(t, cx, cy, rx, ry, rotation = 0, startAngle = 0, endAngle = TWO_PI, counterclockwise = false) {
+        let deltaAngle = endAngle - startAngle;
+        const isEmpty = Math.abs(deltaAngle) <= EPSILON;
+        while (deltaAngle < 0)
+            deltaAngle += TWO_PI;
+        while (deltaAngle > TWO_PI)
+            deltaAngle -= TWO_PI;
+        if (deltaAngle <= EPSILON) {
+            if (isEmpty) {
+                deltaAngle = 0;
+            }
+            else {
+                deltaAngle = TWO_PI;
+            }
+        }
+        if (counterclockwise === true && !isEmpty) {
+            if (deltaAngle === TWO_PI) {
+                deltaAngle = -TWO_PI;
+            }
+            else {
+                deltaAngle = deltaAngle - TWO_PI;
+            }
+        }
+        const angle = startAngle + t * deltaAngle;
+        let x = cx + rx * Math.cos(angle);
+        let y = cy + ry * Math.sin(angle);
+        if (rotation !== 0) {
+            const cos = Math.cos(rotation);
+            const sin = Math.sin(rotation);
+            const deltaX = x - cx;
+            const deltaY = y - cy;
+            x = deltaX * cos - deltaY * sin + cx;
+            y = deltaX * sin + deltaY * cos + cy;
+        }
+        return [x, y];
     }
 }

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

@@ -1,4 +1,5 @@
-import type { Point } from '../../types';
+import type { Point2 } from '../../types';
+import { Vector2 } from '../geometry';
 import Curve from './Curve';
 /**
  * Utility class for manipulating lines
@@ -7,7 +8,7 @@ import Curve from './Curve';
  * @class LineCurve
  * @extends Curve
  */
-export default class LineCurve extends Curve {
+export default class LineCurve extends Curve<Vector2> {
     readonly type: string;
     /**
      * X-axis coordinate of the start point
@@ -33,19 +34,42 @@ export default class LineCurve extends Curve {
      */
     constructor(x1: number, y1: number, x2: number, y2: number);
     /**
-     * Interpolate a point on the line
+     * Interpolate a point on this curve
      *
      * @param {number} t Normalized time value to interpolate
-     * @returns {Point} Interpolated coordinates on the line
+     * @returns {Vector2} Interpolated coordinates on this curve
      */
-    getPoint(t: number): Point;
-    getPointAt(u: number): Point;
+    getPoint(t: number): Vector2;
     /**
-     * Compute an unit vector tangent for the given normalized time value
+     * Interpolate a point on this line
+     *
+     * @param {number} u Normalized position value to interpolate
+     * @returns {Vector2} Interpolated coordinates on this line
+     */
+    getPointAt(u: number): Vector2;
+    /**
+     * Compute an unit vector tangent for a given normalized time value
      *
      * @param {number} t Normalized time value
-     * @returns {[number, number]} Tangent vector
+     * @returns {Vector2} Tangent vector
+     */
+    getTangent(t?: number): Vector2;
+    /**
+     * Compute an unit vector tangent for a given normalized position value
+     *
+     * @param {number} u Normalized position value
+     * @returns {Vector2} Tangent vector
+     */
+    getTangentAt(u?: number): Vector2;
+    /**
+     * 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 {Point2} Interpolated coordinates on the line
      */
-    getTangent(t?: number): [number, number];
-    getTangentAt(u: number): [number, number];
+    static interpolate(t: number, x1: number, y1: number, x2: number, y2: number): Point2;
 }

package/lib/extras/curves/LineCurve.js

@@ -1,4 +1,5 @@
-import { line } from '../../geometry';
+import { lerp } from '../../maths';
+import { Vector2 } from '../geometry';
 import Curve from './Curve';
 /**
  * Utility class for manipulating lines
@@ -39,33 +40,54 @@ export default class LineCurve extends Curve {
         this.y2 = y2;
     }
     /**
-     * Interpolate a point on the line
+     * Interpolate a point on this curve
      *
      * @param {number} t Normalized time value to interpolate
-     * @returns {Point} Interpolated coordinates on the line
+     * @returns {Vector2} Interpolated coordinates on this curve
      */
     getPoint(t) {
-        const point = line(t, this.x1, this.y1, this.x2, this.y2);
-        return point;
+        return new Vector2(...LineCurve.interpolate(t, this.x1, this.y1, this.x2, this.y2));
     }
+    /**
+     * Interpolate a point on this line
+     *
+     * @param {number} u Normalized position value to interpolate
+     * @returns {Vector2} Interpolated coordinates on this line
+     */
     getPointAt(u) {
         return this.getPoint(u);
     }
     /**
-     * Compute an unit vector tangent for the given normalized time value
+     * Compute an unit vector tangent for a given normalized time value
      *
      * @param {number} t Normalized time value
-     * @returns {[number, number]} Tangent vector
+     * @returns {Vector2} 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];
+        return new Vector2(...Vector2.sub([this.x1, this.y1], [this.x2, this.y2])).normalize();
     }
+    /**
+     * Compute an unit vector tangent for a given normalized position value
+     *
+     * @param {number} u Normalized position value
+     * @returns {Vector2} Tangent vector
+     */
     getTangentAt(u) {
         return this.getTangent(u);
     }
+    /**
+     * 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 {Point2} Interpolated coordinates on the line
+     */
+    static interpolate(t, x1, y1, x2, y2) {
+        const x = lerp(t, x1, x2);
+        const y = lerp(t, y1, y2);
+        return [x, y];
+    }
 }

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

@@ -0,0 +1,87 @@
+import type { Point3 } from '../../types';
+import { Vector3 } from '../geometry';
+import Curve from './Curve';
+/**
+ * Utility class for manipulating 3D lines
+ *
+ * @exports
+ * @class LineCurve3
+ * @extends Curve
+ */
+export default class LineCurve3 extends Curve<Vector3> {
+    readonly type: string;
+    /**
+     * X-axis coordinate of the start point
+     */
+    x1: number;
+    /**
+     * Y-axis coordinate of the start point
+     */
+    y1: number;
+    /**
+     * Z-axis coordinate of the start point
+     */
+    z1: number;
+    /**
+     * X-axis coordinate of the end point
+     */
+    x2: number;
+    /**
+     * Y-axis coordinate of the end point
+     */
+    y2: number;
+    /**
+     * Z-axis coordinate of the end point
+     */
+    z2: number;
+    /**
+     * @param {number} x1 X-axis coordinate of the start point
+     * @param {number} y1 Y-axis coordinate of the start point
+     * @param {number} z1 Z-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
+     * @param {number} z2 Z-axis coordinate of the end point
+     */
+    constructor(x1: number, y1: number, z1: number, x2: number, y2: number, z2: number);
+    /**
+     * Interpolate a point on this curve
+     *
+     * @param {number} t Normalized time value to interpolate
+     * @returns {Vector3} Interpolated coordinates on this curve
+     */
+    getPoint(t: number): Vector3;
+    /**
+     * Interpolate a point on this curve
+     *
+     * @param {number} u Normalized position value to interpolate
+     * @returns {Vector3} Interpolated coordinates on this curve
+     */
+    getPointAt(u: number): Vector3;
+    /**
+     * Compute an unit vector tangent for a given normalized time value
+     *
+     * @param {number} t Normalized time value
+     * @returns {Vector3} Tangent vector
+     */
+    getTangent(t?: number): Vector3;
+    /**
+     * Compute an unit vector tangent for a given normalized position value
+     *
+     * @param {number} u Normalized position value
+     * @returns {Vector3} Tangent vector
+     */
+    getTangentAt(u?: number): Vector3;
+    /**
+     * Interpolate a point on a 3D 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} z1 Z-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
+     * @param {number} z2 Z-axis coordinate of the end point
+     * @returns {Point3} Interpolated coordinates on the line
+     */
+    static interpolate(t: number, x1: number, y1: number, z1: number, x2: number, y2: number, z2: number): Point3;
+}