@js-draw/math 1.16.0 → 1.17.0

package/src/shapes/Path.ts

@@ -2,12 +2,12 @@ import LineSegment2 from './LineSegment2';
 import Mat33 from '../Mat33';
 import Rect2 from './Rect2';
 import { Point2, Vec2 } from '../Vec2';
-import Abstract2DShape from './Abstract2DShape';
 import CubicBezier from './CubicBezier';
 import QuadraticBezier from './QuadraticBezier';
 import PointShape2D from './PointShape2D';
 import toRoundedString from '../rounding/toRoundedString';
 import toStringOfSamePrecision from '../rounding/toStringOfSamePrecision';
+import Parameterized2DShape from './Parameterized2DShape';
 
 export enum PathCommandType {
 	LineTo,
@@ -41,17 +41,29 @@ export interface MoveToPathCommand {
 
 export type PathCommand = CubicBezierPathCommand | QuadraticBezierPathCommand | MoveToPathCommand | LinePathCommand;
 
-interface IntersectionResult {
+export interface IntersectionResult {
 	// @internal
-	curve: Abstract2DShape;
+	curve: Parameterized2DShape;
+	// @internal
+	curveIndex: number;
 
-	/** @internal @deprecated */
+	/** Parameter value for the closest point **on** the path to the intersection. @internal @deprecated */
 	parameterValue?: number;
 
-	// Point at which the intersection occured.
+	/** Point at which the intersection occured. */
 	point: Point2;
 }
 
+/**
+ * Allows indexing a particular part of a path.
+ *
+ * @see {@link Path.at} {@link Path.tangentAt}
+ */
+export interface CurveIndexRecord {
+	curveIndex: number;
+	parameterValue: number;
+}
+
 /**
  * Represents a union of lines and curves.
  */
@@ -97,16 +109,16 @@ export class Path {
 		return Rect2.union(...bboxes);
 	}
 
-	private cachedGeometry: Abstract2DShape[]|null = null;
+	private cachedGeometry: Parameterized2DShape[]|null = null;
 
 	// Lazy-loads and returns this path's geometry
-	public get geometry(): Abstract2DShape[] {
+	public get geometry(): Parameterized2DShape[] {
 		if (this.cachedGeometry) {
 			return this.cachedGeometry;
 		}
 
 		let startPoint = this.startPoint;
-		const geometry: Abstract2DShape[] = [];
+		const geometry: Parameterized2DShape[] = [];
 
 		for (const part of this.parts) {
 			let exhaustivenessCheck: never;
@@ -270,7 +282,7 @@ export class Path {
 
 		type DistanceFunction = (point: Point2) => number;
 		type DistanceFunctionRecord = {
-			part: Abstract2DShape,
+			part: Parameterized2DShape,
 			bbox: Rect2,
 			distFn: DistanceFunction,
 		};
@@ -309,9 +321,9 @@ export class Path {
 
 		// Returns the minimum distance to a part in this stroke, where only parts that the given
 		// line could intersect are considered.
-		const sdf = (point: Point2): [Abstract2DShape|null, number] => {
+		const sdf = (point: Point2): [Parameterized2DShape|null, number] => {
 			let minDist = Infinity;
-			let minDistPart: Abstract2DShape|null = null;
+			let minDistPart: Parameterized2DShape|null = null;
 
 			const uncheckedDistFunctions: DistanceFunctionRecord[] = [];
 
@@ -338,7 +350,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;
 				}
 
@@ -388,7 +400,7 @@ export class Path {
 
 		const stoppingThreshold = strokeRadius / 1000;
 
-		// Returns the maximum x value explored
+		// Returns the maximum parameter value explored
 		const raymarchFrom = (
 			startPoint: Point2,
 
@@ -446,9 +458,15 @@ 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;
@@ -489,15 +507,20 @@ export class Path {
 			return [];
 		}
 
+		let index = 0;
 		for (const part of this.geometry) {
-			const intersection = part.intersectsLineSegment(line);
+			const intersections = part.argIntersectsLineSegment(line);
 
-			if (intersection.length > 0) {
+			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.
@@ -513,6 +536,47 @@ export class Path {
 		return result;
 	}
 
+	/**
+	 * @returns the nearest point on this path to the given `point`.
+	 *
+	 * @internal
+	 * @beta
+	 */
+	public nearestPointTo(point: Point2): IntersectionResult {
+		// Find the closest point on this
+		let closestSquareDist = Infinity;
+		let closestPartIndex = 0;
+		let closestParameterValue = 0;
+		let closestPoint: Point2 = 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,
+		};
+	}
+
+	public at(index: CurveIndexRecord) {
+		return this.geometry[index.curveIndex].at(index.parameterValue);
+	}
+
+	public tangentAt(index: CurveIndexRecord) {
+		return this.geometry[index.curveIndex].tangentAt(index.parameterValue);
+	}
+
 	private static mapPathCommand(part: PathCommand, mapping: (point: Point2)=> Point2): PathCommand {
 		switch (part.kind) {
 		case PathCommandType.MoveTo:
@@ -563,19 +627,88 @@ export class Path {
 	}
 
 	// Creates a new path by joining [other] to the end of this path
-	public union(other: Path|null): Path {
+	public union(
+		other: Path|null,
+
+		// allowReverse: true iff reversing other or this is permitted if it means
+		//               no moveTo command is necessary when unioning the paths.
+		options: { allowReverse?: boolean } = { allowReverse: true },
+	): Path {
 		if (!other) {
 			return this;
 		}
 
-		return new Path(this.startPoint, [
-			...this.parts,
+		const thisEnd = this.getEndPoint();
+
+		let newParts: Readonly<PathCommand>[] = [];
+		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
+	 * ```
+	 */
+	public reversed() {
+		const newStart = this.getEndPoint();
+		const newParts: Readonly<PathCommand>[] = [];
+		let lastPoint: Point2 = 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:
 			{
-				kind: PathCommandType.MoveTo,
-				point: other.startPoint,
-			},
-			...other.parts,
-		]);
+				const exhaustivenessCheck: never = part;
+				return exhaustivenessCheck;
+			}
+			}
+		}
+		newParts.reverse();
+		return new Path(newStart, newParts);
 	}
 
 	private getEndPoint() {
@@ -682,6 +815,57 @@ export class Path {
 		return false;
 	}
 
+	/** @returns true if all points on this are equivalent to the points on `other` */
+	public eq(other: Path, tolerance?: number) {
+		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: never = part1;
+				return exhaustivenessCheck;
+			}
+			}
+		}
+
+		return true;
+	}
+
 	/**
 	 * Returns a path that outlines `rect`.
 	 *

package/src/shapes/PointShape2D.ts

@@ -1,7 +1,7 @@
-import { Point2 } from '../Vec2';
+import { Point2, Vec2 } from '../Vec2';
 import Vec3 from '../Vec3';
-import Abstract2DShape from './Abstract2DShape';
 import LineSegment2 from './LineSegment2';
+import Parameterized2DShape from './Parameterized2DShape';
 import Rect2 from './Rect2';
 
 /**
@@ -9,18 +9,18 @@ import Rect2 from './Rect2';
  *
  * Access the internal `Point2` using the `p` property.
  */
-class PointShape2D extends Abstract2DShape {
+class PointShape2D extends Parameterized2DShape {
 	public constructor(public readonly p: Point2) {
 		super();
 	}
 
 	public override signedDistance(point: Vec3): number {
-		return this.p.minus(point).magnitude();
+		return this.p.distanceTo(point);
 	}
 
-	public override intersectsLineSegment(lineSegment: LineSegment2, epsilon?: number): Vec3[] {
+	public override argIntersectsLineSegment(lineSegment: LineSegment2, epsilon?: number): number[] {
 		if (lineSegment.containsPoint(this.p, epsilon)) {
-			return [ this.p ];
+			return [ 0 ];
 		}
 		return [ ];
 	}
@@ -28,6 +28,33 @@ class PointShape2D extends Abstract2DShape {
 	public override getTightBoundingBox(): Rect2 {
 		return new Rect2(this.p.x, this.p.y, 0, 0);
 	}
+
+	public override at(_t: number) {
+		return this.p;
+	}
+
+	/**
+	 * Returns an arbitrary unit-length vector.
+	 */
+	public override normalAt(_t: number) {
+		// Return a vector that makes sense.
+		return Vec2.unitY;
+	}
+
+	public override tangentAt(_t: number): Vec3 {
+		return Vec2.unitX;
+	}
+
+	public override splitAt(_t: number): [PointShape2D] {
+		return [this];
+	}
+
+	public override nearestPointTo(_point: Point2) {
+		return {
+			point: this.p,
+			parameterValue: 0,
+		};
+	}
 }
 
 export default PointShape2D;

package/src/shapes/QuadraticBezier.test.ts

@@ -2,13 +2,12 @@ import { Vec2 } from '../Vec2';
 import QuadraticBezier from './QuadraticBezier';
 
 describe('QuadraticBezier', () => {
-	it('approxmiateDistance should approximately return the distance to the curve', () => {
-		const curves = [
-			new QuadraticBezier(Vec2.zero, Vec2.of(10, 0), Vec2.of(20, 0)),
-			new QuadraticBezier(Vec2.of(-10, 0), Vec2.of(2, 10), Vec2.of(20, 0)),
-			new QuadraticBezier(Vec2.of(0, 0), Vec2.of(4, -10), Vec2.of(20, 60)),
-			new QuadraticBezier(Vec2.of(0, 0), Vec2.of(4, -10), Vec2.of(-20, 60)),
-		];
+	test.each([
+		new QuadraticBezier(Vec2.zero, Vec2.of(10, 0), Vec2.of(20, 0)),
+		new QuadraticBezier(Vec2.of(-10, 0), Vec2.of(2, 10), Vec2.of(20, 0)),
+		new QuadraticBezier(Vec2.of(0, 0), Vec2.of(4, -10), Vec2.of(20, 60)),
+		new QuadraticBezier(Vec2.of(0, 0), Vec2.of(4, -10), Vec2.of(-20, 60)),
+	])('approxmiateDistance should approximately return the distance to the curve (%s)', (curve) => {
 		const testPoints = [
 			Vec2.of(1, 1),
 			Vec2.of(-1, 1),
@@ -18,13 +17,50 @@ describe('QuadraticBezier', () => {
 			Vec2.of(5, 0),
 		];
 
+		for (const point of testPoints) {
+			const actualDist = curve.distance(point);
+			const approxDist = curve.approximateDistance(point);
+
+			expect(approxDist).toBeGreaterThan(actualDist * 0.6 - 0.25);
+			expect(approxDist).toBeLessThan(actualDist * 1.5 + 2.6);
+		}
+	});
+
+	test.each([
+		[ new QuadraticBezier(Vec2.zero, Vec2.unitX, Vec2.unitY), Vec2.zero, 0 ],
+		[ new QuadraticBezier(Vec2.zero, Vec2.unitX, Vec2.unitY), Vec2.unitY, 1 ],
+
+		[ new QuadraticBezier(Vec2.zero, Vec2.of(0.5, 0), Vec2.of(1, 0)), Vec2.of(0.4, 0), 0.4],
+		[ new QuadraticBezier(Vec2.zero, Vec2.of(0, 0.5), Vec2.of(0, 1)), Vec2.of(0, 0.4), 0.4],
+		[ new QuadraticBezier(Vec2.zero, Vec2.unitX, Vec2.unitY), Vec2.unitX, 0.42514 ],
+
+		// Should not return an out-of-range parameter
+		[ new QuadraticBezier(Vec2.zero, Vec2.of(0, 0.5), Vec2.unitY), Vec2.of(0, -1000), 0 ],
+		[ new QuadraticBezier(Vec2.zero, Vec2.of(0, 0.5), Vec2.unitY), Vec2.of(0, 1000), 1 ],
+	])('nearestPointTo should return the nearest point and parameter value on %s to %s', (bezier, point, expectedParameter) => {
+		const nearest = bezier.nearestPointTo(point);
+		expect(nearest.parameterValue).toBeCloseTo(expectedParameter, 0.0001);
+		expect(nearest.point).objEq(bezier.at(nearest.parameterValue));
+	});
+
+	test('.normalAt should return a unit normal vector at the given parameter value', () => {
+		const curves = [
+			new QuadraticBezier(Vec2.zero, Vec2.unitY, Vec2.unitY.times(2)),
+			new QuadraticBezier(Vec2.zero, Vec2.unitX, Vec2.unitY),
+			new QuadraticBezier(Vec2.zero, Vec2.unitX, Vec2.unitY.times(-2)),
+			new QuadraticBezier(Vec2.of(2, 3), Vec2.of(4, 5.1), Vec2.of(6, 7)),
+			new QuadraticBezier(Vec2.of(2, 3), Vec2.of(100, 1000), Vec2.unitY.times(-2)),
+		];
+
 		for (const curve of curves) {
-			for (const point of testPoints) {
-				const actualDist = curve.distance(point);
-				const approxDist = curve.approximateDistance(point);
+			for (let t = 0; t < 1; t += 0.1) {
+				const normal = curve.normalAt(t);
+				expect(normal.length()).toBe(1);
+
+				const tangentApprox = curve.at(t + 0.001).minus(curve.at(t - 0.001));
 
-				expect(approxDist).toBeGreaterThan(actualDist * 0.6 - 0.25);
-				expect(approxDist).toBeLessThan(actualDist * 1.5 + 2.6);
+				// The tangent vector should be perpindicular to the normal
+				expect(tangentApprox.dot(normal)).toBeCloseTo(0);
 			}
 		}
 	});

package/src/shapes/QuadraticBezier.ts

@@ -30,10 +30,19 @@ export class QuadraticBezier extends BezierJSWrapper {
 		return -2 * p0 + 2 * p1 + 2 * t * (p0 - 2 * p1 + p2);
 	}
 
+	private static secondDerivativeComponentAt(t: number, p0: number, p1: number, p2: number) {
+		return 2 * (p0 - 2 * p1 + p2);
+	}
+
 	/**
 	 * @returns the curve evaluated at `t`.
+	 *
+	 * `t` should be a number in `[0, 1]`.
 	 */
 	public override at(t: number): Point2 {
+		if (t === 0) return this.p0;
+		if (t === 1) return this.p2;
+
 		const p0 = this.p0;
 		const p1 = this.p1;
 		const p2 = this.p2;
@@ -53,6 +62,16 @@ export class QuadraticBezier extends BezierJSWrapper {
 		);
 	}
 
+	public override secondDerivativeAt(t: number): Point2 {
+		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),
+		);
+	}
+
 	public override normal(t: number): Vec2 {
 		const tangent = this.derivativeAt(t);
 		return tangent.orthog().normalized();
@@ -126,11 +145,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));
 	}

package/src/shapes/Rect2.ts

@@ -67,6 +67,9 @@ export class Rect2 extends Abstract2DShape {
 				&& this.y + this.h >= other.y + other.h;
 	}
 
+	/**
+	 * @returns true iff this and `other` overlap
+	 */
 	public intersects(other: Rect2): boolean {
 		// Project along x/y axes.
 		const thisMinX = this.x;
@@ -181,7 +184,7 @@ export class Rect2 extends Abstract2DShape {
 		let closest: Point2|null = null;
 		let closestDist: number|null = 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;