@trishchuk/coolors-mcp 1.0.0

package/src/color/hct/tonal-palette.ts

@@ -0,0 +1,211 @@
+/**
+ * Tonal Palette Generator
+ * Creates Material Design 3 tonal palettes from HCT colors
+ */
+
+import type { RGB } from "../types.js";
+import type { HCT } from "./types.js";
+
+import { hct, hctToRgb, rgbToHct } from "./hct-solver.js";
+
+/**
+ * Standard Material 3 tone values
+ */
+export const MATERIAL_TONES = [
+  0, 10, 20, 30, 40, 50, 60, 70, 80, 90, 95, 99, 100,
+] as const;
+
+/**
+ * Extended tone values for more granularity
+ */
+export const EXTENDED_TONES = [
+  0, 5, 10, 15, 20, 25, 30, 35, 40, 45, 50, 55, 60, 65, 70, 75, 80, 85, 90, 92,
+  94, 96, 98, 99, 100,
+] as const;
+
+/**
+ * Material 3 Core Palette
+ * Contains all the tonal palettes needed for a complete theme
+ */
+export interface CorePalette {
+  /** Error color palette */
+  error: TonalPalette;
+  /** Neutral color palette (grays) */
+  neutral: TonalPalette;
+  /** Neutral variant palette (slightly tinted grays) */
+  neutralVariant: TonalPalette;
+  /** Primary color palette */
+  primary: TonalPalette;
+  /** Secondary color palette */
+  secondary: TonalPalette;
+  /** Tertiary color palette */
+  tertiary: TonalPalette;
+}
+
+/**
+ * A tonal palette - variations of a single color at different tones
+ */
+export class TonalPalette {
+  /**
+   * Get extended tones for more options
+   */
+  get extendedTones(): Record<number, RGB> {
+    const tones: Record<number, RGB> = {};
+    for (const t of EXTENDED_TONES) {
+      tones[t] = this.tone(t);
+    }
+    return tones;
+  }
+
+  /**
+   * Get all Material 3 standard tones
+   */
+  get materialTones(): Record<number, RGB> {
+    const tones: Record<number, RGB> = {};
+    for (const t of MATERIAL_TONES) {
+      tones[t] = this.tone(t);
+    }
+    return tones;
+  }
+
+  private cache = new Map<number, RGB>();
+
+  constructor(
+    public readonly hue: number,
+    public readonly chroma: number,
+  ) {}
+
+  /**
+   * Create a tonal palette from an HCT color
+   */
+  static fromHct(color: HCT): TonalPalette {
+    return new TonalPalette(color.h, color.c);
+  }
+
+  /**
+   * Create a tonal palette from an RGB color
+   */
+  static fromRgb(rgb: RGB): TonalPalette {
+    const hctColor = rgbToHct(rgb);
+    return new TonalPalette(hctColor.h, hctColor.c);
+  }
+
+  /**
+   * Get the color at a specific tone
+   */
+  tone(tone: number): RGB {
+    // Check cache first
+    if (this.cache.has(tone)) {
+      return this.cache.get(tone)!;
+    }
+
+    // Generate and cache
+    const color = hctToRgb(hct(this.hue, this.chroma, tone));
+    this.cache.set(tone, color);
+    return color;
+  }
+}
+
+/**
+ * Generate an analogous palette (adjacent hues)
+ */
+export function analogousPalette(
+  source: RGB,
+  count: number = 5,
+  hueShift: number = 30,
+): TonalPalette[] {
+  const sourceHct = rgbToHct(source);
+  const palettes: TonalPalette[] = [];
+
+  const startHue = sourceHct.h - hueShift * Math.floor(count / 2);
+
+  for (let i = 0; i < count; i++) {
+    const hue = (startHue + i * hueShift + 360) % 360;
+    palettes.push(new TonalPalette(hue, sourceHct.c));
+  }
+
+  return palettes;
+}
+
+/**
+ * Generate a complementary palette
+ */
+export function complementaryPalette(
+  source: RGB,
+): [TonalPalette, TonalPalette] {
+  const sourceHct = rgbToHct(source);
+
+  return [
+    new TonalPalette(sourceHct.h, sourceHct.c),
+    new TonalPalette((sourceHct.h + 180) % 360, sourceHct.c),
+  ];
+}
+
+/**
+ * Generate a complete Material 3 core palette from a source color
+ */
+export function corePaletteFromRgb(source: RGB): CorePalette {
+  const sourceHct = rgbToHct(source);
+
+  // Primary uses the source color
+  const primary = new TonalPalette(sourceHct.h, Math.max(48, sourceHct.c));
+
+  // Secondary is shifted in hue and reduced chroma
+  const secondary = new TonalPalette(
+    sourceHct.h,
+    Math.max(16, sourceHct.c / 3),
+  );
+
+  // Tertiary shifts hue by 60 degrees
+  const tertiary = new TonalPalette(
+    (sourceHct.h + 60) % 360,
+    Math.max(24, sourceHct.c / 2),
+  );
+
+  // Error is always red-ish
+  const error = new TonalPalette(25, 84);
+
+  // Neutral has very low chroma
+  const neutral = new TonalPalette(sourceHct.h, Math.min(4, sourceHct.c / 12));
+
+  // Neutral variant has slightly more chroma
+  const neutralVariant = new TonalPalette(
+    sourceHct.h,
+    Math.min(8, sourceHct.c / 6),
+  );
+
+  return {
+    error,
+    neutral,
+    neutralVariant,
+    primary,
+    secondary,
+    tertiary,
+  };
+}
+
+/**
+ * Generate a monochromatic palette (single hue, varying tones)
+ */
+export function monochromaticPalette(
+  source: RGB,
+  tones: readonly number[] = MATERIAL_TONES,
+): RGB[] {
+  const palette = TonalPalette.fromRgb(source);
+  return tones.map((t) => palette.tone(t));
+}
+
+/**
+ * Generate a triadic palette (three colors evenly spaced)
+ */
+export function triadicPalette(
+  source: RGB,
+): [TonalPalette, TonalPalette, TonalPalette] {
+  const sourceHct = rgbToHct(source);
+
+  return [
+    new TonalPalette(sourceHct.h, sourceHct.c),
+    new TonalPalette((sourceHct.h + 120) % 360, sourceHct.c),
+    new TonalPalette((sourceHct.h + 240) % 360, sourceHct.c),
+  ];
+}

