@js-draw/math 1.17.0 → 1.18.0

package/dist/mjs/lib.d.ts

@@ -17,8 +17,9 @@
  * @packageDocumentation
  */
 export { LineSegment2 } from './shapes/LineSegment2';
-export { Path, IntersectionResult as PathIntersectionResult, CurveIndexRecord as PathCurveIndex, 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/BezierJSWrapper.d.ts

@@ -41,6 +41,10 @@ export declare abstract class BezierJSWrapper extends Parameterized2DShape {
         parameterValue: number;
         point: import("../Vec3").Vec3;
     };
+    intersectsBezier(other: BezierJSWrapper): {
+        parameterValue: number;
+        point: import("../Vec3").Vec3;
+    }[];
     toString(): string;
 }
 export default BezierJSWrapper;

package/dist/mjs/shapes/BezierJSWrapper.mjs

@@ -12,6 +12,7 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
 var _BezierJSWrapper_bezierJs;
 import { Bezier } from 'bezier-js';
 import  { Vec2 }  from '../Vec2.mjs';
+import  LineSegment2  from './LineSegment2.mjs';
 import  Rect2  from './Rect2.mjs';
 import  Parameterized2DShape  from './Parameterized2DShape.mjs';
 /**
@@ -78,6 +79,17 @@ export class BezierJSWrapper extends Parameterized2DShape {
         return new Rect2(bbox.x.min, bbox.y.min, width, height);
     }
     argIntersectsLineSegment(line) {
+        // Bezier-js has a bug when all control points of a Bezier curve lie on
+        // a line. Our solution involves converting the Bezier into a line, then
+        // finding the parameter value that produced the intersection.
+        //
+        // TODO: This is unnecessarily slow. A better solution would be to fix
+        // the bug upstream.
+        const asLine = LineSegment2.ofSmallestContainingPoints(this.getPoints());
+        if (asLine) {
+            const intersection = asLine.intersectsLineSegment(line);
+            return intersection.map(p => this.nearestPointTo(p).parameterValue);
+        }
         const bezier = this.getBezier();
         return bezier.intersects(line).map(t => {
             // We're using the .intersects(line) function, which is documented
@@ -160,6 +172,8 @@ export class BezierJSWrapper extends Parameterized2DShape {
         };
         const iterate = () => {
             const slope = secondDerivativeAt(t);
+            if (slope === 0)
+                return;
             // We intersect a line through the point on f'(t) at t with the x-axis:
             //    y = m(x - x₀) + y₀
             // ⇒  x - x₀ = (y - y₀) / m
@@ -183,6 +197,27 @@ export class BezierJSWrapper extends Parameterized2DShape {
         }
         return { parameterValue: t, point: this.at(t) };
     }
+    intersectsBezier(other) {
+        const intersections = this.getBezier().intersects(other.getBezier());
+        if (!intersections || intersections.length === 0) {
+            return [];
+        }
+        const result = [];
+        for (const intersection of intersections) {
+            // From http://pomax.github.io/bezierjs/#intersect-curve,
+            // .intersects returns an array of 't1/t2' pairs, where curve1.at(t1) gives the point.
+            const match = /^([-0-9.eE]+)\/([-0-9.eE]+)$/.exec(intersection);
+            if (!match) {
+                throw new Error(`Incorrect format returned by .intersects: ${intersections} should be array of "number/number"!`);
+            }
+            const t = parseFloat(match[1]);
+            result.push({
+                parameterValue: t,
+                point: this.at(t),
+            });
+        }
+        return result;
+    }
     toString() {
         return `Bézier(${this.getPoints().map(point => point.toString()).join(', ')})`;
     }

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

@@ -25,6 +25,17 @@ export declare class LineSegment2 extends Parameterized2DShape {
     readonly bbox: Rect2;
     /** Creates a new `LineSegment2` from its endpoints. */
     constructor(point1: Point2, point2: Point2);
+    /**
+     * 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: readonly Point2[]): LineSegment2 | null;
     /** Alias for `point1`. */
     get p1(): Point2;
     /** Alias for `point2`. */

package/dist/mjs/shapes/LineSegment2.mjs

@@ -16,6 +16,28 @@ export class LineSegment2 extends Parameterized2DShape {
             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`. */
@@ -98,7 +120,10 @@ export class LineSegment2 extends Parameterized2DShape {
         //     = ((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

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

@@ -1,7 +1,12 @@
 import { Point2, Vec2 } from '../Vec2';
 import Abstract2DShape from './Abstract2DShape';
 import LineSegment2 from './LineSegment2';
-/** A 2-dimensional path with parameter interval $t \in [0, 1]$. */
+/**
+ * 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;

package/dist/mjs/shapes/Parameterized2DShape.mjs

@@ -1,5 +1,10 @@
 import  Abstract2DShape  from './Abstract2DShape.mjs';
-/** A 2-dimensional path with parameter interval $t \in [0, 1]$. */
+/**
+ * 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 class Parameterized2DShape extends Abstract2DShape {
     intersectsLineSegment(line) {
         return this.argIntersectsLineSegment(line).map(t => this.at(t));

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

@@ -32,11 +32,19 @@ export type PathCommand = CubicBezierPathCommand | QuadraticBezierPathCommand |
 export interface IntersectionResult {
     curve: Parameterized2DShape;
     curveIndex: number;
-    /** Parameter value for the closest point **on** the path to the intersection. @internal @deprecated */
-    parameterValue?: 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.
  *
@@ -46,8 +54,43 @@ 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;
@@ -66,6 +109,12 @@ 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(): Parameterized2DShape[];
@@ -79,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.
@@ -99,17 +161,33 @@ export declare class Path {
     intersection(line: LineSegment2, strokeRadius?: number): IntersectionResult[];
     /**
      * @returns the nearest point on this path to the given `point`.
-     *
-     * @internal
-     * @beta
      */
     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, options?: {
+    /**
+     * @internal
+     */
+    closedContainsPoint(point: Point2): boolean;
+    union(other: Path | PathCommand[] | null, options?: {
         allowReverse?: boolean;
     }): Path;
     /**
@@ -122,7 +200,8 @@ export declare class Path {
      * ```
      */
     reversed(): Path;
-    private getEndPoint;
+    /** Computes and returns the end point of this path */
+    getEndPoint(): import("../Vec3").Vec3;
     /**
      * Like {@link closedRoughlyIntersects} except takes stroke width into account.
      *
@@ -134,6 +213,12 @@ 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;
@@ -160,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
@@ -174,6 +257,7 @@ export declare class Path {
      * ```
      */
     static fromString(pathString: string): Path;
+    static fromConvexHullOf(points: Point2[]): Path;
     static empty: Path;
 }
 export default Path;