@js-draw/math 1.11.1 → 1.17.0

package/src/rounding/getLenAfterDecimal.ts

@@ -0,0 +1,29 @@
+import { numberRegex } from './constants';
+
+
+/**
+ * Returns the length of `numberAsString` after a decimal point.
+ *
+ * For example,
+ * ```ts
+ * getLenAfterDecimal('1.001') // -> 3
+ * ```
+ */
+export const getLenAfterDecimal = (numberAsString: string) => {
+	const numberMatch = numberRegex.exec(numberAsString);
+	if (!numberMatch) {
+		// If not a match, either the number is exponential notation (or is something
+		// like NaN or Infinity)
+		if (numberAsString.search(/[eE]/) !== -1 || /^[a-zA-Z]+$/.exec(numberAsString)) {
+			return -1;
+		// Or it has no decimal point
+		} else {
+			return 0;
+		}
+	}
+
+	const afterDecimalLen = numberMatch[3].length;
+	return afterDecimalLen;
+};
+
+export default getLenAfterDecimal;

package/src/rounding/lib.ts

@@ -0,0 +1,2 @@
+
+export { toRoundedString } from './toRoundedString';

package/src/rounding/toRoundedString.test.ts

@@ -0,0 +1,32 @@
+import { toRoundedString } from './toRoundedString';
+
+describe('toRoundedString', () => {
+	it('should round up numbers endings similar to .999999999999999', () => {
+		expect(toRoundedString(0.999999999)).toBe('1');
+		expect(toRoundedString(0.899999999)).toBe('.9');
+		expect(toRoundedString(9.999999999)).toBe('10');
+		expect(toRoundedString(-10.999999999)).toBe('-11');
+	});
+
+	it('should round up numbers similar to 10.999999998', () => {
+		expect(toRoundedString(10.999999998)).toBe('11');
+	});
+
+	it('should round strings with multiple digits after the ending decimal points', () => {
+		expect(toRoundedString(292.2 - 292.8)).toBe('-.6');
+		expect(toRoundedString(4.06425600000023)).toBe('4.064256');
+	});
+
+	it('should round down strings ending endings similar to .00000001', () => {
+		expect(toRoundedString(10.00000001)).toBe('10');
+		expect(toRoundedString(-30.00000001)).toBe('-30');
+		expect(toRoundedString(-14.20000000000002)).toBe('-14.2');
+	});
+
+	it('should not round numbers insufficiently close to the next', () => {
+		expect(toRoundedString(-10.9999)).toBe('-10.9999');
+		expect(toRoundedString(-10.0001)).toBe('-10.0001');
+		expect(toRoundedString(-10.123499)).toBe('-10.123499');
+		expect(toRoundedString(0.00123499)).toBe('.00123499');
+	});
+});

package/src/rounding/toRoundedString.ts