package/src/color/hct/types.ts

@@ -0,0 +1,88 @@
+/**
+ * HCT (Hue, Chroma, Tone) color space types
+ * Based on Material Color Utilities
+ */
+
+/**
+ * CAM16 color appearance model
+ * Predicts color appearance under different viewing conditions
+ */
+export interface CAM16 {
+  /** Chroma composition */
+  astar: number;
+  /** Brightness composition */
+  bstar: number;
+  /** Chroma */
+  chroma: number;
+  /** Hue angle */
+  hue: number;
+  /** Lightness */
+  j: number;
+  /** Hue composition */
+  jstar: number;
+  /** Colorfulness */
+  m: number;
+  /** Brightness */
+  q: number;
+  /** Saturation */
+  s: number;
+}
+
+/**
+ * HCT color representation
+ * A perceptually accurate color space that combines:
+ * - Hue from CAM16
+ * - Chroma from CAM16
+ * - Tone (Lightness) from L* (LAB)
+ */
+export interface HCT {
+  /** Chroma (colorfulness) [0, ~150] - actual max varies by hue and tone */
+  c: number;
+  /** Hue angle in degrees [0, 360) */
+  h: number;
+  /** Tone (lightness) [0, 100] */
+  t: number;
+}
+
+/**
+ * Viewing conditions for CAM16
+ * Describes the environment in which colors are viewed
+ */
+export interface ViewingConditions {
+  /** Background luminance ratio */
+  aw: number;
+  /** Base exponential nonlinearity */
+  c: number;
+  /** Degree of adaptation */
+  fl: number;
+  /** Luminance level adaptation factor */
+  flRoot: number;
+  /** Adapting luminance */
+  n: number;
+  /** Luminance level adaptation factor */
+  nbb: number;
+  /** Chromatic induction factor */
+  nc: number;
+  /** Chromatic induction factor */
+  ncb: number;
+  /** Achromatic response for white */
+  rgbD: [number, number, number];
+  /** Surround factor */
+  z: number;
+}
+
+/**
+ * Standard viewing conditions
+ */
+export const STANDARD_CONDITIONS: ViewingConditions = {
+  aw: 29.98,
+  c: 0.69,
+  fl: 0.388,
+  flRoot: 0.789,
+  n: 0.184,
+  nbb: 1.017,
+  nc: 1.0,
+  ncb: 1.017,
+  rgbD: [1.021, 0.986, 0.934],
+  z: 1.909,
+};

