@js-draw/math 1.17.0 → 1.18.0

package/src/Vec3.ts

@@ -244,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)
 	 * ```
 	 */
@@ -272,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

@@ -23,6 +23,8 @@ export {
 
 	IntersectionResult as PathIntersectionResult,
 	CurveIndexRecord as PathCurveIndex,
+	stepCurveIndexBy as stepPathIndexBy,
+	compareCurveIndices as comparePathIndices,
 	PathCommandType,
 	PathCommand,
 	LinePathCommand,
@@ -31,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/BezierJSWrapper.ts

@@ -87,6 +87,18 @@ export abstract class BezierJSWrapper extends Parameterized2DShape {
 	}
 
 	public override argIntersectsLineSegment(line: LineSegment2): number[] {
+		// Bezier-js has a bug when all control points of a Bezier curve lie on
+		// a line. Our solution involves converting the Bezier into a line, then
+		// finding the parameter value that produced the intersection.
+		//
+		// TODO: This is unnecessarily slow. A better solution would be to fix
+		// the bug upstream.
+		const asLine = LineSegment2.ofSmallestContainingPoints(this.getPoints());
+		if (asLine) {
+			const intersection = asLine.intersectsLineSegment(line);
+			return intersection.map(p => this.nearestPointTo(p).parameterValue);
+		}
+
 		const bezier = this.getBezier();
 
 		return bezier.intersects(line).map(t => {
@@ -186,6 +198,8 @@ export abstract class BezierJSWrapper extends Parameterized2DShape {
 
 		const iterate = () => {
 			const slope = secondDerivativeAt(t);
+			if (slope === 0) return;
+
 			// We intersect a line through the point on f'(t) at t with the x-axis:
 			//    y = m(x - x₀) + y₀
 			// ⇒  x - x₀ = (y - y₀) / m
@@ -211,6 +225,33 @@ export abstract class BezierJSWrapper extends Parameterized2DShape {
 		return { parameterValue: t, point: this.at(t) };
 	}
 
+	public intersectsBezier(other: BezierJSWrapper) {
+		const intersections = this.getBezier().intersects(other.getBezier()) as (string[] | null | undefined);
+		if (!intersections || intersections.length === 0) {
+			return [];
+		}
+
+		const result = [];
+		for (const intersection of intersections) {
+			// From http://pomax.github.io/bezierjs/#intersect-curve,
+			// .intersects returns an array of 't1/t2' pairs, where curve1.at(t1) gives the point.
+			const match = /^([-0-9.eE]+)\/([-0-9.eE]+)$/.exec(intersection);
+
+			if (!match) {
+				throw new Error(
+					`Incorrect format returned by .intersects: ${intersections} should be array of "number/number"!`
+				);
+			}
+
+			const t = parseFloat(match[1]);
+			result.push({
+				parameterValue: t,
+				point: this.at(t),
+			});
+		}
+		return result;
+	}
+
 	public override toString() {
 		return `Bézier(${this.getPoints().map(point => point.toString()).join(', ')})`;
 	}

package/src/shapes/LineSegment2.test.ts

@@ -74,6 +74,14 @@ describe('Line2', () => {
 		expect(line2.intersection(line1)).toBeNull();
 	});
 
+	it('(9.559000000000001, 11.687)->(9.559, 11.67673) should intersect (9.56069, 11.68077)->(9.55719, 11.68077)', () => {
+		// Points taken from an issue observed in the editor.
+		const l1 = new LineSegment2(Vec2.of(9.559000000000001, 11.687), Vec2.of(9.559, 11.67673));
+		const l2 = new LineSegment2(Vec2.of(9.56069, 11.68077), Vec2.of(9.55719, 11.68077));
+		expect(l2.intersects(l1)).toBe(true);
+		expect(l1.intersects(l2)).toBe(true);
+	});
+
 	it('Closest point to (0,0) on the line x = 1 should be (1,0)', () => {
 		const line = new LineSegment2(Vec2.of(1, 100), Vec2.of(1, -100));
 		expect(line.closestPointTo(Vec2.zero)).objEq(Vec2.of(1, 0));
@@ -130,4 +138,22 @@ describe('Line2', () => {
 		expect(new LineSegment2(Vec2.zero, Vec2.unitX)).objEq(new LineSegment2(Vec2.unitX, Vec2.zero));
 		expect(new LineSegment2(Vec2.zero, Vec2.unitX)).not.objEq(new LineSegment2(Vec2.unitX, Vec2.zero), { ignoreDirection: false });
 	});
+
+	it('should support creating from a collection of points', () => {
+		expect(LineSegment2.ofSmallestContainingPoints([])).toBeNull();
+		expect(LineSegment2.ofSmallestContainingPoints([Vec2.of(1, 1)])).toBeNull();
+		expect(LineSegment2.ofSmallestContainingPoints(
+			[Vec2.of(1, 1), Vec2.of(1, 2), Vec2.of(3, 3)]
+		)).toBeNull();
+
+		expect(LineSegment2.ofSmallestContainingPoints(
+			[Vec2.of(1, 1), Vec2.of(1, 2)]
+		)).objEq(new LineSegment2(Vec2.of(1, 1), Vec2.of(1, 2)));
+		expect(LineSegment2.ofSmallestContainingPoints(
+			[Vec2.of(1, 1), Vec2.of(2, 2), Vec2.of(3, 3)]
+		)).objEq(new LineSegment2(Vec2.of(1, 1), Vec2.of(3, 3)));
+		expect(LineSegment2.ofSmallestContainingPoints(
+			[Vec2.of(3, 3), Vec2.of(2, 2), Vec2.of(2.4, 2.4), Vec2.of(3, 3)]
+		)).objEq(new LineSegment2(Vec2.of(2, 2), Vec2.of(3, 3)));
+	});
 });

package/src/shapes/LineSegment2.ts

@@ -46,6 +46,31 @@ export class LineSegment2 extends Parameterized2DShape {
 		}
 	}
 
+	/**
+	 * Returns the smallest line segment that contains all points in `points`, or `null`
+	 * if no such line segment exists.
+	 *
+	 * @example
+	 * ```ts,runnable
+	 * import {LineSegment2, Vec2} from '@js-draw/math';
+	 * console.log(LineSegment2.ofSmallestContainingPoints([Vec2.of(1, 0), Vec2.of(0, 1)]));
+	 * ```
+	 */
+	public static ofSmallestContainingPoints(points: readonly Point2[]) {
+		if (points.length <= 1) return null;
+
+		const sorted = [...points].sort((a, b) => a.x !== b.x ? a.x - b.x : a.y - b.y);
+		const line = new LineSegment2(sorted[0], sorted[sorted.length - 1]);
+
+		for (const point of sorted) {
+			if (!line.containsPoint(point)) {
+				return null;
+			}
+		}
+
+		return line;
+	}
+
 	// Accessors to make LineSegment2 compatible with bezier-js's
 	// interface
 
@@ -139,7 +164,11 @@ export class LineSegment2 extends Parameterized2DShape {
 		//     = ((o₁ᵧ - o₂ᵧ)((d₁ₓd₂ₓ)) + (d₂ᵧd₁ₓ)(o₂ₓ) - (d₁ᵧd₂ₓ)(o₁ₓ))/(d₂ᵧd₁ₓ - d₁ᵧd₂ₓ)
 		// ⇒ y = o₁ᵧ + d₁ᵧ · (x - o₁ₓ) / d₁ₓ = ...
 		let resultPoint, resultT;
-		if (this.direction.x === 0) {
+
+		// Consider very-near-vertical lines to be vertical --- not doing so can lead to
+		// precision error when dividing by this.direction.x.
+		const small = 4e-13;
+		if (Math.abs(this.direction.x) < small) {
 			// Vertical line: Where does the other have x = this.point1.x?
 			// x = o₁ₓ = o₂ₓ + d₂ₓ · (y - o₂ᵧ) / d₂ᵧ
 			// ⇒ (o₁ₓ - o₂ₓ)(d₂ᵧ/d₂ₓ) + o₂ᵧ = y
@@ -184,6 +213,7 @@ export class LineSegment2 extends Parameterized2DShape {
 		const resultToP2 = resultPoint.distanceTo(this.point2);
 		const resultToP3 = resultPoint.distanceTo(other.point1);
 		const resultToP4 = resultPoint.distanceTo(other.point2);
+
 		if (resultToP1 > this.length
 			|| resultToP2 > this.length
 			|| resultToP3 > other.length

package/src/shapes/Parameterized2DShape.ts

@@ -2,7 +2,12 @@ import { Point2, Vec2 } from '../Vec2';
 import Abstract2DShape from './Abstract2DShape';
 import LineSegment2 from './LineSegment2';
 
-/** A 2-dimensional path with parameter interval $t \in [0, 1]$. */
+/**
+ * A 2-dimensional path with parameter interval $t \in [0, 1]$.
+ *
+ * **Note:** Avoid extending this class outside of `js-draw` --- new abstract methods
+ * may be added between minor versions.
+ */
 export abstract class Parameterized2DShape extends Abstract2DShape {
 	/** Returns this at a given parameter. $t \in [0, 1]$ */
 	abstract at(t: number): Point2;

package/src/shapes/Path.test.ts

@@ -1,7 +1,7 @@
 import LineSegment2 from './LineSegment2';
-import Path, { PathCommandType } from './Path';
+import Path, { CurveIndexRecord, PathCommandType } from './Path';
 import Rect2 from './Rect2';
-import { Vec2 } from '../Vec2';
+import { Point2, Vec2 } from '../Vec2';
 import CubicBezier from './CubicBezier';
 import QuadraticBezier from './QuadraticBezier';
 
@@ -238,13 +238,22 @@ describe('Path', () => {
 
 		it.each([
 			[new LineSegment2(Vec2.of(43.5,-12.5), Vec2.of(40.5,24.5)), 0],
-			// TODO: The below case is failing. It seems to be a Bezier-js bug though...
-			// (The Bézier.js method returns an empty array).
-			//[new LineSegment2(Vec2.of(35.5,19.5), Vec2.of(38.5,-17.5)), 0],
+			[new LineSegment2(Vec2.of(35.5,19.5), Vec2.of(38.5,-17.5)), 0],
 		])('should correctly report positive intersections with a line-like Bézier', (line, strokeRadius) => {
 			const bezier = Path.fromString('M0,0 Q50,0 100,0');
 			expect(bezier.intersection(line, strokeRadius).length).toBeGreaterThan(0);
 		});
+
+		it('should handle near-vertical lines', () => {
+			const intersections = Path.fromString('M0,0 Q50,0 100,0').intersection(new LineSegment2(Vec2.of(44, -12), Vec2.of(39, 25)));
+			expect(intersections).toHaveLength(1);
+		});
+
+		it('should handle single-point strokes', () => {
+			const stroke = new Path(Vec2.zero, []);
+			expect(stroke.intersection(new LineSegment2(Vec2.of(-2, -20), Vec2.of(-2, -1)), 1)).toHaveLength(0);
+			expect(stroke.intersection(new LineSegment2(Vec2.of(-2, -2), Vec2.of(2, 2)), 1)).toHaveLength(2);
+		});
 	});
 
 	describe('polylineApproximation', () => {
@@ -348,6 +357,146 @@ describe('Path', () => {
 		});
 	});
 
+	describe('splitAt', () => {
+		it.each([
+			2, 3, 4, 5,
+		])('should split a line into %d sections', (numSections) => {
+			const path = Path.fromString('m0,0 l1,0');
+
+			const splitIndices: CurveIndexRecord[] = [];
+			for (let i = 0; i < numSections; i++) {
+				splitIndices.push({ curveIndex: 0, parameterValue: (i + 1) / (numSections + 1) });
+			}
+			const split = path.splitAt(splitIndices);
+
+			expect(split).toHaveLength(numSections + 1);
+			expect(split[numSections].getEndPoint()).objEq(Vec2.unitX);
+			for (let i = 0; i < numSections; i ++) {
+				expect(split[i].geometry).toHaveLength(1);
+				const geom = split[i].geometry[0] as LineSegment2;
+				expect(geom.p1.y).toBeCloseTo(0);
+				expect(geom.p1.x).toBeCloseTo(i / (numSections + 1));
+				expect(geom.p2.y).toBeCloseTo(0);
+				expect(geom.p2.x).toBeCloseTo((i + 1) / (numSections + 1));
+			}
+		});
+
+		it('should handle the case where the first division is at the beginning of the path', () => {
+			const path = Path.fromString('m0,0 l1,0');
+			const beginningSplit = path.splitAt({ curveIndex: 0, parameterValue: 0 });
+			expect(beginningSplit).toHaveLength(1);
+
+			const endSplit = path.splitAt({ curveIndex: 0, parameterValue: 1 });
+			expect(endSplit).toHaveLength(1);
+
+			expect(beginningSplit[0]).objEq(path);
+			expect(beginningSplit[0]).objEq(endSplit[0]);
+		});
+	});
+
+	describe('splitNear', () => {
+		it('should divide a line in half', () => {
+			const path = Path.fromString('m0,0l8,0');
+			const split = path.splitNear(Vec2.of(4, 0));
+			expect(split).toHaveLength(2);
+			expect(split[0].toString()).toBe('M0,0L4,0');
+			expect(split[1]!.toString()).toBe('M4,0L8,0');
+		});
+
+		it('should divide a polyline into parts', () => {
+			const path = Path.fromString('m0,0L8,0L8,8');
+			const split = path.splitNear(Vec2.of(8, 4));
+			expect(split).toHaveLength(2);
+			expect(split[0].toString()).toBe('M0,0L8,0L8,4');
+			expect(split[1]!.toString()).toBe('M8,4L8,8');
+		});
+
+		it('should divide a quadratic Bézier in half', () => {
+			const path = Path.fromString('m0,0 Q4,0 8,0');
+			const split = path.splitNear(Vec2.of(4, 0));
+			expect(split).toHaveLength(2);
+			expect(split[0].toString()).toBe('M0,0Q2,0 4,0');
+			expect(split[1]!.toString()).toBe('M4,0Q6,0 8,0');
+		});
+
+		it('should divide two quadratic Béziers half', () => {
+			const path = Path.fromString('m0,0 Q4,0 8,0 Q8,4 8,8');
+			const split = path.splitNear(Vec2.of(8, 4));
+			expect(split).toHaveLength(2);
+			expect(split[0].toString()).toBe('M0,0Q4,0 8,0Q8,2 8,4');
+			expect(split[1]!.toString()).toBe('M8,4Q8,6 8,8');
+		});
+
+		it.each([
+			{
+				original: 'm0,0 Q4,0 8,0 Q8,4 8,8',
+				near: Vec2.of(8, 4),
+				map: (p: Point2) => p.plus(Vec2.of(1, 1)),
+				expected: [ 'M0,0Q4,0 8,0Q9,3 9,5', 'M9,5Q9,7 9,9' ],
+			},
+			{
+				original: 'm0,0 L0,10',
+				near: Vec2.of(0, 5),
+				map: (p: Point2) => p.plus(Vec2.of(100, 0)),
+				expected: [ 'M0,0L100,5', 'M100,5L0,10' ],
+			},
+			{
+				// Tested using SVG data similar to:
+				//   <path d="m1,1 C1,2 2,10 4,4 C5,0 9,3 7,7" fill="none" stroke="#ff0000"/>
+				//   <path d="M2,6C3,6 3,6 4,4C5,0 9,3 7,7" fill="none" stroke="#00ff0080"/>
+				// Because of the rounding, the fit path should be slightly off.
+				original: 'm1,1 C1,2 2,10 4,4 C5,0 9,3 7,7',
+				near: Vec2.of(3, 5),
+				map: (p: Point2) => Vec2.of(Math.round(p.x), Math.round(p.y)),
+				expected: [ 'M1,1C1,2 1,6 2,6', 'M2,6C3,6 3,6 4,4C5,0 9,3 7,7' ],
+			},
+		])('should support mapping newly-added points while splitting (case %j)', ({ original, near, map, expected }) => {
+			const path = Path.fromString(original);
+			const split = path.splitNear(near, { mapNewPoint: map });
+			expect(split.map(p => p.toString(false))).toMatchObject(expected);
+		});
+	});
+
+	describe('spliced', () => {
+		it.each([
+			// should support insertion splicing
+			{
+				curve: 'm0,0 l2,0',
+				from: { i: 0, t: 0.5 },
+				to: { i: 0, t: 0.5 },
+				insert: 'm1,0 l0,10 z',
+				expected: 'M0,0 L1,0 L1,10 L1,0 L2,0',
+			},
+
+			// should support removing a segment when splicing
+			{
+				curve: 'm0,0 l4,0',
+				from: { i: 0, t: 0.25 },
+				to: { i: 0, t: 0.75 },
+				insert: 'M1,0 L1,1 L3,1 L3,0',
+				expected: 'M0,0 L1,0 L1,1 L3,1 L3,0 L4,0',
+			},
+
+			// should support reverse splicing and reverse `insert` as necessary
+			{
+				curve: 'M0,0 l4,0',
+				from: { i: 0, t: 0.75 },
+				to: { i: 0, t: 0.25 },
+				insert: 'M1,0 L1,1 L3,1 L3,0',
+				expected: 'M1,0 L3,0 L3,1 L1,1 L1,0',
+			},
+		])('.spliced should support inserting paths inbetween other paths (case %#)', ({ curve, from, to, insert, expected }) => {
+			const originalCurve = Path.fromString(curve);
+			expect(
+				originalCurve.spliced(
+					{ curveIndex: from.i, parameterValue: from.t },
+					{ curveIndex: to.i, parameterValue: to.t },
+					Path.fromString(insert),
+				)
+			).objEq(Path.fromString(expected));
+		});
+	});
+
 	it.each([
 		[ 'm0,0 L1,1', 'M1,1 L0,0' ],
 		[ 'm0,0 L1,1', 'M1,1 L0,0' ],
@@ -366,4 +515,23 @@ describe('Path', () => {
 	])('.nearestPointTo should return the closest point on a path to the given parameter (case %#)', (path, point, expectedClosest) => {
 		expect(Path.fromString(path).nearestPointTo(point).point).objEq(expectedClosest, 0.002);
 	});
+
+	it.each([
+		// Polyline
+		[ 'm0,0 l1,0 l0,1', [ 0, 0.5 ], Vec2.of(1, 0) ],
+		[ 'm0,0 l1,0 l0,1', [ 0, 0.99 ], Vec2.of(1, 0) ],
+		[ 'm0,0 l1,0 l0,1', [ 1, 0 ], Vec2.of(0, 1) ],
+		[ 'm0,0 l1,0 l0,1', [ 1, 0.5 ], Vec2.of(0, 1) ],
+		[ 'm0,0 l1,0 l0,1', [ 1, 1 ], Vec2.of(0, 1) ],
+
+		// Shape with quadratic Bézier curves
+		[ 'M0,0 Q1,0 0,1', [ 0, 0 ], Vec2.of(1, 0) ],
+		[ 'M0,0 Q1,1 0,1', [ 0, 1 ], Vec2.of(-1, 0) ],
+		[ 'M0,0 Q1,0 1,1 Q0,1 0,2', [ 0, 1 ], Vec2.of(0, 1) ],
+		[ 'M0,0 Q1,0 1,1 Q0,1 0,2', [ 1, 1 ], Vec2.of(0, 1) ],
+	])('.tangentAt should point in the direction of increasing parameter values, for curve %s at %j', (pathString, evalAt, expected) => {
+		const at: CurveIndexRecord = { curveIndex: evalAt[0], parameterValue: evalAt[1] };
+		const path = Path.fromString(pathString);
+		expect(path.tangentAt(at)).objEq(expected);
+	});
 });