@trishchuk/coolors-mcp 1.0.0

package/src/color/hct/harmonization.ts

@@ -0,0 +1,204 @@
+/**
+ * Color Harmonization
+ * Algorithms to blend and harmonize colors based on Material Design principles
+ */
+
+import type { RGB } from "../types.js";
+
+import { hct, hctToRgb, rgbToHct } from "./hct-solver.js";
+
+/**
+ * Temperature-based color adjustment
+ * Warmer (positive) or cooler (negative) adjustment
+ */
+export function adjustTemperature(color: RGB, amount: number): RGB {
+  const hctColor = rgbToHct(color);
+
+  // Warm colors: red-orange-yellow (0-60, 300-360)
+  // Cool colors: green-blue-purple (60-300)
+  const isWarm = hctColor.h <= 60 || hctColor.h >= 300;
+
+  let newHue: number;
+  if (amount > 0) {
+    // Make warmer - shift toward orange (30 degrees)
+    newHue = isWarm
+      ? circularInterpolate(hctColor.h, 30, Math.min(amount, 1))
+      : circularInterpolate(hctColor.h, 30, Math.min(amount * 2, 1));
+  } else {
+    // Make cooler - shift toward blue (210 degrees)
+    newHue = !isWarm
+      ? circularInterpolate(hctColor.h, 210, Math.min(-amount, 1))
+      : circularInterpolate(hctColor.h, 210, Math.min(-amount * 2, 1));
+  }
+
+  return hctToRgb(hct(newHue, hctColor.c, hctColor.t));
+}
+
+/**
+ * Find analogous colors (adjacent on color wheel)
+ */
+export function analogous(
+  color: RGB,
+  angle: number = 30,
+  count: number = 2,
+): RGB[] {
+  const hctColor = rgbToHct(color);
+  const colors: RGB[] = [];
+
+  for (let i = 1; i <= count; i++) {
+    // Add colors on both sides
+    colors.push(
+      hctToRgb(
+        hct(
+          sanitizeDegreesDouble(hctColor.h + angle * i),
+          hctColor.c,
+          hctColor.t,
+        ),
+      ),
+    );
+
+    colors.push(
+      hctToRgb(
+        hct(
+          sanitizeDegreesDouble(hctColor.h - angle * i),
+          hctColor.c,
+          hctColor.t,
+        ),
+      ),
+    );
+  }
+
+  return colors;
+}
+
+/**
+ * Blend two colors in HCT space
+ * More perceptually uniform than RGB blending
+ */
+export function blend(from: RGB, to: RGB, amount: number): RGB {
+  const fromHct = rgbToHct(from);
+  const toHct = rgbToHct(to);
+
+  // Interpolate in HCT space
+  const h = circularInterpolate(fromHct.h, toHct.h, amount);
+  const c = fromHct.c + (toHct.c - fromHct.c) * amount;
+  const t = fromHct.t + (toHct.t - fromHct.t) * amount;
+
+  return hctToRgb(hct(h, c, t));
+}
+
+/**
+ * Create a double complementary (rectangle) scheme
+ */
+export function doubleComplementary(
+  color1: RGB,
+  color2: RGB,
+): [RGB, RGB, RGB, RGB] {
+  const hct1 = rgbToHct(color1);
+  const hct2 = rgbToHct(color2);
+
+  return [
+    color1,
+    color2,
+    hctToRgb(hct((hct1.h + 180) % 360, hct1.c, hct1.t)),
+    hctToRgb(hct((hct2.h + 180) % 360, hct2.c, hct2.t)),
+  ];
+}
+
+/**
+ * Create a gradient between two colors
+ */
+export function gradient(from: RGB, to: RGB, steps: number): RGB[] {
+  const colors: RGB[] = [];
+
+  for (let i = 0; i < steps; i++) {
+    const amount = i / (steps - 1);
+    colors.push(blend(from, to, amount));
+  }
+
+  return colors;
+}
+
+/**
+ * Harmonize a color with a target, making them work better together
+ * Based on Material's blend algorithm
+ */
+export function harmonize(design: RGB, source: RGB, factor: number = 0.5): RGB {
+  const fromHct = rgbToHct(design);
+  const toHct = rgbToHct(source);
+
+  const diffDegrees = differenceDegrees(fromHct.h, toHct.h);
+  const rotationDegrees = Math.min(diffDegrees * factor, 15);
+  const outputHue = sanitizeDegreesDouble(
+    fromHct.h + rotationDegrees * rotationDirection(fromHct.h, toHct.h),
+  );
+
+  return hctToRgb(hct(outputHue, fromHct.c, fromHct.t));
+}
+
+/**
+ * Find split-complementary colors
+ */
+export function splitComplementary(
+  color: RGB,
+  angle: number = 30,
+): [RGB, RGB, RGB] {
+  const hctColor = rgbToHct(color);
+  const complement = (hctColor.h + 180) % 360;
+
+  return [
+    color,
+    hctToRgb(
+      hct(sanitizeDegreesDouble(complement - angle), hctColor.c, hctColor.t),
+    ),
+    hctToRgb(
+      hct(sanitizeDegreesDouble(complement + angle), hctColor.c, hctColor.t),
+    ),
+  ];
+}
+
+/**
+ * Find tetradic (square) colors - four colors evenly spaced
+ */
+export function tetradic(color: RGB): [RGB, RGB, RGB, RGB] {
+  const hctColor = rgbToHct(color);
+
+  return [
+    color,
+    hctToRgb(hct((hctColor.h + 90) % 360, hctColor.c, hctColor.t)),
+    hctToRgb(hct((hctColor.h + 180) % 360, hctColor.c, hctColor.t)),
+    hctToRgb(hct((hctColor.h + 270) % 360, hctColor.c, hctColor.t)),
+  ];
+}
+
+// Helper functions
+
+function circularInterpolate(from: number, to: number, amount: number): number {
+  const difference = to - from;
+  const distance = Math.abs(difference);
+
+  if (distance > 180) {
+    // Take the shorter path around the circle
+    if (difference > 0) {
+      from += 360;
+    } else {
+      to += 360;
+    }
+  }
+
+  return sanitizeDegreesDouble(from + (to - from) * amount);
+}
+
+function differenceDegrees(a: number, b: number): number {
+  return Math.abs(((a - b + 180) % 360) - 180);
+}
+
+function rotationDirection(from: number, to: number): number {
+  const difference = to - from;
+  const normalized = ((difference + 180) % 360) - 180;
+  return normalized >= 0 ? 1 : -1;
+}
+
+function sanitizeDegreesDouble(degrees: number): number {
+  return ((degrees % 360) + 360) % 360;
+}

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