package/src/color/image-utils.ts

@@ -0,0 +1,79 @@
+/**
+ * Image processing utilities for color extraction
+ */
+
+import * as utils from "./utils/color_utils.js";
+
+/**
+ * Filter out near-white and near-black pixels
+ * @param pixels - Array of ARGB pixels
+ * @returns Filtered array
+ */
+export function filterExtremeTones(pixels: number[]): number[] {
+  return pixels.filter((pixel) => {
+    const r = utils.redFromArgb(pixel);
+    const g = utils.greenFromArgb(pixel);
+    const b = utils.blueFromArgb(pixel);
+
+    // Calculate luminance (rough approximation)
+    const luminance = 0.299 * r + 0.587 * g + 0.114 * b;
+
+    // Filter out very dark (< 5%) and very light (> 95%) pixels
+    return luminance > 12.75 && luminance < 242.25;
+  });
+}
+
+/**
+ * Convert image data to ARGB pixel array
+ * @param imageData - Canvas ImageData or similar structure
+ * @returns Array of ARGB colors as 32-bit integers
+ */
+export function imageDataToPixels(imageData: {
+  data: number[] | Uint8ClampedArray;
+  height: number;
+  width: number;
+}): number[] {
+  const pixels: number[] = [];
+  const data = imageData.data;
+
+  // Process RGBA data (4 bytes per pixel)
+  for (let i = 0; i < data.length; i += 4) {
+    const r = data[i];
+    const g = data[i + 1];
+    const b = data[i + 2];
+    const a = data[i + 3];
+
+    // Skip fully transparent pixels
+    if (a < 255 * 0.01) continue;
+
+    // Convert to ARGB format
+    const argb = utils.argbFromRgb(r, g, b);
+    pixels.push(argb);
+  }
+
+  return pixels;
+}
+
+/**
+ * Sample pixels from image for faster processing
+ * @param pixels - Full array of pixels
+ * @param maxPixels - Maximum number of pixels to sample
+ * @returns Sampled array of pixels
+ */
+export function samplePixels(
+  pixels: number[],
+  maxPixels: number = 10000,
+): number[] {
+  if (pixels.length <= maxPixels) {
+    return pixels;
+  }
+
+  const sampled: number[] = [];
+  const step = Math.ceil(pixels.length / maxPixels);
+
+  for (let i = 0; i < pixels.length; i += step) {
+    sampled.push(pixels[i]);
+  }
+
+  return sampled;
+}

package/src/color/index.ts

