toosoon-utils 4.0.6 → 4.1.0

package/lib/geometry.js

@@ -1,4 +1,5 @@
-import { PI } from './constants';
+import { EPSILON, PI, TWO_PI } from './constants';
+import { lerp } from './maths';
 /**
  * Convert a radians value into degrees
  *
@@ -32,8 +33,8 @@ export function angle(x1, y1, x2, y2) {
 /**
  * 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 function closestAngle(source, target) {
@@ -70,63 +71,35 @@ export function diagonal(width, height) {
  * @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 function radToSphere(radius, phi, theta, target = { x: 0, y: 0, z: 0 }) {
-    target.x = radius * Math.sin(phi) * Math.sin(theta);
-    target.y = radius * Math.cos(phi);
-    target.z = radius * Math.sin(phi) * Math.cos(theta);
+export function radToSphere(radius, phi, theta, target = [0, 0, 0]) {
+    target[0] = radius * Math.sin(phi) * Math.sin(theta);
+    target[1] = radius * Math.cos(phi);
+    target[2] = radius * Math.sin(phi) * Math.cos(theta);
     return target;
 }
 // *********************
 // Curves
 // *********************
 /**
- * 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} 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} 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
+ * @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 function cubicBezier(t, x1, y1, cpx1, cpy1, cpx2, cpy2, x2, y2) {
-    const t2 = t * t;
-    const t3 = t2 * t;
-    const T = 1 - t;
-    const T2 = T * T;
-    const T3 = T2 * T;
-    const x = T3 * x1 + 3 * T2 * t * cpx1 + 3 * T * t2 * cpx2 + t3 * x2;
-    const y = T3 * y1 + 3 * T2 * t * cpy1 + 3 * T * t2 * cpy2 + t3 * y2;
+export function line(t, x1, y1, x2, y2) {
+    const x = lerp(t, x1, x2);
+    const y = lerp(t, y1, y2);
     return [x, y];
 }
 /**
- * Compute the curvature of a Cubic Bézier curve
- *
- * @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} x2   X-axis coordinate of the end point
- * @param {number} y2   Y-axis coordinate of the end point
- * @returns {number} Computed curvature
- */
-export function computeCubicBezierCurvature(x1, y1, cpx1, cpy1, cpx2, cpy2, x2, y2) {
-    const d1 = Math.hypot(cpx1 - x1, cpy1 - y1);
-    const d2 = Math.hypot(cpx2 - x2, cpy2 - y2);
-    const d3 = Math.hypot(x2 - x1, y2 - y1);
-    return (d1 + d2) / d3;
-}
-/**
- * Interpolate a point on an elliptical arc Quadratic Bézier curve
+ * 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
@@ -135,124 +108,155 @@ export function computeCubicBezierCurvature(x1, y1, cpx1, cpy1, cpx2, cpy2, x2,
  * @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 {[number, number]} Interpolated coordinates on the curve
+ * @returns {Point} Interpolated coordinates on the curve
  */
 export function quadraticBezier(t, x1, y1, cpx, cpy, x2, y2) {
     const t2 = t * t;
-    const T = 1 - t;
-    const T2 = T * T;
-    const x = T2 * x1 + 2 * T * t * cpx + t2 * x2;
-    const y = T2 * y1 + 2 * T * t * cpy + t2 * y2;
+    const k = 1 - t;
+    const k2 = k * k;
+    const x = k2 * x1 + 2 * k * t * cpx + t2 * x2;
+    const y = k2 * y1 + 2 * k * t * cpy + t2 * y2;
+    return [x, y];
+}
+/**
+ * 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} 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 {Point} Interpolated coordinates on the curve
+ */
+export function cubicBezier(t, x1, y1, cp1x, cp1y, cp2x, cp2y, x2, y2) {
+    const t2 = t * t;
+    const t3 = t2 * t;
+    const k = 1 - t;
+    const k2 = k * k;
+    const k3 = k2 * k;
+    const x = k3 * x1 + 3 * k2 * t * cp1x + 3 * k * t2 * cp2x + t3 * x2;
+    const y = k3 * y1 + 3 * k2 * t * cp1y + 3 * k * t2 * cp2y + t3 * y2;
     return [x, y];
 }
 /**
- * Compute the curvature of a 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} Computed curvature
+ * @returns {Point} Interpolated coordinates on the spline
  */
