@js-draw/math 1.18.0 → 1.19.0

package/dist/mjs/Vec3.mjs

@@ -1,29 +1,10 @@
-/**
- * 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());
- * ```
- */
-export class Vec3 {
+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 {
@@ -31,10 +12,6 @@ export 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)
@@ -45,89 +22,40 @@ export 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);
     }
@@ -146,25 +74,12 @@ export 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) {
@@ -172,62 +87,22 @@ export 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);
@@ -236,8 +111,182 @@ export class Vec3 {
         return `Vec(${this.x}, ${this.y}, ${this.z})`;
     }
 }
-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));
+ * ```
+ */
+export 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 || (Vec2 = {}));
+export 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 || (Vec3 = {}));
 export default Vec3;

package/dist/mjs/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: number | Vec3): 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/mjs/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: number | Vec3): 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/mjs/shapes/Rect2.mjs

@@ -221,9 +221,9 @@ export class Rect2 extends Abstract2DShape {
     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}))`;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@js-draw/math",
-	"version": "1.18.0",
+	"version": "1.19.0",
 	"description": "A math library for js-draw. ",
 	"types": "./dist/mjs/lib.d.ts",
 	"main": "./dist/cjs/lib.js",
@@ -28,7 +28,7 @@
 		"bezier-js": "6.1.3"
 	},
 	"devDependencies": {
-		"@js-draw/build-tool": "^1.17.0",
+		"@js-draw/build-tool": "^1.19.0",
 		"@types/bezier-js": "4.1.0",
 		"@types/jest": "29.5.5",
 		"@types/jsdom": "21.1.3"
@@ -45,5 +45,5 @@
 		"svg",
 		"math"
 	],
-	"gitHead": "73c0d802a8439b5d408ba1e60f91be029db7e402"
+	"gitHead": "50fa44a2bb68b93d24efea433760a5e45c56293f"
 }

package/src/Vec2.test.ts

@@ -8,10 +8,12 @@ describe('Vec2', () => {
 
 	it('Addition', () => {
 		expect(Vec2.of(1, 2).plus(Vec2.of(3, 4))).objEq(Vec2.of(4, 6));
+		expect(Vec2.of(1, 2).plus(Vec3.of(3, 4, 1))).objEq(Vec3.of(4, 6, 1));
 	});
 
 	it('Multiplication', () => {
 		expect(Vec2.of(1, -1).times(22)).objEq(Vec2.of(22, -22));
+		expect(Vec2.of(1, -1).scale(Vec3.of(-1, 2, 3))).objEq(Vec2.of(-1, -2));
 	});
 
 	it('More complicated expressions', () => {
@@ -23,8 +25,8 @@ describe('Vec2', () => {
 	});
 
 	it('Perpindicular', () => {
-		const fuzz = 0.001;
-		expect(Vec2.unitX.cross(Vec3.unitZ)).objEq(Vec2.unitY.times(-1), fuzz);
-		expect(Vec2.unitX.orthog()).objEq(Vec2.unitY, fuzz);
+		const tolerance = 0.001;
+		expect(Vec2.unitX.cross(Vec3.unitZ)).objEq(Vec2.unitY.times(-1), tolerance);
+		expect(Vec2.unitX.orthog()).objEq(Vec2.unitY, tolerance);
 	});
 });

package/src/Vec2.ts

@@ -1,49 +1,9 @@
-import Vec3 from './Vec3';
-
-/**
- * Utility functions that facilitate treating `Vec3`s as 2D vectors.
- *
- * @example
- * ```ts,runnable,console
- * import { Vec2 } from '@js-draw/math';
- * console.log(Vec2.of(1, 2));
- * ```
- */
-export namespace Vec2 {
-	/**
-	 * Creates a `Vec2` from an x and y coordinate.
-	 *
-	 * For example,
-	 * ```ts
-	 * const v = Vec2.of(3, 4); // x=3, y=4.
-	 * ```
-	 */
-	export const of = (x: number, y: number): Vec2 => {
-		return Vec3.of(x, y, 0);
-	};
-
-	/**
-	 * Creates a `Vec2` from an object containing x and y coordinates.
-	 *
-	 * For example,
-	 * ```ts
-	 * const v1 = Vec2.ofXY({ x: 3, y: 4.5 });
-	 * const v2 = Vec2.ofXY({ x: -123.4, y: 1 });
-	 * ```
-	 */
-	export const ofXY = ({x, y}: { x: number, y: number }): Vec2 => {
-		return Vec3.of(x, y, 0);
-	};
-
-	/** A vector of length 1 in the X direction (→). */
-	export const unitX = Vec2.of(1, 0);
-
-	/** A vector of length 1 in the Y direction (↑). */
-	export const unitY = Vec2.of(0, 1);
-
-	/** The zero vector: A vector with x=0, y=0. */
-	export const zero = Vec2.of(0, 0);
-}
+// Internally, we define Vec2 as a namespace within Vec3 --
+// this allows referencing Vec2s from Vec3 constructors without
+// cyclic references.
+import { Vec3, Vec2 } from './Vec3';
 
 export type Point2 = Vec3;
-export type Vec2 = Vec3; // eslint-disable-line
+export type Vec2 = Vec3;
+export { Vec3, Vec2 };
+export default Vec2;