@lakuna/color 1.1.2 → 1.2.0

package/src/palette/analogous.ts

@@ -0,0 +1,61 @@
+import type Hsi from "../types/Hsi.js";
+import type Hsl from "../types/Hsl.js";
+import type Hsv from "../types/Hsv.js";
+
+/** Number of degrees in a circle. */
+const d = 360;
+
+/**
+ * Determine the analogous colors of the given color.
+ * @param color - The color to find the analogues of in HSI.
+ * @param subdivisions - The number of slices to divide the color wheel into.
+ * @returns The analogues of the given color.
+ * @public
+ */
+export default function analogous(
+	color: Hsi,
+	subdivisions?: number
+): [[number, number, number] & Hsi, [number, number, number] & Hsi];
+/**
+ * Determine the analogous colors of the given color.
+ * @param color - The color to find the analogues of in HSL.
+ * @param subdivisions - The number of slices to divide the color wheel into.
+ * @returns The analogues of the given color.
+ * @public
+ */
+export default function analogous(
+	color: Hsl,
+	subdivisions?: number
+): [[number, number, number] & Hsl, [number, number, number] & Hsl];
+/**
+ * Determine the analogous colors of the given color.
+ * @param color - The color to find the analogues of in HSV.
+ * @param subdivisions - The number of slices to divide the color wheel into.
+ * @returns The analogues of the given color.
+ * @public
+ */
+export default function analogous(
+	color: Hsv,
+	subdivisions?: number
+): [[number, number, number] & Hsv, [number, number, number] & Hsv];
+export default function analogous(
+	color: Hsi | Hsl | Hsv,
+	subdivisions = 12
+):
+	| [[number, number, number] & Hsi, [number, number, number] & Hsi]
+	| [[number, number, number] & Hsl, [number, number, number] & Hsl]
+	| [[number, number, number] & Hsv, [number, number, number] & Hsv] {
+	const s = color[1];
+
+	const x = color[2];
+
+	const hueAngle = color[0] * d;
+	const deltaAngle = d / subdivisions;
+	const underAngle = hueAngle - deltaAngle;
+	const overAngle = hueAngle + deltaAngle;
+
+	return [
+		[(underAngle > d ? underAngle - d : underAngle) / d, s, x],
+		[(overAngle > d ? overAngle - d : overAngle) / d, s, x]
+	];
+}

package/src/palette/analogousLch.ts

@@ -0,0 +1,49 @@
+import type Lchab from "../types/Lchab.js";
+import type Lchuv from "../types/Lchuv.js";
+
+/** Number of degrees in a circle. */
+const d = 360;
+
+/**
+ * Determine the analogous colors of the given color.
+ * @param color - The color to find the analogues of in CIE-L\*Ch(ab).
+ * @param subdivisions - The number of slices to divide the color wheel into.
+ * @returns The analogues of the given color.
+ * @public
+ */
+export default function analogousLch(
+	color: Lchab,
+	subdivisions?: number
+): [[number, number, number] & Lchab, [number, number, number] & Lchab];
+/**
+ * Determine the analogous colors of the given color.
+ * @param color - The color to find the analogues of in CIE-L\*Ch(uv).
+ * @param subdivisions - The number of slices to divide the color wheel into.
+ * @returns The analogues of the given color.
+ * @public
+ */
+export default function analogousLch(
+	color: Lchuv,
+	subdivisions?: number
+): [[number, number, number] & Lchuv, [number, number, number] & Lchuv];
+export default function analogousLch(
+	color: Lchab | Lchuv,
+	subdivisions = 12
+):
+	| [[number, number, number] & Lchab, [number, number, number] & Lchab]
+	| [[number, number, number] & Lchuv, [number, number, number] & Lchuv] {
+	const l = color[0];
+
+	const c = color[1];
+
+	const h = color[2];
+
+	const deltaAngle = d / subdivisions;
+	const underAngle = h - deltaAngle;
+	const overAngle = h + deltaAngle;
+
+	return [
+		[l, c, (underAngle > d ? underAngle - d : underAngle) / d],
+		[l, c, (overAngle > d ? overAngle - d : overAngle) / d]
+	];
+}

package/src/palette/complement.ts

