js-draw 0.1.11 → 0.2.0

package/src/{geometry → math}/Mat33.ts

@@ -1,15 +1,22 @@
 import { Point2, Vec2 } from './Vec2';
 import Vec3 from './Vec3';
 
-// Represents a three dimensional linear transformation or
-// a two-dimensional affine transformation. (An affine transformation scales/rotates/shears
-// **and** translates while a linear transformation just scales/rotates/shears).
+/**
+ * Represents a three dimensional linear transformation or
+ * a two-dimensional affine transformation. (An affine transformation scales/rotates/shears
+ * **and** translates while a linear transformation just scales/rotates/shears).
+ */
 export default class Mat33 {
 	private readonly rows: Vec3[];
 
-	// ⎡ a1 a2 a3 ⎤
-	// ⎢ b1 b2 b3 ⎥
-	// ⎣ c1 c2 c3 ⎦
+	/**
+	 * Creates a matrix from inputs in the form,
+	 * ```
+	 * ⎡ a1 a2 a3 ⎤
+	 * ⎢ b1 b2 b3 ⎥
+	 * ⎣ c1 c2 c3 ⎦
+	 * ```
+	 */
 	public constructor(
 		public readonly a1: number,
 		public readonly a2: number,
@@ -30,6 +37,14 @@ export default class Mat33 {
 		];
 	}
 
+	/**
+	 * Creates a matrix from the given rows:
+	 * ```
+	 *  ⎡ r1.x r1.y r1.z ⎤
+	 *  ⎢ r2.x r2.y r2.z ⎥
+	 *  ⎣ r3.x r3.y r3.z ⎦
+	 * ```
+	 */
 	public static ofRows(r1: Vec3, r2: Vec3, r3: Vec3): Mat33 {
 		return new Mat33(
 			r1.x, r1.y, r1.z,
@@ -44,8 +59,13 @@ export default class Mat33 {
 		0, 0, 1
 	);
 
-	// Either returns the inverse of this, or, if this matrix is singular/uninvertable,
-	// returns Mat33.identity.
+	/**
+	 * Either returns the inverse of this, or, if this matrix is singular/uninvertable,
+	 * returns Mat33.identity.
+	 * 
+	 * This may cache the computed inverse and return the cached version instead of recomputing
+	 * it.
+	 */
 	public inverse(): Mat33 {
 		return this.computeInverse() ?? Mat33.identity;
 	}
@@ -162,9 +182,11 @@ export default class Mat33 {
 		);
 	}
 
-	// Applies this as an affine transformation to the given vector.
-	// Returns a transformed version of [other].
-	public transformVec2(other: Vec3): Vec2 {
+	/**
+	 * Applies this as an affine transformation to the given vector.
+	 * Returns a transformed version of `other`.
+	 */
+	public transformVec2(other: Vec2): Vec2 {
 		// When transforming a Vec2, we want to use the z transformation
 		// components of this for translation:
 		//  ⎡ . . tX ⎤
@@ -179,8 +201,10 @@ export default class Mat33 {
 		return Vec2.of(intermediate.x, intermediate.y);
 	}
 
-	// Applies this as a linear transformation to the given vector (doesn't translate).
-	// This is the standard way of transforming vectors in ℝ³.
+	/**
+	 * Applies this as a linear transformation to the given vector (doesn't translate).
+	 * This is the standard way of transforming vectors in ℝ³.
+	 */
 	public transformVec3(other: Vec3): Vec3 {
 		return Vec3.of(
 			this.rows[0].dot(other),
@@ -189,7 +213,7 @@ export default class Mat33 {
 		);
 	}
 
-	// Returns true iff this = other ± fuzz
+	/** Returns true iff this = other ± fuzz */
 	public eq(other: Mat33, fuzz: number = 0): boolean {
 		for (let i = 0; i < 3; i++) {
 			if (!this.rows[i].eq(other.rows[i], fuzz)) {
@@ -205,12 +229,16 @@ export default class Mat33 {
 ⎡ ${this.a1},\t ${this.a2},\t ${this.a3}\t ⎤
 ⎢ ${this.b1},\t ${this.b2},\t ${this.b3}\t ⎥
 ⎣ ${this.c1},\t ${this.c2},\t ${this.c3}\t ⎦
-		`.trimRight();
+		`.trimEnd().trimStart();
 	}
 
-	// result[0] = top left element
-	// result[1] = element at row zero, column 1
-	// ...
+	/**
+	 * ```
+	 * result[0] = top left element
+	 * result[1] = element at row zero, column 1
+	 * ...
+	 * ```
+	 */
 	public toArray(): number[] {
 		return [
 			this.a1, this.a2, this.a3,
@@ -219,7 +247,7 @@ export default class Mat33 {
 		];
 	}
 
-	// Constructs a 3x3 translation matrix (for translating Vec2s)
+	/** Constructs a 3x3 translation matrix (for translating `Vec2`s) */
 	public static translation(amount: Vec2): Mat33 {
 		// When transforming Vec2s by a 3x3 matrix, we give the input
 		// Vec2s z = 1. As such,
@@ -269,7 +297,7 @@ export default class Mat33 {
 		return result.rightMul(Mat33.translation(center.times(-1)));
 	}
 
-	// Converts a CSS-form matrix(a, b, c, d, e, f) to a Mat33.
+	/** Converts a CSS-form `matrix(a, b, c, d, e, f)` to a Mat33. */
 	public static fromCSSMatrix(cssString: string): Mat33 {
 		if (cssString === '' || cssString === 'none') {
 			return Mat33.identity;

package/src/{geometry → math}/Path.toString.test.ts

@@ -15,7 +15,7 @@ describe('Path.toString', () => {
 				point: Vec2.of(0.3, 0.4),
 			},
 		]);
-		expect(path.toString()).toBe('M0.1,0.2L0.3,0.4');
+		expect(path.toString()).toBe('M.1,.2L.3,.4');
 	});
 
 	it('should fix rounding errors', () => {
@@ -30,7 +30,8 @@ describe('Path.toString', () => {
 				point: Vec2.of(184.00482359999998, 1)
 			}
 		]);
-		expect(path.toString()).toBe('M0.1,0.2Q9999,-11 0.0003,1.4L184.0048236,1');
+
+		expect(path.toString()).toBe('M.1,.2Q9999,-11 .0003,1.4L184.0048236,1');
 	});
 
 	it('should not remove trailing zeroes before decimal points', () => {
@@ -40,6 +41,14 @@ describe('Path.toString', () => {
 				point: Vec2.of(30.0001, 40.000000001),
 			},
 		]);
+
 		expect(path.toString()).toBe('M1000,2000000L30.0001,40');
 	});
+
+	it('deserialized path should serialize to the same/similar path, but with rounded components', () => {
+		const path1 = Path.fromString('M100,100 L101,101 Q102,102 90.000000001,89.99999999 Z');
+		expect(path1.toString()).toBe([
+			'M100,100', 'L101,101', 'Q102,102 90,90', 'L100,100'
+		].join(''));
+	});
 });

package/src/{geometry → math}/Path.ts

@@ -1,6 +1,7 @@
 import { Bezier } from 'bezier-js';
 import { RenderablePathSpec } from '../rendering/renderers/AbstractRenderer';
 import RenderingStyle from '../rendering/RenderingStyle';
+import { toRoundedString, toStringOfSamePrecision } from './rounding';
 import LineSegment2 from './LineSegment2';
 import Mat33 from './Mat33';
 import Rect2 from './Rect2';
@@ -170,8 +171,8 @@ export default class Path {
 		return result;
 	}
 
-	public transformedBy(affineTransfm: Mat33): Path {
-		const startPoint = affineTransfm.transformVec2(this.startPoint);
+	public mapPoints(mapping: (point: Point2)=>Point2): Path {
+		const startPoint = mapping(this.startPoint);
 		const newParts: PathCommand[] = [];
 
 		let exhaustivenessCheck: never;
@@ -181,22 +182,22 @@ export default class Path {
 			case PathCommandType.LineTo:
 				newParts.push({
 					kind: part.kind,
-					point: affineTransfm.transformVec2(part.point),
+					point: mapping(part.point),
 				});
 				break;
 			case PathCommandType.CubicBezierTo:
 				newParts.push({
 					kind: part.kind,
-					controlPoint1: affineTransfm.transformVec2(part.controlPoint1),
-					controlPoint2: affineTransfm.transformVec2(part.controlPoint2),
-					endPoint: affineTransfm.transformVec2(part.endPoint),
+					controlPoint1: mapping(part.controlPoint1),
+					controlPoint2: mapping(part.controlPoint2),
+					endPoint: mapping(part.endPoint),
 				});
 				break;
 			case PathCommandType.QuadraticBezierTo:
 				newParts.push({
 					kind: part.kind,
-					controlPoint: affineTransfm.transformVec2(part.controlPoint),
-					endPoint: affineTransfm.transformVec2(part.endPoint),
+					controlPoint: mapping(part.controlPoint),
+					endPoint: mapping(part.endPoint),
 				});
 				break;
 			default:
@@ -208,6 +209,10 @@ export default class Path {
 		return new Path(startPoint, newParts);
 	}
 
+	public transformedBy(affineTransfm: Mat33): Path {
+		return this.mapPoints(point => affineTransfm.transformVec2(point));
+	}
+
 	// Creates a new path by joining [other] to the end of this path
 	public union(other: Path|null): Path {
 		if (!other) {
@@ -280,71 +285,69 @@ export default class Path {
 	}
 
 	public toString(): string {
-		return Path.toString(this.startPoint, this.parts);
+		// Hueristic: Try to determine whether converting absolute to relative commands is worth it.
+		//            If we're near (0, 0), it probably isn't worth it and if bounding boxes are large,
+		//            it also probably isn't worth it.
+		const makeRelativeCommands =
+			Math.abs(this.bbox.topLeft.x) > 10 && Math.abs(this.bbox.size.x) < 2
+			&& Math.abs(this.bbox.topLeft.y) > 10 && Math.abs(this.bbox.size.y) < 2;
+
+		return Path.toString(this.startPoint, this.parts, !makeRelativeCommands);
 	}
 
 	public serialize(): string {
 		return this.toString();
 	}
 
-	public static toString(startPoint: Point2, parts: PathCommand[]): string {
+	// @param onlyAbsCommands - True if we should avoid converting absolute coordinates to relative offsets -- such
+	//   conversions can lead to smaller output strings, but also take time.
+	public static toString(startPoint: Point2, parts: PathCommand[], onlyAbsCommands: boolean = true): string {
 		const result: string[] = [];
 
-		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$/;
-			const hasRoundingDownExp = /^([-]?)(\d*)\.(\d{3,}9{4,}\d)$/;
-
-			let text = num.toString();
-			if (text.indexOf('.') === -1) {
-				return text;
-			}
+		let prevPoint: Point2|undefined;
+		const addCommand = (command: string, ...points: Point2[]) => {
+			const absoluteCommandParts: string[] = [];
+			const relativeCommandParts: string[] = [];
+			const makeAbsCommand = !prevPoint || onlyAbsCommands;
+			const roundedPrevX = prevPoint ? toRoundedString(prevPoint.x) : '';
+			const roundedPrevY = prevPoint ? toRoundedString(prevPoint.y) : '';
 
-			const roundingDownMatch = hasRoundingDownExp.exec(text);
-			if (roundingDownMatch) {
-				const negativeSign = roundingDownMatch[1];
-				const lastDigit = parseInt(text.charAt(text.length - 1), 10);
-				const postDecimal = parseInt(roundingDownMatch[3], 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;
-				}
+			for (const point of points) {
+				// Relative commands are often shorter as strings than absolute commands.
+				if (!makeAbsCommand) {
+					const xComponentRelative = toStringOfSamePrecision(point.x - prevPoint!.x, roundedPrevX, roundedPrevY);
+					const yComponentRelative = toStringOfSamePrecision(point.y - prevPoint!.y, roundedPrevX, roundedPrevY);
+
+					// No need for an additional separator if it starts with a '-'
+					if (yComponentRelative.charAt(0) === '-') {
+						relativeCommandParts.push(`${xComponentRelative}${yComponentRelative}`);
+					} else {
+						relativeCommandParts.push(`${xComponentRelative},${yComponentRelative}`);
+					}
+				} else {
+					const xComponent = toRoundedString(point.x);
+					const yComponent = toRoundedString(point.y);
 
-				// parseInt(...).toString() removes leading zeroes. Add them back.
-				while (newPostDecimal.length < origPostDecimalString.length) {
-					newPostDecimal = carry.toString(10) + newPostDecimal;
-					carry = 0;
+					absoluteCommandParts.push(`${xComponent},${yComponent}`);
 				}
-
-				text = `${negativeSign + (preDecimal + carry).toString()}.${newPostDecimal}`;
 			}
 
-			text = text.replace(fixRoundingUpExp, '$1');
-
-			// Remove trailing zeroes
-			text = text.replace(/([.]\d*[^0]+)0+$/, '$1');
-			text = text.replace(/[.]0+$/, '.');
+			let commandString;
+			if (makeAbsCommand) {
+				commandString = `${command}${absoluteCommandParts.join(' ')}`;
+			} else {
+				commandString = `${command.toLowerCase()}${relativeCommandParts.join(' ')}`;
+			}
 
-			// Remove trailing period
-			return text.replace(/[.]$/, '');
-		};
+			// Don't add no-ops.
+			if (commandString === 'l0,0') {
+				return;
+			}
+			result.push(commandString);
 
-		const addCommand = (command: string, ...points: Point2[]) => {
-			const parts: string[] = [];
-			for (const point of points) {
-				const xComponent = toRoundedString(point.x);
-				const yComponent = toRoundedString(point.y);
-				parts.push(`${xComponent},${yComponent}`);
+			if (points.length > 0) {
+				prevPoint = points[points.length - 1];
 			}
-			result.push(`${command}${parts.join(' ')}`);
 		};
 
 		addCommand('M', startPoint);
@@ -374,7 +377,7 @@ export default class Path {
 
 	// Create a Path from a SVG path specification.
 	// TODO: Support a larger subset of SVG paths.
-	// TODO: Support s,t shorthands.
+	// TODO: Support `s`,`t` commands shorthands.
 	public static fromString(pathString: string): Path {
 		// See the MDN reference:
 		// https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/d

package/src/{geometry → math}/Rect2.ts

@@ -2,8 +2,8 @@ import LineSegment2 from './LineSegment2';
 import Mat33 from './Mat33';
 import { Point2, Vec2 } from './Vec2';
 
-// An object that can be converted to a Rect2.
-interface RectTemplate {
+/** An object that can be converted to a Rect2. */
+export interface RectTemplate {
 	x: number;
 	y: number;
 	w?: number;

package/src/{geometry → math}/Vec3.ts

@@ -1,6 +1,10 @@
 
 
-// A vector with three components. Can also be used to represent a two-component vector
+/**
+ * A vector with three components. Can also be used to represent a two-component vector.
+ * 
+ * A `Vec3` is immutable.
+ */
 export default class Vec3 {
 	private constructor(
 		public readonly x: number,
@@ -9,7 +13,7 @@ export default class Vec3 {
 	) {
 	}
 
-	// Returns the x, y components of this
+	/** Returns the x, y components of this. */
 	public get xy(): { x: number; y: number } {
 		// Useful for APIs that behave differently if .z is present.
 		return {
@@ -22,7 +26,7 @@ export default class Vec3 {
 		return new Vec3(x, y, z);
 	}
 
-	// Returns this' [idx]th component
+	/** Returns this' `idx`th component. For example, `Vec3.of(1, 2, 3).at(1) → 2`. */
 	public at(idx: number): number {
 		if (idx === 0) return this.x;
 		if (idx === 1) return this.y;
@@ -31,7 +35,7 @@ export default class Vec3 {
 		throw new Error(`${idx} out of bounds!`);
 	}
 
-	// Alias for this.magnitude
+	/** Alias for this.magnitude. */
 	public length(): number {
 		return this.magnitude();
 	}
@@ -44,16 +48,26 @@ export default class Vec3 {
 		return this.dot(this);
 	}
 
-	// Return this' angle in the XY plane (treats this as a Vec2)
+	/**
+	 * Return this' angle in the XY plane (treats this as a Vec2).
+	 * 
+	 * This is equivalent to `Math.atan2(vec.y, vec.x)`.
+	 */
 	public angle(): number {
 		return Math.atan2(this.y, this.x);
 	}
 
+	/**
+	 * Returns a unit vector in the same direction as this.
+	 * 
+	 * If `this` has zero length, the resultant vector has `NaN` components.
+	 */
 	public normalized(): Vec3 {
 		const norm = this.magnitude();
 		return Vec3.of(this.x / norm, this.y / norm, this.z / norm);
 	}
 
+	/** @returns A copy of `this` multiplied by a scalar. */
 	public times(c: number): Vec3 {
 		return Vec3.of(this.x * c, this.y * c, this.z * c);
 	}
@@ -81,8 +95,10 @@ export default class Vec3 {
 		);
 	}
 
-	// Returns a vector orthogonal to this. If this is a Vec2, returns [this] rotated
-	// 90 degrees counter-clockwise.
+	/**
+	 * Returns a vector orthogonal to this. If this is a Vec2, returns `this` rotated
+	 * 90 degrees counter-clockwise.
+	 */
 	public orthog(): Vec3 {
 		// If parallel to the z-axis
 		if (this.dot(Vec3.unitX) === 0 && this.dot(Vec3.unitY) === 0) {
@@ -92,18 +108,32 @@ export default class Vec3 {
 		return this.cross(Vec3.unitZ.times(-1)).normalized();
 	}
 
-	// Returns this plus a vector of length [distance] in [direction]
+	/** Returns this plus a vector of length `distance` in `direction`. */
 	public extend(distance: number, direction: Vec3): Vec3 {
 		return this.plus(direction.normalized().times(distance));
 	}
 
-	// Returns a vector [fractionTo] of the way to target from this.
+	/** Returns a vector `fractionTo` of the way to target from this. */
 	public lerp(target: Vec3, fractionTo: number): Vec3 {
 		return this.times(1 - fractionTo).plus(target.times(fractionTo));
 	}
 
-	// [zip] Maps a component of this and a corresponding component of
-	// [other] to a component of the output vector.
+	/**
+	 * `zip` Maps a component of this and a corresponding component of
+	 * `other` to a component of the output vector.
+	 * 
+	 * @example
+	 * ```
+	 * const a = Vec3.of(1, 2, 3);
+	 * const b = Vec3.of(0.5, 2.1, 2.9);
+	 * 
+	 * const zipped = a.zip(b, (aComponent, bComponent) => {
+	 *   return Math.min(aComponent, bComponent);
+	 * });
+	 * 
+	 * console.log(zipped.toString()); // → Vec(0.5, 2, 2.9)
+	 * ```
+	 */
 	public zip(
 		other: Vec3, zip: (componentInThis: number, componentInOther: number)=> number
 	): Vec3 {
@@ -114,10 +144,17 @@ export default class Vec3 {
 		);
 	}
 
-	// Returns a vector with each component acted on by [fn]
-	public map(fn: (component: number)=> number): Vec3 {
+	/**
+	 * Returns a vector with each component acted on by `fn`.
+	 * 
+	 * @example
+	 * ```
+	 * console.log(Vec3.of(1, 2, 3).map(val => val + 1)); // → Vec(2, 3, 4)
+	 * ```
+	 */
+	public map(fn: (component: number, index: number)=> number): Vec3 {
 		return Vec3.of(
-			fn(this.x), fn(this.y), fn(this.z)
+			fn(this.x, 0), fn(this.y, 1), fn(this.z, 2)
 		);
 	}
 
@@ -125,8 +162,19 @@ export default class Vec3 {
 		return [this.x, this.y, this.z];
 	}
 
-	// [fuzz] The maximum difference between two components for this and [other]
-	// to be considered equal.
+	/**
+	 * [fuzz] The maximum difference between two components for this and [other]
+	 * to be considered equal.
+	 * 
+	 * @example
+	 * ```
+	 * Vec3.of(1, 2, 3).eq(Vec3.of(4, 5, 6), 100);  // → true
+	 * Vec3.of(1, 2, 3).eq(Vec3.of(4, 5, 6), 0.1);  // → false
+	 * Vec3.of(1, 2, 3).eq(Vec3.of(4, 5, 6), 3);    // → true
+	 * Vec3.of(1, 2, 3).eq(Vec3.of(4, 5, 6), 3.01); // → true
+	 * Vec3.of(1, 2, 3).eq(Vec3.of(4, 5, 6), 2.99); // → false
+	 * ```
+	 */
 	public eq(other: Vec3, fuzz: number): boolean {
 		for (let i = 0; i < 3; i++) {
 			if (Math.abs(other.at(i) - this.at(i)) > fuzz) {

package/src/math/lib.ts

@@ -0,0 +1,15 @@
+import LineSegment2 from './LineSegment2';
+import Mat33 from './Mat33';
+import Path from './Path';
+import Rect2 from './Rect2';
+import { Vec2 } from './Vec2';
+import Vec3 from './Vec3';
+
+export {
+	LineSegment2,
+	Mat33,
+	Path,
+	Rect2,
+	Vec3,
+	Vec2,
+};

package/src/math/rounding.test.ts

@@ -0,0 +1,40 @@
+import { toRoundedString, toStringOfSamePrecision } from './rounding';
+
+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');
+	});
+
+	// Handling this creates situations with potential error:
+	//it('should round strings with multiple digits after the ending decimal points', () => {
+	//	expect(toRoundedString(292.2 - 292.8)).toBe('-0.6');
+	//});
+
+	it('should round down strings ending endings similar to .00000001', () => {
+		expect(toRoundedString(10.00000001)).toBe('10');
+	});
+});
+
+it('toStringOfSamePrecision', () => {
+	expect(toStringOfSamePrecision(1.23456, '1.12')).toBe('1.23');
+	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');
+});