@js-draw/math 1.16.0 → 1.18.0

package/dist/mjs/shapes/PointShape2D.mjs

@@ -1,26 +1,49 @@
-import  Abstract2DShape  from './Abstract2DShape.mjs';
+import  { Vec2 }  from '../Vec2.mjs';
+import  Parameterized2DShape  from './Parameterized2DShape.mjs';
 import  Rect2  from './Rect2.mjs';
 /**
  * Like a {@link Point2}, but with additional functionality (e.g. SDF).
  *
  * Access the internal `Point2` using the `p` property.
  */
-class PointShape2D extends Abstract2DShape {
+class PointShape2D extends Parameterized2DShape {
     constructor(p) {
         super();
         this.p = p;
     }
     signedDistance(point) {
-        return this.p.minus(point).magnitude();
+        return this.p.distanceTo(point);
     }
-    intersectsLineSegment(lineSegment, epsilon) {
+    argIntersectsLineSegment(lineSegment, epsilon) {
         if (lineSegment.containsPoint(this.p, epsilon)) {
-            return [this.p];
+            return [0];
         }
         return [];
     }
     getTightBoundingBox() {
         return new Rect2(this.p.x, this.p.y, 0, 0);
     }
+    at(_t) {
+        return this.p;
+    }
+    /**
+     * Returns an arbitrary unit-length vector.
+     */
+    normalAt(_t) {
+        // Return a vector that makes sense.
+        return Vec2.unitY;
+    }
+    tangentAt(_t) {
+        return Vec2.unitX;
+    }
+    splitAt(_t) {
+        return [this];
+    }
+    nearestPointTo(_point) {
+        return {
+            point: this.p,
+            parameterValue: 0,
+        };
+    }
 }
 export default PointShape2D;

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

@@ -2,10 +2,9 @@ import { Point2, Vec2 } from '../Vec2';
 import BezierJSWrapper from './BezierJSWrapper';
 import Rect2 from './Rect2';
 /**
- * A wrapper around `bezier-js`'s quadratic Bézier.
+ * Represents a 2D Bézier curve.
  *
- * This wrappper lazy-loads `bezier-js`'s Bézier and can perform some operations
- * without loading it at all (e.g. `normal`, `at`, and `approximateDistance`).
+ * **Note**: Many Bézier operations use `bezier-js`'s.
  */
 export declare class QuadraticBezier extends BezierJSWrapper {
     readonly p0: Point2;
@@ -18,11 +17,15 @@ export declare class QuadraticBezier extends BezierJSWrapper {
      */
     private static componentAt;
     private static derivativeComponentAt;
+    private static secondDerivativeComponentAt;
     /**
      * @returns the curve evaluated at `t`.
+     *
+     * `t` should be a number in `[0, 1]`.
      */
     at(t: number): Point2;
     derivativeAt(t: number): Point2;
+    secondDerivativeAt(t: number): Point2;
     normal(t: number): Vec2;
     /** @returns an overestimate of this shape's bounding box. */
     getLooseBoundingBox(): Rect2;

package/dist/mjs/shapes/QuadraticBezier.mjs

@@ -3,10 +3,9 @@ import  solveQuadratic  from '../polynomial/solveQuadratic.mjs';
 import  BezierJSWrapper  from './BezierJSWrapper.mjs';
 import  Rect2  from './Rect2.mjs';
 /**
- * A wrapper around `bezier-js`'s quadratic Bézier.
+ * Represents a 2D Bézier curve.
  *
- * This wrappper lazy-loads `bezier-js`'s Bézier and can perform some operations
- * without loading it at all (e.g. `normal`, `at`, and `approximateDistance`).
+ * **Note**: Many Bézier operations use `bezier-js`'s.
  */
 export class QuadraticBezier extends BezierJSWrapper {
     constructor(p0, p1, p2) {
@@ -25,10 +24,19 @@ export class QuadraticBezier extends BezierJSWrapper {
     static derivativeComponentAt(t, p0, p1, p2) {
         return -2 * p0 + 2 * p1 + 2 * t * (p0 - 2 * p1 + p2);
     }
+    static secondDerivativeComponentAt(t, p0, p1, p2) {
+        return 2 * (p0 - 2 * p1 + p2);
+    }
     /**
      * @returns the curve evaluated at `t`.
+     *
+     * `t` should be a number in `[0, 1]`.
      */
     at(t) {
+        if (t === 0)
+            return this.p0;
+        if (t === 1)
+            return this.p2;
         const p0 = this.p0;
         const p1 = this.p1;
         const p2 = this.p2;
@@ -40,6 +48,12 @@ export class QuadraticBezier extends BezierJSWrapper {
         const p2 = this.p2;
         return Vec2.of(QuadraticBezier.derivativeComponentAt(t, p0.x, p1.x, p2.x), QuadraticBezier.derivativeComponentAt(t, p0.y, p1.y, p2.y));
     }
+    secondDerivativeAt(t) {
+        const p0 = this.p0;
+        const p1 = this.p1;
+        const p2 = this.p2;
+        return Vec2.of(QuadraticBezier.secondDerivativeComponentAt(t, p0.x, p1.x, p2.x), QuadraticBezier.secondDerivativeComponentAt(t, p0.y, p1.y, p2.y));
+    }
     normal(t) {
         const tangent = this.derivativeAt(t);
         return tangent.orthog().normalized();
@@ -100,10 +114,10 @@ export class QuadraticBezier extends BezierJSWrapper {
         }
         const at1 = this.at(min1);
         const at2 = this.at(min2);
-        const sqrDist1 = at1.minus(point).magnitudeSquared();
-        const sqrDist2 = at2.minus(point).magnitudeSquared();
-        const sqrDist3 = this.at(0).minus(point).magnitudeSquared();
-        const sqrDist4 = this.at(1).minus(point).magnitudeSquared();
+        const sqrDist1 = at1.squareDistanceTo(point);
+        const sqrDist2 = at2.squareDistanceTo(point);
+        const sqrDist3 = this.at(0).squareDistanceTo(point);
+        const sqrDist4 = this.at(1).squareDistanceTo(point);
         return Math.sqrt(Math.min(sqrDist1, sqrDist2, sqrDist3, sqrDist4));
     }
     getPoints() {

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

@@ -3,7 +3,7 @@ import Mat33 from '../Mat33';
 import { Point2, Vec2 } from '../Vec2';
 import Abstract2DShape from './Abstract2DShape';
 import Vec3 from '../Vec3';
-/** An object that can be converted to a Rect2. */
+/** An object that can be converted to a {@link Rect2}. */
 export interface RectTemplate {
     x: number;
     y: number;
@@ -12,6 +12,11 @@ export interface RectTemplate {
     width?: number;
     height?: number;
 }
+/**
+ * Represents a rectangle in 2D space, parallel to the XY axes.
+ *
+ * `invariant: w ≥ 0, h ≥ 0, immutable`
+ */
 export declare class Rect2 extends Abstract2DShape {
     readonly x: number;
     readonly y: number;
@@ -25,6 +30,9 @@ export declare class Rect2 extends Abstract2DShape {
     resizedTo(size: Vec2): Rect2;
     containsPoint(other: Point2): boolean;
     containsRect(other: Rect2): boolean;
+    /**
+     * @returns true iff this and `other` overlap
+     */
     intersects(other: Rect2): boolean;
     intersection(other: Rect2): Rect2 | null;
     union(other: Rect2): Rect2;

package/dist/mjs/shapes/Rect2.mjs

@@ -1,7 +1,11 @@
 import  LineSegment2  from './LineSegment2.mjs';
 import  { Vec2 }  from '../Vec2.mjs';
 import  Abstract2DShape  from './Abstract2DShape.mjs';
-// invariant: w ≥ 0, h ≥ 0, immutable
+/**
+ * Represents a rectangle in 2D space, parallel to the XY axes.
+ *
+ * `invariant: w ≥ 0, h ≥ 0, immutable`
+ */
 export class Rect2 extends Abstract2DShape {
     constructor(x, y, w, h) {
         super();
@@ -38,6 +42,9 @@ export class Rect2 extends Abstract2DShape {
             && this.x + this.w >= other.x + other.w
             && this.y + this.h >= other.y + other.h;
     }
+    /**
+     * @returns true iff this and `other` overlap
+     */
     intersects(other) {
         // Project along x/y axes.
         const thisMinX = this.x;
@@ -124,7 +131,7 @@ export class Rect2 extends Abstract2DShape {
         let closest = null;
         let closestDist = null;
         for (const point of closestEdgePoints) {
-            const dist = point.minus(target).length();
+            const dist = point.distanceTo(target);
             if (closestDist === null || dist < closestDist) {
                 closest = point;
                 closestDist = dist;

package/dist/mjs/utils/convexHull2Of.d.ts

@@ -0,0 +1,9 @@
+import { Point2 } from '../Vec2';
+/**
+ * Implements Gift Wrapping, in $O(nh)$. This algorithm is not the most efficient in the worst case.
+ *
+ * See https://en.wikipedia.org/wiki/Gift_wrapping_algorithm
+ * and https://www.cs.jhu.edu/~misha/Spring16/06.pdf
+ */
+declare const convexHull2Of: (points: Point2[]) => import("../Vec3").Vec3[];
+export default convexHull2Of;

package/dist/mjs/utils/convexHull2Of.mjs

@@ -0,0 +1,59 @@
+import  { Vec2 }  from '../Vec2.mjs';
+/**
+ * Implements Gift Wrapping, in $O(nh)$. This algorithm is not the most efficient in the worst case.
+ *
+ * See https://en.wikipedia.org/wiki/Gift_wrapping_algorithm
+ * and https://www.cs.jhu.edu/~misha/Spring16/06.pdf
+ */
+const convexHull2Of = (points) => {
+    if (points.length === 0) {
+        return [];
+    }
+    // 1. Start with a vertex on the hull
+    const lowestPoint = points.reduce((lowest, current) => current.y < lowest.y ? current : lowest, points[0]);
+    const vertices = [lowestPoint];
+    let toProcess = [...points.filter(p => !p.eq(lowestPoint))];
+    let lastBaseDirection = Vec2.of(-1, 0);
+    // 2. Find the point with greatest angle from the vertex:
+    //
+    //  . .     .
+    //   . .   /  <- Notice that **all** other points are to the
+    //       /       **left** of the vector from the current
+    //    ./         vertex to the new point.
+    while (toProcess.length > 0) {
+        const lastVertex = vertices[vertices.length - 1];
+        let smallestDotProductSoFar = lastBaseDirection.dot(lowestPoint.minus(lastVertex).normalizedOrZero());
+        let furthestPointSoFar = lowestPoint;
+        for (const point of toProcess) {
+            // Maximizing the angle is the same as minimizing the dot product:
+            //              point.minus(lastVertex)
+            //             ^
+            //            /
+            //           /
+            //        ϑ /
+            //   <-----. lastBaseDirection
+            const currentDotProduct = lastBaseDirection.dot(point.minus(lastVertex).normalizedOrZero());
+            if (currentDotProduct <= smallestDotProductSoFar) {
+                furthestPointSoFar = point;
+                smallestDotProductSoFar = currentDotProduct;
+            }
+        }
+        toProcess = toProcess.filter(p => !p.eq(furthestPointSoFar));
+        const newBaseDirection = furthestPointSoFar.minus(lastVertex).normalized();
+        // If the last vertex is on the same edge as the current, there's no need to include
+        // the previous one.
+        if (Math.abs(newBaseDirection.dot(lastBaseDirection)) === 1 && vertices.length > 1) {
+            vertices.pop();
+        }
+        // Stoping condition: We've gone in a full circle.
+        if (furthestPointSoFar.eq(lowestPoint)) {
+            break;
+        }
+        else {
+            vertices.push(furthestPointSoFar);
+            lastBaseDirection = lastVertex.minus(furthestPointSoFar).normalized();
+        }
+    }
+    return vertices;
+};
+export default convexHull2Of;

package/dist/mjs/utils/convexHull2Of.test.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@js-draw/math",
-	"version": "1.16.0",
+	"version": "1.18.0",
 	"description": "A math library for js-draw. ",
 	"types": "./dist/mjs/lib.d.ts",
 	"main": "./dist/cjs/lib.js",
@@ -21,14 +21,14 @@
 	"scripts": {
 		"dist-test": "cd dist-test/test_imports && npm install && npm run test",
 		"dist": "npm run build && npm run dist-test",
-		"build": "rm -rf ./dist && mkdir dist && build-tool build",
-		"watch": "rm -rf ./dist/* && mkdir -p dist && build-tool watch"
+		"build": "rm -rf ./dist && build-tool build",
+		"watch": "build-tool watch"
 	},
 	"dependencies": {
 		"bezier-js": "6.1.3"
 	},
 	"devDependencies": {
-		"@js-draw/build-tool": "^1.11.1",
+		"@js-draw/build-tool": "^1.17.0",
 		"@types/bezier-js": "4.1.0",
 		"@types/jest": "29.5.5",
 		"@types/jsdom": "21.1.3"
@@ -45,5 +45,5 @@
 		"svg",
 		"math"
 	],
-	"gitHead": "b0b6d7165d76582e1c197d0f56a10bfe6b46e2bc"
+	"gitHead": "73c0d802a8439b5d408ba1e60f91be029db7e402"
 }

package/src/Mat33.ts

@@ -444,8 +444,13 @@ export class Mat33 {
 			return Mat33.identity;
 		}
 
-		const parseArguments = (argumentString: string) => {
-			return argumentString.split(/[, \t\n]+/g).map(argString => {
+		const parseArguments = (argumentString: string): number[] => {
+			const parsed = argumentString.split(/[, \t\n]+/g).map(argString => {
+				// Handle trailing spaces/commands
+				if (argString.trim() === '') {
+					return null;
+				}
+
 				let isPercentage = false;
 				if (argString.endsWith('%')) {
 					isPercentage = true;
@@ -476,6 +481,7 @@ export class Mat33 {
 
 				return argNumber;
 			});
+			return parsed.filter(n => n !== null) as number[];
 		};
 
 

package/src/Vec3.test.ts

@@ -2,7 +2,7 @@
 import Vec3 from './Vec3';
 
 describe('Vec3', () => {
-	it('.xy should contain the x and y components', () => {
+	test('.xy should contain the x and y components', () => {
 		const vec = Vec3.of(1, 2, 3);
 		expect(vec.xy).toMatchObject({
 			x: 1,
@@ -10,42 +10,77 @@ describe('Vec3', () => {
 		});
 	});
 
-	it('should be combinable with other vectors via .zip', () => {
+	test('should be combinable with other vectors via .zip', () => {
 		const vec1 = Vec3.unitX;
 		const vec2 = Vec3.unitY;
 		expect(vec1.zip(vec2, Math.min)).objEq(Vec3.zero);
 		expect(vec1.zip(vec2, Math.max)).objEq(Vec3.of(1, 1, 0));
 	});
 
-	it('.cross should obey the right hand rule', () => {
+	test('.cross should obey the right hand rule', () => {
 		const vec1 = Vec3.unitX;
 		const vec2 = Vec3.unitY;
 		expect(vec1.cross(vec2)).objEq(Vec3.unitZ);
 		expect(vec2.cross(vec1)).objEq(Vec3.unitZ.times(-1));
 	});
 
-	it('.orthog should return an orthogonal vector', () => {
+	test('.orthog should return an orthogonal vector', () => {
 		expect(Vec3.unitZ.orthog().dot(Vec3.unitZ)).toBe(0);
 
 		// Should return some orthogonal vector, even if given the zero vector
 		expect(Vec3.zero.orthog().dot(Vec3.zero)).toBe(0);
 	});
 
-	it('.minus should return the difference between two vectors', () => {
+	test('.minus should return the difference between two vectors', () => {
 		expect(Vec3.of(1, 2, 3).minus(Vec3.of(4, 5, 6))).objEq(Vec3.of(1 - 4, 2 - 5, 3 - 6));
 	});
 
-	it('.orthog should return a unit vector', () => {
+	test('.orthog should return a unit vector', () => {
 		expect(Vec3.zero.orthog().magnitude()).toBe(1);
 		expect(Vec3.unitZ.orthog().magnitude()).toBe(1);
 		expect(Vec3.unitX.orthog().magnitude()).toBe(1);
 		expect(Vec3.unitY.orthog().magnitude()).toBe(1);
 	});
 
-	it('.normalizedOrZero should normalize the given vector or return zero', () => {
+	test('.normalizedOrZero should normalize the given vector or return zero', () => {
 		expect(Vec3.zero.normalizedOrZero()).objEq(Vec3.zero);
 		expect(Vec3.unitX.normalizedOrZero()).objEq(Vec3.unitX);
 		expect(Vec3.unitX.times(22).normalizedOrZero()).objEq(Vec3.unitX);
 		expect(Vec3.of(1, 1, 1).times(22).normalizedOrZero().length()).toBeCloseTo(1);
 	});
+
+	test.each([
+		{ from: Vec3.of(1, 1, 1), to: Vec3.of(1, 2, 1), expected: 1 },
+		{ from: Vec3.of(1, 1, 1), to: Vec3.of(1, 2, 2), expected: 2 },
+		{ from: Vec3.of(1, 1, 1), to: Vec3.of(2, 2, 2), expected: 3 },
+		{ from: Vec3.of(1, 1, 1), to: Vec3.of(0, 1, 1), expected: 1 },
+		{ from: Vec3.of(1, 1, 1), to: Vec3.of(0, 1, 0), expected: 2 },
+		{ from: Vec3.of(1, 1, 1), to: Vec3.of(0, 0, 0), expected: 3 },
+		{ from: Vec3.of(-1, -10, 0), to: Vec3.of(1, 2, 0), expected: 148 },
+		{ from: Vec3.of(-1, -10, 0), to: Vec3.of(1, 2, 0), expected: 148 },
+	])(
+		'.squareDistanceTo and .distanceTo should return correct square and euclidean distances (%j)',
+		({ from , to, expected }) => {
+			expect(from.squareDistanceTo(to)).toBe(expected);
+			expect(to.squareDistanceTo(from)).toBe(expected);
+			expect(to.distanceTo(from)).toBeCloseTo(Math.sqrt(expected));
+			expect(to.minus(from).magnitudeSquared()).toBe(expected);
+			expect(from.minus(to).magnitudeSquared()).toBe(expected);
+		},
+	);
+
+	test.each([
+		{ a: Vec3.of(1, 2, 3), b: Vec3.of(4, 5, 6), tolerance: 0.1, eq: false },
+		{ a: Vec3.of(1, 2, 3), b: Vec3.of(4, 5, 6), tolerance: 10, eq: true },
+		{ a: Vec3.of(1, 2, 3), b: Vec3.of(1, 2, 3), tolerance: 0, eq: true },
+		{ a: Vec3.of(1, 2, 3), b: Vec3.of(1, 2, 4), tolerance: 0, eq: false },
+		{ a: Vec3.of(1, 2, 3), b: Vec3.of(1, 4, 3), tolerance: 0, eq: false },
+		{ a: Vec3.of(1, 2, 3), b: Vec3.of(4, 2, 3), tolerance: 0, eq: false },
+		{ a: Vec3.of(1, 2, 3.0001), b: Vec3.of(1, 2, 3), tolerance: 1e-12, eq: false },
+		{ a: Vec3.of(1, 2, 3.0001), b: Vec3.of(1, 2, 3), tolerance: 1e-3, eq: true },
+		{ a: Vec3.of(1, 2.00001, 3.0001), b: Vec3.of(1.00001, 2, 3), tolerance: 1e-3, eq: true },
+	])('.eq should support tolerance (case %#)', ({ a, b, tolerance, eq }) => {
+		expect(a.eq(b, tolerance)).toBe(eq);
+		expect(b.eq(a, tolerance)).toBe(eq);
+	});
 });

package/src/Vec3.ts

@@ -63,11 +63,40 @@ export class Vec3 {
 		return this.dot(this);
 	}
 
+	/**
+	 * Interpreting this vector as a point in ℝ^3, computes the square distance
+	 * to another point, `p`.
+	 *
+	 * 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;
+	}
+
+	/**
+	 * Interpreting this vector as a point in ℝ³, returns the distance to the point
+	 * `p`.
+	 *
+	 * Equivalent to `.minus(p).magnitude()`.
+	 */
+	public distanceTo(p: Vec3) {
+		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
+	 * ```
 	 */
 	public maximumEntryMagnitude(): number {
 		return Math.max(Math.abs(this.x), Math.max(Math.abs(this.y), Math.abs(this.z)));
@@ -81,6 +110,7 @@ export class Vec3 {
 	 * 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)
@@ -214,7 +244,8 @@ 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)
 	 * ```
 	 */
@@ -242,13 +273,11 @@ export class Vec3 {
 	 * ```
 	 */
 	public eq(other: Vec3, fuzz: number = 1e-10): boolean {
-		for (let i = 0; i < 3; i++) {
-			if (Math.abs(other.at(i) - this.at(i)) > fuzz) {
-				return false;
-			}
-		}
-
-		return true;
+		return (
+			Math.abs(other.x - this.x) <= fuzz
+			&& Math.abs(other.y - this.y) <= fuzz
+			&& Math.abs(other.z - this.z) <= fuzz
+		);
 	}
 
 	public toString(): string {

package/src/lib.ts

@@ -21,6 +21,10 @@ export { LineSegment2 } from './shapes/LineSegment2';
 export {
 	Path,
 
+	IntersectionResult as PathIntersectionResult,
+	CurveIndexRecord as PathCurveIndex,
+	stepCurveIndexBy as stepPathIndexBy,
+	compareCurveIndices as comparePathIndices,
 	PathCommandType,
 	PathCommand,
 	LinePathCommand,
@@ -29,6 +33,7 @@ export {
 	CubicBezierPathCommand,
 } from './shapes/Path';
 export { Rect2 } from './shapes/Rect2';
+export { Parameterized2DShape } from './shapes/Parameterized2DShape';
 export { QuadraticBezier } from './shapes/QuadraticBezier';
 export { Abstract2DShape } from './shapes/Abstract2DShape';
 

package/src/shapes/Abstract2DShape.ts

@@ -49,6 +49,9 @@ export abstract class Abstract2DShape {
 
 	/**
 	 * Returns a bounding box that precisely fits the content of this shape.
+	 *
+	 * **Note**: This bounding box should aligned with the x/y axes. (Thus, it may be
+	 * possible to find a tighter bounding box not axes-aligned).
 	 */
 	public abstract getTightBoundingBox(): Rect2;