@@ -0,0 +1,57 @@
+import cleanUpNumber from './cleanUpNumber';
+
+/**
+ * Converts `num` to a string, removing trailing digits that were likely caused by
+ * precision errors.
+ *
+ * @example
+ * ```ts,runnable,console
+ * import { toRoundedString } from '@js-draw/math';
+ *
+ * console.log('Rounded: ', toRoundedString(1.000000011));
+ * ```
+ */
+export const toRoundedString = (num: number): string => {
+	// Try to remove rounding errors. If the number ends in at least three/four zeroes
+	// (or nines) just one or two digits, it's probably a rounding error.
+	const fixRoundingUpExp = /^([-]?\d*\.\d{3,})0{4,}\d{1,4}$/;
+	const hasRoundingDownExp = /^([-]?)(\d*)\.(\d{3,}9{4,})\d{1,4}$/;
+
+	let text = num.toString(10);
+	if (text.indexOf('.') === -1) {
+		return text;
+	}
+
+	const roundingDownMatch = hasRoundingDownExp.exec(text);
+	if (roundingDownMatch) {
+		const negativeSign = roundingDownMatch[1];
+		const postDecimalString = roundingDownMatch[3];
+		const lastDigit = parseInt(postDecimalString.charAt(postDecimalString.length - 1), 10);
+		const postDecimal = parseInt(postDecimalString, 10);
+		const preDecimal = parseInt(roundingDownMatch[2], 10);
+
+		const origPostDecimalString = roundingDownMatch[3];
+
+		let newPostDecimal = (postDecimal + 10 - lastDigit).toString();
+		let carry = 0;
+		if (newPostDecimal.length > postDecimal.toString().length) {
+			// Left-shift
+			newPostDecimal = newPostDecimal.substring(1);
+			carry = 1;
+		}
+
+		// parseInt(...).toString() removes leading zeroes. Add them back.
+		while (newPostDecimal.length < origPostDecimalString.length) {
+			newPostDecimal = carry.toString(10) + newPostDecimal;
+			carry = 0;
+		}
+
+		text = `${negativeSign + (preDecimal + carry).toString()}.${newPostDecimal}`;
+	}
+
+	text = text.replace(fixRoundingUpExp, '$1');
+
+	return cleanUpNumber(text);
+};
+
+export default toRoundedString;

package/src/rounding/toStringOfSamePrecision.test.ts

@@ -0,0 +1,21 @@
+import { toStringOfSamePrecision } from './toStringOfSamePrecision';
+
+
+it('toStringOfSamePrecision', () => {
+	expect(toStringOfSamePrecision(1.23456, '1.12')).toBe('1.23');
+	expect(toStringOfSamePrecision(1.23456, '1.120')).toBe('1.235');
+	expect(toStringOfSamePrecision(1.23456, '1.1')).toBe('1.2');
+	expect(toStringOfSamePrecision(1.23456, '1.1', '5.32')).toBe('1.23');
+	expect(toStringOfSamePrecision(-1.23456, '1.1', '5.32')).toBe('-1.23');
+	expect(toStringOfSamePrecision(-1.99999, '1.1', '5.32')).toBe('-2');
+	expect(toStringOfSamePrecision(1.99999, '1.1', '5.32')).toBe('2');
+	expect(toStringOfSamePrecision(1.89999, '1.1', '5.32')).toBe('1.9');
+	expect(toStringOfSamePrecision(9.99999999, '-1.1234')).toBe('10');
+	expect(toStringOfSamePrecision(9.999999998999996, '100')).toBe('10');
+	expect(toStringOfSamePrecision(0.000012345, '0.000012')).toBe('.000012');
+	expect(toStringOfSamePrecision(0.000012645, '.000012')).toBe('.000013');
+	expect(toStringOfSamePrecision(-0.09999999999999432, '291.3')).toBe('-.1');
+	expect(toStringOfSamePrecision(-0.9999999999999432, '291.3')).toBe('-1');
+	expect(toStringOfSamePrecision(9998.9, '.1', '-11')).toBe('9998.9');
+	expect(toStringOfSamePrecision(-14.20000000000002, '.000001', '-11')).toBe('-14.2');
+});

package/src/rounding/toStringOfSamePrecision.ts

