@js-draw/math 1.16.0 → 1.17.0

package/dist/mjs/shapes/Path.mjs

@@ -230,7 +230,7 @@ export class Path {
             for (const { part, distFn, bbox } of uncheckedDistFunctions) {
                 // Skip if impossible for the distance to the target to be lesser than
                 // the current minimum.
-                if (!bbox.grownBy(minDist).containsPoint(point)) {
+                if (isFinite(minDist) && !bbox.grownBy(minDist).containsPoint(point)) {
                     continue;
                 }
                 const currentDist = distFn(point);
@@ -268,7 +268,7 @@ export class Path {
         });
         const result = [];
         const stoppingThreshold = strokeRadius / 1000;
-        // Returns the maximum x value explored
+        // Returns the maximum parameter value explored
         const raymarchFrom = (startPoint, 
         // Direction to march in (multiplies line.direction)
         directionMultiplier, 
@@ -312,9 +312,14 @@ export class Path {
             if (lastPart && isOnLineSegment && Math.abs(lastDist) < stoppingThreshold) {
                 result.push({
                     point: currentPoint,
-                    parameterValue: NaN,
+                    parameterValue: NaN, // lastPart.nearestPointTo(currentPoint).parameterValue,
                     curve: lastPart,
+                    curveIndex: this.geometry.indexOf(lastPart),
                 });
+                // Slightly increase the parameter value to prevent the same point from being
+                // added to the results twice.
+                const parameterIncrease = strokeRadius / 20 / line.length;
+                lastParameter += isFinite(parameterIncrease) ? parameterIncrease : 0;
             }
             return lastParameter;
         };
@@ -347,14 +352,18 @@ export class Path {
         if (!line.bbox.intersects(this.bbox.grownBy(strokeRadius ?? 0))) {
             return [];
         }
+        let index = 0;
         for (const part of this.geometry) {
-            const intersection = part.intersectsLineSegment(line);
-            if (intersection.length > 0) {
+            const intersections = part.argIntersectsLineSegment(line);
+            for (const intersection of intersections) {
                 result.push({
                     curve: part,
-                    point: intersection[0],
+                    curveIndex: index,
+                    point: part.at(intersection),
+                    parameterValue: intersection,
                 });
             }
+            index++;
         }
         // If given a non-zero strokeWidth, attempt to raymarch.
         // Even if raymarching, we need to collect starting points.
@@ -367,6 +376,42 @@ export class Path {
         }
         return result;
     }
+    /**
+     * @returns the nearest point on this path to the given `point`.
+     *
+     * @internal
+     * @beta
+     */
+    nearestPointTo(point) {
+        // Find the closest point on this
+        let closestSquareDist = Infinity;
+        let closestPartIndex = 0;
+        let closestParameterValue = 0;
+        let closestPoint = this.startPoint;
+        for (let i = 0; i < this.geometry.length; i++) {
+            const current = this.geometry[i];
+            const nearestPoint = current.nearestPointTo(point);
+            const sqareDist = nearestPoint.point.squareDistanceTo(point);
+            if (i === 0 || sqareDist < closestSquareDist) {
+                closestPartIndex = i;
+                closestSquareDist = sqareDist;
+                closestParameterValue = nearestPoint.parameterValue;
+                closestPoint = nearestPoint.point;
+            }
+        }
+        return {
+            curve: this.geometry[closestPartIndex],
+            curveIndex: closestPartIndex,
+            parameterValue: closestParameterValue,
+            point: closestPoint,
+        };
+    }
+    at(index) {
+        return this.geometry[index.curveIndex].at(index.parameterValue);
+    }
+    tangentAt(index) {
+        return this.geometry[index.curveIndex].tangentAt(index.parameterValue);
+    }
     static mapPathCommand(part, mapping) {
         switch (part.kind) {
             case PathCommandType.MoveTo:
@@ -410,18 +455,85 @@ export class Path {
         return this.mapPoints(point => affineTransfm.transformVec2(point));
     }
     // Creates a new path by joining [other] to the end of this path
-    union(other) {
+    union(other, 
+    // allowReverse: true iff reversing other or this is permitted if it means
+    //               no moveTo command is necessary when unioning the paths.
+    options = { allowReverse: true }) {
         if (!other) {
             return this;
         }
-        return new Path(this.startPoint, [
-            ...this.parts,
-            {
-                kind: PathCommandType.MoveTo,
-                point: other.startPoint,
-            },
-            ...other.parts,
-        ]);
+        const thisEnd = this.getEndPoint();
+        let newParts = [];
+        if (thisEnd.eq(other.startPoint)) {
+            newParts = this.parts.concat(other.parts);
+        }
+        else if (options.allowReverse && this.startPoint.eq(other.getEndPoint())) {
+            return other.union(this, { allowReverse: false });
+        }
+        else if (options.allowReverse && this.startPoint.eq(other.startPoint)) {
+            return this.union(other.reversed(), { allowReverse: false });
+        }
+        else {
+            newParts = [
+                ...this.parts,
+                {
+                    kind: PathCommandType.MoveTo,
+                    point: other.startPoint,
+                },
+                ...other.parts,
+            ];
+        }
+        return new Path(this.startPoint, newParts);
+    }
+    /**
+     * @returns a version of this path with the direction reversed.
+     *
+     * Example:
+     * ```ts,runnable,console
+     * import {Path} from '@js-draw/math';
+     * console.log(Path.fromString('m0,0l1,1').reversed()); // -> M1,1 L0,0
+     * ```
+     */
+    reversed() {
+        const newStart = this.getEndPoint();
+        const newParts = [];
+        let lastPoint = this.startPoint;
+        for (const part of this.parts) {
+            switch (part.kind) {
+                case PathCommandType.LineTo:
+                case PathCommandType.MoveTo:
+                    newParts.push({
+                        kind: part.kind,
+                        point: lastPoint,
+                    });
+                    lastPoint = part.point;
+                    break;
+                case PathCommandType.CubicBezierTo:
+                    newParts.push({
+                        kind: part.kind,
+                        controlPoint1: part.controlPoint2,
+                        controlPoint2: part.controlPoint1,
+                        endPoint: lastPoint,
+                    });
+                    lastPoint = part.endPoint;
+                    break;
+                case PathCommandType.QuadraticBezierTo:
+                    newParts.push({
+                        kind: part.kind,
+                        controlPoint: part.controlPoint,
+                        endPoint: lastPoint,
+                    });
+                    lastPoint = part.endPoint;
+                    break;
+                default:
+                    {
+                        const exhaustivenessCheck = part;
+                        return exhaustivenessCheck;
+                    }
+            }
+        }
+        newParts.reverse();
+        return new Path(newStart, newParts);
     }
     getEndPoint() {
         if (this.parts.length === 0) {
@@ -513,6 +625,52 @@ export class Path {
         // Even? Probably no intersection.
         return false;
     }
+    /** @returns true if all points on this are equivalent to the points on `other` */
+    eq(other, tolerance) {
+        if (other.parts.length !== this.parts.length) {
+            return false;
+        }
+        for (let i = 0; i < this.parts.length; i++) {
+            const part1 = this.parts[i];
+            const part2 = other.parts[i];
+            switch (part1.kind) {
+                case PathCommandType.LineTo:
+                case PathCommandType.MoveTo:
+                    if (part1.kind !== part2.kind) {
+                        return false;
+                    }
+                    else if (!part1.point.eq(part2.point, tolerance)) {
+                        return false;
+                    }
+                    break;
+                case PathCommandType.CubicBezierTo:
+                    if (part1.kind !== part2.kind) {
+                        return false;
+                    }
+                    else if (!part1.controlPoint1.eq(part2.controlPoint1, tolerance)
+                        || !part1.controlPoint2.eq(part2.controlPoint2, tolerance)
+                        || !part1.endPoint.eq(part2.endPoint, tolerance)) {
+                        return false;
+                    }
+                    break;
+                case PathCommandType.QuadraticBezierTo:
+                    if (part1.kind !== part2.kind) {
+                        return false;
+                    }
+                    else if (!part1.controlPoint.eq(part2.controlPoint, tolerance)
+                        || !part1.endPoint.eq(part2.endPoint, tolerance)) {
+                        return false;
+                    }
+                    break;
+                default:
+                    {
+                        const exhaustivenessCheck = part1;
+                        return exhaustivenessCheck;
+                    }
+            }
+        }
+        return true;
+    }
     /**
      * Returns a path that outlines `rect`.
      *

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

@@ -1,18 +1,29 @@
 import { Point2 } from '../Vec2';
 import Vec3 from '../Vec3';
-import Abstract2DShape from './Abstract2DShape';
 import LineSegment2 from './LineSegment2';
+import Parameterized2DShape from './Parameterized2DShape';
 import Rect2 from './Rect2';
 /**
  * Like a {@link Point2}, but with additional functionality (e.g. SDF).
  *
  * Access the internal `Point2` using the `p` property.
  */
-declare class PointShape2D extends Abstract2DShape {
+declare class PointShape2D extends Parameterized2DShape {
     readonly p: Point2;
     constructor(p: Point2);
     signedDistance(point: Vec3): number;
-    intersectsLineSegment(lineSegment: LineSegment2, epsilon?: number): Vec3[];
+    argIntersectsLineSegment(lineSegment: LineSegment2, epsilon?: number): number[];
     getTightBoundingBox(): Rect2;
+    at(_t: number): Vec3;
+    /**
+     * Returns an arbitrary unit-length vector.
+     */
+    normalAt(_t: number): Vec3;
+    tangentAt(_t: number): Vec3;
+    splitAt(_t: number): [PointShape2D];
+    nearestPointTo(_point: Point2): {
+        point: Vec3;
+        parameterValue: number;
+    };
 }
 export default PointShape2D;

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

@@ -18,11 +18,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

@@ -25,10 +25,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 +49,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 +115,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

@@ -25,6 +25,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

@@ -38,6 +38,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 +127,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/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@js-draw/math",
-	"version": "1.16.0",
+	"version": "1.17.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": "d0eff585750ab5670af3acda8ddff090e8825bd3"
 }

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,61 @@ 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 },
+	])(
+		'.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);
+		},
+	);
 });

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)

package/src/lib.ts

@@ -21,6 +21,8 @@ export { LineSegment2 } from './shapes/LineSegment2';
 export {
 	Path,
 
+	IntersectionResult as PathIntersectionResult,
+	CurveIndexRecord as PathCurveIndex,
 	PathCommandType,
 	PathCommand,
 	LinePathCommand,

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;