@js-draw/math 1.11.1 → 1.17.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

@@ -18,11 +18,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

@@ -31,10 +31,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 +55,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 +121,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

@@ -25,6 +25,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

@@ -44,6 +44,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 +133,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/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)

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)

package/dist/mjs/lib.d.ts

@@ -17,7 +17,7 @@
  * @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, PathCommandType, PathCommand, LinePathCommand, MoveToPathCommand, QuadraticBezierPathCommand, CubicBezierPathCommand, } from './shapes/Path';
 export { Rect2 } from './shapes/Rect2';
 export { QuadraticBezier } from './shapes/QuadraticBezier';
 export { Abstract2DShape } from './shapes/Abstract2DShape';
@@ -25,4 +25,4 @@ export { Mat33, Mat33Array } from './Mat33';
 export { Point2, Vec2 } from './Vec2';
 export { Vec3 } from './Vec3';
 export { Color4 } from './Color4';
-export { toRoundedString } from './rounding';
+export * from './rounding/lib';

package/dist/mjs/lib.mjs

@@ -25,6 +25,6 @@ export  { Mat33 }  from './Mat33.mjs';
 export  { Vec2 }  from './Vec2.mjs';
 export  { Vec3 }  from './Vec3.mjs';
 export  { Color4 }  from './Color4.mjs';
-export  { toRoundedString }  from './rounding.mjs';
+export  *  from './rounding/lib.mjs';
 // Note: All above exports cannot use `export { default as ... } from "..."` because this
 // breaks TypeDoc -- TypeDoc otherwise labels any imports of these classes as `default`.

package/dist/mjs/rounding/cleanUpNumber.d.ts

@@ -0,0 +1,3 @@
+/** Cleans up stringified numbers */
+export declare const cleanUpNumber: (text: string) => string;
+export default cleanUpNumber;

package/dist/mjs/rounding/cleanUpNumber.mjs

@@ -0,0 +1,31 @@
+/** Cleans up stringified numbers */
+export const cleanUpNumber = (text) => {
+    // Regular expression substitions can be somewhat expensive. Only do them
+    // if necessary.
+    if (text.indexOf('e') > 0) {
+        // Round to zero.
+        if (text.match(/[eE][-]\d{2,}$/)) {
+            return '0';
+        }
+    }
+    const lastChar = text.charAt(text.length - 1);
+    if (lastChar === '0' || lastChar === '.') {
+        // Remove trailing zeroes
+        text = text.replace(/([.]\d*[^0]+)0+$/, '$1');
+        text = text.replace(/[.]0+$/, '.');
+        // Remove trailing period
+        text = text.replace(/[.]$/, '');
+    }
+    const firstChar = text.charAt(0);
+    if (firstChar === '0' || firstChar === '-') {
+        // Remove unnecessary leading zeroes.
+        text = text.replace(/^(0+)[.]/, '.');
+        text = text.replace(/^-(0+)[.]/, '-.');
+        text = text.replace(/^(-?)0+$/, '$10');
+    }
+    if (text === '-0') {
+        return '0';
+    }
+    return text;
+};
+export default cleanUpNumber;

package/dist/mjs/rounding/cleanUpNumber.test.d.ts

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

package/dist/mjs/rounding/constants.d.ts

@@ -0,0 +1 @@
+export declare const numberRegex: RegExp;

package/dist/mjs/rounding/constants.mjs

@@ -0,0 +1 @@
+export const numberRegex = /^([-]?)(\d*)[.](\d+)$/;

package/dist/mjs/rounding/getLenAfterDecimal.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Returns the length of `numberAsString` after a decimal point.
+ *
+ * For example,
+ * ```ts
+ * getLenAfterDecimal('1.001') // -> 3
+ * ```
+ */
+export declare const getLenAfterDecimal: (numberAsString: string) => number;
+export default getLenAfterDecimal;

package/dist/mjs/rounding/getLenAfterDecimal.mjs

@@ -0,0 +1,26 @@
+import  { numberRegex }  from './constants.mjs';
+/**
+ * Returns the length of `numberAsString` after a decimal point.
+ *
+ * For example,
+ * ```ts
+ * getLenAfterDecimal('1.001') // -> 3
+ * ```
+ */
+export const getLenAfterDecimal = (numberAsString) => {
+    const numberMatch = numberRegex.exec(numberAsString);
+    if (!numberMatch) {
+        // If not a match, either the number is exponential notation (or is something
+        // like NaN or Infinity)
+        if (numberAsString.search(/[eE]/) !== -1 || /^[a-zA-Z]+$/.exec(numberAsString)) {
+            return -1;
+            // Or it has no decimal point
+        }
+        else {
+            return 0;
+        }
+    }
+    const afterDecimalLen = numberMatch[3].length;
+    return afterDecimalLen;
+};
+export default getLenAfterDecimal;

package/dist/mjs/rounding/lib.d.ts

@@ -0,0 +1 @@
+export { toRoundedString } from './toRoundedString';

package/dist/mjs/rounding/lib.mjs

@@ -0,0 +1 @@
+export  { toRoundedString }  from './toRoundedString.mjs';

package/dist/mjs/{rounding.d.ts → rounding/toRoundedString.d.ts}

@@ -1,4 +1,3 @@
-export declare const cleanUpNumber: (text: string) => string;
 /**
  * Converts `num` to a string, removing trailing digits that were likely caused by
  * precision errors.
@@ -11,5 +10,4 @@ export declare const cleanUpNumber: (text: string) => string;
  * ```
  */
 export declare const toRoundedString: (num: number) => string;
