@trishchuk/coolors-mcp 1.0.0

package/src/color/dislike/dislike-analyzer.ts

@@ -0,0 +1,114 @@
+import { Hct } from "../hct/hct-class.js";
+
+/**
+ * Check and/or fix universally disliked colors.
+ *
+ * Color science studies of color preference indicate universal distaste for
+ * dark yellow-greens, and also show this is correlated to distaste for
+ * biological waste and rotting food.
+ *
+ * See Palmer and Schloss, 2010 or Schloss and Palmer's Chapter 21 in Handbook
+ * of Color Psychology (2015).
+ */
+export class DislikeAnalyzer {
+  /**
+   * Analyze a batch of colors and return statistics
+   * @param colors Array of HCT colors
+   * @return Statistics about disliked colors
+   */
+  static analyzeBatch(colors: Hct[]): {
+    disliked: number;
+    dislikedIndices: number[];
+    percentage: number;
+    total: number;
+  } {
+    const dislikedIndices: number[] = [];
+
+    colors.forEach((color, index) => {
+      if (DislikeAnalyzer.isDisliked(color)) {
+        dislikedIndices.push(index);
+      }
+    });
+
+    return {
+      disliked: dislikedIndices.length,
+      dislikedIndices,
+      percentage: (dislikedIndices.length / colors.length) * 100,
+      total: colors.length,
+    };
+  }
+
+  /**
+   * Fix all disliked colors in a batch
+   * @param colors Array of HCT colors
+   * @return Array with disliked colors fixed
+   */
+  static fixBatch(colors: Hct[]): Hct[] {
+    return colors.map((color) => DislikeAnalyzer.fixIfDisliked(color));
+  }
+
+  /**
+   * If a color is disliked, lighten it to make it likable.
+   *
+   * @param hct A color to be judged.
+   * @return A new color if the original color is disliked, or the original
+   *   color if it is acceptable.
+   */
+  static fixIfDisliked(hct: Hct): Hct {
+    if (DislikeAnalyzer.isDisliked(hct)) {
+      return Hct.from(hct.hue, hct.chroma, 70.0);
+    }
+
+    return hct;
+  }
+
+  /**
+   * Fix a hex color if it's disliked
+   * @param hex Hex color string
+   * @return Fixed hex color or original if not disliked
+   */
+  static fixIfDislikedHex(hex: string): string {
+    const argb = parseInt(hex.replace("#", ""), 16) | 0xff000000;
+    const hct = Hct.fromInt(argb);
+    const fixed = DislikeAnalyzer.fixIfDisliked(hct);
+
+    if (fixed === hct) {
+      return hex;
+    }
+
+    const fixedArgb = fixed.toInt();
+    const r = (fixedArgb >> 16) & 0xff;
+    const g = (fixedArgb >> 8) & 0xff;
+    const b = fixedArgb & 0xff;
+
+    return "#" + [r, g, b].map((x) => x.toString(16).padStart(2, "0")).join("");
+  }
+
+  /**
+   * Returns true if a color is disliked.
+   *
+   * @param hct A color to be judged.
+   * @return Whether the color is disliked.
+   *
+   * Disliked is defined as a dark yellow-green that is not neutral.
+   * Specifically: hue 90-111°, chroma > 16, tone < 65
+   */
+  static isDisliked(hct: Hct): boolean {
+    const huePasses =
+      Math.round(hct.hue) >= 90.0 && Math.round(hct.hue) <= 111.0;
+    const chromaPasses = Math.round(hct.chroma) > 16.0;
+    const tonePasses = Math.round(hct.tone) < 65.0;
+
+    return huePasses && chromaPasses && tonePasses;
+  }
+
+  /**
+   * Check if a color is in the "bile zone" - universally disliked colors
+   * @param hex Hex color string
+   * @return Whether the color is disliked
+   */
+  static isDislikedHex(hex: string): boolean {
+    const hct = Hct.fromInt(parseInt(hex.replace("#", ""), 16) | 0xff000000);
+    return DislikeAnalyzer.isDisliked(hct);
+  }
+}

package/src/color/extract-colors.ts