@@ -0,0 +1,109 @@
+/**
+ * HCT Class wrapper for Material Color Utilities compatibility
+ */
+
+import { argbToRgb, rgbToArgb } from "../conversions.js";
+import { hctToRgb, rgbToHct } from "./hct-solver.js";
+
+/**
+ * HCT class compatible with Material Color Utilities
+ */
+export class Hct {
+  get chroma(): number {
+    return this._chroma;
+  }
+  /**
+   * Set the chroma of this color. Chroma may decrease because chroma has a
+   * different maximum for any given hue and tone.
+   * @param newChroma 0 <= newChroma < ?
+   */
+  set chroma(newChroma: number) {
+    const rgb = hctToRgb({ c: newChroma, h: this._hue, t: this._tone });
+    this._argb = rgbToArgb(rgb);
+    const hct = rgbToHct(rgb);
+    this._hue = hct.h;
+    this._chroma = hct.c;
+    this._tone = hct.t;
+  }
+  get hue(): number {
+    return this._hue;
+  }
+  /**
+   * Set the hue of this color. Chroma may decrease because chroma has a
+   * different maximum for any given hue and tone.
+   * @param newHue 0 <= newHue < 360; invalid values are corrected.
+   */
+  set hue(newHue: number) {
+    const rgb = hctToRgb({ c: this._chroma, h: newHue, t: this._tone });
+    this._argb = rgbToArgb(rgb);
+    const hct = rgbToHct(rgb);
+    this._hue = hct.h;
+    this._chroma = hct.c;
+    this._tone = hct.t;
+  }
+
+  get tone(): number {
+    return this._tone;
+  }
+
+  /**
+   * Set the tone of this color. Chroma may decrease because chroma has a
+   * different maximum for any given hue and tone.
+   * @param newTone 0 <= newTone <= 100; invalid values are corrected.
+   */
+  set tone(newTone: number) {
+    const rgb = hctToRgb({ c: this._chroma, h: this._hue, t: newTone });
+    this._argb = rgbToArgb(rgb);
+    const hct = rgbToHct(rgb);
+    this._hue = hct.h;
+    this._chroma = hct.c;
+    this._tone = hct.t;
+  }
+
+  private _argb: number;
+
+  private _chroma: number;
+
+  private _hue: number;
+
+  private _tone: number;
+
+  private constructor(argb: number) {
+    this._argb = argb;
+    const rgb = argbToRgb(argb);
+    const hct = rgbToHct(rgb);
+    this._hue = hct.h;
+    this._chroma = hct.c;
+    this._tone = hct.t;
+  }
+
+  /**
+   * Create an HCT color from hue, chroma, and tone.
+   * @param hue 0 <= hue < 360; invalid values are corrected.
+   * @param chroma 0 <= chroma < ?; Chroma may decrease because chroma has a
+   *     different maximum for any given hue and tone.
+   * @param tone 0 <= tone <= 100; invalid values are corrected.
+   * @return HCT representation of a color in default viewing conditions.
+   */
+  static from(hue: number, chroma: number, tone: number): Hct {
+    const rgb = hctToRgb({ c: chroma, h: hue, t: tone });
+    const argb = rgbToArgb(rgb);
+    return new Hct(argb);
+  }
+
+  /**
+   * Create an HCT color from a color.
+   * @param argb ARGB representation of a color.
+   * @return HCT representation of a color in default viewing conditions
+   */
+  static fromInt(argb: number): Hct {
+    return new Hct(argb);
+  }
+
+  /**
+   * @return ARGB representation of an HCT color.
+   */
+  toInt(): number {
+    return this._argb;
+  }
+}