@@ -0,0 +1,87 @@
+/**
+ * Color utilities module
+ * Main exports for color manipulation, conversion, and distance calculations
+ */
+
+// Export all conversion functions
+export {
+  argbToRgb,
+  hexToRgb,
+  hslToRgb,
+  hsvToRgb,
+  labToRgb,
+  labToXyz,
+  parseColor,
+  rgbToArgb,
+  rgbToHex,
+  rgbToHsl,
+  rgbToHsv,
+  rgbToLab,
+  rgbToXyz,
+  xyzToLab,
+  xyzToRgb,
+} from "./conversions.js";
+
+// Export dislike analyzer
+export { DislikeAnalyzer } from "./dislike/dislike-analyzer.js";
+
+// Export HCT functionality
+export * from "./hct/index.js";
+
+// Export all metric functions
+export {
+  areColorsSimilar,
+  colorDistance,
+  deltaE2000,
+  deltaE76,
+  deltaE94,
+  euclideanDistance,
+  findMostDifferentColor,
+  findMostSimilarColor,
+  weightedRgbDistance,
+} from "./metrics.js";
+
+// Export all types
+export type {
+  ColorDistanceOptions,
+  ColorInput,
+  HCT,
+  HEX,
+  HSL,
+  HSV,
+  LAB,
+  ParsedColor,
+  RGB,
+  XYZ,
+} from "./types.js";
+
+export { ColorConstants, ColorFormat } from "./types.js";
+
+// Export all utility functions
+export {
+  clampHsl,
+  clampHsv,
+  clampRgb,
+  darken,
+  desaturate,
+  formatColor,
+  formatHsl,
+  formatRgb,
+  getComplementary,
+  getContrastRatio,
+  getLuminance,
+  invertColor,
+  isDark,
+  isLight,
+  isValidHex,
+  isValidHsl,
+  isValidHsv,
+  isValidRgb,
+  lighten,
+  meetsContrastAA,
+  meetsContrastAAA,
+  mixColors,
+  randomColor,
+  saturate,
+  toGrayscale,
+} from "./utils.js";

package/src/color/material-theme.ts

