@trishchuk/coolors-mcp 1.0.0

package/src/color/metrics.test.ts

@@ -0,0 +1,276 @@
+/**
+ * Tests for color distance metrics
+ */
+
+import { describe, expect, it } from "vitest";
+
+import type { LAB, RGB } from "./types";
+
+import { rgbToLab } from "./conversions";
+import {
+  areColorsSimilar,
+  colorDistance,
+  deltaE2000,
+  deltaE76,
+  deltaE94,
+  euclideanDistance,
+  findMostDifferentColor,
+  findMostSimilarColor,
+  weightedRgbDistance,
+} from "./metrics";
+
+describe("Color Metrics", () => {
+  describe("euclideanDistance", () => {
+    it("should calculate Euclidean distance correctly", () => {
+      const black: RGB = { b: 0, g: 0, r: 0 };
+      const white: RGB = { b: 255, g: 255, r: 255 };
+      const red: RGB = { b: 0, g: 0, r: 255 };
+      const green: RGB = { b: 0, g: 255, r: 0 };
+
+      // Same color should have distance 0
+      expect(euclideanDistance(black, black)).toBe(0);
+      expect(euclideanDistance(white, white)).toBe(0);
+
+      // Black to white - maximum distance in RGB cube
+      expect(euclideanDistance(black, white)).toBeCloseTo(441.67, 2);
+
+      // Red to green
+      expect(euclideanDistance(red, green)).toBeCloseTo(360.62, 2);
+    });
+  });
+
+  describe("weightedRgbDistance", () => {
+    it("should calculate weighted RGB distance with default weights", () => {
+      const black: RGB = { b: 0, g: 0, r: 0 };
+      const white: RGB = { b: 255, g: 255, r: 255 };
+
+      const distance = weightedRgbDistance(black, white);
+      expect(distance).toBeGreaterThan(0);
+      expect(distance).toBeLessThan(euclideanDistance(black, white));
+    });
+
+    it("should use custom weights", () => {
+      const color1: RGB = { b: 100, g: 100, r: 100 };
+      const color2: RGB = { b: 150, g: 150, r: 150 };
+
+      const defaultDistance = weightedRgbDistance(color1, color2);
+      const customDistance = weightedRgbDistance(color1, color2, {
+        b: 0,
+        g: 0,
+        r: 1,
+      });
+
+      expect(customDistance).toBe(50); // Only red channel difference
+      expect(defaultDistance).not.toBe(customDistance);
+    });
+  });
+
+  describe("deltaE76", () => {
+    it("should calculate Delta E 76 correctly", () => {
+      const lab1: LAB = { a: 0, b: 0, l: 50 };
+      const lab2: LAB = { a: 0, b: 0, l: 50 };
+
+      // Same color
+      expect(deltaE76(lab1, lab2)).toBe(0);
+
+      // Different colors
+      const lab3: LAB = { a: 10, b: 10, l: 60 };
+      const distance = deltaE76(lab1, lab3);
+      expect(distance).toBeCloseTo(17.32, 2);
+    });
+
+    it("should work with actual colors", () => {
+      const red = rgbToLab({ b: 0, g: 0, r: 255 });
+      const green = rgbToLab({ b: 0, g: 255, r: 0 });
+      const blue = rgbToLab({ b: 255, g: 0, r: 0 });
+
+      const redGreenDistance = deltaE76(red, green);
+      const redBlueDistance = deltaE76(red, blue);
+      const greenBlueDistance = deltaE76(green, blue);
+
+      // All primary colors should be quite different
+      expect(redGreenDistance).toBeGreaterThan(50);
+      expect(redBlueDistance).toBeGreaterThan(50);
+      expect(greenBlueDistance).toBeGreaterThan(50);
+    });
+  });
+
+  describe("deltaE94", () => {
+    it("should calculate Delta E 94 correctly", () => {
+      const lab1: LAB = { a: 0, b: 0, l: 50 };
+      const lab2: LAB = { a: 0, b: 0, l: 50 };
+
+      // Same color
+      expect(deltaE94(lab1, lab2)).toBe(0);
+
+      // Different colors
+      const lab3: LAB = { a: 10, b: 10, l: 60 };
+      const distance = deltaE94(lab1, lab3);
+      expect(distance).toBeGreaterThan(0);
+      expect(distance).toBeLessThanOrEqual(deltaE76(lab1, lab3)); // DE94 may be equal or less than DE76
+    });
+
+    it("should use custom parameters", () => {
+      const lab1: LAB = { a: 20, b: 20, l: 50 };
+      const lab2: LAB = { a: 25, b: 25, l: 60 };
+
+      const defaultDistance = deltaE94(lab1, lab2);
+      const customDistance = deltaE94(lab1, lab2, { kC: 1, kH: 1, kL: 2 });
+
+      expect(customDistance).not.toBe(defaultDistance);
+    });
+  });
+
+  describe("deltaE2000", () => {
+    it("should calculate Delta E 2000 correctly", () => {
+      const lab1: LAB = { a: 0, b: 0, l: 50 };
+      const lab2: LAB = { a: 0, b: 0, l: 50 };
+
+      // Same color
+      expect(deltaE2000(lab1, lab2)).toBe(0);
+
+      // Test with known values
+      const lab3: LAB = { a: 2.6772, b: -79.7751, l: 50 };
+      const lab4: LAB = { a: 0, b: -82.7485, l: 50 };
+      const distance = deltaE2000(lab3, lab4);
+      expect(distance).toBeCloseTo(2.04, 1);
+    });
+
+    it("should handle colors across hue boundaries", () => {
+      const red = rgbToLab({ b: 0, g: 0, r: 255 });
+      const slightlyDifferentRed = rgbToLab({ b: 5, g: 5, r: 250 });
+
+      const distance = deltaE2000(red, slightlyDifferentRed);
+      expect(distance).toBeGreaterThan(0);
+      expect(distance).toBeLessThan(5); // Should be a small difference
+    });
+  });
+
+  describe("colorDistance", () => {
+    const color1: RGB = { b: 0, g: 0, r: 255 };
+    const color2: RGB = { b: 0, g: 255, r: 0 };
+
+    it("should default to deltaE2000", () => {
+      const distance1 = colorDistance(color1, color2);
+      const distance2 = colorDistance(color1, color2, { metric: "deltaE2000" });
+      expect(distance1).toBe(distance2);
+    });
+
+    it("should use specified metric", () => {
+      const euclidean = colorDistance(color1, color2, { metric: "euclidean" });
+      const weighted = colorDistance(color1, color2, { metric: "weighted" });
+      const de76 = colorDistance(color1, color2, { metric: "deltaE76" });
+      const de94 = colorDistance(color1, color2, { metric: "deltaE94" });
+      const de2000 = colorDistance(color1, color2, { metric: "deltaE2000" });
+
+      // All should be different
+      expect(euclidean).not.toBe(weighted);
+      expect(de76).not.toBe(de94);
+      expect(de94).not.toBe(de2000);
+    });
+  });
+
+  describe("areColorsSimilar", () => {
+    it("should identify similar colors", () => {
+      const red1: RGB = { b: 0, g: 0, r: 255 };
+      const red2: RGB = { b: 5, g: 5, r: 250 };
+      const green: RGB = { b: 0, g: 255, r: 0 };
+
+      expect(areColorsSimilar(red1, red1)).toBe(true); // Same color
+      expect(areColorsSimilar(red1, red2)).toBe(true); // Very similar
+      expect(areColorsSimilar(red1, green)).toBe(false); // Very different
+    });
+
+    it("should use custom threshold", () => {
+      const color1: RGB = { b: 100, g: 100, r: 100 };
+      const color2: RGB = { b: 110, g: 110, r: 110 };
+
+      // With default threshold (2.3)
+      expect(areColorsSimilar(color1, color2)).toBe(false);
+
+      // With larger threshold
+      expect(areColorsSimilar(color1, color2, 10)).toBe(true);
+
+      // With smaller threshold
+      expect(areColorsSimilar(color1, color2, 1)).toBe(false);
+    });
+  });
+
+  describe("findMostDifferentColor", () => {
+    it("should find the most different color", () => {
+      const baseColor: RGB = { b: 0, g: 0, r: 255 }; // Red
+      const colors: RGB[] = [
+        { b: 0, g: 0, r: 250 }, // Very similar to red
+        { b: 0, g: 0, r: 200 }, // Darker red
+        { b: 0, g: 255, r: 0 }, // Green - most different
+        { b: 100, g: 100, r: 255 }, // Light red
+      ];
+
+      const mostDifferent = findMostDifferentColor(baseColor, colors);
+      expect(mostDifferent).toEqual({ b: 0, g: 255, r: 0 }); // Green
+    });
+
+    it("should return null for empty array", () => {
+      const baseColor: RGB = { b: 0, g: 0, r: 255 };
+      expect(findMostDifferentColor(baseColor, [])).toBeNull();
+    });
+
+    it("should work with single color", () => {
+      const baseColor: RGB = { b: 0, g: 0, r: 255 };
+      const colors: RGB[] = [{ b: 0, g: 255, r: 0 }];
+
+      const result = findMostDifferentColor(baseColor, colors);
+      expect(result).toEqual({ b: 0, g: 255, r: 0 });
+    });
+  });
+
+  describe("findMostSimilarColor", () => {
+    it("should find the most similar color", () => {
+      const baseColor: RGB = { b: 0, g: 0, r: 255 }; // Red
+      const colors: RGB[] = [
+        { b: 0, g: 0, r: 250 }, // Very similar to red - most similar
+        { b: 0, g: 0, r: 200 }, // Darker red
+        { b: 0, g: 255, r: 0 }, // Green - most different
+        { b: 100, g: 100, r: 255 }, // Light red
+      ];
+
+      const mostSimilar = findMostSimilarColor(baseColor, colors);
+      expect(mostSimilar).toEqual({ b: 0, g: 0, r: 250 });
+    });
+
+    it("should return null for empty array", () => {
+      const baseColor: RGB = { b: 0, g: 0, r: 255 };
+      expect(findMostSimilarColor(baseColor, [])).toBeNull();
+    });
+
+    it("should work with single color", () => {
+      const baseColor: RGB = { b: 0, g: 0, r: 255 };
+      const colors: RGB[] = [{ b: 0, g: 255, r: 0 }];
+
+      const result = findMostSimilarColor(baseColor, colors);
+      expect(result).toEqual({ b: 0, g: 255, r: 0 });
+    });
+  });
+
+  describe("metric comparisons", () => {
+    it("should show different characteristics for each metric", () => {
+      // Colors that are perceptually similar but numerically different
+      const color1: RGB = { b: 50, g: 50, r: 50 };
+      const color2: RGB = { b: 55, g: 55, r: 55 };
+
+      const euclidean = colorDistance(color1, color2, { metric: "euclidean" });
+      const weighted = colorDistance(color1, color2, { metric: "weighted" });
+      const de76 = colorDistance(color1, color2, { metric: "deltaE76" });
+      const de94 = colorDistance(color1, color2, { metric: "deltaE94" });
+      const de2000 = colorDistance(color1, color2, { metric: "deltaE2000" });
+
+      // Euclidean should be largest (not perceptually uniform)
+      expect(euclidean).toBeGreaterThan(weighted);
+
+      // Delta E formulas should give progressively better perceptual uniformity
+      expect(de76).toBeGreaterThan(0);
+      expect(de94).toBeGreaterThan(0);
+      expect(de2000).toBeGreaterThan(0);
+    });
+  });
+});