@@ -0,0 +1,63 @@
+import cleanUpNumber from './cleanUpNumber';
+import { numberRegex } from './constants';
+import getLenAfterDecimal from './getLenAfterDecimal';
+import toRoundedString from './toRoundedString';
+
+// [reference] should be a string representation of a base-10 number (no exponential (e.g. 10e10))
+export const toStringOfSamePrecision = (num: number, ...references: string[]): string => {
+	const text = num.toString(10);
+	const textMatch = numberRegex.exec(text);
+	if (!textMatch) {
+		return text;
+	}
+
+	let decimalPlaces = -1;
+	for (const reference of references) {
+		decimalPlaces = Math.max(getLenAfterDecimal(reference), decimalPlaces);
+	}
+
+	if (decimalPlaces === -1) {
+		return toRoundedString(num);
+	}
+
+	// Make text's after decimal length match [afterDecimalLen].
+	let postDecimal = textMatch[3].substring(0, decimalPlaces);
+	let preDecimal = textMatch[2];
+	const nextDigit = textMatch[3].charAt(decimalPlaces);
+
+	if (nextDigit !== '') {
+		const asNumber = parseInt(nextDigit, 10);
+		if (asNumber >= 5) {
+			// Don't attempt to parseInt() an empty string.
+			if (postDecimal.length > 0) {
+				const leadingZeroMatch = /^(0+)(\d*)$/.exec(postDecimal);
+
+				let leadingZeroes = '';
+				let postLeading = postDecimal;
+				if (leadingZeroMatch) {
+					leadingZeroes = leadingZeroMatch[1];
+					postLeading = leadingZeroMatch[2];
+				}
+
+				postDecimal = (parseInt(postDecimal) + 1).toString();
+
+				// If postDecimal got longer, remove leading zeroes if possible
+				if (postDecimal.length > postLeading.length && leadingZeroes.length > 0) {
+					leadingZeroes = leadingZeroes.substring(1);
+				}
+
+				postDecimal = leadingZeroes + postDecimal;
+			}
+
+			if (postDecimal.length === 0 || postDecimal.length > decimalPlaces) {
+				preDecimal = (parseInt(preDecimal) + 1).toString();
+				postDecimal = postDecimal.substring(1);
+			}
+		}
+	}
+
+	const negativeSign = textMatch[1];
+	return cleanUpNumber(`${negativeSign}${preDecimal}.${postDecimal}`);
+};
+
+export default toStringOfSamePrecision;

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;
 

package/src/shapes/BezierJSWrapper.ts

@@ -1,8 +1,8 @@
 import { Bezier } from 'bezier-js';
 import { Point2, Vec2 } from '../Vec2';
-import Abstract2DShape from './Abstract2DShape';
 import LineSegment2 from './LineSegment2';
 import Rect2 from './Rect2';
+import Parameterized2DShape from './Parameterized2DShape';
 
 /**
  * A lazy-initializing wrapper around Bezier-js.
@@ -10,14 +10,24 @@ import Rect2 from './Rect2';
  * Subclasses may override `at`, `derivativeAt`, and `normal` with functions
  * that do not initialize a `bezier-js` `Bezier`.
  *
- * Do not use this class directly. It may be removed/replaced in a future release.
+ * **Do not use this class directly.** It may be removed/replaced in a future release.
  * @internal
  */