@@ -0,0 +1,228 @@
+/**
+ * Image color extraction using Material Design quantization
+ */
+
+import { DislikeAnalyzer } from "./dislike/dislike-analyzer.js";
+import { Hct } from "./hct/index.js";
+import {
+  filterExtremeTones,
+  imageDataToPixels,
+  samplePixels,
+} from "./image-utils.js";
+import { QuantizerCelebi } from "./quantize/quantizer_celebi.js";
+import { Score } from "./score/score.js";
+import * as utils from "./utils/color_utils.js";
+
+export interface ExtractedColor {
+  hct: { c: number; h: number; t: number };
+  hex: string;
+  percentage: number;
+  population: number;
+  rgb: { b: number; g: number; r: number };
+}
+
+export interface ExtractionOptions {
+  filter?: boolean;
+  fixDislikedColors?: boolean;
+  maxColors?: number;
+  quality?: "high" | "low" | "medium";
+  scoringEnabled?: boolean;
+}
+
+const QUALITY_SETTINGS = {
+  high: { maxPixels: 25000, quantizeColors: 256 },
+  low: { maxPixels: 5000, quantizeColors: 64 },
+  medium: { maxPixels: 10000, quantizeColors: 128 },
+};
+
+/**
+ * Extract dominant colors from image data
+ */
+export function extractColors(
+  imageData: {
+    data: number[] | Uint8ClampedArray;
+    height: number;
+    width: number;
+  },
+  options: ExtractionOptions = {},
+): ExtractedColor[] {
+  const {
+    filter = true,
+    fixDislikedColors = false,
+    maxColors = 5,
+    quality = "medium",
+    scoringEnabled = true,
+  } = options;
+
+  const qualitySettings = QUALITY_SETTINGS[quality];
+
+  // Convert image to pixels
+  let pixels = imageDataToPixels(imageData);
+
+  // Sample for performance
+  pixels = samplePixels(pixels, qualitySettings.maxPixels);
+
+  // Optionally filter extreme tones
+  if (filter) {
+    pixels = filterExtremeTones(pixels);
+  }
+
+  // Quantize colors using Celebi algorithm
+  const quantized = QuantizerCelebi.quantize(
+    pixels,
+    qualitySettings.quantizeColors,
+  );
+
+  // Score and select best colors
+  let selectedColors: number[];
+  if (scoringEnabled) {
+    selectedColors = Score.score(quantized, {
+      desired: maxColors,
+      filter: filter,
+    });
+  } else {
+    // Simple selection by population
+    const sorted = Array.from(quantized.entries())
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, maxColors)
+      .map((entry) => entry[0]);
+    selectedColors = sorted;
+  }
+
+  // Calculate total population for percentages
+  const totalPopulation = Array.from(quantized.values()).reduce(
+    (sum, pop) => sum + pop,
+    0,
+  );
+
+  // Convert to output format
+  return selectedColors.map((argb) => {
+    let hct = Hct.fromInt(argb);
+
+    // Fix disliked colors if requested
+    if (fixDislikedColors && DislikeAnalyzer.isDisliked(hct)) {
+      hct = DislikeAnalyzer.fixIfDisliked(hct);
+      argb = hct.toInt();
+    }
+
+    const r = utils.redFromArgb(argb);
+    const g = utils.greenFromArgb(argb);
+    const b = utils.blueFromArgb(argb);
+    const population = quantized.get(argb) || 0;
+
+    return {
+      hct: { c: hct.chroma, h: hct.hue, t: hct.tone },
+      hex: rgbToHex(r, g, b),
+      percentage: (population / totalPopulation) * 100,
+      population,
+      rgb: { b, g, r },
+    };
+  });
+}
+
+/**
+ * Extract a color palette suitable for UI themes
+ */
+export function extractThemePalette(imageData: {
+  data: number[] | Uint8ClampedArray;
+  height: number;
+  width: number;
+}): {
+  error?: ExtractedColor;
+  neutral?: ExtractedColor;
+  primary: ExtractedColor;
+  secondary?: ExtractedColor;
+  tertiary?: ExtractedColor;
+} {
+  // Extract with high quality and scoring, fixing disliked colors
+  const colors = extractColors(imageData, {
+    filter: true,
+    fixDislikedColors: true, // Always fix disliked colors for themes
+    maxColors: 8,
+    quality: "high",
+    scoringEnabled: true,
+  });
+
+  if (colors.length === 0) {
+    throw new Error("No colors could be extracted from image");
+  }
+
+  const result: {
+    error?: ExtractedColor;
+    neutral?: ExtractedColor;
+    primary: ExtractedColor;
+    secondary?: ExtractedColor;
+    tertiary?: ExtractedColor;
+  } = {
+    primary: colors[0],
+  };
+
+  // Assign additional colors based on hue differences
+  if (colors.length > 1) {
+    // Find color with most different hue from primary
+    const primaryHue = colors[0].hct.h;
+    let maxHueDiff = 0;
+    let secondaryIndex = 1;
+
+    for (let i = 1; i < Math.min(colors.length, 4); i++) {
+      const hueDiff = Math.abs(hueDifference(primaryHue, colors[i].hct.h));
+      if (hueDiff > maxHueDiff) {
+        maxHueDiff = hueDiff;
+        secondaryIndex = i;
+      }
+    }
+
+    result.secondary = colors[secondaryIndex];
+
+    // Find tertiary (different from both primary and secondary)
+    if (colors.length > 2) {
+      const secondaryHue = colors[secondaryIndex].hct.h;
+      let bestTertiaryIndex = -1;
+      let bestScore = 0;
+
+      for (let i = 1; i < colors.length; i++) {
+        if (i === secondaryIndex) continue;
+
+        const hue = colors[i].hct.h;
+        const primaryDiff = Math.abs(hueDifference(primaryHue, hue));
+        const secondaryDiff = Math.abs(hueDifference(secondaryHue, hue));
+        const score = Math.min(primaryDiff, secondaryDiff);
+
+        if (score > bestScore) {
+          bestScore = score;
+          bestTertiaryIndex = i;
+        }
+      }
+
+      if (bestTertiaryIndex !== -1) {
+        result.tertiary = colors[bestTertiaryIndex];
+      }
+    }
+  }
+
+  // Find a neutral color (low chroma)
+  const neutral = colors.find((c) => c.hct.c < 20);
+  if (neutral) {
+    result.neutral = neutral;
+  }
+
+  // Error color (prefer red/orange hue if available, 0-40 or 350-360)
+  const errorColor = colors.find((c) => c.hct.h >= 350 || c.hct.h <= 40);
+  if (errorColor) {
+    result.error = errorColor;
+  }
+
+  return result;
+}
+
+function hueDifference(h1: number, h2: number): number {
+  const diff = Math.abs(h1 - h2);
+  return diff > 180 ? 360 - diff : diff;
+}
+
+function rgbToHex(r: number, g: number, b: number): string {
+  return (
+    "#" +
+    [r, g, b].map((x) => Math.round(x).toString(16).padStart(2, "0")).join("")
+  );
+}