package/src/color/metrics.ts

@@ -0,0 +1,281 @@
+/**
+ * Color distance metrics for calculating perceptual differences between colors
+ */
+
+import type { ColorDistanceOptions, LAB, RGB } from "./types.js";
+
+import { rgbToLab } from "./conversions.js";
+
+/**
+ * Determine if two colors are perceptually similar
+ * Uses Delta E 2000 with a threshold
+ */
+export function areColorsSimilar(
+  color1: RGB,
+  color2: RGB,
+  threshold: number = 2.3, // JND (Just Noticeable Difference)
+): boolean {
+  const distance = colorDistance(color1, color2, { metric: "deltaE2000" });
+  return distance <= threshold;
+}
+
+/**
+ * Calculate color distance between two RGB colors using specified metric
+ */
+export function colorDistance(
+  color1: RGB,
+  color2: RGB,
+  options?: ColorDistanceOptions,
+): number {
+  const metric = options?.metric ?? "deltaE2000";
+
+  switch (metric) {
+    case "deltaE76": {
+      const lab1 = rgbToLab(color1);
+      const lab2 = rgbToLab(color2);
+      return deltaE76(lab1, lab2);
+    }
+
+    case "deltaE94": {
+      const lab1 = rgbToLab(color1);
+      const lab2 = rgbToLab(color2);
+      return deltaE94(lab1, lab2, options?.deltaE94);
+    }
+
+    case "euclidean":
+      return euclideanDistance(color1, color2);
+
+    case "weighted":
+      return weightedRgbDistance(color1, color2, options?.weights);
+
+    case "deltaE2000":
+    default: {
+      const lab1 = rgbToLab(color1);
+      const lab2 = rgbToLab(color2);
+      return deltaE2000(lab1, lab2);
+    }
+  }
+}
+
+/**
+ * Calculate Delta E CIE2000 (ΔE*00)
+ * Most accurate perceptual color difference formula
+ */
+export function deltaE2000(lab1: LAB, lab2: LAB): number {
+  const deg2rad = (deg: number) => deg * (Math.PI / 180);
+  const rad2deg = (rad: number) => rad * (180 / Math.PI);
+
+  // Weight factors
+  const kL = 1;
+  const kC = 1;
+  const kH = 1;
+
+  // Calculate C' and h'
+  const C1 = Math.sqrt(lab1.a * lab1.a + lab1.b * lab1.b);
+  const C2 = Math.sqrt(lab2.a * lab2.a + lab2.b * lab2.b);
+  const Cbar = (C1 + C2) / 2;
+
+  const G =
+    0.5 *
+    (1 - Math.sqrt(Math.pow(Cbar, 7) / (Math.pow(Cbar, 7) + Math.pow(25, 7))));
+
+  const a1p = lab1.a * (1 + G);
+  const a2p = lab2.a * (1 + G);
+
+  const C1p = Math.sqrt(a1p * a1p + lab1.b * lab1.b);
+  const C2p = Math.sqrt(a2p * a2p + lab2.b * lab2.b);
+
+  let h1p = Math.atan2(lab1.b, a1p);
+  let h2p = Math.atan2(lab2.b, a2p);
+
+  if (h1p < 0) h1p += 2 * Math.PI;
+  if (h2p < 0) h2p += 2 * Math.PI;
+
+  h1p = rad2deg(h1p);
+  h2p = rad2deg(h2p);
+
+  // Calculate deltas
+  const dLp = lab2.l - lab1.l;
+  const dCp = C2p - C1p;
+
+  let dhp = h2p - h1p;
+  if (dhp > 180) dhp -= 360;
+  if (dhp < -180) dhp += 360;
+
+  const dHp = 2 * Math.sqrt(C1p * C2p) * Math.sin(deg2rad(dhp) / 2);
+
+  // Calculate averages
+  const Lbar = (lab1.l + lab2.l) / 2;
+  const Cpbar = (C1p + C2p) / 2;
+
+  let hpbar = (h1p + h2p) / 2;
+  if (Math.abs(h1p - h2p) > 180) {
+    if (h1p + h2p < 360) {
+      hpbar += 180;
+    } else {
+      hpbar -= 180;
+    }
+  }
+
+  // Calculate T
+  const T =
+    1 -
+    0.17 * Math.cos(deg2rad(hpbar - 30)) +
+    0.24 * Math.cos(deg2rad(2 * hpbar)) +
+    0.32 * Math.cos(deg2rad(3 * hpbar + 6)) -
+    0.2 * Math.cos(deg2rad(4 * hpbar - 63));
+
+  // Calculate rotation term
+  const dTheta = 30 * Math.exp(-Math.pow((hpbar - 275) / 25, 2));
+  const RC =
+    2 * Math.sqrt(Math.pow(Cpbar, 7) / (Math.pow(Cpbar, 7) + Math.pow(25, 7)));
+  const RT = -RC * Math.sin(2 * deg2rad(dTheta));
+
+  // Calculate weighting functions
+  const SL =
+    1 +
+    (0.015 * Math.pow(Lbar - 50, 2)) / Math.sqrt(20 + Math.pow(Lbar - 50, 2));
+  const SC = 1 + 0.045 * Cpbar;
+  const SH = 1 + 0.015 * Cpbar * T;
+
+  // Calculate final Delta E 2000
+  const dLpKlSl = dLp / (kL * SL);
+  const dCpKcSc = dCp / (kC * SC);
+  const dHpKhSh = dHp / (kH * SH);
+
+  return Math.sqrt(
+    dLpKlSl * dLpKlSl +
+      dCpKcSc * dCpKcSc +
+      dHpKhSh * dHpKhSh +
+      RT * dCpKcSc * dHpKhSh,
+  );
+}
+
+/**
+ * Calculate Delta E CIE76 (ΔE*ab)
+ * Original CIE color difference formula
+ */
+export function deltaE76(lab1: LAB, lab2: LAB): number {
+  const dL = lab1.l - lab2.l;
+  const da = lab1.a - lab2.a;
+  const db = lab1.b - lab2.b;
+
+  return Math.sqrt(dL * dL + da * da + db * db);
+}
+
+/**
+ * Calculate Delta E CIE94 (ΔE*94)
+ * Improved perceptual uniformity over CIE76
+ */
+export function deltaE94(
+  lab1: LAB,
+  lab2: LAB,
+  options?: { kC?: number; kH?: number; kL?: number },
+): number {
+  // Default values for graphic arts
+  const kL = options?.kL ?? 1;
+  const kC = options?.kC ?? 1;
+  const kH = options?.kH ?? 1;
+
+  const dL = lab1.l - lab2.l;
+  const da = lab1.a - lab2.a;
+  const db = lab1.b - lab2.b;
+
+  const C1 = Math.sqrt(lab1.a * lab1.a + lab1.b * lab1.b);
+  const C2 = Math.sqrt(lab2.a * lab2.a + lab2.b * lab2.b);
+  const dC = C1 - C2;
+
+  const dH2 = da * da + db * db - dC * dC;
+  const dH = dH2 > 0 ? Math.sqrt(dH2) : 0;
+
+  const SL = 1;
+  const SC = 1 + 0.045 * C1;
+  const SH = 1 + 0.015 * C1;
+
+  const dLKlSl = dL / (kL * SL);
+  const dCKcSc = dC / (kC * SC);
+  const dHKhSh = dH / (kH * SH);
+
+  return Math.sqrt(dLKlSl * dLKlSl + dCKcSc * dCKcSc + dHKhSh * dHKhSh);
+}
+
+/**
+ * Calculate Euclidean distance between two RGB colors
+ * Simple but not perceptually uniform
+ */
+export function euclideanDistance(color1: RGB, color2: RGB): number {
+  const dr = color1.r - color2.r;
+  const dg = color1.g - color2.g;
+  const db = color1.b - color2.b;
+
+  return Math.sqrt(dr * dr + dg * dg + db * db);
+}
+
+/**
+ * Find the most different color from a set of colors
+ */
+export function findMostDifferentColor(
+  baseColor: RGB,
+  colors: RGB[],
+  options?: ColorDistanceOptions,
+): null | RGB {
+  if (colors.length === 0) return null;
+
+  let maxDistance = -Infinity;
+  let mostDifferent = colors[0];
+
+  for (const color of colors) {
+    const distance = colorDistance(baseColor, color, options);
+    if (distance > maxDistance) {
+      maxDistance = distance;
+      mostDifferent = color;
+    }
+  }
+
+  return mostDifferent;
+}
+
+/**
+ * Find the most similar color from a set of colors
+ */
+export function findMostSimilarColor(
+  baseColor: RGB,
+  colors: RGB[],
+  options?: ColorDistanceOptions,
+): null | RGB {
+  if (colors.length === 0) return null;
+
+  let minDistance = Infinity;
+  let mostSimilar = colors[0];
+
+  for (const color of colors) {
+    const distance = colorDistance(baseColor, color, options);
+    if (distance < minDistance) {
+      minDistance = distance;
+      mostSimilar = color;
+    }
+  }
+
+  return mostSimilar;
+}
+
+/**
+ * Calculate weighted RGB distance
+ * Better approximation of perceptual difference than simple Euclidean
+ */
+export function weightedRgbDistance(
+  color1: RGB,
+  color2: RGB,
+  weights?: { b?: number; g?: number; r?: number },
+): number {
+  // Default weights based on human eye sensitivity
+  const wr = weights?.r ?? 0.3;
+  const wg = weights?.g ?? 0.59;
+  const wb = weights?.b ?? 0.11;
+
+  const dr = (color1.r - color2.r) * wr;
+  const dg = (color1.g - color2.g) * wg;
+  const db = (color1.b - color2.b) * wb;
+
+  return Math.sqrt(dr * dr + dg * dg + db * db);
+}