@js-draw/math 1.18.0 → 1.21.1

package/src/Vec3.ts

@@ -19,49 +19,25 @@
  * console.log('As an array:', Vec3.unitZ.asArray());
  * ```
  */
-export class Vec3 {
-	private constructor(
-		public readonly x: number,
-		public readonly y: number,
-		public readonly z: number
-	) {
-	}
-
-	/** Returns the x, y components of this. */
-	public get xy(): { x: number; y: number } {
-		// Useful for APIs that behave differently if .z is present.
-		return {
-			x: this.x,
-			y: this.y,
-		};
-	}
+export interface Vec3 {
+	readonly x: number;
+	readonly y: number;
+	readonly z: number;
 
-	/** Construct a vector from three components. */
-	public static of(x: number, y: number, z: number): Vec3 {
-		return new Vec3(x, y, z);
-	}
-
-	/** Returns this' `idx`th component. For example, `Vec3.of(1, 2, 3).at(1) → 2`. */
-	public at(idx: number): number {
-		if (idx === 0) return this.x;
-		if (idx === 1) return this.y;
-		if (idx === 2) return this.z;
-
-		throw new Error(`${idx} out of bounds!`);
-	}
-
-	/** Alias for this.magnitude. */
-	public length(): number {
-		return this.magnitude();
-	}
+	/**
+	 * Returns the x, y components of this.
+	 * May be implemented as a getter method.
+	 */
+	readonly xy: { x: number, y: number };
 
-	public magnitude(): number {
-		return Math.sqrt(this.dot(this));
-	}
+	/** Returns the vector's `idx`th component. For example, `Vec3.of(1, 2, 3).at(1) → 2`. */
+	at(i: number): number;
 
-	public magnitudeSquared(): number {
-		return this.dot(this);
-	}
+	/** Alias for `.magnitude`. */
+	length(): number;
+	/** Returns the length of this vector in ℝ^3. */
+	magnitude(): number;
+	magnitudeSquared(): number;
 
 	/**
 	 * Interpreting this vector as a point in ℝ^3, computes the square distance
@@ -69,12 +45,7 @@ export class Vec3 {
 	 *
 	 * Equivalent to `.minus(p).magnitudeSquared()`.
 	 */
-	public squareDistanceTo(p: Vec3) {
-		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;
-	}
+	squareDistanceTo(other: Vec3): number;
 
 	/**
 	 * Interpreting this vector as a point in ℝ³, returns the distance to the point
@@ -82,9 +53,7 @@ export class Vec3 {
 	 *
 	 * Equivalent to `.minus(p).magnitude()`.
 	 */
-	public distanceTo(p: Vec3) {
-		return Math.sqrt(this.squareDistanceTo(p));
-	}
+	distanceTo(p: Vec3): number;
 
 	/**
 	 * Returns the entry of this with the greatest magnitude.
@@ -98,9 +67,7 @@ export class Vec3 {
 	 * console.log(Vec3.of(-1, -10, 8).maximumEntryMagnitude()); // -> 10
 	 * ```
 	 */
-	public maximumEntryMagnitude(): number {
-		return Math.max(Math.abs(this.x), Math.max(Math.abs(this.y), Math.abs(this.z)));
-	}
+	maximumEntryMagnitude(): number;
 
 	/**
 	 * Return this' angle in the XY plane (treats this as a Vec2).
@@ -117,23 +84,175 @@ export class Vec3 {
 	 * console.log(Vec2.of(-1, 0).angle());  // atan2(0, -1)
 	 * ```
 	 */
-	public angle(): number {
-		return Math.atan2(this.y, this.x);
-	}
+	angle(): number;
 
 	/**
 	 * Returns a unit vector in the same direction as this.
 	 *
 	 * If `this` has zero length, the resultant vector has `NaN` components.
 	 */
