@js-draw/math 1.16.0 → 1.18.0

package/dist/cjs/shapes/PointShape2D.js

@@ -3,29 +3,52 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-const Abstract2DShape_1 = __importDefault(require("./Abstract2DShape"));
+const Vec2_1 = require("../Vec2");
+const Parameterized2DShape_1 = __importDefault(require("./Parameterized2DShape"));
 const Rect2_1 = __importDefault(require("./Rect2"));
 /**
  * Like a {@link Point2}, but with additional functionality (e.g. SDF).
  *
  * Access the internal `Point2` using the `p` property.
  */
-class PointShape2D extends Abstract2DShape_1.default {
+class PointShape2D extends Parameterized2DShape_1.default {
     constructor(p) {
         super();
         this.p = p;
     }
     signedDistance(point) {
-        return this.p.minus(point).magnitude();
+        return this.p.distanceTo(point);
     }
-    intersectsLineSegment(lineSegment, epsilon) {
+    argIntersectsLineSegment(lineSegment, epsilon) {
         if (lineSegment.containsPoint(this.p, epsilon)) {
-            return [this.p];
+            return [0];
         }
         return [];
     }
     getTightBoundingBox() {
         return new Rect2_1.default(this.p.x, this.p.y, 0, 0);
     }
+    at(_t) {
+        return this.p;
+    }
+    /**
+     * Returns an arbitrary unit-length vector.
+     */
+    normalAt(_t) {
+        // Return a vector that makes sense.
+        return Vec2_1.Vec2.unitY;
+    }
+    tangentAt(_t) {
+        return Vec2_1.Vec2.unitX;
+    }
+    splitAt(_t) {
+        return [this];
+    }
+    nearestPointTo(_point) {
+        return {
+            point: this.p,
+            parameterValue: 0,
+        };
+    }
 }
 exports.default = PointShape2D;

package/dist/cjs/shapes/QuadraticBezier.d.ts

@@ -2,10 +2,9 @@ import { Point2, Vec2 } from '../Vec2';
 import BezierJSWrapper from './BezierJSWrapper';
 import Rect2 from './Rect2';
 /**
- * A wrapper around `bezier-js`'s quadratic Bézier.
+ * Represents a 2D Bézier curve.
  *
- * This wrappper lazy-loads `bezier-js`'s Bézier and can perform some operations
- * without loading it at all (e.g. `normal`, `at`, and `approximateDistance`).
+ * **Note**: Many Bézier operations use `bezier-js`'s.
  */
 export declare class QuadraticBezier extends BezierJSWrapper {
     readonly p0: Point2;
@@ -18,11 +17,15 @@ export declare class QuadraticBezier extends BezierJSWrapper {
      */
     private static componentAt;
     private static derivativeComponentAt;
+    private static secondDerivativeComponentAt;
     /**
      * @returns the curve evaluated at `t`.
+     *
+     * `t` should be a number in `[0, 1]`.
      */
     at(t: number): Point2;
     derivativeAt(t: number): Point2;
+    secondDerivativeAt(t: number): Point2;
     normal(t: number): Vec2;
     /** @returns an overestimate of this shape's bounding box. */
     getLooseBoundingBox(): Rect2;

package/dist/cjs/shapes/QuadraticBezier.js

@@ -9,10 +9,9 @@ const solveQuadratic_1 = __importDefault(require("../polynomial/solveQuadratic")
 const BezierJSWrapper_1 = __importDefault(require("./BezierJSWrapper"));
 const Rect2_1 = __importDefault(require("./Rect2"));
 /**
- * A wrapper around `bezier-js`'s quadratic Bézier.
+ * Represents a 2D Bézier curve.
  *
- * This wrappper lazy-loads `bezier-js`'s Bézier and can perform some operations
- * without loading it at all (e.g. `normal`, `at`, and `approximateDistance`).
+ * **Note**: Many Bézier operations use `bezier-js`'s.
  */
 class QuadraticBezier extends BezierJSWrapper_1.default {
     constructor(p0, p1, p2) {
@@ -31,10 +30,19 @@ class QuadraticBezier extends BezierJSWrapper_1.default {
     static derivativeComponentAt(t, p0, p1, p2) {
         return -2 * p0 + 2 * p1 + 2 * t * (p0 - 2 * p1 + p2);
     }
+    static secondDerivativeComponentAt(t, p0, p1, p2) {
+        return 2 * (p0 - 2 * p1 + p2);
+    }
     /**
      * @returns the curve evaluated at `t`.
+     *
+     * `t` should be a number in `[0, 1]`.
      */
     at(t) {
+        if (t === 0)
+            return this.p0;
+        if (t === 1)
+            return this.p2;
         const p0 = this.p0;
         const p1 = this.p1;
         const p2 = this.p2;
@@ -46,6 +54,12 @@ class QuadraticBezier extends BezierJSWrapper_1.default {
         const p2 = this.p2;
         return Vec2_1.Vec2.of(QuadraticBezier.derivativeComponentAt(t, p0.x, p1.x, p2.x), QuadraticBezier.derivativeComponentAt(t, p0.y, p1.y, p2.y));
     }
+    secondDerivativeAt(t) {
+        const p0 = this.p0;
+        const p1 = this.p1;
+        const p2 = this.p2;
+        return Vec2_1.Vec2.of(QuadraticBezier.secondDerivativeComponentAt(t, p0.x, p1.x, p2.x), QuadraticBezier.secondDerivativeComponentAt(t, p0.y, p1.y, p2.y));
+    }
     normal(t) {
         const tangent = this.derivativeAt(t);
         return tangent.orthog().normalized();
@@ -106,10 +120,10 @@ class QuadraticBezier extends BezierJSWrapper_1.default {
         }
         const at1 = this.at(min1);
         const at2 = this.at(min2);
-        const sqrDist1 = at1.minus(point).magnitudeSquared();
-        const sqrDist2 = at2.minus(point).magnitudeSquared();
-        const sqrDist3 = this.at(0).minus(point).magnitudeSquared();
-        const sqrDist4 = this.at(1).minus(point).magnitudeSquared();
+        const sqrDist1 = at1.squareDistanceTo(point);
+        const sqrDist2 = at2.squareDistanceTo(point);
+        const sqrDist3 = this.at(0).squareDistanceTo(point);
+        const sqrDist4 = this.at(1).squareDistanceTo(point);
         return Math.sqrt(Math.min(sqrDist1, sqrDist2, sqrDist3, sqrDist4));
     }
     getPoints() {

package/dist/cjs/shapes/Rect2.d.ts

@@ -3,7 +3,7 @@ import Mat33 from '../Mat33';
 import { Point2, Vec2 } from '../Vec2';
 import Abstract2DShape from './Abstract2DShape';
 import Vec3 from '../Vec3';
-/** An object that can be converted to a Rect2. */
+/** An object that can be converted to a {@link Rect2}. */
 export interface RectTemplate {
     x: number;
     y: number;
@@ -12,6 +12,11 @@ export interface RectTemplate {
     width?: number;
     height?: number;
 }
+/**
+ * Represents a rectangle in 2D space, parallel to the XY axes.
+ *
+ * `invariant: w ≥ 0, h ≥ 0, immutable`
+ */
 export declare class Rect2 extends Abstract2DShape {
     readonly x: number;
     readonly y: number;
@@ -25,6 +30,9 @@ export declare class Rect2 extends Abstract2DShape {
     resizedTo(size: Vec2): Rect2;
     containsPoint(other: Point2): boolean;
     containsRect(other: Rect2): boolean;
+    /**
+     * @returns true iff this and `other` overlap
+     */
     intersects(other: Rect2): boolean;
     intersection(other: Rect2): Rect2 | null;
     union(other: Rect2): Rect2;

package/dist/cjs/shapes/Rect2.js

@@ -7,7 +7,11 @@ exports.Rect2 = void 0;
 const LineSegment2_1 = __importDefault(require("./LineSegment2"));
 const Vec2_1 = require("../Vec2");
 const Abstract2DShape_1 = __importDefault(require("./Abstract2DShape"));
-// invariant: w ≥ 0, h ≥ 0, immutable
+/**
+ * Represents a rectangle in 2D space, parallel to the XY axes.
+ *
+ * `invariant: w ≥ 0, h ≥ 0, immutable`
+ */
 class Rect2 extends Abstract2DShape_1.default {
     constructor(x, y, w, h) {
         super();
@@ -44,6 +48,9 @@ class Rect2 extends Abstract2DShape_1.default {
             && this.x + this.w >= other.x + other.w
             && this.y + this.h >= other.y + other.h;
     }
+    /**
+     * @returns true iff this and `other` overlap
+     */
     intersects(other) {
         // Project along x/y axes.
         const thisMinX = this.x;
@@ -130,7 +137,7 @@ class Rect2 extends Abstract2DShape_1.default {
         let closest = null;
         let closestDist = null;
         for (const point of closestEdgePoints) {
-            const dist = point.minus(target).length();
+            const dist = point.distanceTo(target);
             if (closestDist === null || dist < closestDist) {
                 closest = point;
                 closestDist = dist;

package/dist/cjs/utils/convexHull2Of.d.ts

@@ -0,0 +1,9 @@
+import { Point2 } from '../Vec2';
+/**
+ * Implements Gift Wrapping, in $O(nh)$. This algorithm is not the most efficient in the worst case.
+ *
+ * See https://en.wikipedia.org/wiki/Gift_wrapping_algorithm
+ * and https://www.cs.jhu.edu/~misha/Spring16/06.pdf
+ */
+declare const convexHull2Of: (points: Point2[]) => import("../Vec3").Vec3[];
+export default convexHull2Of;

package/dist/cjs/utils/convexHull2Of.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const Vec2_1 = require("../Vec2");
+/**
+ * Implements Gift Wrapping, in $O(nh)$. This algorithm is not the most efficient in the worst case.
+ *
+ * See https://en.wikipedia.org/wiki/Gift_wrapping_algorithm
+ * and https://www.cs.jhu.edu/~misha/Spring16/06.pdf
+ */
+const convexHull2Of = (points) => {
+    if (points.length === 0) {
+        return [];
+    }
+    // 1. Start with a vertex on the hull
+    const lowestPoint = points.reduce((lowest, current) => current.y < lowest.y ? current : lowest, points[0]);
+    const vertices = [lowestPoint];
+    let toProcess = [...points.filter(p => !p.eq(lowestPoint))];
+    let lastBaseDirection = Vec2_1.Vec2.of(-1, 0);
+    // 2. Find the point with greatest angle from the vertex:
+    //
+    //  . .     .
+    //   . .   /  <- Notice that **all** other points are to the
+    //       /       **left** of the vector from the current
+    //    ./         vertex to the new point.
+    while (toProcess.length > 0) {
+        const lastVertex = vertices[vertices.length - 1];
+        let smallestDotProductSoFar = lastBaseDirection.dot(lowestPoint.minus(lastVertex).normalizedOrZero());
+        let furthestPointSoFar = lowestPoint;
+        for (const point of toProcess) {
+            // Maximizing the angle is the same as minimizing the dot product:
+            //              point.minus(lastVertex)
+            //             ^
+            //            /
+            //           /
+            //        ϑ /
+            //   <-----. lastBaseDirection
+            const currentDotProduct = lastBaseDirection.dot(point.minus(lastVertex).normalizedOrZero());
+            if (currentDotProduct <= smallestDotProductSoFar) {
+                furthestPointSoFar = point;
+                smallestDotProductSoFar = currentDotProduct;
+            }
+        }
+        toProcess = toProcess.filter(p => !p.eq(furthestPointSoFar));
+        const newBaseDirection = furthestPointSoFar.minus(lastVertex).normalized();
+        // If the last vertex is on the same edge as the current, there's no need to include
+        // the previous one.
+        if (Math.abs(newBaseDirection.dot(lastBaseDirection)) === 1 && vertices.length > 1) {
+            vertices.pop();
+        }
+        // Stoping condition: We've gone in a full circle.
+        if (furthestPointSoFar.eq(lowestPoint)) {
+            break;
+        }
+        else {
+            vertices.push(furthestPointSoFar);
+            lastBaseDirection = lastVertex.minus(furthestPointSoFar).normalized();
+        }
+    }
+    return vertices;
+};
+exports.default = convexHull2Of;

package/dist/cjs/utils/convexHull2Of.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/mjs/Mat33.mjs

@@ -334,7 +334,11 @@ export class Mat33 {
             return Mat33.identity;
         }
         const parseArguments = (argumentString) => {
-            return argumentString.split(/[, \t\n]+/g).map(argString => {
+            const parsed = argumentString.split(/[, \t\n]+/g).map(argString => {
+                // Handle trailing spaces/commands
+                if (argString.trim() === '') {
+                    return null;
+                }
                 let isPercentage = false;
                 if (argString.endsWith('%')) {
                     isPercentage = true;
@@ -355,6 +359,7 @@ export class Mat33 {
                 }
                 return argNumber;
             });
+            return parsed.filter(n => n !== null);
         };
         const keywordToAction = {
             matrix: (matrixData) => {

package/dist/mjs/Vec3.d.ts

@@ -35,11 +35,31 @@ export declare class Vec3 {
     length(): number;
     magnitude(): number;
     magnitudeSquared(): number;
+    /**
+     * Interpreting this vector as a point in ℝ^3, computes the square distance
+     * to another point, `p`.
+     *
+     * Equivalent to `.minus(p).magnitudeSquared()`.
+     */
+    squareDistanceTo(p: Vec3): number;
+    /**
+     * Interpreting this vector as a point in ℝ³, returns the distance to the point
+     * `p`.
+     *
+     * Equivalent to `.minus(p).magnitude()`.
+     */
+    distanceTo(p: Vec3): number;
     /**
      * Returns the entry of this with the greatest magnitude.
      *
      * In other words, returns $\max \{ |x| : x \in {\bf v} \}$, where ${\bf v}$ is the set of
      * all entries of this vector.
+     *
+     * **Example**:
+     * ```ts,runnable,console
+     * import { Vec3 } from '@js-draw/math';
+     * console.log(Vec3.of(-1, -10, 8).maximumEntryMagnitude()); // -> 10
+     * ```
      */
     maximumEntryMagnitude(): number;
     /**
@@ -50,6 +70,7 @@ export declare class Vec3 {
      * As such, observing that `Math.atan2(-0, -1)` $\approx -\pi$ and `Math.atan2(0, -1)`$\approx \pi$
      * the resultant angle is in the range $[-\pi, pi]$.
      *
+     * **Example**:
      * ```ts,runnable,console
      * import { Vec2 } from '@js-draw/math';
      * console.log(Vec2.of(-1, -0).angle()); // atan2(-0, -1)
@@ -113,7 +134,8 @@ export declare class Vec3 {
      * Returns a vector with each component acted on by `fn`.
      *
      * @example
-     * ```
+     * ```ts,runnable,console
+     * import { Vec3 } from '@js-draw/math';
      * console.log(Vec3.of(1, 2, 3).map(val => val + 1)); // → Vec(2, 3, 4)
      * ```
      */

package/dist/mjs/Vec3.mjs

@@ -55,11 +55,38 @@ export class Vec3 {
     magnitudeSquared() {
         return this.dot(this);
     }
+    /**
+     * Interpreting this vector as a point in ℝ^3, computes the square distance
+     * to another point, `p`.
+     *
+     * Equivalent to `.minus(p).magnitudeSquared()`.
+     */
+    squareDistanceTo(p) {
+        const dx = this.x - p.x;
+        const dy = this.y - p.y;
+        const dz = this.z - p.z;
+        return dx * dx + dy * dy + dz * dz;
+    }
+    /**
+     * Interpreting this vector as a point in ℝ³, returns the distance to the point
+     * `p`.
+     *
+     * Equivalent to `.minus(p).magnitude()`.
+     */
+    distanceTo(p) {
+        return Math.sqrt(this.squareDistanceTo(p));
+    }
     /**
      * Returns the entry of this with the greatest magnitude.
      *
      * In other words, returns $\max \{ |x| : x \in {\bf v} \}$, where ${\bf v}$ is the set of
      * all entries of this vector.
+     *
+     * **Example**:
+     * ```ts,runnable,console
+     * import { Vec3 } from '@js-draw/math';
+     * console.log(Vec3.of(-1, -10, 8).maximumEntryMagnitude()); // -> 10
+     * ```
      */
     maximumEntryMagnitude() {
         return Math.max(Math.abs(this.x), Math.max(Math.abs(this.y), Math.abs(this.z)));
@@ -72,6 +99,7 @@ export class Vec3 {
      * As such, observing that `Math.atan2(-0, -1)` $\approx -\pi$ and `Math.atan2(0, -1)`$\approx \pi$
      * the resultant angle is in the range $[-\pi, pi]$.
      *
+     * **Example**:
      * ```ts,runnable,console
      * import { Vec2 } from '@js-draw/math';
      * console.log(Vec2.of(-1, -0).angle()); // atan2(-0, -1)
@@ -175,7 +203,8 @@ export class Vec3 {
      * Returns a vector with each component acted on by `fn`.
      *
      * @example
-     * ```
+     * ```ts,runnable,console
+     * import { Vec3 } from '@js-draw/math';
      * console.log(Vec3.of(1, 2, 3).map(val => val + 1)); // → Vec(2, 3, 4)
      * ```
      */
@@ -199,12 +228,9 @@ export class Vec3 {
      * ```
      */
     eq(other, fuzz = 1e-10) {
-        for (let i = 0; i < 3; i++) {
-            if (Math.abs(other.at(i) - this.at(i)) > fuzz) {
-                return false;
-            }
-        }
-        return true;
+        return (Math.abs(other.x - this.x) <= fuzz
+            && Math.abs(other.y - this.y) <= fuzz
+            && Math.abs(other.z - this.z) <= fuzz);
     }
     toString() {
         return `Vec(${this.x}, ${this.y}, ${this.z})`;

package/dist/mjs/lib.d.ts

@@ -17,8 +17,9 @@
  * @packageDocumentation
  */
 export { LineSegment2 } from './shapes/LineSegment2';
-export { Path, PathCommandType, PathCommand, LinePathCommand, MoveToPathCommand, QuadraticBezierPathCommand, CubicBezierPathCommand, } from './shapes/Path';
+export { Path, IntersectionResult as PathIntersectionResult, CurveIndexRecord as PathCurveIndex, stepCurveIndexBy as stepPathIndexBy, compareCurveIndices as comparePathIndices, PathCommandType, PathCommand, LinePathCommand, MoveToPathCommand, QuadraticBezierPathCommand, CubicBezierPathCommand, } from './shapes/Path';
 export { Rect2 } from './shapes/Rect2';
+export { Parameterized2DShape } from './shapes/Parameterized2DShape';
 export { QuadraticBezier } from './shapes/QuadraticBezier';
 export { Abstract2DShape } from './shapes/Abstract2DShape';
 export { Mat33, Mat33Array } from './Mat33';

package/dist/mjs/lib.mjs

@@ -17,8 +17,9 @@
  * @packageDocumentation
  */
 export  { LineSegment2 }  from './shapes/LineSegment2.mjs';
-export  { Path, PathCommandType, }  from './shapes/Path.mjs';
+export  { Path, stepCurveIndexBy as stepPathIndexBy, compareCurveIndices as comparePathIndices, PathCommandType, }  from './shapes/Path.mjs';
 export  { Rect2 }  from './shapes/Rect2.mjs';
+export  { Parameterized2DShape }  from './shapes/Parameterized2DShape.mjs';
 export  { QuadraticBezier }  from './shapes/QuadraticBezier.mjs';
 export  { Abstract2DShape }  from './shapes/Abstract2DShape.mjs';
 export  { Mat33 }  from './Mat33.mjs';

package/dist/mjs/shapes/Abstract2DShape.d.ts

@@ -38,6 +38,9 @@ export declare abstract class Abstract2DShape {
     containsPoint(point: Point2, epsilon?: number): boolean;
     /**
      * Returns a bounding box that precisely fits the content of this shape.
+     *
+     * **Note**: This bounding box should aligned with the x/y axes. (Thus, it may be
+     * possible to find a tighter bounding box not axes-aligned).
      */
     abstract getTightBoundingBox(): Rect2;
     /**

package/dist/mjs/shapes/BezierJSWrapper.d.ts

@@ -1,21 +1,22 @@
 import { Bezier } from 'bezier-js';
 import { Point2, Vec2 } from '../Vec2';
-import Abstract2DShape from './Abstract2DShape';
 import LineSegment2 from './LineSegment2';
 import Rect2 from './Rect2';
+import Parameterized2DShape from './Parameterized2DShape';
 /**
  * A lazy-initializing wrapper around Bezier-js.
  *
  * Subclasses may override `at`, `derivativeAt`, and `normal` with functions
  * that do not initialize a `bezier-js` `Bezier`.
  *
- * Do not use this class directly. It may be removed/replaced in a future release.
+ * **Do not use this class directly.** It may be removed/replaced in a future release.
  * @internal
  */
-declare abstract class BezierJSWrapper extends Abstract2DShape {
+export declare abstract class BezierJSWrapper extends Parameterized2DShape {
     #private;
+    protected constructor(bezierJsBezier?: Bezier);
     /** Returns the start, control points, and end point of this Bézier. */
-    abstract getPoints(): Point2[];
+    abstract getPoints(): readonly Point2[];
     protected getBezier(): Bezier;
     signedDistance(point: Point2): number;
     /**
@@ -29,8 +30,21 @@ declare abstract class BezierJSWrapper extends Abstract2DShape {
      */
     at(t: number): Point2;
     derivativeAt(t: number): Point2;
+    secondDerivativeAt(t: number): Point2;
     normal(t: number): Vec2;
+    normalAt(t: number): Vec2;
+    tangentAt(t: number): Vec2;
     getTightBoundingBox(): Rect2;
-    intersectsLineSegment(line: LineSegment2): Point2[];
+    argIntersectsLineSegment(line: LineSegment2): number[];
+    splitAt(t: number): [BezierJSWrapper] | [BezierJSWrapper, BezierJSWrapper];
+    nearestPointTo(point: Point2): {
+        parameterValue: number;
+        point: import("../Vec3").Vec3;
+    };
+    intersectsBezier(other: BezierJSWrapper): {
+        parameterValue: number;
+        point: import("../Vec3").Vec3;
+    }[];
+    toString(): string;
 }
 export default BezierJSWrapper;