@js-draw/math 1.16.0 → 1.18.0

package/dist/cjs/shapes/LineSegment2.js

@@ -6,9 +6,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.LineSegment2 = void 0;
 const Rect2_1 = __importDefault(require("./Rect2"));
 const Vec2_1 = require("../Vec2");
-const Abstract2DShape_1 = __importDefault(require("./Abstract2DShape"));
+const Parameterized2DShape_1 = __importDefault(require("./Parameterized2DShape"));
 /** Represents a line segment. A `LineSegment2` is immutable. */
-class LineSegment2 extends Abstract2DShape_1.default {
+class LineSegment2 extends Parameterized2DShape_1.default {
     /** Creates a new `LineSegment2` from its endpoints. */
     constructor(point1, point2) {
         super();
@@ -22,6 +22,28 @@ class LineSegment2 extends Abstract2DShape_1.default {
             this.direction = this.direction.times(1 / this.length);
         }
     }
+    /**
+     * Returns the smallest line segment that contains all points in `points`, or `null`
+     * if no such line segment exists.
+     *
+     * @example
+     * ```ts,runnable
+     * import {LineSegment2, Vec2} from '@js-draw/math';
+     * console.log(LineSegment2.ofSmallestContainingPoints([Vec2.of(1, 0), Vec2.of(0, 1)]));
+     * ```
+     */
+    static ofSmallestContainingPoints(points) {
+        if (points.length <= 1)
+            return null;
+        const sorted = [...points].sort((a, b) => a.x !== b.x ? a.x - b.x : a.y - b.y);
+        const line = new LineSegment2(sorted[0], sorted[sorted.length - 1]);
+        for (const point of sorted) {
+            if (!line.containsPoint(point)) {
+                return null;
+            }
+        }
+        return line;
+    }
     // Accessors to make LineSegment2 compatible with bezier-js's
     // interface
     /** Alias for `point1`. */
@@ -32,8 +54,11 @@ class LineSegment2 extends Abstract2DShape_1.default {
     get p2() {
         return this.point2;
     }
+    get center() {
+        return this.point1.lerp(this.point2, 0.5);
+    }
     /**
-     * Gets a point a distance `t` along this line.
+     * Gets a point a **distance** `t` along this line.
      *
      * @deprecated
      */
@@ -50,7 +75,31 @@ class LineSegment2 extends Abstract2DShape_1.default {
     at(t) {
         return this.get(t * this.length);
     }
+    normalAt(_t) {
+        return this.direction.orthog();
+    }
+    tangentAt(_t) {
+        return this.direction;
+    }
+    splitAt(t) {
+        if (t <= 0 || t >= 1) {
+            return [this];
+        }
+        return [
+            new LineSegment2(this.point1, this.at(t)),
+            new LineSegment2(this.at(t), this.point2),
+        ];
+    }
+    /**
+     * Returns the intersection of this with another line segment.
+     *
+     * **WARNING**: The parameter value returned by this method does not range from 0 to 1 and
+     *              is currently a length.
+     *              This will change in a future release.
+     * @deprecated
+     */
     intersection(other) {
+        // TODO(v2.0.0): Make this return a `t` value from `0` to `1`.
         // We want x₁(t) = x₂(t) and y₁(t) = y₂(t)
         // Observe that
         // x = this.point1.x + this.direction.x · t₁
@@ -77,7 +126,10 @@ class LineSegment2 extends Abstract2DShape_1.default {
         //     = ((o₁ᵧ - o₂ᵧ)((d₁ₓd₂ₓ)) + (d₂ᵧd₁ₓ)(o₂ₓ) - (d₁ᵧd₂ₓ)(o₁ₓ))/(d₂ᵧd₁ₓ - d₁ᵧd₂ₓ)
         // ⇒ y = o₁ᵧ + d₁ᵧ · (x - o₁ₓ) / d₁ₓ = ...
         let resultPoint, resultT;
-        if (this.direction.x === 0) {
+        // Consider very-near-vertical lines to be vertical --- not doing so can lead to
+        // precision error when dividing by this.direction.x.
+        const small = 4e-13;
+        if (Math.abs(this.direction.x) < small) {
             // Vertical line: Where does the other have x = this.point1.x?
             // x = o₁ₓ = o₂ₓ + d₂ₓ · (y - o₂ᵧ) / d₂ᵧ
             // ⇒ (o₁ₓ - o₂ₓ)(d₂ᵧ/d₂ₓ) + o₂ᵧ = y
@@ -109,10 +161,10 @@ class LineSegment2 extends Abstract2DShape_1.default {
             resultT = (xIntersect - this.point1.x) / this.direction.x;
         }
         // Ensure the result is in this/the other segment.
-        const resultToP1 = resultPoint.minus(this.point1).magnitude();
-        const resultToP2 = resultPoint.minus(this.point2).magnitude();
-        const resultToP3 = resultPoint.minus(other.point1).magnitude();
-        const resultToP4 = resultPoint.minus(other.point2).magnitude();
+        const resultToP1 = resultPoint.distanceTo(this.point1);
+        const resultToP2 = resultPoint.distanceTo(this.point2);
+        const resultToP3 = resultPoint.distanceTo(other.point1);
+        const resultToP4 = resultPoint.distanceTo(other.point2);
         if (resultToP1 > this.length
             || resultToP2 > this.length
             || resultToP3 > other.length
@@ -127,6 +179,13 @@ class LineSegment2 extends Abstract2DShape_1.default {
     intersects(other) {
         return this.intersection(other) !== null;
     }
+    argIntersectsLineSegment(lineSegment) {
+        const intersection = this.intersection(lineSegment);
+        if (intersection) {
+            return [intersection.t / this.length];
+        }
+        return [];
+    }
     /**
      * Returns the points at which this line segment intersects the
      * given line segment.
@@ -144,18 +203,21 @@ class LineSegment2 extends Abstract2DShape_1.default {
     }
     // Returns the closest point on this to [target]
     closestPointTo(target) {
+        return this.nearestPointTo(target).point;
+    }
+    nearestPointTo(target) {
         // Distance from P1 along this' direction.
         const projectedDistFromP1 = target.minus(this.p1).dot(this.direction);
         const projectedDistFromP2 = this.length - projectedDistFromP1;
         const projection = this.p1.plus(this.direction.times(projectedDistFromP1));
         if (projectedDistFromP1 > 0 && projectedDistFromP1 < this.length) {
-            return projection;
+            return { point: projection, parameterValue: projectedDistFromP1 / this.length };
         }
         if (Math.abs(projectedDistFromP2) < Math.abs(projectedDistFromP1)) {
-            return this.p2;
+            return { point: this.p2, parameterValue: 1 };
         }
         else {
-            return this.p1;
+            return { point: this.p1, parameterValue: 0 };
         }
     }
     /**
@@ -178,6 +240,22 @@ class LineSegment2 extends Abstract2DShape_1.default {
     toString() {
         return `LineSegment(${this.p1.toString()}, ${this.p2.toString()})`;
     }
+    /**
+     * Returns `true` iff this is equivalent to `other`.
+     *
+     * **Options**:
+     * - `tolerance`: The maximum difference between endpoints. (Default: 0)
+     * - `ignoreDirection`: Allow matching a version of `this` with opposite direction. (Default: `true`)
+     */
+    eq(other, options) {
+        if (!(other instanceof LineSegment2)) {
+            return false;
+        }
+        const tolerance = options?.tolerance;
+        const ignoreDirection = options?.ignoreDirection ?? true;
+        return ((other.p1.eq(this.p1, tolerance) && other.p2.eq(this.p2, tolerance))
+            || (ignoreDirection && other.p1.eq(this.p2, tolerance) && other.p2.eq(this.p1, tolerance)));
+    }
 }
 exports.LineSegment2 = LineSegment2;
 exports.default = LineSegment2;

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

@@ -0,0 +1,36 @@
+import { Point2, Vec2 } from '../Vec2';
+import Abstract2DShape from './Abstract2DShape';
+import LineSegment2 from './LineSegment2';
+/**
+ * A 2-dimensional path with parameter interval $t \in [0, 1]$.
+ *
+ * **Note:** Avoid extending this class outside of `js-draw` --- new abstract methods
+ * may be added between minor versions.
+ */
+export declare abstract class Parameterized2DShape extends Abstract2DShape {
+    /** Returns this at a given parameter. $t \in [0, 1]$ */
+    abstract at(t: number): Point2;
+    /** Computes the unit normal vector at $t$. */
+    abstract normalAt(t: number): Vec2;
+    abstract tangentAt(t: number): Vec2;
+    /**
+     * Divides this shape into two separate shapes at parameter value $t$.
+     */
+    abstract splitAt(t: number): [Parameterized2DShape] | [Parameterized2DShape, Parameterized2DShape];
+    /**
+     * Returns the nearest point on `this` to `point` and the `parameterValue` at which
+     * that point occurs.
+     */
+    abstract nearestPointTo(point: Point2): {
+        point: Point2;
+        parameterValue: number;
+    };
+    /**
+     * Returns the **parameter values** at which `lineSegment` intersects this shape.
+     *
+     * See also {@link intersectsLineSegment}
+     */
+    abstract argIntersectsLineSegment(lineSegment: LineSegment2): number[];
+    intersectsLineSegment(line: LineSegment2): Point2[];
+}
+export default Parameterized2DShape;

package/dist/cjs/shapes/Parameterized2DShape.js

@@ -0,0 +1,20 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Parameterized2DShape = void 0;
+const Abstract2DShape_1 = __importDefault(require("./Abstract2DShape"));
+/**
+ * A 2-dimensional path with parameter interval $t \in [0, 1]$.
+ *
+ * **Note:** Avoid extending this class outside of `js-draw` --- new abstract methods
+ * may be added between minor versions.
+ */
+class Parameterized2DShape extends Abstract2DShape_1.default {
+    intersectsLineSegment(line) {
+        return this.argIntersectsLineSegment(line).map(t => this.at(t));
+    }
+}
+exports.Parameterized2DShape = Parameterized2DShape;
+exports.default = Parameterized2DShape;

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

@@ -2,7 +2,7 @@ import LineSegment2 from './LineSegment2';
 import Mat33 from '../Mat33';
 import Rect2 from './Rect2';
 import { Point2 } from '../Vec2';
-import Abstract2DShape from './Abstract2DShape';
+import Parameterized2DShape from './Parameterized2DShape';
 export declare enum PathCommandType {
     LineTo = 0,
     MoveTo = 1,
@@ -29,14 +29,68 @@ export interface MoveToPathCommand {
     point: Point2;
 }
 export type PathCommand = CubicBezierPathCommand | QuadraticBezierPathCommand | MoveToPathCommand | LinePathCommand;
-interface IntersectionResult {
-    curve: Abstract2DShape;
-    /** @internal @deprecated */
-    parameterValue?: number;
+export interface IntersectionResult {
+    curve: Parameterized2DShape;
+    curveIndex: number;
+    /** Parameter value for the closest point **on** the path to the intersection. @internal */
+    parameterValue: number;
+    /** Point at which the intersection occured. */
     point: Point2;
 }
+/** Options for {@link Path.splitNear} and {@link Path.splitAt} */
+export interface PathSplitOptions {
+    /**
+     * Allows mapping points on newly added segments. This is useful, for example,
+     * to round points to prevent long decimals when later saving.
+     */
+    mapNewPoint?: (point: Point2) => Point2;
+}
+/**
+ * Allows indexing a particular part of a path.
+ *
+ * @see {@link Path.at} {@link Path.tangentAt}
+ */
+export interface CurveIndexRecord {
+    curveIndex: number;
+    parameterValue: number;
+}
+/** Returns a positive number if `a` comes after `b`, 0 if equal, and negative otherwise. */
+export declare const compareCurveIndices: (a: CurveIndexRecord, b: CurveIndexRecord) => number;
+/**
+ * Returns a version of `index` with its parameter value incremented by `stepBy`
+ * (which can be either positive or negative).
+ */
+export declare const stepCurveIndexBy: (index: CurveIndexRecord, stepBy: number) => CurveIndexRecord;
 /**
  * Represents a union of lines and curves.
+ *
+ * To create a path from a string, see {@link fromString}.
+ *
+ * @example
+ * ```ts,runnable,console
+ * import {Path, Mat33, Vec2, LineSegment2} from '@js-draw/math';
+ *
+ * // Creates a path from an SVG path string.
+ * // In this case,
+ * // 1. Move to (0,0)
+ * // 2. Line to (100,0)
+ * const path = Path.fromString('M0,0 L100,0');
+ *
+ * // Logs the distance from (10,0) to the curve 1 unit
+ * // away from path. This curve forms a stroke with the path at
+ * // its center.
+ * const strokeRadius = 1;
+ * console.log(path.signedDistance(Vec2.of(10,0), strokeRadius));
+ *
+ * // Log a version of the path that's scaled by a factor of 4.
+ * console.log(path.transformedBy(Mat33.scaling2D(4)).toString());
+ *
+ * // Log all intersections of a stroked version of the path with
+ * // a vertical line segment.
+ * // (Try removing the `strokeRadius` parameter).
+ * const segment = new LineSegment2(Vec2.of(5, -100), Vec2.of(5, 100));
+ * console.log(path.intersection(segment, strokeRadius).map(i => i.point));
+ * ```
  */
 export declare class Path {
     readonly startPoint: Point2;
@@ -55,9 +109,15 @@ export declare class Path {
      * See also {@link fromString}
      */
     constructor(startPoint: Point2, parts: Readonly<PathCommand>[]);
+    /**
+     * Computes and returns the full bounding box for this path.
+     *
+     * If a slight over-estimate of a path's bounding box is sufficient, use
+     * {@link bbox} instead.
+     */
     getExactBBox(): Rect2;
     private cachedGeometry;
-    get geometry(): Abstract2DShape[];
+    get geometry(): Parameterized2DShape[];
     /**
      * Iterates through the start/end points of each component in this path.
      *
@@ -68,7 +128,20 @@ export declare class Path {
     private cachedPolylineApproximation;
     polylineApproximation(): LineSegment2[];
     static computeBBoxForSegment(startPoint: Point2, part: PathCommand): Rect2;
-    /** **Note**: `strokeRadius = strokeWidth / 2` */
+    /**
+     * Returns the signed distance between `point` and a curve `strokeRadius` units
+     * away from this path.
+     *
+     * This returns the **signed distance**, which means that points inside this shape
+     * have their distance negated. For example,
+     * ```ts,runnable,console
+     * import {Path, Vec2} from '@js-draw/math';
+     * console.log(Path.fromString('m0,0 L100,0').signedDistance(Vec2.zero, 1));
+     * ```
+     * would print `-1` because (0,0) is on `m0,0 L100,0` and thus one unit away from its boundary.
+     *
+     * **Note**: `strokeRadius = strokeWidth / 2`
+     */
     signedDistance(point: Point2, strokeRadius: number): number;
     /**
      * Let `S` be a closed path a distance `strokeRadius` from this path.
@@ -86,11 +159,49 @@ export declare class Path {
      * **Note**: `strokeRadius` is half of a stroke's width.
      */
     intersection(line: LineSegment2, strokeRadius?: number): IntersectionResult[];
+    /**
+     * @returns the nearest point on this path to the given `point`.
+     */
+    nearestPointTo(point: Point2): IntersectionResult;
+    at(index: CurveIndexRecord): import("../Vec3").Vec3;
+    tangentAt(index: CurveIndexRecord): import("../Vec3").Vec3;
+    /** Splits this path in two near the given `point`. */
+    splitNear(point: Point2, options?: PathSplitOptions): [Path] | [Path, Path];
+    /**
+     * Returns a copy of this path with `deleteFrom` until `deleteUntil` replaced with `insert`.
+     *
+     * This method is analogous to {@link Array.toSpliced}.
+     */
+    spliced(deleteFrom: CurveIndexRecord, deleteTo: CurveIndexRecord, insert: Path | undefined, options?: PathSplitOptions): Path;
+    splitAt(at: CurveIndexRecord, options?: PathSplitOptions): [Path] | [Path, Path];
+    splitAt(at: CurveIndexRecord[], options?: PathSplitOptions): Path[];
+    /**
+     * Replaces all `MoveTo` commands with `LineTo` commands and connects the end point of this
+     * path to the start point.
+     */
+    asClosed(): Path;
     private static mapPathCommand;
     mapPoints(mapping: (point: Point2) => Point2): Path;
     transformedBy(affineTransfm: Mat33): Path;
-    union(other: Path | null): Path;
-    private getEndPoint;
+    /**
+     * @internal
+     */
+    closedContainsPoint(point: Point2): boolean;
+    union(other: Path | PathCommand[] | null, options?: {
+        allowReverse?: boolean;
+    }): Path;
+    /**
+     * @returns a version of this path with the direction reversed.
+     *
+     * Example:
+     * ```ts,runnable,console
+     * import {Path} from '@js-draw/math';
+     * console.log(Path.fromString('m0,0l1,1').reversed()); // -> M1,1 L0,0
+     * ```
+     */
+    reversed(): Path;
+    /** Computes and returns the end point of this path */
+    getEndPoint(): import("../Vec3").Vec3;
     /**
      * Like {@link closedRoughlyIntersects} except takes stroke width into account.
      *
@@ -102,7 +213,15 @@ export declare class Path {
      * `strokeRadius` is half of `strokeWidth`.
      */
     roughlyIntersects(rect: Rect2, strokeWidth?: number): boolean;
+    /**
+     * Treats this as a closed path and returns true if part of `rect` is *roughly* within
+     * this path's interior.
+     *
+     * **Note**: Assumes that this is a closed, non-self-intersecting path.
+     */
     closedRoughlyIntersects(rect: Rect2): boolean;
+    /** @returns true if all points on this are equivalent to the points on `other` */
+    eq(other: Path, tolerance?: number): boolean;
     /**
      * Returns a path that outlines `rect`.
      *
@@ -126,10 +245,8 @@ export declare class Path {
     /**
      * Create a `Path` from a subset of the SVG path specification.
      *
-     * ## To-do
-     * - TODO: Support a larger subset of SVG paths
-     *   - Elliptical arcs are currently unsupported.
-     * - TODO: Support `s`,`t` commands shorthands.
+     * Currently, this does not support elliptical arcs or `s` and `t` command
+     * shorthands. See https://github.com/personalizedrefrigerator/js-draw/pull/19.
      *
      * @example
      * ```ts,runnable,console
@@ -140,6 +257,7 @@ export declare class Path {
      * ```
      */
     static fromString(pathString: string): Path;
+    static fromConvexHullOf(points: Point2[]): Path;
     static empty: Path;
 }
 export default Path;