@@ -0,0 +1,65 @@
+import type Hsi from "../types/Hsi.js";
+import type Hsl from "../types/Hsl.js";
+import type Hsv from "../types/Hsv.js";
+
+/** Number of degrees in a circle. */
+const d = 360;
+
+/**
+ * Determine the complementary color(s) of the given color.
+ * @param color - The color to find the complement(s) of in HSI.
+ * @param n - The number of complements to find. This can be `1` for a complementary color, `2` for triadic colors, `3` for tetradic colors, and so on.
+ * @returns The complements of the given color.
+ * @public
+ */
+export default function complement(
+	color: Hsi,
+	n?: number
+): ([number, number, number] & Hsi)[];
+/**
+ * Determine the complementary color(s) of the given color.
+ * @param color - The color to find the complement(s) of in HSL.
+ * @param n - The number of complements to find. This can be `1` for a complementary color, `2` for triadic colors, `3` for tetradic colors, and so on.
+ * @returns The complements of the given color.
+ * @public
+ */
+export default function complement(
+	color: Hsl,
+	n?: number
+): ([number, number, number] & Hsl)[];
+/**
+ * Determine the complementary color(s) of the given color.
+ * @param color - The color to find the complement(s) of in HSV.
+ * @param n - The number of complements to find. This can be `1` for a complementary color, `2` for triadic colors, `3` for tetradic colors, and so on.
+ * @returns The complements of the given color.
+ * @public
+ */
+export default function complement(
+	color: Hsv,
+	n?: number
+): ([number, number, number] & Hsv)[];
+export default function complement(
+	color: Hsi | Hsl | Hsv,
+	n = 1
+):
+	| ([number, number, number] & Hsi)[]
+	| ([number, number, number] & Hsl)[]
+	| ([number, number, number] & Hsv)[] {
+	const s = color[1];
+
+	const x = color[2];
+
+	const hueAngle = color[0] * d;
+	const deltaAngle = d / (n + 1);
+
+	const out:
+		| ([number, number, number] & Hsi)[]
+		| ([number, number, number] & Hsl)[]
+		| ([number, number, number] & Hsv)[] = [];
+	for (let i = 1; i <= n; i++) {
+		const angle = hueAngle + deltaAngle * i;
+		out.push([(angle > d ? angle - d : angle) / d, s, x]);
+	}
+
+	return out;
+}

package/src/palette/complementLch.ts

@@ -0,0 +1,50 @@
+import type Lchab from "../types/Lchab.js";
+import type Lchuv from "../types/Lchuv.js";
+
+/** Number of degrees in a circle. */
+const d = 360;
+
+/**
+ * Determine the complementary color(s) of the given color.
+ * @param color - The color to find the complement(s) of in CIE-L\*Ch(ab).
+ * @param n - The number of complements to find. This can be `1` for a complementary color, `2` for triadic colors, `3` for tetradic colors, and so on.
+ * @returns The complements of the given color.
+ * @public
+ */
+export default function complementLch(
+	color: Lchab,
+	n?: number
+): ([number, number, number] & Lchab)[];
+/**
+ * Determine the complementary color(s) of the given color.
+ * @param color - The color to find the complement(s) of in CIE-L\*Ch(uv).
+ * @param n - The number of complements to find. This can be `1` for a complementary color, `2` for triadic colors, `3` for tetradic colors, and so on.
+ * @returns The complements of the given color.
+ * @public
+ */
+export default function complementLch(
+	color: Lchuv,
+	n?: number
+): ([number, number, number] & Lchuv)[];
+export default function complementLch(
+	color: Lchab | Lchuv,
+	n = 1
+): ([number, number, number] & Lchab)[] | ([number, number, number] & Lchuv)[] {
+	const l = color[0];
+
+	const c = color[1];
+
+	const h = color[2];
+
+	const deltaAngle = d / (n + 1);
+
+	const out:
+		| ([number, number, number] & Lchab)[]
+		| ([number, number, number] & Lchuv)[] = [];
+	for (let i = 1; i <= n; i++) {
+		const angle = h + deltaAngle * i;
+		out.push([l, c, (angle > d ? angle - d : angle) / d]);
+	}
+
+	return out;
+}

