@js-draw/math 1.16.0 → 1.18.0

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,14 +17,72 @@ 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 ],
+
+		// Edge case -- just a point
+		[ new QuadraticBezier(Vec2.zero, Vec2.zero, Vec2.zero), Vec2.of(0, 1000), 0 ],
+	])('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);
 			}
 		}
 	});
+
+	test.each([
+		new QuadraticBezier(Vec2.zero, Vec2.unitY, Vec2.unitY.times(2)),
+		new QuadraticBezier(Vec2.zero, Vec2.unitX, Vec2.unitY),
+		new QuadraticBezier(Vec2.zero, Vec2.unitY, Vec2.unitX),
+	])('.derivativeAt should return a derivative vector with the correct direction (curve: %s)', (curve) => {
+		for (let t = 0; t < 1; t += 0.1) {
+			const derivative = curve.derivativeAt(t);
+			const derivativeApprox = curve.at(t + 0.001).minus(curve.at(t - 0.001));
+			expect(derivativeApprox.normalized()).objEq(derivative.normalized(), 0.01);
+		}
+	});
+
+	test('should support Bezier-Bezier intersections', () => {
+		const b1 = new QuadraticBezier(Vec2.zero, Vec2.unitX, Vec2.unitY);
+		const b2 = new QuadraticBezier(Vec2.of(-1, 0.5), Vec2.of(0, 0.6), Vec2.of(1, 0.4));
+		expect(b1.intersectsBezier(b2)).toHaveLength(1);
+	});
 });

package/src/shapes/QuadraticBezier.ts

@@ -4,10 +4,9 @@ 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 class QuadraticBezier extends BezierJSWrapper {
 	public constructor(
@@ -30,10 +29,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 +61,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 +144,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

@@ -4,7 +4,7 @@ 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;
@@ -14,7 +14,11 @@ export interface RectTemplate {
 	height?: number;
 }
 
-// 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 {
 	// Derived state:
 
@@ -67,6 +71,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 +188,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;

package/src/utils/convexHull2Of.test.ts

@@ -0,0 +1,43 @@
+import { Vec2 } from '../Vec2';
+import { Rect2 } from '../shapes/Rect2';
+import convexHull2Of from './convexHull2Of';
+
+describe('convexHull2Of', () => {
+	it.each([
+		[ [ Vec2.of(1, 1) ] , [ Vec2.of(1, 1) ] ],
+
+		// Line
+		[ [ Vec2.of(1, 1), Vec2.of(2, 2) ] , [ Vec2.of(1, 1), Vec2.of(2, 2) ] ],
+
+		// Just a triangle
+		[ [ Vec2.of(1, 1), Vec2.of(4, 2), Vec2.of(3, 3) ] , [ Vec2.of(1, 1), Vec2.of(4, 2), Vec2.of(3, 3) ]],
+
+		// Triangle with an extra point
+		[ [ Vec2.of(1, 1), Vec2.of(2, 20), Vec2.of(3, 5), Vec2.of(4, 3) ] , [ Vec2.of(1, 1), Vec2.of(4, 3), Vec2.of(2, 20) ]],
+
+		// Points within a triangle
+		[
+			[ Vec2.of(28, 5), Vec2.of(4, 5), Vec2.of(-100, -100), Vec2.of(7, 120), Vec2.of(1, 8), Vec2.of(100, -100), Vec2.of(2, 4), Vec2.of(3, 4), Vec2.of(4, 5) ],
+			[ Vec2.of(-100, -100), Vec2.of(100, -100), Vec2.of(7, 120) ],
+		],
+
+		// Points within a triangle (repeated vertex)
+		[
+			[ Vec2.of(28, 5), Vec2.of(4, 5), Vec2.of(-100, -100), Vec2.of(-100, -100), Vec2.of(7, 120), Vec2.of(1, 8), Vec2.of(100, -100), Vec2.of(2, 4), Vec2.of(3, 4), Vec2.of(4, 5) ],
+			[ Vec2.of(-100, -100), Vec2.of(100, -100), Vec2.of(7, 120) ],
+		],
+
+		// Points within a square
+		[
+			[ Vec2.of(28, 5), Vec2.of(4, 5), Vec2.of(-100, -100), Vec2.of(100, 100), Vec2.of(7, 100), Vec2.of(1, 8), Vec2.of(-100, 100), Vec2.of(100, -100), Vec2.of(2, 4), Vec2.of(3, 4), Vec2.of(4, 5) ],
+			[ Vec2.of(-100, -100), Vec2.of(100, -100), Vec2.of(100, 100), Vec2.of(-100, 100) ],
+		],
+
+		[
+			Rect2.unitSquare.corners,
+			[ Vec2.of(1, 0), Vec2.of(1, 1), Vec2.of(0, 1), Vec2.of(0, 0) ],
+		]
+	])('should compute the convex hull of a set of points (%j)', (points, expected) => {
+		expect(convexHull2Of(points)).toMatchObject(expected);
+	});
+});

package/src/utils/convexHull2Of.ts

@@ -0,0 +1,71 @@
+import { Point2, Vec2 } 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
+ */
+const convexHull2Of = (points: Point2[]) => {
+	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: number = 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;