@js-draw/math 1.0.2 → 1.2.1

package/dist/cjs/Color4.d.ts

@@ -46,6 +46,25 @@ export default class Color4 {
      * ```
      */
     mix(other: Color4, fractionTo: number): Color4;
+    /**
+     * Ignoring this color's alpha component, returns a vector with components,
+     * $$
+     * \begin{pmatrix} \colorbox{#F44}{\tt r} \\ \colorbox{#4F4}{\tt g} \\ \colorbox{#44F}{\tt b} \end{pmatrix}
+     * $$
+     */
+    get rgb(): Vec3;
+    /**
+     * Returns the [relative luminance](https://www.w3.org/TR/2008/REC-WCAG20-20081211/#relativeluminancedef)
+     * of this color in the sRGB color space.
+     *
+     * Ignores the alpha component.
+     */
+    relativeLuminance(): number;
+    /**
+     * Returns the [contrast ratio](https://www.w3.org/TR/2008/REC-WCAG20-20081211/#contrast-ratiodef)
+     * between `colorA` and `colorB`.
+     */
+    static contrastRatio(colorA: Color4, colorB: Color4): number;
     /**
      * @returns the component-wise average of `colors`, or `Color4.transparent` if `colors` is empty.
      */
@@ -57,6 +76,27 @@ export default class Color4 {
      * The resultant hue is represented in radians and is thus in $[0, 2\pi]$.
      */
     asHSV(): Vec3;
+    /**
+     * Creates a new `Color4` from a representation [in $HSV$](https://en.wikipedia.org/wiki/HSL_and_HSV#HSV_to_RGB).
+     *
+     * [Algorithm](https://en.wikipedia.org/wiki/HSL_and_HSV#HSV_to_RGB).
+     *
+     * Note that hue must be given **in radians**. While non-standard, this is consistent with
+     * {@link asHSV}.
+     *
+     * `hue` and `value` should range from 0 to 1.
+     *
+     * @param hue $H \in [0, 2\pi]$
+     * @param saturation $S_V \in [0, 1]$
+     * @param value $V \in [0, 1]$
+     */
+    static fromHSV(hue: number, saturation: number, value: number): Color4;
+    /**
+     * Equivalent to `ofRGB(rgb.x, rgb.y, rgb.z)`.
+     *
+     * All components should be in the range `[0, 1]` (0 to 1 inclusive).
+     */
+    static fromRGBVector(rgb: Vec3, alpha?: number): Color4;
     private hexString;
     /**
      * @returns a hexadecimal color string representation of `this`, in the form `#rrggbbaa`.

package/dist/cjs/Color4.js

@@ -85,6 +85,9 @@ class Color4 {
         if (text === 'none' || text === 'transparent') {
             return Color4.transparent;
         }
+        if (text === '') {
+            return Color4.black;
+        }
         // rgba?: Match both rgb and rgba strings.
         // ([,0-9.]+): Match any string of only numeric, '.' and ',' characters.
         const rgbRegex = /^rgba?\(([,0-9.]+)\)$/i;
@@ -144,6 +147,49 @@ class Color4 {
         const fractionOfThis = 1 - fractionTo;
         return new Color4(this.r * fractionOfThis + other.r * fractionTo, this.g * fractionOfThis + other.g * fractionTo, this.b * fractionOfThis + other.b * fractionTo, this.a * fractionOfThis + other.a * fractionTo);
     }
+    /**
+     * Ignoring this color's alpha component, returns a vector with components,
+     * $$
+     * \begin{pmatrix} \colorbox{#F44}{\tt r} \\ \colorbox{#4F4}{\tt g} \\ \colorbox{#44F}{\tt b} \end{pmatrix}
+     * $$
+     */
+    get rgb() {
+        return Vec3_1.default.of(this.r, this.g, this.b);
+    }
+    /**
+     * Returns the [relative luminance](https://www.w3.org/TR/2008/REC-WCAG20-20081211/#relativeluminancedef)
+     * of this color in the sRGB color space.
+     *
+     * Ignores the alpha component.
+     */
+    relativeLuminance() {
+        // References:
+        // - https://www.w3.org/TR/2008/REC-WCAG20-20081211/#relativeluminancedef
+        // - https://stackoverflow.com/a/9733420
+        // Normalize the components, as per above
+        const components = [this.r, this.g, this.b].map(component => {
+            if (component < 0.03928) {
+                return component / 12.92;
+            }
+            else {
+                return Math.pow((component + 0.055) / 1.055, 2.4);
+            }
+        });
+        // From w3.org,
+        // > For the sRGB colorspace, the relative luminance of a color is
+        // > defined as L = 0.2126 * R + 0.7152 * G + 0.0722 * B
+        // where R, G, B are defined in components above.
+        return 0.2126 * components[0] + 0.7152 * components[1] + 0.0722 * components[2];
+    }
+    /**
+     * Returns the [contrast ratio](https://www.w3.org/TR/2008/REC-WCAG20-20081211/#contrast-ratiodef)
+     * between `colorA` and `colorB`.
+     */
+    static contrastRatio(colorA, colorB) {
+        const L1 = colorA.relativeLuminance();
+        const L2 = colorB.relativeLuminance();
+        return (Math.max(L1, L2) + 0.05) / (Math.min(L1, L2) + 0.05);
+    }
     /**
      * @returns the component-wise average of `colors`, or `Color4.transparent` if `colors` is empty.
      */
@@ -229,6 +275,65 @@ class Color4 {
         const saturation = value > 0 ? chroma / value : 0;
         return Vec3_1.default.of(hue, saturation, value);
     }
+    /**
+     * Creates a new `Color4` from a representation [in $HSV$](https://en.wikipedia.org/wiki/HSL_and_HSV#HSV_to_RGB).
+     *
+     * [Algorithm](https://en.wikipedia.org/wiki/HSL_and_HSV#HSV_to_RGB).
+     *
+     * Note that hue must be given **in radians**. While non-standard, this is consistent with
+     * {@link asHSV}.
+     *
+     * `hue` and `value` should range from 0 to 1.
+     *
+     * @param hue $H \in [0, 2\pi]$
+     * @param saturation $S_V \in [0, 1]$
+     * @param value $V \in [0, 1]$
+     */
+    static fromHSV(hue, saturation, value) {
+        if (hue < 0) {
+            hue += Math.PI * 2;
+        }
+        hue %= Math.PI * 2;
+        // Clamp value and saturation to [0, 1]
+        value = Math.max(0, Math.min(1, value));
+        saturation = Math.max(0, Math.min(1, saturation));
+        // Formula from https://en.wikipedia.org/wiki/HSL_and_HSV#HSV_to_RGB
+        // Saturation can be thought of as scaled chroma. Unapply the scaling.
+        // See https://en.wikipedia.org/wiki/HSL_and_HSV#Saturation
+        const chroma = value * saturation;
+        // Determines which edge of the projected color cube
+        const huePrime = hue / (Math.PI / 3);
+        const secondLargestComponent = chroma * (1 - Math.abs((huePrime % 2) - 1));
+        let rgb;
+        if (huePrime < 1) {
+            rgb = [chroma, secondLargestComponent, 0];
+        }
+        else if (huePrime < 2) {
+            rgb = [secondLargestComponent, chroma, 0];
+        }
+        else if (huePrime < 3) {
+            rgb = [0, chroma, secondLargestComponent];
+        }
+        else if (huePrime < 4) {
+            rgb = [0, secondLargestComponent, chroma];
+        }
+        else if (huePrime < 5) {
+            rgb = [secondLargestComponent, 0, chroma];
+        }
+        else {
+            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)`.
+     *
+     * All components should be in the range `[0, 1]` (0 to 1 inclusive).
+     */
+    static fromRGBVector(rgb, alpha) {
+        return Color4.ofRGBA(rgb.x, rgb.y, rgb.z, alpha ?? 1);
+    }
     /**
      * @returns a hexadecimal color string representation of `this`, in the form `#rrggbbaa`.
      *

package/dist/mjs/Color4.d.ts

@@ -46,6 +46,25 @@ export default class Color4 {
      * ```
      */
     mix(other: Color4, fractionTo: number): Color4;
+    /**
+     * Ignoring this color's alpha component, returns a vector with components,
+     * $$
+     * \begin{pmatrix} \colorbox{#F44}{\tt r} \\ \colorbox{#4F4}{\tt g} \\ \colorbox{#44F}{\tt b} \end{pmatrix}
+     * $$
+     */
+    get rgb(): Vec3;
+    /**
+     * Returns the [relative luminance](https://www.w3.org/TR/2008/REC-WCAG20-20081211/#relativeluminancedef)
+     * of this color in the sRGB color space.
+     *
+     * Ignores the alpha component.
+     */
+    relativeLuminance(): number;
+    /**
+     * Returns the [contrast ratio](https://www.w3.org/TR/2008/REC-WCAG20-20081211/#contrast-ratiodef)
+     * between `colorA` and `colorB`.
+     */
+    static contrastRatio(colorA: Color4, colorB: Color4): number;
     /**
      * @returns the component-wise average of `colors`, or `Color4.transparent` if `colors` is empty.
      */
@@ -57,6 +76,27 @@ export default class Color4 {
      * The resultant hue is represented in radians and is thus in $[0, 2\pi]$.
      */
     asHSV(): Vec3;
+    /**
+     * Creates a new `Color4` from a representation [in $HSV$](https://en.wikipedia.org/wiki/HSL_and_HSV#HSV_to_RGB).
+     *
+     * [Algorithm](https://en.wikipedia.org/wiki/HSL_and_HSV#HSV_to_RGB).
+     *
+     * Note that hue must be given **in radians**. While non-standard, this is consistent with
+     * {@link asHSV}.
+     *
+     * `hue` and `value` should range from 0 to 1.
+     *
+     * @param hue $H \in [0, 2\pi]$
+     * @param saturation $S_V \in [0, 1]$
+     * @param value $V \in [0, 1]$
+     */
+    static fromHSV(hue: number, saturation: number, value: number): Color4;
+    /**
+     * Equivalent to `ofRGB(rgb.x, rgb.y, rgb.z)`.
+     *
+     * All components should be in the range `[0, 1]` (0 to 1 inclusive).
+     */
+    static fromRGBVector(rgb: Vec3, alpha?: number): Color4;
     private hexString;
     /**
      * @returns a hexadecimal color string representation of `this`, in the form `#rrggbbaa`.

package/dist/mjs/Color4.mjs

@@ -79,6 +79,9 @@ class Color4 {
         if (text === 'none' || text === 'transparent') {
             return Color4.transparent;
         }
+        if (text === '') {
+            return Color4.black;
+        }
         // rgba?: Match both rgb and rgba strings.
         // ([,0-9.]+): Match any string of only numeric, '.' and ',' characters.
         const rgbRegex = /^rgba?\(([,0-9.]+)\)$/i;
@@ -138,6 +141,49 @@ class Color4 {
         const fractionOfThis = 1 - fractionTo;
         return new Color4(this.r * fractionOfThis + other.r * fractionTo, this.g * fractionOfThis + other.g * fractionTo, this.b * fractionOfThis + other.b * fractionTo, this.a * fractionOfThis + other.a * fractionTo);
     }
+    /**
+     * Ignoring this color's alpha component, returns a vector with components,
+     * $$
+     * \begin{pmatrix} \colorbox{#F44}{\tt r} \\ \colorbox{#4F4}{\tt g} \\ \colorbox{#44F}{\tt b} \end{pmatrix}
+     * $$
+     */
+    get rgb() {
+        return Vec3.of(this.r, this.g, this.b);
+    }
+    /**
+     * Returns the [relative luminance](https://www.w3.org/TR/2008/REC-WCAG20-20081211/#relativeluminancedef)
+     * of this color in the sRGB color space.
+     *
+     * Ignores the alpha component.
+     */
+    relativeLuminance() {
+        // References:
+        // - https://www.w3.org/TR/2008/REC-WCAG20-20081211/#relativeluminancedef
+        // - https://stackoverflow.com/a/9733420
+        // Normalize the components, as per above
+        const components = [this.r, this.g, this.b].map(component => {
+            if (component < 0.03928) {
+                return component / 12.92;
+            }
+            else {
+                return Math.pow((component + 0.055) / 1.055, 2.4);
+            }
+        });
+        // From w3.org,
+        // > For the sRGB colorspace, the relative luminance of a color is
+        // > defined as L = 0.2126 * R + 0.7152 * G + 0.0722 * B
+        // where R, G, B are defined in components above.
+        return 0.2126 * components[0] + 0.7152 * components[1] + 0.0722 * components[2];
+    }
+    /**
+     * Returns the [contrast ratio](https://www.w3.org/TR/2008/REC-WCAG20-20081211/#contrast-ratiodef)
+     * between `colorA` and `colorB`.
+     */
+    static contrastRatio(colorA, colorB) {
+        const L1 = colorA.relativeLuminance();
+        const L2 = colorB.relativeLuminance();
+        return (Math.max(L1, L2) + 0.05) / (Math.min(L1, L2) + 0.05);
+    }
     /**
      * @returns the component-wise average of `colors`, or `Color4.transparent` if `colors` is empty.
      */
@@ -223,6 +269,65 @@ class Color4 {
         const saturation = value > 0 ? chroma / value : 0;
         return Vec3.of(hue, saturation, value);
     }
+    /**
+     * Creates a new `Color4` from a representation [in $HSV$](https://en.wikipedia.org/wiki/HSL_and_HSV#HSV_to_RGB).
+     *
+     * [Algorithm](https://en.wikipedia.org/wiki/HSL_and_HSV#HSV_to_RGB).
+     *
+     * Note that hue must be given **in radians**. While non-standard, this is consistent with
+     * {@link asHSV}.
+     *
+     * `hue` and `value` should range from 0 to 1.
+     *
+     * @param hue $H \in [0, 2\pi]$
+     * @param saturation $S_V \in [0, 1]$
+     * @param value $V \in [0, 1]$
+     */
+    static fromHSV(hue, saturation, value) {
+        if (hue < 0) {
+            hue += Math.PI * 2;
+        }
+        hue %= Math.PI * 2;
+        // Clamp value and saturation to [0, 1]
+        value = Math.max(0, Math.min(1, value));
+        saturation = Math.max(0, Math.min(1, saturation));
+        // Formula from https://en.wikipedia.org/wiki/HSL_and_HSV#HSV_to_RGB
+        // Saturation can be thought of as scaled chroma. Unapply the scaling.
+        // See https://en.wikipedia.org/wiki/HSL_and_HSV#Saturation
+        const chroma = value * saturation;
+        // Determines which edge of the projected color cube
+        const huePrime = hue / (Math.PI / 3);
+        const secondLargestComponent = chroma * (1 - Math.abs((huePrime % 2) - 1));
+        let rgb;
+        if (huePrime < 1) {
+            rgb = [chroma, secondLargestComponent, 0];
+        }
+        else if (huePrime < 2) {
+            rgb = [secondLargestComponent, chroma, 0];
+        }
+        else if (huePrime < 3) {
+            rgb = [0, chroma, secondLargestComponent];
+        }
+        else if (huePrime < 4) {
+            rgb = [0, secondLargestComponent, chroma];
+        }
+        else if (huePrime < 5) {
+            rgb = [secondLargestComponent, 0, chroma];
+        }
+        else {
+            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)`.
+     *
+     * All components should be in the range `[0, 1]` (0 to 1 inclusive).
+     */
+    static fromRGBVector(rgb, alpha) {
+        return Color4.ofRGBA(rgb.x, rgb.y, rgb.z, alpha ?? 1);
+    }
     /**
      * @returns a hexadecimal color string representation of `this`, in the form `#rrggbbaa`.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@js-draw/math",
-	"version": "1.0.2",
+	"version": "1.2.1",
 	"description": "A math library for js-draw. ",
 	"types": "./dist/mjs/lib.d.ts",
 	"main": "./dist/cjs/lib.js",
@@ -45,5 +45,5 @@
 		"svg",
 		"math"
 	],
-	"gitHead": "f5a92284625b49b2ef6541bdafce1bd926c10441"
+	"gitHead": "0cb756d3150c8b33dd9a3217faa7d18229688f34"
 }

package/src/Color4.test.ts

@@ -49,4 +49,46 @@ describe('Color4', () => {
 		expect(Color4.ofRGB(0.5, 0.5, 0.5).asHSV()).objEq(Vec3.of(0, 0, 0.5));
 		expect(Color4.ofRGB(0.5, 0.25, 0.5).asHSV()).objEq(Vec3.of(Math.PI * 5 / 3, 0.5, 0.5), 0.1);
 	});
+
+	it('fromHSV(color.asHSV) should return the original color', () => {
+		const testColors = [
+			Color4.red, Color4.green, Color4.blue,
+			Color4.white, Color4.black,
+		];
+
+		const testWithColor = (color: Color4) => {
+			expect(Color4.fromHSV(...color.asHSV().asArray())).objEq(color);
+		};
+
+		for (const color of testColors) {
+			testWithColor(color);
+		}
+
+		for (let i = 0; i <= 6; i++) {
+			testWithColor(Color4.fromHSV(i * Math.PI / 7, 0.5, 0.5));
+			testWithColor(Color4.fromHSV(i * Math.PI / 6, 0.5, 0.5));
+		}
+	});
+
+	it('.rgb should return a 3-component vector', () => {
+		expect(Color4.red.rgb).objEq(Vec3.of(1, 0, 0));
+		expect(Color4.green.rgb).objEq(Vec3.of(0, 1, 0));
+		expect(Color4.blue.rgb).objEq(Vec3.of(0, 0, 1));
+	});
+
+	it('should return correct contrast ratios', () => {
+		// Expected values from https://webaim.org/resources/contrastchecker/
+		const testCases: [ Color4, Color4, number ][] = [
+			[ Color4.white, Color4.black, 21 ],
+			[ Color4.fromHex('#FF0000'), Color4.black, 5.25 ],
+			[ Color4.fromHex('#FF0000'), Color4.fromHex('#0000FF'), 2.14 ],
+			[ Color4.fromHex('#300000'), Color4.fromHex('#003000'), 1.26 ],
+			[ Color4.fromHex('#300000'), Color4.fromHex('#003000'), 1.26 ],
+			[ Color4.fromHex('#D60000'), Color4.fromHex('#003000'), 2.71 ],
+		];
+
+		for (const [ colorA, colorB, expectedContrast ] of testCases) {
+			expect(Color4.contrastRatio(colorA, colorB)).toBeCloseTo(expectedContrast, 1);
+		}
+	});
 });

package/src/Color4.ts

@@ -93,6 +93,10 @@ export default class Color4 {
 			return Color4.transparent;
 		}
 
+		if (text === '') {
+			return Color4.black;
+		}
+
 		// rgba?: Match both rgb and rgba strings.
 		// ([,0-9.]+): Match any string of only numeric, '.' and ',' characters.
 		const rgbRegex = /^rgba?\(([,0-9.]+)\)$/i;
@@ -170,6 +174,54 @@ export default class Color4 {
 		);
 	}
 
+	/**
+	 * Ignoring this color's alpha component, returns a vector with components,
+	 * $$
+	 * \begin{pmatrix} \colorbox{#F44}{\tt r} \\ \colorbox{#4F4}{\tt g} \\ \colorbox{#44F}{\tt b} \end{pmatrix}
+	 * $$
+	 */
+	public get rgb() {
+		return Vec3.of(this.r, this.g, this.b);
+	}
+
+	/**
+	 * Returns the [relative luminance](https://www.w3.org/TR/2008/REC-WCAG20-20081211/#relativeluminancedef)
+	 * of this color in the sRGB color space.
+	 *
+	 * Ignores the alpha component.
+	 */
+	public relativeLuminance(): number {
+		// References:
+		// - https://www.w3.org/TR/2008/REC-WCAG20-20081211/#relativeluminancedef
+		// - https://stackoverflow.com/a/9733420
+
+		// Normalize the components, as per above
+		const components = [ this.r, this.g, this.b ].map(component => {
+			if (component < 0.03928) {
+				return component / 12.92;
+			} else {
+				return Math.pow((component + 0.055) / 1.055, 2.4);
+			}
+		});
+
+		// From w3.org,
+		// > For the sRGB colorspace, the relative luminance of a color is
+		// > defined as L = 0.2126 * R + 0.7152 * G + 0.0722 * B
+		// where R, G, B are defined in components above.
+		return 0.2126 * components[0] + 0.7152 * components[1] + 0.0722 * components[2];
+	}
+
+	/**
+	 * Returns the [contrast ratio](https://www.w3.org/TR/2008/REC-WCAG20-20081211/#contrast-ratiodef)
+	 * between `colorA` and `colorB`.
+	 */
+	public static contrastRatio(colorA: Color4, colorB: Color4): number {
+		const L1 = colorA.relativeLuminance();
+		const L2 = colorB.relativeLuminance();
+
+		return (Math.max(L1, L2) + 0.05) / (Math.min(L1, L2) + 0.05);
+	}
+
 	/**
 	 * @returns the component-wise average of `colors`, or `Color4.transparent` if `colors` is empty.
 	 */
@@ -263,6 +315,70 @@ export default class Color4 {
 		return Vec3.of(hue, saturation, value);
 	}
 
+	/**
+	 * Creates a new `Color4` from a representation [in $HSV$](https://en.wikipedia.org/wiki/HSL_and_HSV#HSV_to_RGB).
+	 *
+	 * [Algorithm](https://en.wikipedia.org/wiki/HSL_and_HSV#HSV_to_RGB).
+	 *
+	 * Note that hue must be given **in radians**. While non-standard, this is consistent with
+	 * {@link asHSV}.
+	 *
+	 * `hue` and `value` should range from 0 to 1.
+	 *
+	 * @param hue $H \in [0, 2\pi]$
+	 * @param saturation $S_V \in [0, 1]$
+	 * @param value $V \in [0, 1]$
+	 */
+	public static fromHSV(hue: number, saturation: number, value: number) {
+		if (hue < 0) {
+			hue += Math.PI * 2;
+		}
+		hue %= Math.PI * 2;
+
+		// Clamp value and saturation to [0, 1]
+		value = Math.max(0, Math.min(1, value));
+		saturation = Math.max(0, Math.min(1, saturation));
+
+		// Formula from https://en.wikipedia.org/wiki/HSL_and_HSV#HSV_to_RGB
+
+		// Saturation can be thought of as scaled chroma. Unapply the scaling.
+		// See https://en.wikipedia.org/wiki/HSL_and_HSV#Saturation
+		const chroma = value * saturation;
+
+		// Determines which edge of the projected color cube
+		const huePrime = hue / (Math.PI / 3);
+
+		const secondLargestComponent = chroma * (1 - Math.abs((huePrime % 2) - 1));
+
+		let rgb;
+		if (huePrime < 1) {
+			rgb = [ chroma, secondLargestComponent, 0 ];
+		} else if (huePrime < 2) {
+			rgb = [ secondLargestComponent, chroma, 0 ];
+		} else if (huePrime < 3) {
+			rgb = [ 0, chroma, secondLargestComponent ];
+		} else if (huePrime < 4) {
+			rgb = [ 0, secondLargestComponent, chroma ];
+		} else if (huePrime < 5) {
+			rgb = [ secondLargestComponent, 0, chroma ];
+		} else {
+			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)`.
+	 *
+	 * All components should be in the range `[0, 1]` (0 to 1 inclusive).
+	 */
+	public static fromRGBVector(rgb: Vec3, alpha?: number) {
+		return Color4.ofRGBA(rgb.x, rgb.y, rgb.z, alpha ?? 1);
+	}
+
 	private hexString: string|null = null;
 
 	/**