@js-draw/math 1.18.0 → 1.21.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 Henry Heino
+Copyright (c) 2023-2024 Henry Heino
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/dist/cjs/Mat33.d.ts

@@ -1,5 +1,8 @@
 import { Point2, Vec2 } from './Vec2';
 import Vec3 from './Vec3';
+/**
+ * See {@link Mat33.toArray}.
+ */
 export type Mat33Array = [
     number,
     number,
@@ -15,6 +18,46 @@ export type Mat33Array = [
  * Represents a three dimensional linear transformation or
  * a two-dimensional affine transformation. (An affine transformation scales/rotates/shears
  * **and** translates while a linear transformation just scales/rotates/shears).
+ *
+ * In addition to other matrices, {@link Mat33}s can be used to transform {@link Vec3}s and {@link Vec2}s.
+ *
+ * For example, to move the point $(1, 1)$ by 5 units to the left and 6 units up,
+ * ```ts,runnable,console
+ * import {Mat33, Vec2} from '@js-draw/math';
+ *
+ * const moveLeftAndUp = Mat33.translation(Vec2.of(5, 6));
+ * console.log(moveLeftAndUp);
+ * ```
+ *
+ * This `moveLeftAndUp` matrix could then translate (move) a {@link Vec2} using
+ * {@link Mat33.transformVec2}:
+ *
+ * ```ts,runnable,console
+ * ---use-previous---
+ * ---visible---
+ * console.log(moveLeftAndUp.transformVec2(Vec2.of(1, 1)));
+ * console.log(moveLeftAndUp.transformVec2(Vec2.of(-1, 2)));
+ * ```
+ *
+ * It's also possible to create transformation matrices that scale and rotate.
+ * A single transform matrix can be created from multiple using matrix multiplication
+ * (see {@link Mat33.rightMul}):
+ *
+ * ```ts,runnable,console
+ * ---use-previous---
+ * ---visible---
+ * // Create a matrix by right multiplying.
+ * const scaleThenRotate =
+ *   // The resultant matrix first scales by a factor of two
+ *   Mat33.scaling2D(2).rightMul(
+ *     // ...then rotates by pi/2 radians = 90 degrees.
+ *     Mat33.zRotation(Math.PI / 2)
+ *   );
+ * console.log(scaleThenRotate);
+ *
+ * // Use scaleThenRotate to scale then rotate a vector.
+ * console.log(scaleThenRotate.transformVec2(Vec2.unitX));
+ * ```
  */
 export declare class Mat33 {
     readonly a1: number;
@@ -36,6 +79,9 @@ export declare class Mat33 {
      *   c1 & c2 & c3
      * \end{bmatrix}
      * $$
+     *
+     * Static constructor methods are also available.
+     * See {@link Mat33.scaling2D}, {@link Mat33.zRotation}, {@link Mat33.translation}, and {@link Mat33.fromCSSMatrix}.
      */
     constructor(a1: number, a2: number, a3: number, b1: number, b2: number, b3: number, c1: number, c2: number, c3: number);
     /**
@@ -49,6 +95,7 @@ export declare class Mat33 {
      * $$
      */
     static ofRows(r1: Vec3, r2: Vec3, r3: Vec3): Mat33;
+    /** The 3x3 [identity matrix](https://en.wikipedia.org/wiki/Identity_matrix). */
     static identity: Mat33;
     /**
      * Either returns the inverse of this, or, if this matrix is singular/uninvertable,
@@ -62,6 +109,29 @@ export declare class Mat33 {
     private cachedInverse;
     private computeInverse;
     transposed(): Mat33;
+    /**
+     * [Right-multiplies](https://en.wikipedia.org/wiki/Matrix_multiplication) this by `other`.
+     *
+     * See also {@link transformVec3} and {@link transformVec2}.
+     *
+     * Example:
+     * ```ts,runnable,console
+     * import {Mat33, Vec2} from '@js-draw/math';
+     * console.log(Mat33.identity.rightMul(Mat33.identity));
+     *
+     * // Create a matrix by right multiplying.
+     * const scaleThenRotate =
+     *   // The resultant matrix first scales by a factor of two
+     *   Mat33.scaling2D(2).rightMul(
+     *     // ...then rotates by pi/4 radians = 45 degrees.
+     *     Mat33.zRotation(Math.PI / 4)
+     *   );
+     * console.log(scaleThenRotate);
+     *
+     * // Use scaleThenRotate to scale then rotate a vector.
+     * console.log(scaleThenRotate.transformVec2(Vec2.unitX));
+     * ```
+     */
     rightMul(other: Mat33): Mat33;
     /**
      * Applies this as an **affine** transformation to the given vector.
@@ -79,6 +149,15 @@ export declare class Mat33 {
     isIdentity(): boolean;
     /** Returns true iff this = other ± fuzz */
     eq(other: Mat33, fuzz?: number): boolean;
+    /**
+     * Creates a human-readable representation of the matrix.
+     *
+     * Example:
+     * ```ts,runnable,console
+     * import { Mat33 } from '@js-draw/math';
+     * console.log(Mat33.identity.toString());
+     * ```
+     */
     toString(): string;
     /**
      * ```
@@ -86,6 +165,18 @@ export declare class Mat33 {
      * result[1] = element at row zero, column 1
      * ...
      * ```
+     *
+     * Example:
+     * ```ts,runnable,console
+     * import { Mat33 } from '@js-draw/math';
+     * console.log(
+     *   new Mat33(
+     *     1, 2, 3,
+     *     4, 5, 6,
+     *     7, 8, 9,
+     *   )
+     * );
+     * ```
      */
     toArray(): Mat33Array;
     /**

package/dist/cjs/Mat33.js

@@ -10,6 +10,46 @@ const Vec3_1 = __importDefault(require("./Vec3"));
  * Represents a three dimensional linear transformation or
  * a two-dimensional affine transformation. (An affine transformation scales/rotates/shears
  * **and** translates while a linear transformation just scales/rotates/shears).
+ *
+ * In addition to other matrices, {@link Mat33}s can be used to transform {@link Vec3}s and {@link Vec2}s.
+ *
+ * For example, to move the point $(1, 1)$ by 5 units to the left and 6 units up,
+ * ```ts,runnable,console
+ * import {Mat33, Vec2} from '@js-draw/math';
+ *
+ * const moveLeftAndUp = Mat33.translation(Vec2.of(5, 6));
+ * console.log(moveLeftAndUp);
+ * ```
+ *
+ * This `moveLeftAndUp` matrix could then translate (move) a {@link Vec2} using
+ * {@link Mat33.transformVec2}:
+ *
+ * ```ts,runnable,console
+ * ---use-previous---
+ * ---visible---
+ * console.log(moveLeftAndUp.transformVec2(Vec2.of(1, 1)));
+ * console.log(moveLeftAndUp.transformVec2(Vec2.of(-1, 2)));
+ * ```
+ *
+ * It's also possible to create transformation matrices that scale and rotate.
+ * A single transform matrix can be created from multiple using matrix multiplication
+ * (see {@link Mat33.rightMul}):
+ *
+ * ```ts,runnable,console
+ * ---use-previous---
+ * ---visible---
+ * // Create a matrix by right multiplying.
+ * const scaleThenRotate =
+ *   // The resultant matrix first scales by a factor of two
+ *   Mat33.scaling2D(2).rightMul(
+ *     // ...then rotates by pi/2 radians = 90 degrees.
+ *     Mat33.zRotation(Math.PI / 2)
+ *   );
+ * console.log(scaleThenRotate);
+ *
+ * // Use scaleThenRotate to scale then rotate a vector.
+ * console.log(scaleThenRotate.transformVec2(Vec2.unitX));
+ * ```
  */
 class Mat33 {
     /**
@@ -21,6 +61,9 @@ class Mat33 {
      *   c1 & c2 & c3
      * \end{bmatrix}
      * $$
+     *
+     * Static constructor methods are also available.
+     * See {@link Mat33.scaling2D}, {@link Mat33.zRotation}, {@link Mat33.translation}, and {@link Mat33.fromCSSMatrix}.
      */
     constructor(a1, a2, a3, b1, b2, b3, c1, c2, c3) {
         this.a1 = a1;
@@ -131,6 +174,29 @@ class Mat33 {
     transposed() {
         return new Mat33(this.a1, this.b1, this.c1, this.a2, this.b2, this.c2, this.a3, this.b3, this.c3);
     }
+    /**
+     * [Right-multiplies](https://en.wikipedia.org/wiki/Matrix_multiplication) this by `other`.
+     *
+     * See also {@link transformVec3} and {@link transformVec2}.
+     *
+     * Example:
+     * ```ts,runnable,console
+     * import {Mat33, Vec2} from '@js-draw/math';
+     * console.log(Mat33.identity.rightMul(Mat33.identity));
+     *
+     * // Create a matrix by right multiplying.
+     * const scaleThenRotate =
+     *   // The resultant matrix first scales by a factor of two
+     *   Mat33.scaling2D(2).rightMul(
+     *     // ...then rotates by pi/4 radians = 45 degrees.
+     *     Mat33.zRotation(Math.PI / 4)
+     *   );
+     * console.log(scaleThenRotate);
+     *
+     * // Use scaleThenRotate to scale then rotate a vector.
+     * console.log(scaleThenRotate.transformVec2(Vec2.unitX));
+     * ```
+     */
     rightMul(other) {
         other = other.transposed();
         const at = (row, col) => {
@@ -180,6 +246,15 @@ class Mat33 {
         }
         return true;
     }
+    /**
+     * Creates a human-readable representation of the matrix.
+     *
+     * Example:
+     * ```ts,runnable,console
+     * import { Mat33 } from '@js-draw/math';
+     * console.log(Mat33.identity.toString());
+     * ```
+     */
     toString() {
         let result = '';
         const maxColumnLens = [0, 0, 0];
@@ -228,6 +303,18 @@ class Mat33 {
      * result[1] = element at row zero, column 1
      * ...
      * ```
+     *
+     * Example:
+     * ```ts,runnable,console
+     * import { Mat33 } from '@js-draw/math';
+     * console.log(
+     *   new Mat33(
+     *     1, 2, 3,
+     *     4, 5, 6,
+     *     7, 8, 9,
+     *   )
+     * );
+     * ```
      */
     toArray() {
         return [
@@ -436,5 +523,6 @@ class Mat33 {
     }
 }
 exports.Mat33 = Mat33;
+/** The 3x3 [identity matrix](https://en.wikipedia.org/wiki/Identity_matrix). */
 Mat33.identity = new Mat33(1, 0, 0, 0, 1, 0, 0, 0, 1);
 exports.default = Mat33;

package/dist/cjs/Vec2.d.ts

@@ -1,42 +1,5 @@
-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 declare namespace Vec2 {
-    /**
-     * Creates a `Vec2` from an x and y coordinate.
-     *
-     * For example,
-     * ```ts
-     * const v = Vec2.of(3, 4); // x=3, y=4.
-     * ```
-     */
-    const of: (x: number, y: number) => Vec2;
-    /**
-     * 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 });
-     * ```
-     */
-    const ofXY: ({ x, y }: {
-        x: number;
-        y: number;
-    }) => Vec2;
-    /** A vector of length 1 in the X direction (→). */
-    const unitX: Vec3;
-    /** A vector of length 1 in the Y direction (↑). */
-    const unitY: Vec3;
-    /** The zero vector: A vector with x=0, y=0. */
-    const zero: Vec3;
-}
+import { Vec3, Vec2 } from './Vec3';
 export type Point2 = Vec3;
 export type Vec2 = Vec3;
+export { Vec3, Vec2 };
+export default Vec2;

package/dist/cjs/Vec2.js

@@ -1,48 +1,10 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Vec2 = void 0;
-const Vec3_1 = __importDefault(require("./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));
- * ```
- */
-var Vec2;
-(function (Vec2) {
-    /**
-     * Creates a `Vec2` from an x and y coordinate.
-     *
-     * For example,
-     * ```ts
-     * const v = Vec2.of(3, 4); // x=3, y=4.
-     * ```
-     */
-    Vec2.of = (x, y) => {
-        return Vec3_1.default.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 });
-     * ```
-     */
-    Vec2.ofXY = ({ x, y }) => {
-        return Vec3_1.default.of(x, y, 0);
-    };
-    /** 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 = {}));
+exports.Vec2 = exports.Vec3 = void 0;
+// Internally, we define Vec2 as a namespace within Vec3 --
+// this allows referencing Vec2s from Vec3 constructors without
+// cyclic references.
+const Vec3_1 = require("./Vec3");
+Object.defineProperty(exports, "Vec3", { enumerable: true, get: function () { return Vec3_1.Vec3; } });
+Object.defineProperty(exports, "Vec2", { enumerable: true, get: function () { return Vec3_1.Vec2; } });
+exports.default = Vec3_1.Vec2;

package/dist/cjs/Vec3.d.ts

@@ -17,22 +17,23 @@
  * console.log('As an array:', Vec3.unitZ.asArray());
  * ```
  */
-export declare class Vec3 {
+export interface Vec3 {
     readonly x: number;
     readonly y: number;
     readonly z: number;
-    private constructor();
-    /** Returns the x, y components of this. */
-    get xy(): {
+    /**
+     * Returns the x, y components of this.
+     * May be implemented as a getter method.
+     */
+    readonly xy: {
         x: number;
         y: number;
     };
-    /** Construct a vector from three components. */
-    static of(x: number, y: number, z: number): Vec3;
-    /** Returns this' `idx`th component. For example, `Vec3.of(1, 2, 3).at(1) → 2`. */
-    at(idx: number): number;
-    /** Alias for this.magnitude. */
+    /** Returns the vector's `idx`th component. For example, `Vec3.of(1, 2, 3).at(1) → 2`. */
+    at(i: number): number;
+    /** Alias for `.magnitude`. */
     length(): number;
+    /** Returns the length of this vector in ℝ^3. */
     magnitude(): number;
     magnitudeSquared(): number;
     /**
@@ -41,7 +42,7 @@ export declare class Vec3 {
      *
      * Equivalent to `.minus(p).magnitudeSquared()`.
      */
-    squareDistanceTo(p: Vec3): number;
+    squareDistanceTo(other: Vec3): number;
     /**
      * Interpreting this vector as a point in ℝ³, returns the distance to the point
      * `p`.
@@ -90,10 +91,17 @@ export declare class Vec3 {
     normalizedOrZero(): Vec3;
     /** @returns A copy of `this` multiplied by a scalar. */
     times(c: number): Vec3;
+    /** Performs vector addition. */
     plus(v: Vec3): Vec3;
     minus(v: Vec3): Vec3;
-    dot(other: Vec3): number;
-    cross(other: Vec3): Vec3;
+    /**
+     * Computes the scalar product between this and `v`.
+     *
+     * In particular, `a.dot(b)` is equivalent to `a.x * b.x + a.y * b.y + a.z * b.z`.
+     */
+    dot(v: Vec3): number;
+    /** Computes the cross product between this and `v` */
+    cross(v: Vec3): Vec3;
     /**
      * If `other` is a `Vec3`, multiplies `this` component-wise by `other`. Otherwise,
      * if `other is a `number`, returns the result of scalar multiplication.
@@ -154,11 +162,99 @@ export declare class Vec3 {
      * Vec3.of(1, 2, 3).eq(Vec3.of(4, 5, 6), 2.99); // → false
      * ```
      */
+    eq(other: Vec3, tolerance?: number): boolean;
+    toString(): string;
+}
+declare class Vec2Impl implements Vec3 {
+    readonly x: number;
+    readonly y: number;
+    constructor(x: number, y: number);
+    get z(): number;
+    get 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;
-    static unitX: Vec3;
-    static unitY: Vec3;
-    static unitZ: Vec3;
-    static zero: Vec3;
+}
+/**
+ * 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 declare namespace 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.
+     * ```
+     */
+    const of: (x: number, y: number) => Vec2Impl;
+    /**
+     * 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 });
+     * ```
+     */
+    const ofXY: ({ x, y }: {
+        x: number;
+        y: number;
+    }) => Vec2Impl;
+    /** A vector of length 1 in the X direction (→). */
+    const unitX: Vec2Impl;
+    /** A vector of length 1 in the Y direction (↑). */
+    const unitY: Vec2Impl;
+    /** The zero vector: A vector with x=0, y=0. */
+    const zero: Vec2Impl;
+}
+export declare namespace Vec3 {
+    /**
+     * Construct a vector from three components.
+     *
+     * @example
+     * ```ts,runnable,console
+     * import { Vec3 } from '@js-draw/math';
+     * const v1 = Vec3.of(1, 2, 3);
+     * ```
+     */
+    const of: (x: number, y: number, z: number) => Vec3;
+    const unitX: Vec2Impl;
+    const unitY: Vec2Impl;
+    const zero: Vec2Impl;
+    /** A vector of length 1 in the z direction. */
+    const unitZ: Vec3;
 }
 export default Vec3;