@js-draw/math 1.21.3 → 1.23.1

package/src/Color4.ts

@@ -25,9 +25,8 @@ export class Color4 {
 		public readonly b: number,
 
 		/** Alpha/transparent component. ${\tt a} \in [0, 1]$. 0 = transparent */
-		public readonly a: number
-	) {
-	}
+		public readonly a: number,
+	) {}
 
 	/**
 	 * Create a color from red, green, blue components. The color is fully opaque (`a = 1.0`).
@@ -38,6 +37,10 @@ export class Color4 {
 		return Color4.ofRGBA(red, green, blue, 1.0);
 	}
 
+	/**
+	 * Creates a color from red, green, blue, and transparency components. Each component should
+	 * be in the range $[0, 1]$.
+	 */
 	public static ofRGBA(red: number, green: number, blue: number, alpha: number): Color4 {
 		red = Math.max(0, Math.min(red, 1));
 		green = Math.max(0, Math.min(green, 1));
@@ -47,6 +50,40 @@ export class Color4 {
 		return new Color4(red, green, blue, alpha);
 	}
 
+	/**
+	 * Creates a color from an RGB (or RGBA) array.
+	 *
+	 * This is similar to {@link ofRGB} and {@link ofRGBA}, but, by default, takes values
+	 * that range from 0 to 255.
+	 *
+	 * If the array values instead range from 0-1, pass `maxValue` as `1`.
+	 */
+	public static fromRGBArray(
+		array: Uint8Array | Uint8ClampedArray | number[],
+		maxValue: number = 255,
+	) {
+		const red = array[0];
+		const green = array[1] ?? red;
+		const blue = array[2] ?? red;
+
+		let alpha = 255;
+		if (3 < array.length) {
+			alpha = array[3];
+		}
+
+		return Color4.ofRGBA(red / maxValue, green / maxValue, blue / maxValue, alpha / maxValue);
+	}
+
+	/**
+	 * Creates a `Color4` from a three or four-component hexadecimal
+	 * [color string](https://en.wikipedia.org/wiki/Web_colors#Hex_triplet).
+	 *
+	 * Example:
+	 * ```ts,runnable,console
+	 * import { Color4 } from '@js-draw/math';
+	 * console.log(Color4.fromHex('#ff0'));
+	 * ```
+	 */
 	public static fromHex(hexString: string): Color4 {
 		// Remove starting '#' (if present)
 		hexString = (hexString.match(/^[#]?(.*)$/) ?? [])[1];
@@ -62,7 +99,7 @@ export class Color4 {
 			const components = hexString.split('');
 
 			// Convert to RRGGBBAA or RRGGBB format
-			hexString = components.map(component => `${component}0`).join('');
+			hexString = components.map((component) => `${component}0`).join('');
 		}
 
 		if (hexString.length === 6) {
@@ -83,7 +120,7 @@ export class Color4 {
 		return Color4.ofRGBA(components[0], components[1], components[2], components[3]);
 	}
 
-	/** Like fromHex, but can handle additional colors if an `HTMLCanvasElement` is available. */
+	/** Like {@link fromHex}, but can handle additional colors if an `HTMLCanvasElement` is available. */
 	public static fromString(text: string): Color4 {
 		if (text.startsWith('#')) {
 			return Color4.fromHex(text);
@@ -108,14 +145,21 @@ export class Color4 {
 
 			if (componentsList.length === 3) {
 				return Color4.ofRGB(
-					componentsList[0] / 255, componentsList[1] / 255, componentsList[2] / 255
+					componentsList[0] / 255,
+					componentsList[1] / 255,
+					componentsList[2] / 255,
 				);
 			} else if (componentsList.length === 4) {
 				return Color4.ofRGBA(
-					componentsList[0] / 255, componentsList[1] / 255, componentsList[2] / 255, componentsList[3]
+					componentsList[0] / 255,
+					componentsList[1] / 255,
+					componentsList[2] / 255,
+					componentsList[3],
 				);
 			} else {
-				throw new Error(`RGB string, ${text}, has wrong number of components: ${componentsList.length}`);
+				throw new Error(
+					`RGB string, ${text}, has wrong number of components: ${componentsList.length}`,
+				);
 			}
 		}
 
@@ -145,7 +189,7 @@ export class Color4 {
 	}
 
 	/** @returns true if `this` and `other` are approximately equal. */
-	public eq(other: Color4|null|undefined): boolean {
+	public eq(other: Color4 | null | undefined): boolean {
 		if (other == null) {
 			return false;
 		}
@@ -202,7 +246,7 @@ export class Color4 {
 		// - https://stackoverflow.com/a/9733420
 
 		// Normalize the components, as per above
-		const components = [ this.r, this.g, this.b ].map(component => {
+		const components = [this.r, this.g, this.b].map((component) => {
 			if (component < 0.03928) {
 				return component / 12.92;
 			} else {
@@ -358,24 +402,23 @@ export class Color4 {
 
 		let rgb;
 		if (huePrime < 1) {
-			rgb = [ chroma, secondLargestComponent, 0 ];
+			rgb = [chroma, secondLargestComponent, 0];
 		} else if (huePrime < 2) {
-			rgb = [ secondLargestComponent, chroma, 0 ];
+			rgb = [secondLargestComponent, chroma, 0];
 		} else if (huePrime < 3) {
-			rgb = [ 0, chroma, secondLargestComponent ];
+			rgb = [0, chroma, secondLargestComponent];
 		} else if (huePrime < 4) {
-			rgb = [ 0, secondLargestComponent, chroma ];
+			rgb = [0, secondLargestComponent, chroma];
 		} else if (huePrime < 5) {
-			rgb = [ secondLargestComponent, 0, chroma ];
+			rgb = [secondLargestComponent, 0, chroma];
 		} else {
-			rgb = [ chroma, 0, secondLargestComponent ];
+			rgb = [chroma, 0, secondLargestComponent];
 		}
 
 		const adjustment = value - chroma;
 		return Color4.ofRGB(rgb[0] + adjustment, rgb[1] + adjustment, rgb[2] + adjustment);
 	}
 
-
 	/**
 	 * Equivalent to `ofRGB(rgb.x, rgb.y, rgb.z)`.
 	 *
@@ -385,7 +428,7 @@ export class Color4 {
 		return Color4.ofRGBA(rgb.x, rgb.y, rgb.z, alpha ?? 1);
 	}
 
-	private hexString: string|null = null;
+	private hexString: string | null = null;
 
 	/**
 	 * @returns a hexadecimal color string representation of `this`, in the form `#rrggbbaa`.

package/src/Mat33.fromCSSMatrix.test.ts

@@ -2,65 +2,51 @@ import Mat33 from './Mat33';
 import { Vec2 } from './Vec2';
 
 describe('Mat33.fromCSSMatrix', () => {
-	it('should convert CSS matrix(...) strings to matricies', () => {
+	it('should convert CSS matrix(...) strings to matrices', () => {
 		// From MDN:
 		// 		⎡ a c e ⎤
 		// 		⎢ b d f ⎥  =  matrix(a,b,c,d,e,f)
 		// 		⎣ 0 0 1 ⎦
 		const identity = Mat33.fromCSSMatrix('matrix(1, 0, 0, 1, 0, 0)');
 		expect(identity).objEq(Mat33.identity);
-		expect(Mat33.fromCSSMatrix('matrix(1, 2, 3, 4, 5, 6)')).objEq(new Mat33(
-			1, 3, 5,
-			2, 4, 6,
-			0, 0, 1,
-		));
-		expect(Mat33.fromCSSMatrix('matrix(1e2, 2, 3, 4, 5, 6)')).objEq(new Mat33(
-			1e2, 3, 5,
-			2, 4, 6,
-			0, 0, 1,
-		));
-		expect(Mat33.fromCSSMatrix('matrix(1.6, 2, .3, 4, 5, 6)')).objEq(new Mat33(
-			1.6, .3, 5,
-			2, 4, 6,
-			0, 0, 1,
-		));
-		expect(Mat33.fromCSSMatrix('matrix(-1, 2, 3.E-2, 4, -5.123, -6.5)')).objEq(new Mat33(
-			-1, 0.03, -5.123,
-			2, 4, -6.5,
-			0, 0, 1,
-		));
-		expect(Mat33.fromCSSMatrix('matrix(1.6,\n\t2, .3, 4, 5, 6)')).objEq(new Mat33(
-			1.6, .3, 5,
-			2, 4, 6,
-			0, 0, 1,
-		));
-		expect(Mat33.fromCSSMatrix('matrix(1.6,2, .3E-2, 4, 5, 6)')).objEq(new Mat33(
-			1.6, 3e-3, 5,
-			2, 4, 6,
-			0, 0, 1,
-		));
-		expect(Mat33.fromCSSMatrix('matrix(-1, 2e6,	3E-2,-5.123, -6.5e-1, 0.01)')).objEq(new Mat33(
-			-1, 	3E-2,  	-6.5e-1,
-			2e6,	-5.123,	0.01,
-			0,  	0,     	1,
-		));
+		expect(Mat33.fromCSSMatrix('matrix(1, 2, 3, 4, 5, 6)')).objEq(
+			new Mat33(1, 3, 5, 2, 4, 6, 0, 0, 1),
+		);
+		expect(Mat33.fromCSSMatrix('matrix(1e2, 2, 3, 4, 5, 6)')).objEq(
+			new Mat33(1e2, 3, 5, 2, 4, 6, 0, 0, 1),
+		);
+		expect(Mat33.fromCSSMatrix('matrix(1.6, 2, .3, 4, 5, 6)')).objEq(
+			new Mat33(1.6, 0.3, 5, 2, 4, 6, 0, 0, 1),
+		);
+		expect(Mat33.fromCSSMatrix('matrix(-1, 2, 3.E-2, 4, -5.123, -6.5)')).objEq(
+			new Mat33(-1, 0.03, -5.123, 2, 4, -6.5, 0, 0, 1),
+		);
+		expect(Mat33.fromCSSMatrix('matrix(1.6,\n\t2, .3, 4, 5, 6)')).objEq(
+			new Mat33(1.6, 0.3, 5, 2, 4, 6, 0, 0, 1),
+		);
+		expect(Mat33.fromCSSMatrix('matrix(1.6,2, .3E-2, 4, 5, 6)')).objEq(
+			new Mat33(1.6, 3e-3, 5, 2, 4, 6, 0, 0, 1),
+		);
+		expect(Mat33.fromCSSMatrix('matrix(-1, 2e6,	3E-2,-5.123, -6.5e-1, 0.01)')).objEq(
+			new Mat33(-1, 3e-2, -6.5e-1, 2e6, -5.123, 0.01, 0, 0, 1),
+		);
 	});
 
 	it('should convert multi-matrix arguments into a single CSS matrix', () => {
 		const identity = Mat33.fromCSSMatrix('matrix(1, 0, 0, 1, 0, 0) matrix(1, 0, 0, 1, 0, 0)');
 		expect(identity).objEq(Mat33.identity);
 
-		expect(Mat33.fromCSSMatrix('matrix(1, 0, 0, 1, 0, 0) matrix(1, 2, 3, 4, 5, 6) matrix(1, 0, 0, 1, 0, 0)')).objEq(new Mat33(
-			1, 3, 5,
-			2, 4, 6,
-			0, 0, 1,
-		));
+		expect(
+			Mat33.fromCSSMatrix(
+				'matrix(1, 0, 0, 1, 0, 0) matrix(1, 2, 3, 4, 5, 6) matrix(1, 0, 0, 1, 0, 0)',
+			),
+		).objEq(new Mat33(1, 3, 5, 2, 4, 6, 0, 0, 1));
 
-		expect(Mat33.fromCSSMatrix('matrix(2,\n\t 0, 0, 2, 0, 0) matrix(1, 2, 3, 4, 5, 6) matrix(1, 0, 0, 1, 0, 0)')).objEq(new Mat33(
-			2, 6, 10,
-			4, 8, 12,
-			0, 0, 1,
-		));
+		expect(
+			Mat33.fromCSSMatrix(
+				'matrix(2,\n\t 0, 0, 2, 0, 0) matrix(1, 2, 3, 4, 5, 6) matrix(1, 0, 0, 1, 0, 0)',
+			),
+		).objEq(new Mat33(2, 6, 10, 4, 8, 12, 0, 0, 1));
 	});
 
 	it('should convert scale()s with a single argument', () => {

package/src/Mat33.test.ts

@@ -2,76 +2,44 @@ import Mat33 from './Mat33';
 import { Point2, Vec2 } from './Vec2';
 import Vec3 from './Vec3';
 
-
 describe('Mat33 tests', () => {
 	it('equality', () => {
 		expect(Mat33.identity).objEq(Mat33.identity);
-		expect(new Mat33(
-			0.1, 0.2, 0.3,
-			0.4, 0.5, 0.6,
-			0.7, 0.8, -0.9
-		)).objEq(new Mat33(
-			0.2, 0.1, 0.4,
-			0.5, 0.5, 0.7,
-			0.7, 0.8, -0.9
-		), 0.2);
+		expect(new Mat33(0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, -0.9)).objEq(
+			new Mat33(0.2, 0.1, 0.4, 0.5, 0.5, 0.7, 0.7, 0.8, -0.9),
+			0.2,
+		);
 	});
 
 	it('transposition', () => {
 		expect(Mat33.identity.transposed()).objEq(Mat33.identity);
-		expect(new Mat33(
-			1, 2, 0,
-			0, 0, 0,
-			0, 1, 0
-		).transposed()).objEq(new Mat33(
-			1, 0, 0,
-			2, 0, 1,
-			0, 0, 0
-		));
+		expect(new Mat33(1, 2, 0, 0, 0, 0, 0, 1, 0).transposed()).objEq(
+			new Mat33(1, 0, 0, 2, 0, 1, 0, 0, 0),
+		);
 	});
 
 	it('multiplication', () => {
-		const M = new Mat33(
-			1, 2, 3,
-			4, 5, 6,
-			7, 8, 9
-		);
+		const M = new Mat33(1, 2, 3, 4, 5, 6, 7, 8, 9);
 
 		expect(Mat33.identity.rightMul(Mat33.identity)).objEq(Mat33.identity);
 		expect(M.rightMul(Mat33.identity)).objEq(M);
-		expect(M.rightMul(new Mat33(
-			1, 0, 0,
-			0, 2, 0,
-			0, 0, 1
-		))).objEq(new Mat33(
-			1, 4, 3,
-			4, 10, 6,
-			7, 16, 9
-		));
-		expect(M.rightMul(new Mat33(
-			2, 0, 1,
-			0, 1, 0,
-			0, 0, 3
-		))).objEq(new Mat33(
-			2, 2, 10,
-			8, 5, 22,
-			14, 8, 34
-		));
+		expect(M.rightMul(new Mat33(1, 0, 0, 0, 2, 0, 0, 0, 1))).objEq(
+			new Mat33(1, 4, 3, 4, 10, 6, 7, 16, 9),
+		);
+		expect(M.rightMul(new Mat33(2, 0, 1, 0, 1, 0, 0, 0, 3))).objEq(
+			new Mat33(2, 2, 10, 8, 5, 22, 14, 8, 34),
+		);
 	});
 
 	it('the inverse of the identity matrix should be the identity matrix', () => {
 		const fuzz = 0.01;
 		expect(Mat33.identity.inverse()).objEq(Mat33.identity, fuzz);
 
-		const M = new Mat33(
-			1, 2, 3,
-			4, 1, 0,
-			2, 3, 0
-		);
+		const M = new Mat33(1, 2, 3, 4, 1, 0, 2, 3, 0);
 		expect(M.inverse().rightMul(M)).objEq(Mat33.identity, fuzz);
 	});
 
-	it('90 degree z-rotation matricies should rotate 90 degrees counter clockwise', () => {
+	it('90 degree z-rotation matrices should rotate 90 degrees counter clockwise', () => {
 		const fuzz = 0.001;
 
 		const M = Mat33.zRotation(Math.PI / 2);
@@ -80,19 +48,19 @@ describe('Mat33 tests', () => {
 		expect(M.transformVec2(rotated)).objEq(Vec2.unitX.times(-1), fuzz);
 	});
 
-	it('z-rotation matricies should preserve the given origin', () => {
+	it('z-rotation matrices should preserve the given origin', () => {
 		const testPairs: Array<[number, Vec2]> = [
-			[ Math.PI / 2, Vec2.zero ],
-			[ -Math.PI / 2, Vec2.zero ],
-			[ -Math.PI / 2, Vec2.of(10, 10) ],
+			[Math.PI / 2, Vec2.zero],
+			[-Math.PI / 2, Vec2.zero],
+			[-Math.PI / 2, Vec2.of(10, 10)],
 		];
 
-		for (const [ angle, center ] of testPairs) {
+		for (const [angle, center] of testPairs) {
 			expect(Mat33.zRotation(angle, center).transformVec2(center)).objEq(center);
 		}
 	});
 
-	it('translation matricies should translate Vec2s', () => {
+	it('translation matrices should translate Vec2s', () => {
 		const fuzz = 0.01;
 
 		const M = Mat33.translation(Vec2.of(1, -4));
@@ -100,7 +68,7 @@ describe('Mat33 tests', () => {
 		expect(M.transformVec2(Vec2.of(-1, 3))).objEq(Vec2.of(0, -1), fuzz);
 	});
 
-	it('scaling matricies should scale about the provided center', () => {
+	it('scaling matrices should scale about the provided center', () => {
 		const fuzz = 0.01;
 
 		const center = Vec2.of(1, -4);
@@ -109,29 +77,29 @@ describe('Mat33 tests', () => {
 		expect(M.transformVec2(Vec2.of(0, 0))).objEq(Vec2.of(-1, 4), fuzz);
 	});
 
-	it('calling inverse on singular matricies should result in the identity matrix', () => {
+	it('calling inverse on singular matrices should result in the identity matrix', () => {
 		const fuzz = 0.001;
-		const singularMat = Mat33.ofRows(
-			Vec3.of(0, 0, 1),
-			Vec3.of(0, 1, 0),
-			Vec3.of(0, 1, 1)
-		);
+		const singularMat = Mat33.ofRows(Vec3.of(0, 0, 1), Vec3.of(0, 1, 0), Vec3.of(0, 1, 1));
 		expect(singularMat.invertable()).toBe(false);
 		expect(singularMat.inverse()).objEq(Mat33.identity, fuzz);
 	});
 
-	it('z-rotation matricies should be invertable', () => {
+	it('z-rotation matrices should be invertable', () => {
 		const fuzz = 0.01;
 		const M = Mat33.zRotation(-0.2617993877991494, Vec2.of(481, 329.5));
-		expect(
-			M.inverse().transformVec2(M.transformVec2(Vec2.unitX))
-		).objEq(Vec2.unitX, fuzz);
+		expect(M.inverse().transformVec2(M.transformVec2(Vec2.unitX))).objEq(Vec2.unitX, fuzz);
 		expect(M.invertable());
 
 		const starterTransform = new Mat33(
-			-0.2588190451025205, -0.9659258262890688, 923.7645204565603,
-			0.9659258262890688,  -0.2588190451025205, -49.829447083761465,
-			0, 0, 1
+			-0.2588190451025205,
+			-0.9659258262890688,
+			923.7645204565603,
+			0.9659258262890688,
+			-0.2588190451025205,
+			-49.829447083761465,
+			0,
+			0,
+			1,
 		);
 		expect(starterTransform.invertable()).toBe(true);
 
@@ -139,32 +107,32 @@ describe('Mat33 tests', () => {
 		const fullTransformInverse = fullTransform.inverse();
 		expect(fullTransform.invertable()).toBe(true);
 
-		expect(
-			fullTransformInverse.rightMul(fullTransform)
-		).objEq(Mat33.identity, fuzz);
+		expect(fullTransformInverse.rightMul(fullTransform)).objEq(Mat33.identity, fuzz);
 
-		expect(
-			fullTransform.transformVec2(fullTransformInverse.transformVec2(Vec2.unitX))
-		).objEq(Vec2.unitX, fuzz);
+		expect(fullTransform.transformVec2(fullTransformInverse.transformVec2(Vec2.unitX))).objEq(
+			Vec2.unitX,
+			fuzz,
+		);
 
-		expect(
-			fullTransformInverse.transformVec2(fullTransform.transformVec2(Vec2.unitX))
-		).objEq(Vec2.unitX, fuzz);
+		expect(fullTransformInverse.transformVec2(fullTransform.transformVec2(Vec2.unitX))).objEq(
+			Vec2.unitX,
+			fuzz,
+		);
 	});
 
 	it('z-rotation matrix inverses should undo the z-rotation', () => {
-		const testCases: Array<[ number, Point2 ]> = [
-			[ Math.PI / 2, Vec2.zero ],
-			[ Math.PI, Vec2.of(1, 1) ],
-			[ -Math.PI, Vec2.of(1, 1) ],
-			[ -Math.PI * 2, Vec2.of(1, 1) ],
-			[ -Math.PI * 2, Vec2.of(123, 456) ],
-			[ -Math.PI / 4, Vec2.of(123, 456) ],
-			[ 0.1, Vec2.of(1, 2) ],
+		const testCases: Array<[number, Point2]> = [
+			[Math.PI / 2, Vec2.zero],
+			[Math.PI, Vec2.of(1, 1)],
+			[-Math.PI, Vec2.of(1, 1)],
+			[-Math.PI * 2, Vec2.of(1, 1)],
+			[-Math.PI * 2, Vec2.of(123, 456)],
+			[-Math.PI / 4, Vec2.of(123, 456)],
+			[0.1, Vec2.of(1, 2)],
 		];
 
 		const fuzz = 0.00001;
-		for (const [ angle, center ] of testCases) {
+		for (const [angle, center] of testCases) {
 			const mat = Mat33.zRotation(angle, center);
 			expect(mat.inverse().rightMul(mat)).objEq(Mat33.identity, fuzz);
 			expect(mat.rightMul(mat.inverse())).objEq(Mat33.identity, fuzz);
@@ -172,30 +140,24 @@ describe('Mat33 tests', () => {
 	});
 
 	it('z-rotation should preserve given origin', () => {
-		const testCases: Array<[ number, Point2 ]> = [
-			[ 6.205048847547065, Vec2.of(75.16363373235318, 104.29870408043762) ],
-			[ 1.234, Vec2.of(-56, 789) ],
-			[ -Math.PI, Vec2.of(-56, 789) ],
-			[ -Math.PI / 2, Vec2.of(-0.001, 1.0002) ],
+		const testCases: Array<[number, Point2]> = [
+			[6.205048847547065, Vec2.of(75.16363373235318, 104.29870408043762)],
+			[1.234, Vec2.of(-56, 789)],
+			[-Math.PI, Vec2.of(-56, 789)],
+			[-Math.PI / 2, Vec2.of(-0.001, 1.0002)],
 		];
 
 		for (const [angle, rotationOrigin] of testCases) {
-			expect(Mat33.zRotation(angle, rotationOrigin).transformVec2(rotationOrigin)).objEq(rotationOrigin);
+			expect(Mat33.zRotation(angle, rotationOrigin).transformVec2(rotationOrigin)).objEq(
+				rotationOrigin,
+			);
 		}
 	});
 
 	it('should correctly apply a mapping to all components', () => {
 		expect(
-			new Mat33(
-				1, 2, 3,
-				4, 5, 6,
-				7, 8, 9,
-			).mapEntries(component => component - 1)
-		).toMatchObject(new Mat33(
-			0, 1, 2,
-			3, 4, 5,
-			6, 7, 8,
-		));
+			new Mat33(1, 2, 3, 4, 5, 6, 7, 8, 9).mapEntries((component) => component - 1),
+		).toMatchObject(new Mat33(0, 1, 2, 3, 4, 5, 6, 7, 8));
 	});
 
 	it('getColumn should return the given column index', () => {