package/src/color/hct/hct-solver.ts

@@ -0,0 +1,168 @@
+/**
+ * HCT Solver - Converts between HCT and RGB color spaces
+ * Based on Material Color Utilities algorithms
+ */
+
+import type { RGB } from "../types.js";
+import type { HCT } from "./types.js";
+
+import { labToXyz, rgbToXyz, xyzToLab, xyzToRgb } from "../conversions.js";
+
+/**
+ * Create an HCT color from components
+ */
+export function hct(hue: number, chroma: number, tone: number): HCT {
+  return {
+    c: Math.max(0, chroma),
+    h: sanitizeDegrees(hue),
+    t: Math.max(0, Math.min(100, tone)),
+  };
+}
+
+/**
+ * Convert HCT to RGB using iterative solving
+ * This is a simplified version of Material's HCT solver
+ */
+export function hctToRgb(hct: HCT): RGB {
+  const hue = sanitizeDegrees(hct.h);
+  const chroma = Math.max(0, hct.c);
+  const tone = Math.max(0, Math.min(100, hct.t));
+
+  // Special cases
+  if (chroma < 0.0001 || tone < 0.5 || tone > 99.5) {
+    const gray = (tone / 100) * 255;
+    return { b: gray, g: gray, r: gray };
+  }
+
+  // Convert tone to L*
+  const lstar = tone;
+
+  // Use iterative approach to find the right chroma
+  let bestRgb: null | RGB = null;
+
+  // Binary search for achievable chroma
+  let low = 0;
+  let high = chroma;
+  const epsilon = 0.01;
+
+  while (high - low > epsilon) {
+    const mid = (low + high) / 2;
+
+    // Convert to LAB using approximate chroma
+    const a = mid * Math.cos((hue * Math.PI) / 180);
+    const b = mid * Math.sin((hue * Math.PI) / 180);
+
+    // Convert LAB to XYZ to RGB
+    const xyz = labToXyz({ a, b, l: lstar });
+    const rgb = xyzToRgb(xyz);
+
+    // Check if RGB is in gamut
+    if (isInGamut(rgb)) {
+      bestRgb = rgb;
+      low = mid;
+    } else {
+      high = mid;
+    }
+  }
+
+  // If we found a valid RGB, use it
+  if (bestRgb) {
+    return clampRgb(bestRgb);
+  }
+
+  // Fallback: reduce chroma until in gamut
+  for (let c = chroma; c >= 0; c -= 1) {
+    const a = c * Math.cos((hue * Math.PI) / 180);
+    const b = c * Math.sin((hue * Math.PI) / 180);
+
+    const xyz = labToXyz({ a, b, l: lstar });
+    const rgb = xyzToRgb(xyz);
+
+    if (isInGamut(rgb)) {
+      return clampRgb(rgb);
+    }
+  }
+
+  // Final fallback: gray
+  const gray = (tone / 100) * 255;
+  return { b: gray, g: gray, r: gray };
+}
+
+/**
+ * Get maximum chroma for a given hue and tone
+ * This is an approximation - actual max varies
+ */
+export function maxChroma(hue: number, tone: number): number {
+  // Edge cases
+  if (tone <= 0 || tone >= 100) return 0;
+
+  // Approximate maximum chroma
+  // This varies significantly based on hue and tone
+  // Red/magenta hues can achieve higher chroma
+  const hueCycle = (hue % 360) / 360;
+  const redBoost = Math.sin(hueCycle * Math.PI * 2) * 0.2 + 1;
+
+  // Chroma peaks around middle tones
+  const toneFactor = Math.sin((tone / 100) * Math.PI);
+
+  return toneFactor * 120 * redBoost;
+}
+
+/**
+ * Convert RGB to HCT
+ */
+export function rgbToHct(rgb: RGB): HCT {
+  // Convert RGB to LAB
+  const xyz = rgbToXyz(rgb);
+  const lab = xyzToLab(xyz);
+
+  // Extract tone from L*
+  const tone = lab.l;
+
+  // Calculate chroma and hue from a* and b*
+  const chroma = Math.sqrt(lab.a * lab.a + lab.b * lab.b);
+  let hue = (Math.atan2(lab.b, lab.a) * 180) / Math.PI;
+
+  // Ensure hue is positive
+  if (hue < 0) {
+    hue += 360;
+  }
+
+  return {
+    c: chroma,
+    h: sanitizeDegrees(hue),
+    t: tone,
+  };
+}
+
+/**
+ * Clamp RGB values to valid range
+ */
+function clampRgb(rgb: RGB): RGB {
+  return {
+    b: Math.round(Math.max(0, Math.min(255, rgb.b))),
+    g: Math.round(Math.max(0, Math.min(255, rgb.g))),
+    r: Math.round(Math.max(0, Math.min(255, rgb.r))),
+  };
+}
+
+/**
+ * Check if RGB values are in valid gamut
+ */
+function isInGamut(rgb: RGB): boolean {
+  return (
+    rgb.r >= 0 &&
+    rgb.r <= 255 &&
+    rgb.g >= 0 &&
+    rgb.g <= 255 &&
+    rgb.b >= 0 &&
+    rgb.b <= 255
+  );
+}
+
+/**
+ * Sanitize degrees to be in [0, 360)
+ */
+function sanitizeDegrees(degrees: number): number {
+  return ((degrees % 360) + 360) % 360;
+}

package/src/color/hct/index.ts

@@ -0,0 +1,39 @@
+/**
+ * HCT Color Module
+ * Export all HCT-related functionality
+ */
+
+// Harmonization
+export {
+  adjustTemperature,
+  analogous,
+  blend,
+  doubleComplementary,
+  gradient,
+  harmonize,
+  splitComplementary,
+  tetradic,
+} from "./harmonization.js";
+// HCT Class (Material Color Utilities compatible)
+export { Hct } from "./hct-class.js";
+
+// HCT Solver
+export { hct, hctToRgb, maxChroma, rgbToHct } from "./hct-solver.js";
+
+// Tonal Palettes
+export {
+  analogousPalette,
+  complementaryPalette,
+  type CorePalette,
+  corePaletteFromRgb,
+  EXTENDED_TONES,
+  MATERIAL_TONES,
+  monochromaticPalette,
+  TonalPalette,
+  triadicPalette,
+} from "./tonal-palette.js";
+
+// Types
+export type { CAM16, HCT, ViewingConditions } from "./types.js";
+
+export { STANDARD_CONDITIONS } from "./types.js";