package/src/palette/splitComplement.ts

@@ -0,0 +1,61 @@
+import type Hsi from "../types/Hsi.js";
+import type Hsl from "../types/Hsl.js";
+import type Hsv from "../types/Hsv.js";
+
+/** Number of degrees in a circle. */
+const d = 360;
+
+/**
+ * Determine the split complementary colors of the given color.
+ * @param color - The color to find the split complements of in HSI.
+ * @param subdivisions - The number of slices to divide the color wheel into.
+ * @returns The complements of the given color.
+ * @public
+ */
+export default function splitComplement(
+	color: Hsi,
+	subdivisions?: number
+): [[number, number, number] & Hsi, [number, number, number] & Hsi];
+/**
+ * Determine the split complementary colors of the given color.
+ * @param color - The color to find the split complements of in HSL.
+ * @param subdivisions - The number of slices to divide the color wheel into.
+ * @returns The complements of the given color.
+ * @public
+ */
+export default function splitComplement(
+	color: Hsl,
+	subdivisions?: number
+): [[number, number, number] & Hsl, [number, number, number] & Hsl];
+/**
+ * Determine the split complementary colors of the given color.
+ * @param color - The color to find the split complements of in HSV.
+ * @param subdivisions - The number of slices to divide the color wheel into.
+ * @returns The complements of the given color.
+ * @public
+ */
+export default function splitComplement(
+	color: Hsv,
+	subdivisions?: number
+): [[number, number, number] & Hsv, [number, number, number] & Hsv];
+export default function splitComplement(
+	color: Hsi | Hsl | Hsv,
+	subdivisions = 12
+):
+	| [[number, number, number] & Hsi, [number, number, number] & Hsi]
+	| [[number, number, number] & Hsl, [number, number, number] & Hsl]
+	| [[number, number, number] & Hsv, [number, number, number] & Hsv] {
+	const s = color[1];
+
+	const x = color[2];
+
+	const deltaAngle = d / subdivisions;
+	const oppositeAngle = color[0] * d + d / 2;
+	const underAngle = oppositeAngle - deltaAngle;
+	const overAngle = oppositeAngle + deltaAngle;
+
+	return [
+		[(underAngle > d ? underAngle - d : underAngle) / d, s, x],
+		[(overAngle > d ? overAngle - d : overAngle) / d, s, x]
+	];
+}

package/src/palette/splitComplementLch.ts

@@ -0,0 +1,48 @@
+import type Lchab from "../types/Lchab.js";
+import type Lchuv from "../types/Lchuv.js";
+
+/** Number of degrees in a circle. */
+const d = 360;
+
+/**
+ * Determine the split complementary colors of the given color.
+ * @param color - The color to find the split complements of in CIE-L\*Ch(ab).
+ * @param subdivisions - The number of slices to divide the color wheel into.
+ * @returns The complements of the given color.
+ * @public
+ */
+export default function splitComplementLch(
+	color: Lchab,
+	subdivisions?: number
+): [[number, number, number] & Lchab, [number, number, number] & Lchab];
+/**
+ * Determine the split complementary colors of the given color.
+ * @param color - The color to find the split complements of in CIE-L\*Ch(uv).
+ * @param subdivisions - The number of slices to divide the color wheel into.
+ * @returns The complements of the given color.
+ * @public
+ */
+export default function splitComplementLch(
+	color: Lchuv,
+	subdivisions?: number
+): [[number, number, number] & Lchuv, [number, number, number] & Lchuv];
+export default function splitComplementLch(
+	color: Lchab | Lchuv,
+	subdivisions = 12
+):
+	| [[number, number, number] & Lchab, [number, number, number] & Lchab]
+	| [[number, number, number] & Lchuv, [number, number, number] & Lchuv] {
+	const l = color[0];
+
+	const c = color[1];
+
+	const deltaAngle = d / subdivisions;
+	const oppositeAngle = color[2] + d / 2;
+	const underAngle = oppositeAngle - deltaAngle;
+	const overAngle = oppositeAngle + deltaAngle;
+
+	return [
+		[l, c, (underAngle > d ? underAngle - d : underAngle) / d],
+		[l, c, (overAngle > d ? overAngle - d : overAngle) / d]
+	];
+}