-export declare const getLenAfterDecimal: (numberAsString: string) => number;
-export declare const toStringOfSamePrecision: (num: number, ...references: string[]) => string;
+export default toRoundedString;

package/dist/mjs/rounding/toRoundedString.mjs

@@ -0,0 +1,47 @@
+import  cleanUpNumber  from './cleanUpNumber.mjs';
+/**
+ * Converts `num` to a string, removing trailing digits that were likely caused by
+ * precision errors.
+ *
+ * @example
+ * ```ts,runnable,console
+ * import { toRoundedString } from '@js-draw/math';
+ *
+ * console.log('Rounded: ', toRoundedString(1.000000011));
+ * ```
+ */
+export const toRoundedString = (num) => {
+    // Try to remove rounding errors. If the number ends in at least three/four zeroes
+    // (or nines) just one or two digits, it's probably a rounding error.
+    const fixRoundingUpExp = /^([-]?\d*\.\d{3,})0{4,}\d{1,4}$/;
+    const hasRoundingDownExp = /^([-]?)(\d*)\.(\d{3,}9{4,})\d{1,4}$/;
+    let text = num.toString(10);
+    if (text.indexOf('.') === -1) {
+        return text;
+    }
+    const roundingDownMatch = hasRoundingDownExp.exec(text);
+    if (roundingDownMatch) {
+        const negativeSign = roundingDownMatch[1];
+        const postDecimalString = roundingDownMatch[3];
+        const lastDigit = parseInt(postDecimalString.charAt(postDecimalString.length - 1), 10);
+        const postDecimal = parseInt(postDecimalString, 10);
+        const preDecimal = parseInt(roundingDownMatch[2], 10);
+        const origPostDecimalString = roundingDownMatch[3];
+        let newPostDecimal = (postDecimal + 10 - lastDigit).toString();
+        let carry = 0;
+        if (newPostDecimal.length > postDecimal.toString().length) {
+            // Left-shift
+            newPostDecimal = newPostDecimal.substring(1);
+            carry = 1;
+        }
+        // parseInt(...).toString() removes leading zeroes. Add them back.
+        while (newPostDecimal.length < origPostDecimalString.length) {
+            newPostDecimal = carry.toString(10) + newPostDecimal;
+            carry = 0;
+        }
+        text = `${negativeSign + (preDecimal + carry).toString()}.${newPostDecimal}`;
+    }
+    text = text.replace(fixRoundingUpExp, '$1');
+    return cleanUpNumber(text);
+};
+export default toRoundedString;

package/dist/mjs/rounding/toRoundedString.test.d.ts

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

package/dist/mjs/rounding/toStringOfSamePrecision.d.ts

@@ -0,0 +1,2 @@
+export declare const toStringOfSamePrecision: (num: number, ...references: string[]) => string;
+export default toStringOfSamePrecision;

package/dist/mjs/rounding/toStringOfSamePrecision.mjs

@@ -0,0 +1,51 @@
+import  cleanUpNumber  from './cleanUpNumber.mjs';
+import  { numberRegex }  from './constants.mjs';
+import  getLenAfterDecimal  from './getLenAfterDecimal.mjs';
+import  toRoundedString  from './toRoundedString.mjs';
+// [reference] should be a string representation of a base-10 number (no exponential (e.g. 10e10))
+export const toStringOfSamePrecision = (num, ...references) => {
+    const text = num.toString(10);
+    const textMatch = numberRegex.exec(text);
+    if (!textMatch) {
+        return text;
+    }
+    let decimalPlaces = -1;
+    for (const reference of references) {
+        decimalPlaces = Math.max(getLenAfterDecimal(reference), decimalPlaces);
+    }
+    if (decimalPlaces === -1) {
+        return toRoundedString(num);
+    }
+    // Make text's after decimal length match [afterDecimalLen].
+    let postDecimal = textMatch[3].substring(0, decimalPlaces);
+    let preDecimal = textMatch[2];
+    const nextDigit = textMatch[3].charAt(decimalPlaces);
+    if (nextDigit !== '') {
+        const asNumber = parseInt(nextDigit, 10);
+        if (asNumber >= 5) {
+            // Don't attempt to parseInt() an empty string.
+            if (postDecimal.length > 0) {
+                const leadingZeroMatch = /^(0+)(\d*)$/.exec(postDecimal);
+                let leadingZeroes = '';
+                let postLeading = postDecimal;
+                if (leadingZeroMatch) {
+                    leadingZeroes = leadingZeroMatch[1];
+                    postLeading = leadingZeroMatch[2];
+                }
+                postDecimal = (parseInt(postDecimal) + 1).toString();
+                // If postDecimal got longer, remove leading zeroes if possible
+                if (postDecimal.length > postLeading.length && leadingZeroes.length > 0) {
+                    leadingZeroes = leadingZeroes.substring(1);
+                }
+                postDecimal = leadingZeroes + postDecimal;
+            }
+            if (postDecimal.length === 0 || postDecimal.length > decimalPlaces) {
+                preDecimal = (parseInt(preDecimal) + 1).toString();
+                postDecimal = postDecimal.substring(1);
+            }
+        }
+    }
+    const negativeSign = textMatch[1];
+    return cleanUpNumber(`${negativeSign}${preDecimal}.${postDecimal}`);
+};
+export default toStringOfSamePrecision;

package/dist/mjs/rounding/toStringOfSamePrecision.test.d.ts

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

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,17 @@ 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;
+    };
+    toString(): string;
 }
 export default BezierJSWrapper;