@js-draw/math 1.18.0 → 1.21.1

package/dist/cjs/Vec3.js

@@ -1,32 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Vec3 = void 0;
-/**
- * A vector with three components, $\begin{pmatrix} x \\ y \\ z \end{pmatrix}$.
- * Can also be used to represent a two-component vector.
- *
- * A `Vec3` is immutable.
- *
- * @example
- *
- * ```ts,runnable,console
- * import { Vec3 } from '@js-draw/math';
- *
- * console.log('Vector addition:', Vec3.of(1, 2, 3).plus(Vec3.of(0, 1, 0)));
- * console.log('Scalar multiplication:', Vec3.of(1, 2, 3).times(2));
- * console.log('Cross products:', Vec3.unitX.cross(Vec3.unitY));
- * console.log('Magnitude:', Vec3.of(1, 2, 3).length(), 'or', Vec3.of(1, 2, 3).magnitude());
- * console.log('Square Magnitude:', Vec3.of(1, 2, 3).magnitudeSquared());
- * console.log('As an array:', Vec3.unitZ.asArray());
- * ```
- */
-class Vec3 {
+exports.Vec3 = exports.Vec2 = void 0;
+const defaultEqlTolerance = 1e-10;
+class Vec3Impl {
     constructor(x, y, z) {
         this.x = x;
         this.y = y;
         this.z = z;
     }
-    /** Returns the x, y components of this. */
     get xy() {
         // Useful for APIs that behave differently if .z is present.
         return {
@@ -34,10 +15,6 @@ class Vec3 {
             y: this.y,
         };
     }
-    /** Construct a vector from three components. */
-    static of(x, y, z) {
-        return new Vec3(x, y, z);
-    }
     /** Returns this' `idx`th component. For example, `Vec3.of(1, 2, 3).at(1) → 2`. */
     at(idx) {
         if (idx === 0)
@@ -48,89 +25,40 @@ class Vec3 {
             return this.z;
         throw new Error(`${idx} out of bounds!`);
     }
-    /** Alias for this.magnitude. */
     length() {
         return this.magnitude();
     }
     magnitude() {
-        return Math.sqrt(this.dot(this));
+        return Math.sqrt(this.magnitudeSquared());
     }
     magnitudeSquared() {
-        return this.dot(this);
+        return this.x * this.x + this.y * this.y + this.z * this.z;
     }
-    /**
-     * 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)));
     }
-    /**
-     * Return this' angle in the XY plane (treats this as a Vec2).
-     *
-     * This is equivalent to `Math.atan2(vec.y, vec.x)`.
-     *
-     * 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)
-     * console.log(Vec2.of(-1, 0).angle());  // atan2(0, -1)
-     * ```
-     */
     angle() {
         return Math.atan2(this.y, this.x);
     }
-    /**
-     * Returns a unit vector in the same direction as this.
-     *
-     * If `this` has zero length, the resultant vector has `NaN` components.
-     */
     normalized() {
         const norm = this.magnitude();
         return Vec3.of(this.x / norm, this.y / norm, this.z / norm);
     }
-    /**
-     * Like {@link normalized}, except returns zero if this has zero magnitude.
-     */
     normalizedOrZero() {
         if (this.eq(Vec3.zero)) {
             return Vec3.zero;
         }
         return this.normalized();
     }
-    /** @returns A copy of `this` multiplied by a scalar. */
     times(c) {
         return Vec3.of(this.x * c, this.y * c, this.z * c);
     }
@@ -149,25 +77,12 @@ class Vec3 {
         // | x2 y2 z2|
         return Vec3.of(this.y * other.z - other.y * this.z, other.x * this.z - this.x * other.z, this.x * other.y - other.x * this.y);
     }
-    /**
-     * If `other` is a `Vec3`, multiplies `this` component-wise by `other`. Otherwise,
-     * if `other is a `number`, returns the result of scalar multiplication.
-     *
-     * @example
-     * ```
-     * Vec3.of(1, 2, 3).scale(Vec3.of(2, 4, 6)); // → Vec3(2, 8, 18)
-     * ```
-     */
     scale(other) {
         if (typeof other === 'number') {
             return this.times(other);
         }
         return Vec3.of(this.x * other.x, this.y * other.y, this.z * other.z);
     }
-    /**
-     * Returns a vector orthogonal to this. If this is a Vec2, returns `this` rotated
-     * 90 degrees counter-clockwise.
-     */
     orthog() {
         // If parallel to the z-axis
         if (this.dot(Vec3.unitX) === 0 && this.dot(Vec3.unitY) === 0) {
@@ -175,62 +90,22 @@ class Vec3 {
         }
         return this.cross(Vec3.unitZ.times(-1)).normalized();
     }
-    /** Returns this plus a vector of length `distance` in `direction`. */
     extend(distance, direction) {
         return this.plus(direction.normalized().times(distance));
     }
-    /** Returns a vector `fractionTo` of the way to target from this. */
     lerp(target, fractionTo) {
         return this.times(1 - fractionTo).plus(target.times(fractionTo));
     }
-    /**
-     * `zip` Maps a component of this and a corresponding component of
-     * `other` to a component of the output vector.
-     *
-     * @example
-     * ```
-     * const a = Vec3.of(1, 2, 3);
-     * const b = Vec3.of(0.5, 2.1, 2.9);
-     *
-     * const zipped = a.zip(b, (aComponent, bComponent) => {
-     *   return Math.min(aComponent, bComponent);
-     * });
-     *
-     * console.log(zipped.toString()); // → Vec(0.5, 2, 2.9)
-     * ```
-     */
     zip(other, zip) {
         return Vec3.of(zip(other.x, this.x), zip(other.y, this.y), zip(other.z, this.z));
     }
-    /**
-     * 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)
-     * ```
-     */
     map(fn) {
         return Vec3.of(fn(this.x, 0), fn(this.y, 1), fn(this.z, 2));
     }
     asArray() {
         return [this.x, this.y, this.z];
     }
-    /**
-     * [fuzz] The maximum difference between two components for this and [other]
-     * to be considered equal.
-     *
-     * @example
-     * ```
-     * Vec3.of(1, 2, 3).eq(Vec3.of(4, 5, 6), 100);  // → true
-     * Vec3.of(1, 2, 3).eq(Vec3.of(4, 5, 6), 0.1);  // → false
-     * Vec3.of(1, 2, 3).eq(Vec3.of(4, 5, 6), 3);    // → true
-     * Vec3.of(1, 2, 3).eq(Vec3.of(4, 5, 6), 3.01); // → true
-     * Vec3.of(1, 2, 3).eq(Vec3.of(4, 5, 6), 2.99); // → false
-     * ```
-     */
-    eq(other, fuzz = 1e-10) {
+    eq(other, fuzz = defaultEqlTolerance) {
         return (Math.abs(other.x - this.x) <= fuzz
             && Math.abs(other.y - this.y) <= fuzz
             && Math.abs(other.z - this.z) <= fuzz);
@@ -239,9 +114,182 @@ class Vec3 {
         return `Vec(${this.x}, ${this.y}, ${this.z})`;
     }
 }
-exports.Vec3 = Vec3;
-Vec3.unitX = Vec3.of(1, 0, 0);
-Vec3.unitY = Vec3.of(0, 1, 0);
-Vec3.unitZ = Vec3.of(0, 0, 1);
-Vec3.zero = Vec3.of(0, 0, 0);
+class Vec2Impl {
+    constructor(x, y) {
+        this.x = x;
+        this.y = y;
+    }
+    get z() { return 0; }
+    get xy() {
+        // Useful for APIs that behave differently if .z is present.
+        return {
+            x: this.x,
+            y: this.y,
+        };
+    }
+    at(idx) {
+        if (idx === 0)
+            return this.x;
+        if (idx === 1)
+            return this.y;
+        if (idx === 2)
+            return 0;
+        throw new Error(`${idx} out of bounds!`);
+    }
+    length() {
+        return this.magnitude();
+    }
+    magnitude() {
+        return Math.sqrt(this.x * this.x + this.y * this.y);
+    }
+    magnitudeSquared() {
+        return this.x * this.x + this.y * this.y;
+    }
+    squareDistanceTo(p) {
+        const dx = this.x - p.x;
+        const dy = this.y - p.y;
+        return dx * dx + dy * dy + p.z * p.z;
+    }
+    distanceTo(p) {
+        return Math.sqrt(this.squareDistanceTo(p));
+    }
+    maximumEntryMagnitude() {
+        return Math.max(Math.abs(this.x), Math.abs(this.y));
+    }
+    angle() {
+        return Math.atan2(this.y, this.x);
+    }
+    normalized() {
+        const norm = this.magnitude();
+        return Vec2.of(this.x / norm, this.y / norm);
+    }
+    normalizedOrZero() {
+        if (this.eq(Vec3.zero)) {
+            return Vec3.zero;
+        }
+        return this.normalized();
+    }
+    times(c) {
+        return Vec2.of(this.x * c, this.y * c);
+    }
+    plus(v) {
+        return Vec3.of(this.x + v.x, this.y + v.y, v.z);
+    }
+    minus(v) {
+        return Vec3.of(this.x - v.x, this.y - v.y, -v.z);
+    }
+    dot(other) {
+        return this.x * other.x + this.y * other.y;
+    }
+    cross(other) {
+        // | i  j  k |
+        // | x1 y1 z1| = (i)(y1z2 - y2z1) - (j)(x1z2 - x2z1) + (k)(x1y2 - x2y1)
+        // | x2 y2 z2|
+        return Vec3.of(this.y * other.z, -this.x * other.z, this.x * other.y - other.x * this.y);
+    }
+    scale(other) {
+        if (typeof other === 'number') {
+            return this.times(other);
+        }
+        return Vec2.of(this.x * other.x, this.y * other.y);
+    }
+    orthog() {
+        // If parallel to the z-axis
+        if (this.dot(Vec3.unitX) === 0 && this.dot(Vec3.unitY) === 0) {
+            return this.dot(Vec3.unitX) === 0 ? Vec3.unitX : this.cross(Vec3.unitX).normalized();
+        }
+        return this.cross(Vec3.unitZ.times(-1)).normalized();
+    }
+    extend(distance, direction) {
+        return this.plus(direction.normalized().times(distance));
+    }
+    lerp(target, fractionTo) {
+        return this.times(1 - fractionTo).plus(target.times(fractionTo));
+    }
+    zip(other, zip) {
+        return Vec3.of(zip(other.x, this.x), zip(other.y, this.y), zip(other.z, 0));
+    }
+    map(fn) {
+        return Vec3.of(fn(this.x, 0), fn(this.y, 1), fn(0, 2));
+    }
+    asArray() {
+        return [this.x, this.y, 0];
+    }
+    eq(other, fuzz = defaultEqlTolerance) {
+        return (Math.abs(other.x - this.x) <= fuzz
+            && Math.abs(other.y - this.y) <= fuzz
+            && Math.abs(other.z) <= fuzz);
+    }
+    toString() {
+        return `Vec(${this.x}, ${this.y})`;
+    }
+}
+/**
+ * A `Vec2` is a `Vec3` optimized for working in a plane. As such, they have an
+ * always-zero `z` component.
+ *
+ * ```ts,runnable,console
+ * import { Vec2 } from '@js-draw/math';
+ * console.log(Vec2.of(1, 2));
+ * ```
+ */
+var Vec2;
+(function (Vec2) {
+    /**
+     * Creates a `Vec2` from an x and y coordinate.
+     *
+     * @example
+     * ```ts,runnable,console
+     * import { Vec2 } from '@js-draw/math';
+     * const v = Vec2.of(3, 4); // x=3, y=4.
+     * ```
+     */
+    Vec2.of = (x, y) => {
+        return new Vec2Impl(x, y);
+    };
+    /**
+     * Creates a `Vec2` from an object containing `x` and `y` coordinates.
+     *
+     * @example
+     * ```ts,runnable,console
+     * import { Vec2 } from '@js-draw/math';
+     * const v1 = Vec2.ofXY({ x: 3, y: 4.5 });
+     * const v2 = Vec2.ofXY({ x: -123.4, y: 1 });
+     * ```
+     */
+    Vec2.ofXY = ({ x, y }) => {
+        return Vec2.of(x, y);
+    };
+    /** A vector of length 1 in the X direction (→). */
+    Vec2.unitX = Vec2.of(1, 0);
+    /** A vector of length 1 in the Y direction (↑). */
+    Vec2.unitY = Vec2.of(0, 1);
+    /** The zero vector: A vector with x=0, y=0. */
+    Vec2.zero = Vec2.of(0, 0);
+})(Vec2 || (exports.Vec2 = Vec2 = {}));
+var Vec3;
+(function (Vec3) {
+    /**
+     * Construct a vector from three components.
+     *
+     * @example
+     * ```ts,runnable,console
+     * import { Vec3 } from '@js-draw/math';
+     * const v1 = Vec3.of(1, 2, 3);
+     * ```
+     */
+    Vec3.of = (x, y, z) => {
+        if (z === 0) {
+            return Vec2.of(x, y);
+        }
+        else {
+            return new Vec3Impl(x, y, z);
+        }
+    };
+    Vec3.unitX = Vec2.unitX;
+    Vec3.unitY = Vec2.unitY;
+    Vec3.zero = Vec2.zero;
+    /** A vector of length 1 in the z direction. */
+    Vec3.unitZ = Vec3.of(0, 0, 1);
+})(Vec3 || (exports.Vec3 = Vec3 = {}));
 exports.default = Vec3;

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

@@ -7,7 +7,18 @@ interface IntersectionResult {
     point: Point2;
     t: number;
 }
-/** Represents a line segment. A `LineSegment2` is immutable. */
+/**
+ * Represents a line segment. A `LineSegment2` is immutable.
+ *
+ * @example
+ * ```ts,runnable,console
+ * import {LineSegment2, Vec2} from '@js-draw/math';
+ * const l = new LineSegment2(Vec2.of(1, 1), Vec2.of(2, 2));
+ * console.log('length: ', l.length);
+ * console.log('direction: ', l.direction);
+ * console.log('bounding box: ', l.bbox);
+ * ```
+ */
 export declare class LineSegment2 extends Parameterized2DShape {
     private readonly point1;
     private readonly point2;
@@ -30,7 +41,7 @@ export declare class LineSegment2 extends Parameterized2DShape {
      * if no such line segment exists.
      *
      * @example
-     * ```ts,runnable
+     * ```ts,runnable,console
      * import {LineSegment2, Vec2} from '@js-draw/math';
      * console.log(LineSegment2.ofSmallestContainingPoints([Vec2.of(1, 0), Vec2.of(0, 1)]));
      * ```

package/dist/cjs/shapes/LineSegment2.js

@@ -7,7 +7,18 @@ exports.LineSegment2 = void 0;
 const Rect2_1 = __importDefault(require("./Rect2"));
 const Vec2_1 = require("../Vec2");
 const Parameterized2DShape_1 = __importDefault(require("./Parameterized2DShape"));
-/** Represents a line segment. A `LineSegment2` is immutable. */
+/**
+ * Represents a line segment. A `LineSegment2` is immutable.
+ *
+ * @example
+ * ```ts,runnable,console
+ * import {LineSegment2, Vec2} from '@js-draw/math';
+ * const l = new LineSegment2(Vec2.of(1, 1), Vec2.of(2, 2));
+ * console.log('length: ', l.length);
+ * console.log('direction: ', l.direction);
+ * console.log('bounding box: ', l.bbox);
+ * ```
+ */
 class LineSegment2 extends Parameterized2DShape_1.default {
     /** Creates a new `LineSegment2` from its endpoints. */
     constructor(point1, point2) {
@@ -27,7 +38,7 @@ class LineSegment2 extends Parameterized2DShape_1.default {
      * if no such line segment exists.
      *
      * @example
-     * ```ts,runnable
+     * ```ts,runnable,console
      * import {LineSegment2, Vec2} from '@js-draw/math';
      * console.log(LineSegment2.ofSmallestContainingPoints([Vec2.of(1, 0), Vec2.of(0, 1)]));
      * ```

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

@@ -18,7 +18,39 @@ declare class PointShape2D extends Parameterized2DShape {
     /**
      * Returns an arbitrary unit-length vector.
      */
-    normalAt(_t: number): Vec3;
+    normalAt(_t: number): {
+        readonly x: number;
+        readonly y: number;
+        readonly z: number;
+        readonly xy: {
+            x: number;
+            y: number;
+        };
+        at(idx: number): number;
+        length(): number;
+        magnitude(): number;
+        magnitudeSquared(): number;
+        squareDistanceTo(p: Vec3): number;
+        distanceTo(p: Vec3): number;
+        maximumEntryMagnitude(): number;
+        angle(): number;
+        normalized(): Vec3;
+        normalizedOrZero(): Vec3;
+        times(c: number): Vec3;
+        plus(v: Vec3): Vec3;
+        minus(v: Vec3): Vec3;
+        dot(other: Vec3): number;
+        cross(other: Vec3): Vec3;
+        scale(other: Vec3 | number): Vec3;
+        orthog(): Vec3;
+        extend(distance: number, direction: Vec3): Vec3;
+        lerp(target: Vec3, fractionTo: number): Vec3;
+        zip(other: Vec3, zip: (componentInThis: number, componentInOther: number) => number): Vec3;
+        map(fn: (component: number, index: number) => number): Vec3;
+        asArray(): [number, number, number];
+        eq(other: Vec3, fuzz?: number): boolean;
+        toString(): string;
+    };
     tangentAt(_t: number): Vec3;
     splitAt(_t: number): [PointShape2D];
     nearestPointTo(_point: Point2): {

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

@@ -57,14 +57,46 @@ export declare class Rect2 extends Abstract2DShape {
     get bottomLeft(): Vec3;
     get width(): number;
     get height(): number;
-    get center(): Vec3;
+    get center(): {
+        readonly x: number;
+        readonly y: number;
+        readonly z: number;
+        readonly xy: {
+            x: number;
+            y: number;
+        };
+        at(idx: number): number;
+        length(): number;
+        magnitude(): number;
+        magnitudeSquared(): number;
+        squareDistanceTo(p: Vec3): number;
+        distanceTo(p: Vec3): number;
+        maximumEntryMagnitude(): number;
+        angle(): number;
+        normalized(): Vec3;
+        normalizedOrZero(): Vec3;
+        times(c: number): Vec3;
+        plus(v: Vec3): Vec3;
+        minus(v: Vec3): Vec3;
+        dot(other: Vec3): number;
+        cross(other: Vec3): Vec3;
+        scale(other: Vec3 | number): Vec3;
+        orthog(): Vec3;
+        extend(distance: number, direction: Vec3): Vec3;
+        lerp(target: Vec3, fractionTo: number): Vec3;
+        zip(other: Vec3, zip: (componentInThis: number, componentInOther: number) => number): Vec3;
+        map(fn: (component: number, index: number) => number): Vec3;
+        asArray(): [number, number, number];
+        eq(other: Vec3, fuzz?: number): boolean;
+        toString(): string;
+    };
     getEdges(): LineSegment2[];
     intersectsLineSegment(lineSegment: LineSegment2): Point2[];
     signedDistance(point: Vec3): number;
     getTightBoundingBox(): Rect2;
     transformedBoundingBox(affineTransform: Mat33): Rect2;
-    /** @return true iff this is equal to [other] ± fuzz */
-    eq(other: Rect2, fuzz?: number): boolean;
+    /** @return true iff this is equal to `other ± tolerance` */
+    eq(other: Rect2, tolerance?: number): boolean;
     toString(): string;
     static fromCorners(corner1: Point2, corner2: Point2): Rect2;
     static bboxOf(points: Point2[], margin?: number): Rect2;

package/dist/cjs/shapes/Rect2.js

@@ -227,9 +227,9 @@ class Rect2 extends Abstract2DShape_1.default {
     transformedBoundingBox(affineTransform) {
         return Rect2.bboxOf(this.corners.map(corner => affineTransform.transformVec2(corner)));
     }
-    /** @return true iff this is equal to [other] ± fuzz */
-    eq(other, fuzz = 0) {
-        return this.topLeft.eq(other.topLeft, fuzz) && this.size.eq(other.size, fuzz);
+    /** @return true iff this is equal to `other ± tolerance` */
+    eq(other, tolerance = 0) {
+        return this.topLeft.eq(other.topLeft, tolerance) && this.size.eq(other.size, tolerance);
     }
     toString() {
         return `Rect(point(${this.x}, ${this.y}), size(${this.w}, ${this.h}))`;