package/src/types/Adobe.ts

@@ -7,11 +7,14 @@ import type { Color } from "./Color.js";
  */
 export default interface Adobe extends Color {
 	/** The red channel of this color in the range `[0x00,0xff]`. */
+	// eslint-disable-next-line @typescript-eslint/naming-convention
 	0: number;
 
 	/** The green channel of this color in the range `[0x00,0xff]`. */
+	// eslint-disable-next-line @typescript-eslint/naming-convention
 	1: number;
 
 	/** The blue channel of this color in the range `[0x00,0xff]`. */
+	// eslint-disable-next-line @typescript-eslint/naming-convention
 	2: number;
 }

package/src/types/Cmy.ts

@@ -7,11 +7,14 @@ import type { Color } from "./Color.js";
  */
 export default interface Cmy extends Color {
 	/** The cyan channel of this color in the range `[0,1]`. */
+	// eslint-disable-next-line @typescript-eslint/naming-convention
 	0: number;
 
 	/** The magenta channel of this color in the range `[0,1]`. */
+	// eslint-disable-next-line @typescript-eslint/naming-convention
 	1: number;
 
 	/** The yellow channel of this color in the range `[0,1]`. */
+	// eslint-disable-next-line @typescript-eslint/naming-convention
 	2: number;
 }

package/src/types/Cmyk.ts

@@ -7,14 +7,18 @@ import type { Color } from "./Color.js";
  */
 export default interface Cmyk extends Color {
 	/** The cyan channel of this color in the range `[0,1]`. */
+	// eslint-disable-next-line @typescript-eslint/naming-convention
 	0: number;
 
 	/** The magenta channel of this color in the range `[0,1]`. */
+	// eslint-disable-next-line @typescript-eslint/naming-convention
 	1: number;
 
 	/** The yellow channel of this color in the range `[0,1]`. */
+	// eslint-disable-next-line @typescript-eslint/naming-convention
 	2: number;
 
 	/** The key (black) channel of this color in the range `[0,1]`. */
+	// eslint-disable-next-line @typescript-eslint/naming-convention
 	3: number;
 }

package/src/types/Hsi.ts

@@ -0,0 +1,20 @@
+import type { Color } from "./Color.js";
+
+/**
+ * An HSI representation of a color. Commonly used in computer vision applications.
+ * @see {@link https://en.wikipedia.org/wiki/HSL_and_HSV | HSL and HSV}
+ * @public
+ */
+export default interface Hsi extends Color {
+	/** The hue channel of this color in the range `[0,1]`. Multiply this value by 360 to get the hue angle in degrees. */
+	// eslint-disable-next-line @typescript-eslint/naming-convention
+	0: number;
+
+	/** The saturation channel of this color in the range `[0,1]`. */
+	// eslint-disable-next-line @typescript-eslint/naming-convention
+	1: number;
+
+	/** The intensity channel of this color in the range `[0,1]`. */
+	// eslint-disable-next-line @typescript-eslint/naming-convention
+	2: number;
+}

package/src/types/Hsl.ts

@@ -6,12 +6,15 @@ import type { Color } from "./Color.js";
  * @public
  */
 export default interface Hsl extends Color {
-	/** The hue channel of this color in the range `[0,1]`. */
+	/** The hue channel of this color in the range `[0,1]`. Multiply this value by 360 to get the hue angle in degrees. */
+	// eslint-disable-next-line @typescript-eslint/naming-convention
 	0: number;
 
 	/** The saturation channel of this color in the range `[0,1]`. */
+	// eslint-disable-next-line @typescript-eslint/naming-convention
 	1: number;
 
 	/** The lightness channel of this color in the range `[0,1]`. */
+	// eslint-disable-next-line @typescript-eslint/naming-convention
 	2: number;
 }

package/src/types/Hsv.ts