-abstract class BezierJSWrapper extends Abstract2DShape {
+export abstract class BezierJSWrapper extends Parameterized2DShape {
 	#bezierJs: Bezier|null = null;
 
+	protected constructor(
+		bezierJsBezier?: Bezier
+	) {
+		super();
+
+		if (bezierJsBezier) {
+			this.#bezierJs = bezierJsBezier;
+		}
+	}
+
 	/** Returns the start, control points, and end point of this Bézier. */
-	public abstract getPoints(): Point2[];
+	public abstract getPoints(): readonly Point2[];
 
 	protected getBezier() {
 		if (!this.#bezierJs) {
@@ -28,7 +38,7 @@ abstract class BezierJSWrapper extends Abstract2DShape {
 
 	public override signedDistance(point: Point2): number {
 		// .d: Distance
-		return this.getBezier().project(point.xy).d!;
+		return this.nearestPointTo(point).point.distanceTo(point);
 	}
 
 	/**
@@ -44,7 +54,7 @@ abstract class BezierJSWrapper extends Abstract2DShape {
 	/**
 	 * @returns the curve evaluated at `t`.
 	 */
-	public at(t: number): Point2 {
+	public override at(t: number): Point2 {
 		return Vec2.ofXY(this.getBezier().get(t));
 	}
 
@@ -52,10 +62,22 @@ abstract class BezierJSWrapper extends Abstract2DShape {
 		return Vec2.ofXY(this.getBezier().derivative(t));
 	}
 
+	public secondDerivativeAt(t: number): Point2 {
+		return Vec2.ofXY((this.getBezier() as any).dderivative(t));
+	}
+
 	public normal(t: number): Vec2 {
 		return Vec2.ofXY(this.getBezier().normal(t));
 	}
 
+	public override normalAt(t: number): Vec2 {
+		return this.normal(t);
+	}
+
+	public override tangentAt(t: number): Vec2 {
+		return this.derivativeAt(t).normalized();
+	}
+
 	public override getTightBoundingBox(): Rect2 {
 		const bbox = this.getBezier().bbox();
 		const width = bbox.x.max - bbox.x.min;
@@ -64,10 +86,10 @@ abstract class BezierJSWrapper extends Abstract2DShape {
 		return new Rect2(bbox.x.min, bbox.y.min, width, height);
 	}
 
-	public override intersectsLineSegment(line: LineSegment2): Point2[] {
+	public override argIntersectsLineSegment(line: LineSegment2): number[] {
 		const bezier = this.getBezier();
 
-		const intersectionPoints = bezier.intersects(line).map(t => {
+		return bezier.intersects(line).map(t => {
 			// We're using the .intersects(line) function, which is documented
 			// to always return numbers. However, to satisfy the type checker (and
 			// possibly improperly-defined types),
@@ -75,18 +97,136 @@ abstract class BezierJSWrapper extends Abstract2DShape {
 				t = parseFloat(t);
 			}
 
-			const point = Vec2.ofXY(bezier.get(t));
+			const point = Vec2.ofXY(this.at(t));
 
 			// Ensure that the intersection is on the line segment
-			if (point.minus(line.p1).magnitude() > line.length
-					|| point.minus(line.p2).magnitude() > line.length) {
+			if (point.distanceTo(line.p1) > line.length
+					|| point.distanceTo(line.p2) > line.length) {
 				return null;
 			}
 
-			return point;
-		}).filter(entry => entry !== null) as Point2[];
+			return t;
+		}).filter(entry => entry !== null) as number[];
+	}
+
+	public override splitAt(t: number): [BezierJSWrapper] | [BezierJSWrapper, BezierJSWrapper] {
+		if (t <= 0 || t >= 1) {
+			return [ this ];
+		}
+
+		const bezier = this.getBezier();
+		const split = bezier.split(t);
+		return [
+			new BezierJSWrapperImpl(split.left.points.map(point => Vec2.ofXY(point)), split.left),
+			new BezierJSWrapperImpl(split.right.points.map(point => Vec2.ofXY(point)), split.right),
+		];
+	}
+
+	public override nearestPointTo(point: Point2) {
+		// One implementation could be similar to this:
+		//   const projection = this.getBezier().project(point);
+		//   return {
+		//    point: Vec2.ofXY(projection),
+		//    parameterValue: projection.t!,
+		//   };
+		// However, Bezier-js is rather impercise (and relies on a lookup table).
+		// Thus, we instead use Newton's Method:
+
+		// We want to find t such that f(t) = |B(t) - p|² is minimized.
+		// Expanding,
+		//   f(t)  = (Bₓ(t) - pₓ)² + (Bᵧ(t) - pᵧ)²
+		// ⇒ f'(t) = Dₜ(Bₓ(t) - pₓ)² + Dₜ(Bᵧ(t) - pᵧ)²
+		// ⇒ f'(t) = 2(Bₓ(t) - pₓ)(Bₓ'(t)) + 2(Bᵧ(t) - pᵧ)(Bᵧ'(t))
+		//         = 2Bₓ(t)Bₓ'(t) - 2pₓBₓ'(t) + 2Bᵧ(t)Bᵧ'(t) - 2pᵧBᵧ'(t)
+		// ⇒ f''(t)= 2Bₓ'(t)Bₓ'(t) + 2Bₓ(t)Bₓ''(t) - 2pₓBₓ''(t) + 2Bᵧ'(t)Bᵧ'(t)
+		//         + 2Bᵧ(t)Bᵧ''(t) - 2pᵧBᵧ''(t)
+		// Because f'(t) = 0 at relative extrema, we can use Newton's Method
+		// to improve on an initial guess.
+
+		const sqrDistAt = (t: number) => point.squareDistanceTo(this.at(t));
+		const yIntercept = sqrDistAt(0);
+		let t = 0;
+		let minSqrDist = yIntercept;
+
+		// Start by testing a few points:
+		const pointsToTest = 4;
+		for (let i = 0; i < pointsToTest; i ++) {
+			const testT = i / (pointsToTest - 1);
+			const testMinSqrDist = sqrDistAt(testT);
+
+			if (testMinSqrDist < minSqrDist) {
+				t = testT;
+				minSqrDist = testMinSqrDist;
+			}
+		}
+
+		// To use Newton's Method, we need to evaluate the second derivative of the distance
+		// function:
+		const secondDerivativeAt = (t: number) => {
+			// f''(t) = 2Bₓ'(t)Bₓ'(t) + 2Bₓ(t)Bₓ''(t) - 2pₓBₓ''(t)
+			//        + 2Bᵧ'(t)Bᵧ'(t) + 2Bᵧ(t)Bᵧ''(t) - 2pᵧBᵧ''(t)
+			const b = this.at(t);
+			const bPrime = this.derivativeAt(t);
+			const bPrimePrime = this.secondDerivativeAt(t);
+			return (
+				2 * bPrime.x * bPrime.x  +  2 * b.x * bPrimePrime.x  -  2 * point.x * bPrimePrime.x
+				+ 2 * bPrime.y * bPrime.y  +  2 * b.y * bPrimePrime.y  -  2 * point.y * bPrimePrime.y
+			);
+		};
+		// Because we're zeroing f'(t), we also need to be able to compute it:
+		const derivativeAt = (t: number) => {
+			// f'(t) = 2Bₓ(t)Bₓ'(t) - 2pₓBₓ'(t) + 2Bᵧ(t)Bᵧ'(t) - 2pᵧBᵧ'(t)
+			const b = this.at(t);
+			const bPrime = this.derivativeAt(t);
+			return (
+				2 * b.x * bPrime.x - 2 * point.x * bPrime.x
+				+ 2 * b.y * bPrime.y - 2 * point.y * bPrime.y
+			);
+		};
+
+		const iterate = () => {
+			const slope = secondDerivativeAt(t);
+			// 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
+			// ⇒  x = (y - y₀) / m + x₀
+			//
+			// Thus, when zeroed,
+			//   tN = (0 - f'(t)) / m + t
+			const newT = (0 - derivativeAt(t)) / slope + t;
+			//const distDiff = sqrDistAt(newT) - sqrDistAt(t);
+			//console.assert(distDiff <= 0, `${-distDiff} >= 0`);
+			t = newT;
+			if (t > 1) {
+				t = 1;
+			} else if (t < 0) {
+				t = 0;
+			}
+		};
+
+		for (let i = 0; i < 12; i++) {
+			iterate();
+		}
+
+		return { parameterValue: t, point: this.at(t) };
+	}
+
+	public override toString() {
+		return `Bézier(${this.getPoints().map(point => point.toString()).join(', ')})`;
+	}
+}
+
+/**
+ * Private concrete implementation of `BezierJSWrapper`, used by methods above that need to return a wrapper
+ * around a `Bezier`.
+ */
+class BezierJSWrapperImpl extends BezierJSWrapper {
+	public constructor(private controlPoints: readonly Point2[], curve?: Bezier) {
+		super(curve);
+	}
 
-		return intersectionPoints;
+	public override getPoints() {
+		return this.controlPoints;
 	}
 }
 

package/src/shapes/LineSegment2.test.ts

@@ -28,7 +28,7 @@ describe('Line2', () => {
 
 		expect(line1.intersection(line2)?.point).objEq(Vec2.of(0, 10));
 
-		// t=10 implies 10 units along he line from (10, 10) to (-10, 10)
+		// t=10 implies 10 units along the line from (10, 10) to (-10, 10)
 		expect(line1.intersection(line2)?.t).toBe(10);
 
 		// Similarly, t = 12 implies 12 units above (0, -2) in the direction of (0, 200)
@@ -96,4 +96,38 @@ describe('Line2', () => {
 			p2: Vec2.of(3, 98),
 		});
 	});
+
+	it.each([
+		{ from: Vec2.of(0, 0), to: Vec2.of(2, 2) },
+		{ from: Vec2.of(100, 0), to: Vec2.of(2, 2) },
+	])('should be able to split a line segment between %j', ({ from, to }) => {
+		const midpoint = from.lerp(to, 0.5);
+		const lineSegment = new LineSegment2(from, to);
+
+		// Halving
+		//
+		expect(lineSegment.at(0.5)).objEq(midpoint);
+		const [ firstHalf, secondHalf ] = lineSegment.splitAt(0.5);
+
+		if (!secondHalf) {
+			throw new Error('Splitting a line segment in half should yield two line segments.');
+		}
+
+		expect(firstHalf.p2).objEq(midpoint);
+		expect(firstHalf.p1).objEq(from);
+		expect(secondHalf.p2).objEq(to);
+		expect(secondHalf.p1).objEq(midpoint);
+
+		// Before start/end
+		expect(lineSegment.splitAt(0)[0]).objEq(lineSegment);
+		expect(lineSegment.splitAt(0)).toHaveLength(1);
+		expect(lineSegment.splitAt(1)).toHaveLength(1);
+		expect(lineSegment.splitAt(2)).toHaveLength(1);
+	});
+
+	it('equivalence check should allow ignoring direction', () => {
+		expect(new LineSegment2(Vec2.zero, Vec2.unitX)).objEq(new LineSegment2(Vec2.zero, Vec2.unitX));
+		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 });
+	});
 });

package/src/shapes/LineSegment2.ts

@@ -1,7 +1,8 @@
 import Mat33 from '../Mat33';
 import Rect2 from './Rect2';
 import { Vec2, Point2 } from '../Vec2';
-import Abstract2DShape from './Abstract2DShape';
+import Parameterized2DShape from './Parameterized2DShape';
+import Vec3 from '../Vec3';
 
 interface IntersectionResult {
 	point: Point2;
@@ -9,7 +10,7 @@ interface IntersectionResult {
 }
 
 /** Represents a line segment. A `LineSegment2` is immutable. */
-export class LineSegment2 extends Abstract2DShape {
+export class LineSegment2 extends Parameterized2DShape {
 	// invariant: ||direction|| = 1
 
 	/**
@@ -58,8 +59,12 @@ export class LineSegment2 extends Abstract2DShape {
 		return this.point2;
 	}
 
+	public get center(): Point2 {
+		return this.point1.lerp(this.point2, 0.5);
+	}
+
 	/**
-	 * Gets a point a distance `t` along this line.
+	 * Gets a point a **distance** `t` along this line.
 	 *
 	 * @deprecated
 	 */
@@ -74,11 +79,40 @@ export class LineSegment2 extends Abstract2DShape {
 	 *
 	 * `t` should be in `[0, 1]`.
 	 */
-	public at(t: number): Point2 {
+	public override at(t: number): Point2 {
 		return this.get(t * this.length);
 	}
 
+	public override normalAt(_t: number): Vec2 {
+		return this.direction.orthog();
+	}
+
+	public override tangentAt(_t: number): Vec3 {
+		return this.direction;
+	}
+
+	public splitAt(t: number): [LineSegment2]|[LineSegment2,LineSegment2] {
+		if (t <= 0 || t >= 1) {
+			return [this];
+		}
+
+		return [
+			new LineSegment2(this.point1, this.at(t)),
+			new LineSegment2(this.at(t), this.point2),
+		];
+	}
+
+	/**
+	 * Returns the intersection of this with another line segment.
+	 *
+	 * **WARNING**: The parameter value returned by this method does not range from 0 to 1 and
+	 *              is currently a length.
+	 *              This will change in a future release.
+	 * @deprecated
+	 */
 	public intersection(other: LineSegment2): IntersectionResult|null {
+		// TODO(v2.0.0): Make this return a `t` value from `0` to `1`.
+
 		// We want x₁(t) = x₂(t) and y₁(t) = y₂(t)
 		// Observe that
 		// x = this.point1.x + this.direction.x · t₁
@@ -146,10 +180,10 @@ export class LineSegment2 extends Abstract2DShape {
 		}
 
 		// Ensure the result is in this/the other segment.
-		const resultToP1 = resultPoint.minus(this.point1).magnitude();
-		const resultToP2 = resultPoint.minus(this.point2).magnitude();
-		const resultToP3 = resultPoint.minus(other.point1).magnitude();
-		const resultToP4 = resultPoint.minus(other.point2).magnitude();
+		const resultToP1 = resultPoint.distanceTo(this.point1);
+		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
@@ -167,6 +201,15 @@ export class LineSegment2 extends Abstract2DShape {
 		return this.intersection(other) !== null;
 	}
 
+	public override argIntersectsLineSegment(lineSegment: LineSegment2) {
+		const intersection = this.intersection(lineSegment);
+
+		if (intersection) {
+			return [ intersection.t / this.length ];
+		}
+		return [];
+	}
+
 	/**
 	 * Returns the points at which this line segment intersects the
 	 * given line segment.
@@ -186,6 +229,10 @@ export class LineSegment2 extends Abstract2DShape {
 
 	// Returns the closest point on this to [target]
 	public closestPointTo(target: Point2) {
+		return this.nearestPointTo(target).point;
+	}
+
+	public override nearestPointTo(target: Vec3): { point: Vec3; parameterValue: number; } {
 		// Distance from P1 along this' direction.
 		const projectedDistFromP1 = target.minus(this.p1).dot(this.direction);
 		const projectedDistFromP2 = this.length - projectedDistFromP1;
@@ -193,13 +240,13 @@ export class LineSegment2 extends Abstract2DShape {
 		const projection = this.p1.plus(this.direction.times(projectedDistFromP1));
 
 		if (projectedDistFromP1 > 0 && projectedDistFromP1 < this.length) {
-			return projection;
+			return { point: projection, parameterValue: projectedDistFromP1 / this.length };
 		}
 
 		if (Math.abs(projectedDistFromP2) < Math.abs(projectedDistFromP1)) {
-			return this.p2;
+			return { point: this.p2, parameterValue: 1 };
 		} else {
-			return this.p1;
+			return { point: this.p1, parameterValue: 0 };
 		}
 	}
 
@@ -228,5 +275,26 @@ export class LineSegment2 extends Abstract2DShape {
 	public override toString() {
 		return `LineSegment(${this.p1.toString()}, ${this.p2.toString()})`;
 	}
+
+	/**
+	 * Returns `true` iff this is equivalent to `other`.
+	 *
+	 * **Options**:
+	 * - `tolerance`: The maximum difference between endpoints. (Default: 0)
+	 * - `ignoreDirection`: Allow matching a version of `this` with opposite direction. (Default: `true`)
+	 */
+	public eq(other: LineSegment2, options?: { tolerance?: number, ignoreDirection?: boolean }) {
+		if (!(other instanceof LineSegment2)) {
+			return false;
+		}
+
+		const tolerance = options?.tolerance;
+		const ignoreDirection = options?.ignoreDirection ?? true;
+
+		return (
+			(other.p1.eq(this.p1, tolerance) && other.p2.eq(this.p2, tolerance))
+			|| (ignoreDirection && other.p1.eq(this.p2, tolerance) && other.p2.eq(this.p1, tolerance))
+		);
+	}
 }
 export default LineSegment2;