@js-draw/math 1.21.3 → 1.23.1

package/dist/mjs/Mat33.mjs

@@ -70,11 +70,7 @@ export class Mat33 {
         this.c2 = c2;
         this.c3 = c3;
         this.cachedInverse = undefined;
-        this.rows = [
-            Vec3.of(a1, a2, a3),
-            Vec3.of(b1, b2, b3),
-            Vec3.of(c1, c2, c3),
-        ];
+        this.rows = [Vec3.of(a1, a2, a3), Vec3.of(b1, b2, b3), Vec3.of(c1, c2, c3)];
     }
     /**
      * Creates a matrix from the given rows:
@@ -106,16 +102,8 @@ export class Mat33 {
         if (this.cachedInverse !== undefined) {
             return this.cachedInverse;
         }
-        const toIdentity = [
-            this.rows[0],
-            this.rows[1],
-            this.rows[2],
-        ];
-        const toResult = [
-            Vec3.unitX,
-            Vec3.unitY,
-            Vec3.unitZ,
-        ];
+        const toIdentity = [this.rows[0], this.rows[1], this.rows[2]];
+        const toResult = [Vec3.unitX, Vec3.unitY, Vec3.unitZ];
         // Convert toIdentity to the identity matrix and
         // toResult to the inverse through elementary row operations
         for (let cursor = 0; cursor < 3; cursor++) {
@@ -311,11 +299,7 @@ export class Mat33 {
      * ```
      */
     toArray() {
-        return [
-            this.a1, this.a2, this.a3,
-            this.b1, this.b2, this.b3,
-            this.c1, this.c2, this.c3,
-        ];
+        return [this.a1, this.a2, this.a3, this.b1, this.b2, this.b3, this.c1, this.c2, this.c3];
     }
     /**
      * Returns a new `Mat33` where each entry is the output of the function
@@ -372,6 +356,26 @@ export class Mat33 {
         //   ...
         return new Mat33(1, 0, amount.x, 0, 1, amount.y, 0, 0, 1);
     }
+    /**
+     * Creates a matrix for rotating `Vec2`s about `center` by some number of `radians`.
+     *
+     * For this function, {@link Vec2}s are considered to be points in 2D space.
+     *
+     * For example,
+     * ```ts,runnable,console
+     * import { Mat33, Vec2 } from '@js-draw/math';
+     *
+     * const halfCircle = Math.PI; // PI radians = 180 degrees = 1/2 circle
+     * const center = Vec2.of(1, 1); // The point (1,1)
+     * const rotationMatrix = Mat33.zRotation(halfCircle, center);
+     *
+     * console.log(
+     *   'Rotating (0,0) 180deg about', center, 'results in',
+     *   // Rotates (0,0)
+     *   rotationMatrix.transformVec2(Vec2.zero),
+     * );
+     * ```
+     */
     static zRotation(radians, center = Vec2.zero) {
         if (radians === 0) {
             return Mat33.identity;
@@ -421,7 +425,7 @@ export class Mat33 {
             return Mat33.identity;
         }
         const parseArguments = (argumentString) => {
-            const parsed = argumentString.split(/[, \t\n]+/g).map(argString => {
+            const parsed = argumentString.split(/[, \t\n]+/g).map((argString) => {
                 // Handle trailing spaces/commands
                 if (argString.trim() === '') {
                     return null;
@@ -432,7 +436,7 @@ export class Mat33 {
                     argString = argString.substring(0, argString.length - 1);
                 }
                 // Remove trailing px units.
-                argString = argString.replace(/px$/ig, '');
+                argString = argString.replace(/px$/gi, '');
                 const numberExp = /^[-]?\d*(?:\.\d*)?(?:[eE][-+]?\d+)?$/i;
                 if (!numberExp.exec(argString)) {
                     throw new Error(`All arguments to transform functions must be numeric (state: ${JSON.stringify({
@@ -446,7 +450,7 @@ export class Mat33 {
                 }
                 return argNumber;
             });
-            return parsed.filter(n => n !== null);
+            return parsed.filter((n) => n !== null);
         };
         const keywordToAction = {
             matrix: (matrixData) => {
@@ -496,7 +500,7 @@ export class Mat33 {
         };
         // A command (\w+)
         // followed by a set of arguments ([ \t\n0-9eE.,\-%]+)
-        const partRegex = /\s*(\w+)\s*\(([^)]*)\)/ig;
+        const partRegex = /\s*(\w+)\s*\(([^)]*)\)/gi;
         let match;
         let matrix = null;
         while ((match = partRegex.exec(cssString)) !== null) {

package/dist/mjs/Vec3.d.ts

@@ -150,7 +150,7 @@ export interface Vec3 {
     map(fn: (component: number, index: number) => number): Vec3;
     asArray(): [number, number, number];
     /**
-     * [fuzz] The maximum difference between two components for this and [other]
+     * @param tolerance The maximum difference between two components for this and [other]
      * to be considered equal.
      *
      * @example
@@ -200,12 +200,16 @@ declare class Vec2Impl implements Vec3 {
     toString(): string;
 }
 /**
- * A `Vec2` is a `Vec3` optimized for working in a plane. As such, they have an
+ * A `Vec2` is a {@link Vec3} optimized for working in a plane. `Vec2`s have an
  * always-zero `z` component.
  *
  * ```ts,runnable,console
  * import { Vec2 } from '@js-draw/math';
- * console.log(Vec2.of(1, 2));
+ *
+ * const v = Vec2.of(1, 2);
+ * console.log('a Vec2:', v);
+ * console.log('x component:', v.x);
+ * console.log('z component:', v.z);
  * ```
  */
 export declare namespace Vec2 {
@@ -240,6 +244,7 @@ export declare namespace Vec2 {
     /** The zero vector: A vector with x=0, y=0. */
     const zero: Vec2Impl;
 }
+/** Contains static methods for constructing a {@link Vec3}. */
 export declare namespace Vec3 {
     /**
      * Construct a vector from three components.
@@ -248,11 +253,15 @@ export declare namespace Vec3 {
      * ```ts,runnable,console
      * import { Vec3 } from '@js-draw/math';
      * const v1 = Vec3.of(1, 2, 3);
+     * console.log(v1.plus(Vec3.of(0, 100, 0)));
      * ```
      */
     const of: (x: number, y: number, z: number) => Vec3;
+    /** A unit vector in the x direction (`[1, 0, 0]`). */
     const unitX: Vec2Impl;
+    /** A unit vector in the y direction (`[0, 1, 0]`). */
     const unitY: Vec2Impl;
+    /** The zero vector (`[0, 0, 0]`). */
     const zero: Vec2Impl;
     /** A vector of length 1 in the z direction. */
     const unitZ: Vec3;

package/dist/mjs/Vec3.mjs

@@ -103,9 +103,9 @@ class Vec3Impl {
         return [this.x, this.y, this.z];
     }
     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);
+        return (Math.abs(other.x - this.x) <= fuzz &&
+            Math.abs(other.y - this.y) <= fuzz &&
+            Math.abs(other.z - this.z) <= fuzz);
     }
     toString() {
         return `Vec(${this.x}, ${this.y}, ${this.z})`;
@@ -116,7 +116,9 @@ class Vec2Impl {
         this.x = x;
         this.y = y;
     }
-    get z() { return 0; }
+    get z() {
+        return 0;
+    }
     get xy() {
         // Useful for APIs that behave differently if .z is present.
         return {
@@ -213,21 +215,25 @@ class Vec2Impl {
         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);
+        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
+ * A `Vec2` is a {@link Vec3} optimized for working in a plane. `Vec2`s have an
  * always-zero `z` component.
  *
  * ```ts,runnable,console
  * import { Vec2 } from '@js-draw/math';
- * console.log(Vec2.of(1, 2));
+ *
+ * const v = Vec2.of(1, 2);
+ * console.log('a Vec2:', v);
+ * console.log('x component:', v.x);
+ * console.log('z component:', v.z);
  * ```
  */
 export var Vec2;
@@ -264,6 +270,7 @@ export var Vec2;
     /** The zero vector: A vector with x=0, y=0. */
     Vec2.zero = Vec2.of(0, 0);
 })(Vec2 || (Vec2 = {}));
+/** Contains static methods for constructing a {@link Vec3}. */
 export var Vec3;
 (function (Vec3) {
     /**
@@ -273,6 +280,7 @@ export var Vec3;
      * ```ts,runnable,console
      * import { Vec3 } from '@js-draw/math';
      * const v1 = Vec3.of(1, 2, 3);
+     * console.log(v1.plus(Vec3.of(0, 100, 0)));
      * ```
      */
     Vec3.of = (x, y, z) => {
@@ -283,8 +291,11 @@ export var Vec3;
             return new Vec3Impl(x, y, z);
         }
     };
+    /** A unit vector in the x direction (`[1, 0, 0]`). */
     Vec3.unitX = Vec2.unitX;
+    /** A unit vector in the y direction (`[0, 1, 0]`). */
     Vec3.unitY = Vec2.unitY;
+    /** The zero vector (`[0, 0, 0]`). */
     Vec3.zero = Vec2.zero;
     /** A vector of length 1 in the z direction. */
     Vec3.unitZ = Vec3.of(0, 0, 1);

package/dist/mjs/lib.d.ts

@@ -1,4 +1,7 @@
 /**
+ * This package contains general math utilities used by `js-draw`.
+ * These include 2D and 3D vectors, 2D paths, and 3x3 matrices.
+ *
  * ```ts,runnable,console
  * import { Vec2, Mat33, Rect2 } from '@js-draw/math';
  *

package/dist/mjs/lib.mjs

@@ -1,4 +1,7 @@
 /**
+ * This package contains general math utilities used by `js-draw`.
+ * These include 2D and 3D vectors, 2D paths, and 3x3 matrices.
+ *
  * ```ts,runnable,console
  * import { Vec2, Mat33, Rect2 } from '@js-draw/math';
  *

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

@@ -29,8 +29,10 @@ export declare abstract class BezierJSWrapper extends Parameterized2DShape {
      * @returns the curve evaluated at `t`.
      */
     at(t: number): Point2;
+    /** @returns the curve's directional derivative at `t`. */
     derivativeAt(t: number): Point2;
     secondDerivativeAt(t: number): Point2;
+    /** @returns the [normal vector](https://en.wikipedia.org/wiki/Normal_(geometry)) to this curve at `t`. */
     normal(t: number): Vec2;
     normalAt(t: number): Vec2;
     tangentAt(t: number): Vec2;

package/dist/mjs/shapes/BezierJSWrapper.mjs

@@ -34,7 +34,7 @@ export class BezierJSWrapper extends Parameterized2DShape {
     }
     getBezier() {
         if (!__classPrivateFieldGet(this, _BezierJSWrapper_bezierJs, "f")) {
-            __classPrivateFieldSet(this, _BezierJSWrapper_bezierJs, new Bezier(this.getPoints().map(p => p.xy)), "f");
+            __classPrivateFieldSet(this, _BezierJSWrapper_bezierJs, new Bezier(this.getPoints().map((p) => p.xy)), "f");
         }
         return __classPrivateFieldGet(this, _BezierJSWrapper_bezierJs, "f");
     }
@@ -57,12 +57,14 @@ export class BezierJSWrapper extends Parameterized2DShape {
     at(t) {
         return Vec2.ofXY(this.getBezier().get(t));
     }
+    /** @returns the curve's directional derivative at `t`. */
     derivativeAt(t) {
         return Vec2.ofXY(this.getBezier().derivative(t));
     }
     secondDerivativeAt(t) {
         return Vec2.ofXY(this.getBezier().dderivative(t));
     }
+    /** @returns the [normal vector](https://en.wikipedia.org/wiki/Normal_(geometry)) to this curve at `t`. */
     normal(t) {
         return Vec2.ofXY(this.getBezier().normal(t));
     }
@@ -88,10 +90,12 @@ export class BezierJSWrapper extends Parameterized2DShape {
         const asLine = LineSegment2.ofSmallestContainingPoints(this.getPoints());
         if (asLine) {
             const intersection = asLine.intersectsLineSegment(line);
-            return intersection.map(p => this.nearestPointTo(p).parameterValue);
+            return intersection.map((p) => this.nearestPointTo(p).parameterValue);
         }
         const bezier = this.getBezier();
-        return bezier.intersects(line).map(t => {
+        return bezier
+            .intersects(line)
+            .map((t) => {
             // We're using the .intersects(line) function, which is documented
             // to always return numbers. However, to satisfy the type checker (and
             // possibly improperly-defined types),
@@ -100,12 +104,12 @@ export class BezierJSWrapper extends Parameterized2DShape {
             }
             const point = Vec2.ofXY(this.at(t));
             // Ensure that the intersection is on the line segment
-            if (point.distanceTo(line.p1) > line.length
-                || point.distanceTo(line.p2) > line.length) {
+            if (point.distanceTo(line.p1) > line.length || point.distanceTo(line.p2) > line.length) {
                 return null;
             }
             return t;
-        }).filter(entry => entry !== null);
+        })
+            .filter((entry) => entry !== null);
     }
     splitAt(t) {
         if (t <= 0 || t >= 1) {
@@ -114,8 +118,8 @@ export class BezierJSWrapper extends Parameterized2DShape {
         const bezier = this.getBezier();
         const split = bezier.split(t);
         return [
-            new BezierJSWrapperImpl(split.left.points.map(point => Vec2.ofXY(point)), split.left),
-            new BezierJSWrapperImpl(split.right.points.map(point => Vec2.ofXY(point)), split.right),
+            new BezierJSWrapperImpl(split.left.points.map((point) => Vec2.ofXY(point)), split.left),
+            new BezierJSWrapperImpl(split.right.points.map((point) => Vec2.ofXY(point)), split.right),
         ];
     }
     nearestPointTo(point) {
@@ -159,16 +163,19 @@ export class BezierJSWrapper extends Parameterized2DShape {
             const b = this.at(t);
             const bPrime = this.derivativeAt(t);
             const bPrimePrime = this.secondDerivativeAt(t);
-            return (2 * bPrime.x * bPrime.x + 2 * b.x * bPrimePrime.x - 2 * point.x * bPrimePrime.x
-                + 2 * bPrime.y * bPrime.y + 2 * b.y * bPrimePrime.y - 2 * point.y * bPrimePrime.y);
+            return (2 * bPrime.x * bPrime.x +
+                2 * b.x * bPrimePrime.x -
+                2 * point.x * bPrimePrime.x +
+                2 * bPrime.y * bPrime.y +
+                2 * b.y * bPrimePrime.y -
+                2 * point.y * bPrimePrime.y);
         };
         // Because we're zeroing f'(t), we also need to be able to compute it:
         const derivativeAt = (t) => {
             // f'(t) = 2Bₓ(t)Bₓ'(t) - 2pₓBₓ'(t) + 2Bᵧ(t)Bᵧ'(t) - 2pᵧBᵧ'(t)
             const b = this.at(t);
             const bPrime = this.derivativeAt(t);
-            return (2 * b.x * bPrime.x - 2 * point.x * bPrime.x
-                + 2 * b.y * bPrime.y - 2 * point.y * bPrime.y);
+            return (2 * b.x * bPrime.x - 2 * point.x * bPrime.x + 2 * b.y * bPrime.y - 2 * point.y * bPrime.y);
         };
         const iterate = () => {
             const slope = secondDerivativeAt(t);
@@ -219,7 +226,9 @@ export class BezierJSWrapper extends Parameterized2DShape {
         return result;
     }
     toString() {
-        return `Bézier(${this.getPoints().map(point => point.toString()).join(', ')})`;
+        return `Bézier(${this.getPoints()
+            .map((point) => point.toString())
+            .join(', ')})`;
     }
 }
 _BezierJSWrapper_bezierJs = new WeakMap();

package/dist/mjs/shapes/LineSegment2.mjs

@@ -40,7 +40,7 @@ export class LineSegment2 extends Parameterized2DShape {
     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 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)) {
@@ -90,10 +90,7 @@ export class LineSegment2 extends Parameterized2DShape {
         if (t <= 0 || t >= 1) {
             return [this];
         }
-        return [
-            new LineSegment2(this.point1, this.at(t)),
-            new LineSegment2(this.at(t), this.point2),
-        ];
+        return [new LineSegment2(this.point1, this.at(t)), new LineSegment2(this.at(t), this.point2)];
     }
     /**
      * Returns the intersection of this with another line segment.
@@ -143,18 +140,17 @@ export class LineSegment2 extends Parameterized2DShape {
                 return null;
             }
             const xIntersect = this.point1.x;
-            const yIntersect = (this.point1.x - other.point1.x) * other.direction.y / other.direction.x + other.point1.y;
+            const yIntersect = ((this.point1.x - other.point1.x) * other.direction.y) / other.direction.x + other.point1.y;
             resultPoint = Vec2.of(xIntersect, yIntersect);
             resultT = (yIntersect - this.point1.y) / this.direction.y;
         }
         else {
             // From above,
             // x = ((o₁ᵧ - o₂ᵧ)(d₁ₓd₂ₓ) + (d₂ᵧd₁ₓ)(o₂ₓ) - (d₁ᵧd₂ₓ)(o₁ₓ))/(d₂ᵧd₁ₓ - d₁ᵧd₂ₓ)
-            const numerator = ((this.point1.y - other.point1.y) * this.direction.x * other.direction.x
-                + this.direction.x * other.direction.y * other.point1.x
-                - this.direction.y * other.direction.x * this.point1.x);
-            const denominator = (other.direction.y * this.direction.x
-                - this.direction.y * other.direction.x);
+            const numerator = (this.point1.y - other.point1.y) * this.direction.x * other.direction.x +
+                this.direction.x * other.direction.y * other.point1.x -
+                this.direction.y * other.direction.x * this.point1.x;
+            const denominator = other.direction.y * this.direction.x - this.direction.y * other.direction.x;
             // Avoid dividing by zero. It means there is no intersection
             if (denominator === 0) {
                 return null;
@@ -170,10 +166,10 @@ export class LineSegment2 extends Parameterized2DShape {
         const resultToP2 = resultPoint.distanceTo(this.point2);
         const resultToP3 = resultPoint.distanceTo(other.point1);
         const resultToP4 = resultPoint.distanceTo(other.point2);
-        if (resultToP1 > this.length
-            || resultToP2 > this.length
-            || resultToP3 > other.length
-            || resultToP4 > other.length) {
+        if (resultToP1 > this.length ||
+            resultToP2 > this.length ||
+            resultToP3 > other.length ||
+            resultToP4 > other.length) {
             return null;
         }
         return {
@@ -258,8 +254,8 @@ export class LineSegment2 extends Parameterized2DShape {
         }
         const tolerance = options?.tolerance;
         const ignoreDirection = options?.ignoreDirection ?? true;
-        return ((other.p1.eq(this.p1, tolerance) && other.p2.eq(this.p2, tolerance))
-            || (ignoreDirection && other.p1.eq(this.p2, tolerance) && other.p2.eq(this.p1, tolerance)));
+        return ((other.p1.eq(this.p1, tolerance) && other.p2.eq(this.p2, tolerance)) ||
+            (ignoreDirection && other.p1.eq(this.p2, tolerance) && other.p2.eq(this.p1, tolerance)));
     }
 }
 export default LineSegment2;

package/dist/mjs/shapes/Parameterized2DShape.mjs

@@ -7,7 +7,7 @@ import  Abstract2DShape  from './Abstract2DShape.mjs';
  */
 export class Parameterized2DShape extends Abstract2DShape {
     intersectsLineSegment(line) {
-        return this.argIntersectsLineSegment(line).map(t => this.at(t));
+        return this.argIntersectsLineSegment(line).map((t) => this.at(t));
     }
 }
 export default Parameterized2DShape;

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

@@ -3,6 +3,7 @@ import Mat33 from '../Mat33';
 import Rect2 from './Rect2';
 import { Point2 } from '../Vec2';
 import Parameterized2DShape from './Parameterized2DShape';
+/** Identifiers for different path commands. These commands can make up a {@link Path}. */
 export declare enum PathCommandType {
     LineTo = 0,
     MoveTo = 1,