+	normalized(): Vec3;
+
+	/**
+	 * Like {@link normalized}, except returns zero if this has zero magnitude.
+	 */
+	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;
+
+	/**
+	 * 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.
+	 *
+	 * @example
+	 * ```
+	 * Vec3.of(1, 2, 3).scale(Vec3.of(2, 4, 6)); // → Vec3(2, 8, 18)
+	 * ```
+	 */
+	scale(other: Vec3|number): Vec3;
+
+	/**
+	 * Returns a vector orthogonal to this. If this is a Vec2, returns `this` rotated
+	 * 90 degrees counter-clockwise.
+	 */
+	orthog(): Vec3;
+
+	/** Returns this plus a vector of length `distance` in `direction`. */
+	extend(distance: number, direction: Vec3): Vec3;
+
+	/** Returns a vector `fractionTo` of the way to target from this. */
+	lerp(target: Vec3, fractionTo: number): Vec3;
+
+	/**
+	 * `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: Vec3, zip: (componentInThis: number, componentInOther: number)=> number
+	): Vec3;
+
+	/**
+	 * 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: (component: number, index: number)=> number): Vec3;
+
+	asArray(): [ number, number, number ];
+
+
+	/**
+	 * [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: Vec3, tolerance?: number): boolean;
+
+	toString(): string;
+}
+
+const defaultEqlTolerance = 1e-10;
+
+class Vec3Impl implements Vec3 {
+	public constructor(
+		public readonly x: number,
+		public readonly y: number,
+		public readonly z: number
+	) {
+	}
+
+	public get xy(): { x: number; y: number } {
+		// Useful for APIs that behave differently if .z is present.
+		return {
+			x: this.x,
+			y: this.y,
+		};
+	}
+
+	/** Returns this' `idx`th component. For example, `Vec3.of(1, 2, 3).at(1) → 2`. */
+	public at(idx: number): number {
+		if (idx === 0) return this.x;
+		if (idx === 1) return this.y;
+		if (idx === 2) return this.z;
+
+		throw new Error(`${idx} out of bounds!`);
+	}
+
+	public length(): number {
+		return this.magnitude();
+	}
+
+	public magnitude(): number {
+		return Math.sqrt(this.magnitudeSquared());
+	}
+
+	public magnitudeSquared(): number {
+		return this.x * this.x + this.y * this.y + this.z * this.z;
+	}
+
+	public squareDistanceTo(p: Vec3) {
+		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;
+	}
+
+	public distanceTo(p: Vec3) {
+		return Math.sqrt(this.squareDistanceTo(p));
+	}
+
+	public maximumEntryMagnitude(): number {
+		return Math.max(Math.abs(this.x), Math.max(Math.abs(this.y), Math.abs(this.z)));
+	}
+
+	public angle(): number {
+		return Math.atan2(this.y, this.x);
+	}
+
 	public normalized(): Vec3 {
 		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.
-	 */
 	public normalizedOrZero(): Vec3 {
 		if (this.eq(Vec3.zero)) {
 			return Vec3.zero;
@@ -142,7 +261,6 @@ export class Vec3 {
 		return this.normalized();
 	}
 
-	/** @returns A copy of `this` multiplied by a scalar. */
 	public times(c: number): Vec3 {
 		return Vec3.of(this.x * c, this.y * c, this.z * c);
 	}
@@ -166,19 +284,10 @@ export class Vec3 {
 		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
+			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)
-	 * ```
-	 */
 	public scale(other: Vec3|number): Vec3 {
 		if (typeof other === 'number') {
 			return this.times(other);
@@ -191,10 +300,6 @@ export class Vec3 {
 		);
 	}
 
-	/**
-	 * Returns a vector orthogonal to this. If this is a Vec2, returns `this` rotated
-	 * 90 degrees counter-clockwise.
-	 */
 	public orthog(): Vec3 {
 		// If parallel to the z-axis
 		if (this.dot(Vec3.unitX) === 0 && this.dot(Vec3.unitY) === 0) {
@@ -204,32 +309,14 @@ export class Vec3 {
 		return this.cross(Vec3.unitZ.times(-1)).normalized();
 	}
 
-	/** Returns this plus a vector of length `distance` in `direction`. */
 	public extend(distance: number, direction: Vec3): Vec3 {
 		return this.plus(direction.normalized().times(distance));
 	}
 
-	/** Returns a vector `fractionTo` of the way to target from this. */
 	public lerp(target: Vec3, fractionTo: number): Vec3 {
 		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)
-	 * ```
-	 */
 	public zip(
 		other: Vec3, zip: (componentInThis: number, componentInOther: number)=> number
 	): Vec3 {
@@ -240,39 +327,15 @@ export class Vec3 {
 		);
 	}
 
-	/**
-	 * 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)
-	 * ```
-	 */
 	public map(fn: (component: number, index: number)=> number): Vec3 {
-		return Vec3.of(
-			fn(this.x, 0), fn(this.y, 1), fn(this.z, 2)
-		);
+		return Vec3.of(fn(this.x, 0), fn(this.y, 1), fn(this.z, 2));
 	}
 
 	public asArray(): [ number, number, number ] {
 		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
-	 * ```
-	 */
-	public eq(other: Vec3, fuzz: number = 1e-10): boolean {
+	public eq(other: Vec3, fuzz: number = defaultEqlTolerance): boolean {
 		return (
 			Math.abs(other.x - this.x) <= fuzz
 			&& Math.abs(other.y - this.y) <= fuzz
@@ -283,11 +346,235 @@ export class Vec3 {
 	public toString(): string {
 		return `Vec(${this.x}, ${this.y}, ${this.z})`;
 	}
+}
+
+class Vec2Impl implements Vec3 {
+	public constructor(
+		public readonly x: number,
+		public readonly y: number,
+	) {
+	}
+
+	public get z() { return 0; }
+
+	public get xy(): { x: number; y: number } {
+		// Useful for APIs that behave differently if .z is present.
+		return {
+			x: this.x,
+			y: this.y,
+		};
+	}
+
+	public at(idx: number): number {
+		if (idx === 0) return this.x;
+		if (idx === 1) return this.y;
+		if (idx === 2) return 0;
+
+		throw new Error(`${idx} out of bounds!`);
+	}
+
+	public length(): number {
+		return this.magnitude();
+	}
+
+	public magnitude(): number {
+		return Math.sqrt(this.x * this.x + this.y * this.y);
+	}
+
+	public magnitudeSquared(): number {
+		return this.x * this.x + this.y * this.y;
+	}
+
+	public squareDistanceTo(p: Vec3) {
+		const dx = this.x - p.x;
+		const dy = this.y - p.y;
+		return dx * dx + dy * dy + p.z * p.z;
+	}
 
+	public distanceTo(p: Vec3) {
+		return Math.sqrt(this.squareDistanceTo(p));
+	}
+
+	public maximumEntryMagnitude(): number {
+		return Math.max(Math.abs(this.x), Math.abs(this.y));
+	}
+
+	public angle(): number {
+		return Math.atan2(this.y, this.x);
+	}
+
+	public normalized(): Vec3 {
+		const norm = this.magnitude();
+		return Vec2.of(this.x / norm, this.y / norm);
+	}
+
+	public normalizedOrZero(): Vec3 {
+		if (this.eq(Vec3.zero)) {
+			return Vec3.zero;
+		}
+
+		return this.normalized();
+	}
+
+	public times(c: number): Vec3 {
+		return Vec2.of(this.x * c, this.y * c);
+	}
+
+	public plus(v: Vec3): Vec3 {
+		return Vec3.of(this.x + v.x, this.y + v.y, v.z);
+	}
+
+	public minus(v: Vec3): Vec3 {
+		return Vec3.of(this.x - v.x, this.y - v.y, -v.z);
+	}
 
-	public static unitX = Vec3.of(1, 0, 0);
-	public static unitY = Vec3.of(0, 1, 0);
-	public static unitZ = Vec3.of(0, 0, 1);
-	public static zero = Vec3.of(0, 0, 0);
+	public dot(other: Vec3): number {
+		return this.x * other.x + this.y * other.y;
+	}
+
+	public cross(other: Vec3): Vec3 {
+		// | 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,
+		);
+	}
+
+	public scale(other: Vec3|number): Vec3 {
+		if (typeof other === 'number') {
+			return this.times(other);
+		}
+
+		return Vec2.of(
+			this.x * other.x,
+			this.y * other.y,
+		);
+	}
+
+	public orthog(): Vec3 {
+		// 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();
+	}
+
+	public extend(distance: number, direction: Vec3): Vec3 {
+		return this.plus(direction.normalized().times(distance));
+	}
+
+	public lerp(target: Vec3, fractionTo: number): Vec3 {
+		return this.times(1 - fractionTo).plus(target.times(fractionTo));
+	}
+
+	public zip(
+		other: Vec3, zip: (componentInThis: number, componentInOther: number)=> number
+	): Vec3 {
+		return Vec3.of(
+			zip(other.x, this.x),
+			zip(other.y, this.y),
+			zip(other.z, 0),
+		);
+	}
+
+	public map(fn: (component: number, index: number)=> number): Vec3 {
+		return Vec3.of(
+			fn(this.x, 0), fn(this.y, 1), fn(0, 2)
+		);
+	}
+
+	public asArray(): [ number, number, number ] {
+		return [this.x, this.y, 0];
+	}
+
+	public eq(other: Vec3, fuzz: number = defaultEqlTolerance): boolean {
+		return (
+			Math.abs(other.x - this.x) <= fuzz
+			&& Math.abs(other.y - this.y) <= fuzz
+			&& Math.abs(other.z) <= fuzz
+		);
+	}
+
+	public toString(): string {
+		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 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.
+	 * ```
+	 */
+	export const of = (x: number, y: number) => {
+		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 });
+	 * ```
+	 */
+	export const ofXY = ({x, y}: {x: number, y: number}) => {
+		return Vec2.of(x, y);
+	};
+
+	/** 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);
 }
+
+export 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);
+	 * ```
+	 */
+	export const of = (x: number, y: number, z: number): Vec3 => {
+		if (z === 0) {
+			return Vec2.of(x, y);
+		} else {
+			return new Vec3Impl(x, y, z);
+		}
+	};
+
+	export const unitX = Vec2.unitX;
+	export const unitY = Vec2.unitY;
+	export const zero = Vec2.zero;
+
+	/** A vector of length 1 in the z direction. */
+	export const unitZ = Vec3.of(0, 0, 1);
+}
+
 export default Vec3;

package/src/shapes/BezierJSWrapper.ts

@@ -118,7 +118,7 @@ export abstract class BezierJSWrapper extends Parameterized2DShape {
 			}
 
 			return t;
-		}).filter(entry => entry !== null) as number[];
+		}).filter(entry => entry !== null);
 	}
 
 	public override splitAt(t: number): [BezierJSWrapper] | [BezierJSWrapper, BezierJSWrapper] {

package/src/shapes/LineSegment2.ts

@@ -9,7 +9,18 @@ interface IntersectionResult {
 	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 class LineSegment2 extends Parameterized2DShape {
 	// invariant: ||direction|| = 1
 
@@ -51,7 +62,7 @@ export 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/src/shapes/Rect2.ts

@@ -298,9 +298,9 @@ export class Rect2 extends Abstract2DShape {
 		return Rect2.bboxOf(this.corners.map(corner => affineTransform.transformVec2(corner)));
 	}
 
-	/** @return true iff this is equal to [other] ± fuzz */
-	public eq(other: Rect2, fuzz: number = 0): boolean {
-		return this.topLeft.eq(other.topLeft, fuzz) && this.size.eq(other.size, fuzz);
+	/** @return true iff this is equal to `other ± tolerance` */
+	public eq(other: Rect2, tolerance: number = 0): boolean {
+		return this.topLeft.eq(other.topLeft, tolerance) && this.size.eq(other.size, tolerance);
 	}
 
 	public override toString(): string {

package/dist-test/test_imports/package-lock.json

@@ -1,13 +0,0 @@
-{
-	"name": "js-draw-math-test-imports",
-	"version": "0.0.1",
-	"lockfileVersion": 3,
-	"requires": true,
-	"packages": {
-		"": {
-			"name": "js-draw-math-test-imports",
-			"version": "0.0.1",
-			"license": "MIT"
-		}
-	}
-}