@@ -6,12 +6,15 @@ import type { Color } from "./Color.js";
  * @public
  */
 export default interface Hsv extends Color {
-	/** The hue channel of this color in the range `[0,1]`. */
+	/** The hue channel of this color in the range `[0,1]`. Multiply this value by 360 to get the hue angle in degrees. */
+	// eslint-disable-next-line @typescript-eslint/naming-convention
 	0: number;
 
 	/** The saturation channel of this color in the range `[0,1]`. */
+	// eslint-disable-next-line @typescript-eslint/naming-convention
 	1: number;
 
 	/** The value (brightness) channel of this color in the range `[0,1]`. */
+	// eslint-disable-next-line @typescript-eslint/naming-convention
 	2: number;
 }

package/src/types/Hunter.ts

@@ -7,11 +7,14 @@ import type { Color } from "./Color.js";
  */
 export default interface Hunter extends Color {
 	/** The L (lightness) value of this color in the range `[0,100]` (lighter values are whiter). */
+	// eslint-disable-next-line @typescript-eslint/naming-convention
 	0: number;
 
 	/** The a opponent color axis value of this color. The positive direction represents redness, while the negative direction represents greenness. */
+	// eslint-disable-next-line @typescript-eslint/naming-convention
 	1: number;
 
 	/** The b opponent color axis value of this color. The positive direction represents yellowness, while the negative direction represents blueness. */
+	// eslint-disable-next-line @typescript-eslint/naming-convention
 	2: number;
 }

package/src/types/Lab.ts

@@ -1,17 +1,20 @@
 import type { Color } from "./Color.js";
 
 /**
- * A CIELAB (L*a*b*) representation of a color. Intended to be a perceptually uniform space. Derived from CIEXYZ. Colors are defined relative to a standard observer. Compared to CIELUV, CIELAB is considered better for reflective surface colors.
+ * A CIELAB (L\*a\*b\* or CIE-L\*ab) representation of a color. Intended to be a perceptually uniform space. Derived from CIEXYZ. Colors are defined relative to a standard observer. Compared to CIELUV, CIELAB is considered better for reflective surface colors.
  * @see {@link https://en.wikipedia.org/wiki/CIELAB_color_space | CIELAB color space}
  * @public
  */
 export default interface Lab extends Color {
-	/** The L* (perceptual brightness) value of this color in the range `[0,100]`. */
+	/** The L* (luminance or perceptual brightness) value of this color in the range `[0,100]`. */
+	// eslint-disable-next-line @typescript-eslint/naming-convention
 	0: number;
 
 	/** The a* value of this color. Forms a Cartesian coordinate pair with b* to represent the four unique colors of human vision (red, green, blue, and yellow). */
+	// eslint-disable-next-line @typescript-eslint/naming-convention
 	1: number;
 
 	/** The b* value of this color. Forms a Cartesian coordinate pair with a* to represent the four unique colors of human vision (red, green, blue, and yellow). */
+	// eslint-disable-next-line @typescript-eslint/naming-convention
 	2: number;
 }

package/src/types/Lchab.ts

@@ -0,0 +1,20 @@
+import type { Color } from "./Color.js";
+
+/**
+ * A CIELCh (CIEHLC or CIE-L\*Ch(ab)) representation of a color. Intended to be a perceptually uniform space. Colors are defined relative to a standard observer.
+ * @see {@link https://en.wikipedia.org/wiki/CIELAB_color_space | CIELAB color space}
+ * @public
+ */
+export default interface Lchab extends Color {
+	/** The L* (luminance or perceptual brightness) value of this color in the range `[0,100]`. */
+	// eslint-disable-next-line @typescript-eslint/naming-convention
+	0: number;
+
+	/** The C* (chroma/chromaticity or relative saturation) value of this color. Forms a polar coordinate pair with h° to represent the four unique colors of human vision (red, green, blue, and yellow). */
+	// eslint-disable-next-line @typescript-eslint/naming-convention
+	1: number;
+
+	/** The h° (hue angle) value of this color. Forms a polar coordinate pair with C* to represent the four unique colors of human vision (red, green, blue, and yellow). */
+	// eslint-disable-next-line @typescript-eslint/naming-convention
+	2: number;
+}

package/src/types/Lchuv.ts