package/src/color/hct/__tests__/hct-class.test.ts

@@ -0,0 +1,232 @@
+/**
+ * Tests for HCT class (Material Color Utilities compatible)
+ */
+
+import { describe, expect, it } from "vitest";
+
+import * as utils from "../../utils/color_utils";
+import { Hct } from "../hct-class";
+
+describe("Hct Class", () => {
+  describe("from static method", () => {
+    it("should create HCT from hue, chroma, and tone", () => {
+      const hct = Hct.from(180, 50, 50);
+
+      expect(hct.hue).toBeCloseTo(180, -1); // Within 10 degrees
+      // Chroma might be adjusted to achievable value
+      expect(hct.chroma).toBeGreaterThan(30); // At least some chroma
+      expect(hct.chroma).toBeLessThanOrEqual(50); // Not more than requested
+      expect(hct.tone).toBeCloseTo(50, -1); // Within 10 units
+    });
+
+    it("should handle zero chroma (grayscale)", () => {
+      const hct = Hct.from(0, 0, 50);
+
+      expect(hct.chroma).toBeCloseTo(0, 1);
+      expect(hct.tone).toBeCloseTo(50, -1); // Within 10 units
+    });
+
+    it("should handle extreme tones", () => {
+      const black = Hct.from(0, 0, 0);
+      const white = Hct.from(0, 0, 100);
+
+      expect(black.tone).toBeCloseTo(0, 0);
+      expect(white.tone).toBeCloseTo(100, 0);
+    });
+
+    it("should clamp chroma to achievable values", () => {
+      // Very high chroma might not be achievable
+      const hct = Hct.from(0, 200, 50);
+
+      // Chroma should be clamped to achievable value
+      expect(hct.chroma).toBeLessThanOrEqual(150);
+    });
+  });
+
+  describe("fromInt static method", () => {
+    it("should create HCT from ARGB integer", () => {
+      const argb = utils.argbFromRgb(255, 0, 0); // Red
+      const hct = Hct.fromInt(argb);
+
+      // Red should have hue around 0-30
+      expect(hct.hue).toBeGreaterThanOrEqual(0);
+      expect(hct.hue).toBeLessThan(60);
+      expect(hct.chroma).toBeGreaterThan(0);
+    });
+
+    it("should handle grayscale colors", () => {
+      const gray = utils.argbFromRgb(128, 128, 128);
+      const hct = Hct.fromInt(gray);
+
+      expect(hct.chroma).toBeCloseTo(0, 1);
+      expect(hct.tone).toBeCloseTo(50, -1); // Within 10 units
+    });
+
+    it("should handle primary colors", () => {
+      const red = utils.argbFromRgb(255, 0, 0);
+      const green = utils.argbFromRgb(0, 255, 0);
+      const blue = utils.argbFromRgb(0, 0, 255);
+
+      const hctRed = Hct.fromInt(red);
+      const hctGreen = Hct.fromInt(green);
+      const hctBlue = Hct.fromInt(blue);
+
+      // Check that primary colors have high chroma
+      expect(hctRed.chroma).toBeGreaterThan(100);
+      expect(hctGreen.chroma).toBeGreaterThan(100);
+      expect(hctBlue.chroma).toBeGreaterThan(80);
+    });
+  });
+
+  describe("toInt method", () => {
+    it("should convert back to ARGB integer", () => {
+      const originalArgb = utils.argbFromRgb(128, 64, 192);
+      const hct = Hct.fromInt(originalArgb);
+      const resultArgb = hct.toInt();
+
+      // Should be close to original (some loss due to color space conversion)
+      const originalRgb = {
+        b: utils.blueFromArgb(originalArgb),
+        g: utils.greenFromArgb(originalArgb),
+        r: utils.redFromArgb(originalArgb),
+      };
+
+      const resultRgb = {
+        b: utils.blueFromArgb(resultArgb),
+        g: utils.greenFromArgb(resultArgb),
+        r: utils.redFromArgb(resultArgb),
+      };
+
+      expect(resultRgb.r).toBeCloseTo(originalRgb.r, -1); // Within 10
+      expect(resultRgb.g).toBeCloseTo(originalRgb.g, -1);
+      expect(resultRgb.b).toBeCloseTo(originalRgb.b, -1);
+    });
+
+    it("should maintain opaque alpha channel", () => {
+      const hct = Hct.from(180, 50, 50);
+      const argb = hct.toInt();
+
+      // Alpha should be 255 (fully opaque)
+      const alpha = (argb >> 24) & 0xff;
+      expect(alpha).toBe(0xff);
+    });
+  });
+
+  describe("getters", () => {
+    it("should return correct hue", () => {
+      const hct = Hct.from(123.45, 50, 50);
+      expect(hct.hue).toBeCloseTo(123.45, 0);
+    });
+
+    it("should return correct chroma", () => {
+      const hct = Hct.from(180, 45.67, 50);
+      // Chroma might be adjusted to achievable value
+      expect(hct.chroma).toBeGreaterThan(30); // At least some chroma
+      expect(hct.chroma).toBeLessThanOrEqual(45.67); // Not more than requested
+    });
+
+    it("should return correct tone", () => {
+      const hct = Hct.from(180, 50, 78.9);
+      expect(hct.tone).toBeCloseTo(78.9, 0);
+    });
+  });
+
+  describe("setters", () => {
+    it("should update hue", () => {
+      const hct = Hct.from(0, 50, 50);
+      hct.hue = 180;
+
+      expect(hct.hue).toBeCloseTo(180, -1); // Within 10 degrees
+      // Chroma might adjust based on new hue
+      expect(hct.chroma).toBeGreaterThan(30); // At least some chroma
+      expect(hct.tone).toBeCloseTo(50, -1); // Within 10 tone units
+    });
+
+    it("should update chroma", () => {
+      const hct = Hct.from(180, 30, 50);
+      hct.chroma = 60;
+
+      // Chroma might be clamped to achievable value
+      expect(hct.chroma).toBeGreaterThan(30); // At least original chroma
+      expect(hct.chroma).toBeLessThanOrEqual(60); // Not more than requested
+      // Hue should be maintained, allowing for some adjustment
+      expect(hct.hue).toBeGreaterThan(170);
+      expect(hct.hue).toBeLessThan(190);
+      expect(hct.tone).toBeCloseTo(50, -1); // Within 10 tone units
+    });
+
+    it("should update tone", () => {
+      const hct = Hct.from(180, 50, 30);
+      hct.tone = 70;
+
+      expect(hct.tone).toBeCloseTo(70, 0); // Very close
+      // Hue might adjust slightly
+      expect(hct.hue).toBeGreaterThan(170);
+      expect(hct.hue).toBeLessThan(190);
+    });
+
+    it("should handle hue wrapping", () => {
+      const hct = Hct.from(350, 50, 50);
+      hct.hue = 370; // Should wrap to 10
+
+      expect(hct.hue).toBeCloseTo(10, 0); // Should be close
+    });
+
+    it("should clamp tone to valid range", () => {
+      const hct = Hct.from(180, 50, 50);
+
+      hct.tone = -10;
+      expect(hct.tone).toBeCloseTo(0, 1);
+
+      hct.tone = 110;
+      expect(hct.tone).toBeCloseTo(100, 1);
+    });
+
+    it("should adjust chroma when not achievable", () => {
+      const hct = Hct.from(180, 50, 95); // High tone
+      hct.chroma = 100; // High chroma at high tone is difficult
+
+      // Chroma should be adjusted to achievable value
+      expect(hct.chroma).toBeLessThanOrEqual(100);
+    });
+  });
+
+  describe("round-trip conversions", () => {
+    it("should maintain values through round-trip", () => {
+      const originalHct = Hct.from(240, 40, 60);
+      const argb = originalHct.toInt();
+      const newHct = Hct.fromInt(argb);
+
+      expect(newHct.hue).toBeCloseTo(originalHct.hue, 0);
+      expect(newHct.chroma).toBeCloseTo(originalHct.chroma, 1);
+      expect(newHct.tone).toBeCloseTo(originalHct.tone, 1);
+    });
+
+    it("should handle edge cases in round-trip", () => {
+      const testCases = [
+        { c: 0, h: 0, t: 0 }, // Black
+        { c: 0, h: 0, t: 100 }, // White
+        { c: 0, h: 0, t: 50 }, // Gray
+        { c: 100, h: 0, t: 50 }, // High chroma red
+        { c: 100, h: 120, t: 50 }, // High chroma green
+        { c: 100, h: 240, t: 50 }, // High chroma blue
+      ];
+
+      for (const testCase of testCases) {
+        const hct1 = Hct.from(testCase.h, testCase.c, testCase.t);
+        const argb = hct1.toInt();
+        const hct2 = Hct.fromInt(argb);
+
+        // Tone should be very close
+        expect(hct2.tone).toBeCloseTo(hct1.tone, 0);
+
+        // For non-grayscale, hue should be maintained
+        if (testCase.c > 0 && hct2.chroma > 1) {
+          const hueDiff = Math.abs(hct2.hue - hct1.hue);
+          const normalizedDiff = Math.min(hueDiff, 360 - hueDiff);
+          expect(normalizedDiff).toBeLessThan(5);
+        }
+      }
+    });
+  });
+});