@@ -0,0 +1,157 @@
+/**
+ * Material Design Theme Generation
+ * Core functionality for Material Design 3 color theme creation
+ */
+
+import { DislikeAnalyzer } from "./dislike/dislike-analyzer.js";
+import { Hct } from "./hct/hct-class.js";
+import {
+  corePaletteFromRgb,
+  parseColor,
+  rgbToArgb,
+  rgbToHex,
+} from "./index.js";
+
+export interface MaterialColorScheme {
+  background: string;
+  error: string;
+  errorContainer: string;
+  onBackground: string;
+  onError: string;
+  onErrorContainer: string;
+  onPrimary: string;
+  onPrimaryContainer: string;
+  onSecondary: string;
+  onSecondaryContainer: string;
+  onSurface: string;
+  onSurfaceVariant: string;
+  onTertiary: string;
+  onTertiaryContainer: string;
+  outline: string;
+  primary: string;
+  primaryContainer: string;
+  secondary: string;
+  secondaryContainer: string;
+  surface: string;
+  surfaceVariant: string;
+  tertiary: string;
+  tertiaryContainer: string;
+}
+
+export interface MaterialTheme {
+  customColors?: Record<string, unknown>;
+  schemes: {
+    dark: MaterialColorScheme;
+    light: MaterialColorScheme;
+  };
+  sourceColor: string;
+}
+
+export interface MaterialThemeOptions {
+  fixDislikedColors?: boolean;
+  includeCustomColors?: boolean;
+  isDark?: boolean;
+}
+
+/**
+ * Generate a complete Material Design 3 theme from a source color
+ */
+export function generateMaterialTheme(
+  sourceColor: string,
+  options: MaterialThemeOptions = {},
+): MaterialTheme {
+  const { fixDislikedColors = true } = options;
+
+  let source = parseColor(sourceColor);
+  if (!source) {
+    throw new Error(`Invalid color format: ${sourceColor}`);
+  }
+
+  // Fix source color if it's disliked
+  if (fixDislikedColors) {
+    const sourceHct = Hct.fromInt(rgbToArgb(source));
+    if (DislikeAnalyzer.isDisliked(sourceHct)) {
+      const fixedHct = DislikeAnalyzer.fixIfDisliked(sourceHct);
+      const fixedArgb = fixedHct.toInt();
+      source = {
+        b: fixedArgb & 0xff,
+        g: (fixedArgb >> 8) & 0xff,
+        r: (fixedArgb >> 16) & 0xff,
+      };
+    }
+  }
+
+  const corePalette = corePaletteFromRgb(source);
+
+  // Generate light theme colors
+  const lightScheme: MaterialColorScheme = {
+    background: rgbToHex(corePalette.neutral.tone(99)),
+    error: rgbToHex(corePalette.error.tone(40)),
+    errorContainer: rgbToHex(corePalette.error.tone(90)),
+    onBackground: rgbToHex(corePalette.neutral.tone(10)),
+
+    onError: rgbToHex(corePalette.error.tone(100)),
+    onErrorContainer: rgbToHex(corePalette.error.tone(10)),
+    onPrimary: rgbToHex(corePalette.primary.tone(100)),
+    onPrimaryContainer: rgbToHex(corePalette.primary.tone(10)),
+
+    onSecondary: rgbToHex(corePalette.secondary.tone(100)),
+    onSecondaryContainer: rgbToHex(corePalette.secondary.tone(10)),
+    onSurface: rgbToHex(corePalette.neutral.tone(10)),
+    onSurfaceVariant: rgbToHex(corePalette.neutralVariant.tone(30)),
+
+    onTertiary: rgbToHex(corePalette.tertiary.tone(100)),
+    onTertiaryContainer: rgbToHex(corePalette.tertiary.tone(10)),
+    outline: rgbToHex(corePalette.neutralVariant.tone(50)),
+    primary: rgbToHex(corePalette.primary.tone(40)),
+
+    primaryContainer: rgbToHex(corePalette.primary.tone(90)),
+    secondary: rgbToHex(corePalette.secondary.tone(40)),
+    secondaryContainer: rgbToHex(corePalette.secondary.tone(90)),
+    surface: rgbToHex(corePalette.neutral.tone(99)),
+
+    surfaceVariant: rgbToHex(corePalette.neutralVariant.tone(90)),
+    tertiary: rgbToHex(corePalette.tertiary.tone(40)),
+    tertiaryContainer: rgbToHex(corePalette.tertiary.tone(90)),
+  };
+
+  // Generate dark theme colors
+  const darkScheme: MaterialColorScheme = {
+    background: rgbToHex(corePalette.neutral.tone(10)),
+    error: rgbToHex(corePalette.error.tone(80)),
+    errorContainer: rgbToHex(corePalette.error.tone(30)),
+    onBackground: rgbToHex(corePalette.neutral.tone(90)),
+
+    onError: rgbToHex(corePalette.error.tone(20)),
+    onErrorContainer: rgbToHex(corePalette.error.tone(90)),
+    onPrimary: rgbToHex(corePalette.primary.tone(20)),
+    onPrimaryContainer: rgbToHex(corePalette.primary.tone(90)),
+
+    onSecondary: rgbToHex(corePalette.secondary.tone(20)),
+    onSecondaryContainer: rgbToHex(corePalette.secondary.tone(90)),
+    onSurface: rgbToHex(corePalette.neutral.tone(90)),
+    onSurfaceVariant: rgbToHex(corePalette.neutralVariant.tone(80)),
+
+    onTertiary: rgbToHex(corePalette.tertiary.tone(20)),
+    onTertiaryContainer: rgbToHex(corePalette.tertiary.tone(90)),
+    outline: rgbToHex(corePalette.neutralVariant.tone(60)),
+    primary: rgbToHex(corePalette.primary.tone(80)),
+
+    primaryContainer: rgbToHex(corePalette.primary.tone(30)),
+    secondary: rgbToHex(corePalette.secondary.tone(80)),
+    secondaryContainer: rgbToHex(corePalette.secondary.tone(30)),
+    surface: rgbToHex(corePalette.neutral.tone(10)),
+
+    surfaceVariant: rgbToHex(corePalette.neutralVariant.tone(30)),
+    tertiary: rgbToHex(corePalette.tertiary.tone(80)),
+    tertiaryContainer: rgbToHex(corePalette.tertiary.tone(30)),
+  };
+
+  return {
+    schemes: {
+      dark: darkScheme,
+      light: lightScheme,
+    },
+    sourceColor,
+  };
+}