@@ -0,0 +1,20 @@
+import type { Color } from "./Color.js";
+
+/**
+ * A CIELCh (CIEHLC or CIE-L\*Ch(uv)) representation of a color. Intended to be a perceptually uniform space. Colors are defined relative to a standard observer.
+ * @see {@link https://en.wikipedia.org/wiki/CIELUV | CIELUV}
+ * @public
+ */
+export default interface Lchuv extends Color {
+	/** The L* (luminance or perceptual brightness) value of this color in the range `[0,100]`. */
+	// eslint-disable-next-line @typescript-eslint/naming-convention
+	0: number;
+
+	/** The C* (chroma/chromaticity or relative saturation) value of this color. Forms a polar coordinate pair with h° to represent the four unique colors of human vision (red, green, blue, and yellow). */
+	// eslint-disable-next-line @typescript-eslint/naming-convention
+	1: number;
+
+	/** The h° (hue angle) value of this color. Forms a polar coordinate pair with C* to represent the four unique colors of human vision (red, green, blue, and yellow). */
+	// eslint-disable-next-line @typescript-eslint/naming-convention
+	2: number;
+}

package/src/types/Luv.ts

@@ -1,17 +1,20 @@
 import type { Color } from "./Color.js";
 
 /**
- * A CIELUV (CIE 1976 L*,u*,v*) representation of a color. Intended to be a perceptually uniform space. Derived from CIEXYZ. Colors are defined relative to a standard observer. Compared to CIELAB, CIELUV is considered better for emissive, self-illuminated colors (such as those on a monitor).
+ * A CIELUV (CIE 1976 L\*,u\*,v\* or CIE-L\*uv) representation of a color. Intended to be a perceptually uniform space. Derived from CIEXYZ. Colors are defined relative to a standard observer. Compared to CIELAB, CIELUV is considered better for emissive, self-illuminated colors (such as those on a monitor).
  * @see {@link https://en.wikipedia.org/wiki/CIELUV | CIELUV}
  * @public
  */
 export default interface Luv extends Color {
 	/** The L* (perceptual brightness) value of this color in the range `[0,100]`. */
+	// eslint-disable-next-line @typescript-eslint/naming-convention
 	0: number;
 
 	/** The u* value of this color. Forms a Cartesian coordinate pair with v* to represent the four unique colors of human vision (red, green, blue, and yellow). */
+	// eslint-disable-next-line @typescript-eslint/naming-convention
 	1: number;
 
 	/** The v* value of this color. Forms a Cartesian coordinate pair with u* to represent the four unique colors of human vision (red, green, blue, and yellow). */
+	// eslint-disable-next-line @typescript-eslint/naming-convention
 	2: number;
 }

package/src/types/Rgb.ts

@@ -7,11 +7,14 @@ import type { Color } from "./Color.js";
  */
 export default interface Rgb extends Color {
 	/** The red channel of this color in the range `[0x00,0xff]`. */
+	// eslint-disable-next-line @typescript-eslint/naming-convention
 	0: number;
 
 	/** The green channel of this color in the range `[0x00,0xff]`. */
+	// eslint-disable-next-line @typescript-eslint/naming-convention
 	1: number;
 
 	/** The blue channel of this color in the range `[0x00,0xff]`. */
+	// eslint-disable-next-line @typescript-eslint/naming-convention
 	2: number;
 }

package/src/types/Xyz.ts

@@ -7,11 +7,14 @@ import type { Color } from "./Color.js";
  */
 export default interface Xyz extends Color {
 	/** The X value of this color. */
+	// eslint-disable-next-line @typescript-eslint/naming-convention
 	0: number;
 
 	/** The Y value of this color. */
+	// eslint-disable-next-line @typescript-eslint/naming-convention
 	1: number;
 
 	/** The Z value of this color. */
+	// eslint-disable-next-line @typescript-eslint/naming-convention
 	2: number;
 }

package/src/types/Yxy.ts

@@ -7,11 +7,14 @@ import type { Color } from "./Color.js";
  */
 export default interface Yxy extends Color {
 	/** The Y value of this color in the range `[0,100]`. */
+	// eslint-disable-next-line @typescript-eslint/naming-convention
 	0: number;
 
 	/** The x value of this color. */
+	// eslint-disable-next-line @typescript-eslint/naming-convention
 	1: number;
 
 	/** The y value of this color. */
+	// eslint-disable-next-line @typescript-eslint/naming-convention
 	2: number;
 }