-export function computeQuadraticBezierCurvature(x1, y1, cpx, cpy, x2, y2) {
-    const d1 = Math.hypot(cpx - x1, cpy - y1);
-    const d2 = Math.hypot(cpx - x2, cpy - y2);
-    const d3 = Math.hypot(x2 - x1, y2 - y1);
-    return (d1 + d2) / d3;
+export function catmullRom(t, x1, y1, cp1x, cp1y, cp2x, cp2y, x2, y2) {
+    const t2 = t * t;
+    const t3 = t2 * t;
+    const vx1 = (cp2x - x1) * 0.5;
+    const vy1 = (cp2y - y1) * 0.5;
+    const vx2 = (x2 - cp1x) * 0.5;
+    const vy2 = (y2 - cp1y) * 0.5;
+    const x = (2 * cp1x - 2 * cp2x + vx1 + vx2) * t3 + (-3 * cp1x + 3 * cp2x - 2 * vx1 - vx2) * t2 + vx1 * t + cp1x;
+    const y = (2 * cp1y - 2 * cp2y + vy1 + vy2) * t3 + (-3 * cp1y + 3 * cp2y - 2 * vy1 - vy2) * t2 + vy1 * t + cp1y;
+    return [x, y];
 }
 /**
- * @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 {ComputedArc}
+ * 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 {Point} Interpolated coordinates on the arc
  */
-function computeArc(x1, y1, x2, y2, rx, ry, angle, largeArc = true, clockwise = true) {
-    const centerX = (x1 - x2) / 2;
-    const centerY = (y1 - y2) / 2;
-    const cosAngle = Math.cos(angle);
-    const sinAngle = Math.sin(angle);
-    const x1p = cosAngle * centerX + sinAngle * centerY;
-    const y1p = -sinAngle * centerX + cosAngle * centerY;
-    rx = Math.abs(rx);
-    ry = Math.abs(ry);
-    const lambda = x1p ** 2 / rx ** 2 + y1p ** 2 / ry ** 2;
-    if (lambda > 1) {
-        rx *= Math.sqrt(lambda);
-        ry *= Math.sqrt(lambda);
-    }
-    const sign = largeArc !== clockwise ? 1 : -1;
-    const factor = sign *
-        Math.sqrt(Math.max(0, (rx ** 2 * ry ** 2 - rx ** 2 * y1p ** 2 - ry ** 2 * x1p ** 2) / (rx ** 2 * y1p ** 2 + ry ** 2 * x1p ** 2)));
-    const cxp = (factor * rx * y1p) / ry;
-    const cyp = (-factor * ry * x1p) / rx;
-    const cx = cosAngle * cxp - sinAngle * cyp + (x1 + x2) / 2;
-    const cy = sinAngle * cxp + cosAngle * cyp + (y1 + y2) / 2;
-    const startAngle = Math.atan2((y1p - cyp) / ry, (x1p - cxp) / rx);
-    const endAngle = Math.atan2((-y1p - cyp) / ry, (-x1p - cxp) / rx);
+export function ellipse(t, cx, cy, rx, ry, rotation = 0, startAngle = 0, endAngle = TWO_PI, counterclockwise = false) {
     let deltaAngle = endAngle - startAngle;
-    if (clockwise === false && deltaAngle > 0) {
-        deltaAngle -= 2 * PI;
+    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;
+        }
     }
-    else if (clockwise === true && deltaAngle < 0) {
-        deltaAngle += 2 * PI;
+    if (counterclockwise === false && !isEmpty) {
+        if (deltaAngle === TWO_PI) {
+            deltaAngle = -TWO_PI;
+        }
+        else {
+            deltaAngle = deltaAngle - TWO_PI;
+        }
     }
-    return {
-        cx,
-        cy,
-        cosAngle,
-        sinAngle,
-        startAngle,
-        deltaAngle
-    };
+    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];
 }
 /**
- * Interpolate a point on an elliptical arc
+ * Interpolate a point on a circular 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]  Flag indicating whether to draw the larger of the two possible arcs
- * @param {boolean} [clockwise] Flag indicating the direction of the arc
- * @returns {[number, number]} Interpolated coordinates on the 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 function arc(t, x1, y1, x2, y2, rx, ry, angle, largeArc, clockwise) {
-    const arc = computeArc(x1, y1, x2, y2, rx, ry, angle, largeArc, clockwise);
-    const { cx, cy, cosAngle, sinAngle, startAngle, deltaAngle } = arc;
-    const theta = startAngle + t * deltaAngle;
-    const x = cx + rx * Math.cos(theta) * cosAngle - ry * Math.sin(theta) * sinAngle;
-    const y = cy + rx * Math.cos(theta) * sinAngle + ry * Math.sin(theta) * cosAngle;
-    return [x, y];
+export function arc(t, cx, cy, radius, startAngle, endAngle, counterclockwise) {
+    return ellipse(t, cx, cy, radius, radius, 0, startAngle, endAngle, counterclockwise);
+}
+/**
+ * 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 function isCoincident(x1, y1, x2, y2) {
+    return distance(x1, y1, x2, y2) <= EPSILON;
 }
 /**
- * Compute the curvature of an elliptical arc
+ * Check if three points are collinear (aligned on the same line)
  *
- * @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]  Flag indicating whether to draw the larger of the two possible arcs
- * @param {boolean} [clockwise] Flag indicating the direction of the arc
- * @returns Computed curvature
+ * @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 function computeArcCurvature(x1, y1, x2, y2, rx, ry, angle, largeArc = true, clockwise = true) {
-    const { deltaAngle } = computeArc(x1, y1, x2, y2, rx, ry, angle, largeArc, clockwise);
-    return deltaAngle / PI;
+export function isCollinear(x1, y1, x2, y2, x3, y3) {
+    return Math.abs((x2 - x1) * (y3 - y2) - (y2 - y1) * (x3 - x2)) <= EPSILON;
 }
 /**
  * Make a target fit a container

package/lib/prng.js

@@ -216,8 +216,9 @@ export function randomIndex(prng, weights) {
     for (let weight of weights) {
         totalWeight += weight;
     }
-    if (totalWeight <= 0)
+    if (totalWeight <= 0) {
         console.warn('PRNG randomIndex()', 'Weights must sum to > 0', totalWeight);
+    }
     let weight = random(prng) * totalWeight;
     for (let i = 0; i < weights.length; i++) {
         if (weight < weights[i])

package/lib/random.d.ts

@@ -1,4 +1,4 @@
-import type { Vector2, Vector3 } from './types';
+import type { Point, Point3 } from './types';
 /**
  * Generate a random boolean (true or false)
  *
@@ -69,31 +69,31 @@ export declare function randomGaussian(mean?: number, spread?: number): number;
  * Produce a random 2D point around the perimiter of a unit circle
  *
  * @param  {number} [radius=1] Radius of the circle
- * @param  {Vector2} [target]  Target vector
- * @returns {Vector2} Random 2D point on circle
+ * @param  {Point} [target]    Target point
+ * @returns {Point} Random 2D point on circle
  */
-export declare function onCircle(radius?: number, target?: Vector2): Vector2;
+export declare function onCircle(radius?: number, target?: Point): Point;
 /**
  * Produce a random 2D point inside a unit circle
  *
  * @param  {number} [radius=1] Radius of the circle
- * @param  {Vector2} [target]  Target vector
- * @returns {Vector2} Random 2D point inside circle
+ * @param  {Point} [target]    Target vector
+ * @returns {Point} Random 2D point inside circle
  */
-export declare function insideCircle(radius?: number, target?: Vector2): Vector2;
+export declare function insideCircle(radius?: number, target?: Point): Point;
 /**
  * Produce a random 3D point on the surface of a unit sphere
  *
  * @param  {number} [radius=1] Radius of the sphere
- * @param  {Vector3} [target]  Target vector
- * @returns {Vector3} Random 3D point on sphere
+ * @param  {Point3} [target]   Target vector
+ * @returns {Point3} Random 3D point on sphere
  */
-export declare function onSphere(radius?: number, target?: Vector3): Vector3;
+export declare function onSphere(radius?: number, target?: Point3): Point3;
 /**
  * Produce a random 3D point inside a unit sphere
  *
  * @param  {number} [radius=1] Radius of the sphere
- * @param  {Vector3} [target]  Target vector
- * @returns {Vector3} Random 3D point inside sphere
+ * @param  {Point3} [target]   Target vector
+ * @returns {Point3} Random 3D point inside sphere
  */
-export declare function insideSphere(radius?: number, target?: Vector3): Vector3;
+export declare function insideSphere(radius?: number, target?: Point3): Point3;

package/lib/random.js

@@ -114,23 +114,23 @@ export function randomGaussian(mean = 0, spread = 1) {
  * Produce a random 2D point around the perimiter of a unit circle
  *
  * @param  {number} [radius=1] Radius of the circle
- * @param  {Vector2} [target]  Target vector
- * @returns {Vector2} Random 2D point on circle
+ * @param  {Point} [target]    Target point
+ * @returns {Point} Random 2D point on circle
  */
-export function onCircle(radius = 1, target = { x: 0, y: 0 }) {
+export function onCircle(radius = 1, target = [0, 0]) {
     const angle = Math.random() * 2.0 * Math.PI;
-    target.x = radius * Math.cos(angle);
-    target.y = radius * Math.sin(angle);
+    target[0] = radius * Math.cos(angle);
+    target[1] = radius * Math.sin(angle);
     return target;
 }
 /**
  * Produce a random 2D point inside a unit circle
  *
  * @param  {number} [radius=1] Radius of the circle
- * @param  {Vector2} [target]  Target vector
- * @returns {Vector2} Random 2D point inside circle
+ * @param  {Point} [target]    Target vector
+ * @returns {Point} Random 2D point inside circle
  */
-export function insideCircle(radius = 1, target = { x: 0, y: 0 }) {
+export function insideCircle(radius = 1, target = [0, 0]) {
     radius *= Math.random();
     return onCircle(radius, target);
 }
@@ -138,10 +138,10 @@ export function insideCircle(radius = 1, target = { x: 0, y: 0 }) {
  * Produce a random 3D point on the surface of a unit sphere
  *
  * @param  {number} [radius=1] Radius of the sphere
- * @param  {Vector3} [target]  Target vector
- * @returns {Vector3} Random 3D point on sphere
+ * @param  {Point3} [target]   Target vector
+ * @returns {Point3} Random 3D point on sphere
  */
-export function onSphere(radius = 1, target = { x: 0, y: 0, z: 0 }) {
+export function onSphere(radius = 1, target = [0, 0, 0]) {
     const u = Math.random() * Math.PI * 2;
     const v = Math.random() * 2 - 1;
     const phi = u;
@@ -152,10 +152,10 @@ export function onSphere(radius = 1, target = { x: 0, y: 0, z: 0 }) {
  * Produce a random 3D point inside a unit sphere
  *
  * @param  {number} [radius=1] Radius of the sphere
- * @param  {Vector3} [target]  Target vector
- * @returns {Vector3} Random 3D point inside sphere
+ * @param  {Point3} [target]   Target vector
+ * @returns {Point3} Random 3D point inside sphere
  */
-export function insideSphere(radius = 1, target = { x: 0, y: 0, z: 0 }) {
+export function insideSphere(radius = 1, target = [0, 0, 0]) {
     radius *= Math.random();
     return onSphere(radius, target);
 }