@trishchuk/coolors-mcp 1.0.0

package/src/color/score/score.ts

@@ -0,0 +1,175 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { Hct } from "../hct/index.js";
+import * as math from "../utils/math_utils.js";
+
+/**
+ * Default options for ranking colors based on usage counts.
+ * desired: is the max count of the colors returned.
+ * fallbackColorARGB: Is the default color that should be used if no
+ *                    other colors are suitable.
+ * filter: controls if the resulting colors should be filtered to not include
+ *         hues that are not used often enough, and colors that are effectively
+ *         grayscale.
+ */
+declare interface ScoreOptions {
+  desired?: number;
+  fallbackColorARGB?: number;
+  filter?: boolean;
+}
+
+const SCORE_OPTION_DEFAULTS = {
+  desired: 4, // 4 colors matches what Android wallpaper picker.
+  fallbackColorARGB: 0xff4285f4, // Google Blue.
+  filter: true, // Avoid unsuitable colors.
+};
+
+function compare(
+  a: { hct: Hct; score: number },
+  b: { hct: Hct; score: number },
+): number {
+  if (a.score > b.score) {
+    return -1;
+  } else if (a.score < b.score) {
+    return 1;
+  }
+  return 0;
+}
+
+/**
+ *  Given a large set of colors, remove colors that are unsuitable for a UI
+ *  theme, and rank the rest based on suitability.
+ *
+ *  Enables use of a high cluster count for image quantization, thus ensuring
+ *  colors aren't muddied, while curating the high cluster count to a much
+ *  smaller number of appropriate choices.
+ */
+export class Score {
+  private static readonly CUTOFF_CHROMA = 5.0;
+  private static readonly CUTOFF_EXCITED_PROPORTION = 0.01;
+  private static readonly TARGET_CHROMA = 48.0; // A1 Chroma
+  private static readonly WEIGHT_CHROMA_ABOVE = 0.3;
+  private static readonly WEIGHT_CHROMA_BELOW = 0.1;
+  private static readonly WEIGHT_PROPORTION = 0.7;
+
+  private constructor() {}
+
+  /**
+   * Given a map with keys of colors and values of how often the color appears,
+   * rank the colors based on suitability for being used for a UI theme.
+   *
+   * @param colorsToPopulation map with keys of colors and values of how often
+   *     the color appears, usually from a source image.
+   * @param {ScoreOptions} options optional parameters.
+   * @return Colors sorted by suitability for a UI theme. The most suitable
+   *     color is the first item, the least suitable is the last. There will
+   *     always be at least one color returned. If all the input colors
+   *     were not suitable for a theme, a default fallback color will be
+   *     provided, Google Blue.
+   */
+  static score(
+    colorsToPopulation: Map<number, number>,
+    options?: ScoreOptions,
+  ): number[] {
+    const { desired, fallbackColorARGB, filter } = {
+      ...SCORE_OPTION_DEFAULTS,
+      ...options,
+    };
+    // Get the HCT color for each Argb value, while finding the per hue count and
+    // total count.
+    const colorsHct: Hct[] = [];
+    const huePopulation = new Array<number>(360).fill(0);
+    let populationSum = 0;
+    for (const [argb, population] of colorsToPopulation.entries()) {
+      const hct = Hct.fromInt(argb);
+      colorsHct.push(hct);
+      const hue = Math.floor(hct.hue);
+      huePopulation[hue] += population;
+      populationSum += population;
+    }
+
+    // Hues with more usage in neighboring 30 degree slice get a larger number.
+    const hueExcitedProportions = new Array<number>(360).fill(0.0);
+    for (let hue = 0; hue < 360; hue++) {
+      const proportion = huePopulation[hue] / populationSum;
+      for (let i = hue - 14; i < hue + 16; i++) {
+        const neighborHue = math.sanitizeDegreesInt(i);
+        hueExcitedProportions[neighborHue] += proportion;
+      }
+    }
+
+    // Scores each HCT color based on usage and chroma, while optionally
+    // filtering out values that do not have enough chroma or usage.
+    const scoredHct = new Array<{ hct: Hct; score: number }>();
+    for (const hct of colorsHct) {
+      const hue = math.sanitizeDegreesInt(Math.round(hct.hue));
+      const proportion = hueExcitedProportions[hue];
+      if (
+        filter &&
+        (hct.chroma < Score.CUTOFF_CHROMA ||
+          proportion <= Score.CUTOFF_EXCITED_PROPORTION)
+      ) {
+        continue;
+      }
+
+      const proportionScore = proportion * 100.0 * Score.WEIGHT_PROPORTION;
+      const chromaWeight =
+        hct.chroma < Score.TARGET_CHROMA
+          ? Score.WEIGHT_CHROMA_BELOW
+          : Score.WEIGHT_CHROMA_ABOVE;
+      const chromaScore = (hct.chroma - Score.TARGET_CHROMA) * chromaWeight;
+      const score = proportionScore + chromaScore;
+      scoredHct.push({ hct, score });
+    }
+    // Sorted so that colors with higher scores come first.
+    scoredHct.sort(compare);
+
+    // Iterates through potential hue differences in degrees in order to select
+    // the colors with the largest distribution of hues possible. Starting at
+    // 90 degrees(maximum difference for 4 colors) then decreasing down to a
+    // 15 degree minimum.
+    const chosenColors: Hct[] = [];
+    for (
+      let differenceDegrees = 90;
+      differenceDegrees >= 15;
+      differenceDegrees--
+    ) {
+      chosenColors.length = 0;
+      for (const { hct } of scoredHct) {
+        const duplicateHue = chosenColors.find((chosenHct) => {
+          return (
+            math.differenceDegrees(hct.hue, chosenHct.hue) < differenceDegrees
+          );
+        });
+        if (!duplicateHue) {
+          chosenColors.push(hct);
+        }
+        if (chosenColors.length >= desired) break;
+      }
+      if (chosenColors.length >= desired) break;
+    }
+    const colors: number[] = [];
+    if (chosenColors.length === 0) {
+      colors.push(fallbackColorARGB);
+    }
+    for (const chosenHct of chosenColors) {
+      colors.push(chosenHct.toInt());
+    }
+    return colors;
+  }
+}

package/src/color/types.ts

@@ -0,0 +1,151 @@
+/**
+ * Color type definitions for various color spaces
+ */
+
+/**
+ * Supported color formats for parsing
+ */
+export enum ColorFormat {
+  HEX = "hex",
+  HSL = "hsl",
+  HSV = "hsv",
+  LAB = "lab",
+  RGB = "rgb",
+  XYZ = "xyz",
+}
+
+/**
+ * Options for color distance calculations
+ */
+export interface ColorDistanceOptions {
+  /**
+   * Parameters for Delta E 94
+   */
+  deltaE94?: {
+    kC?: number;
+    kH?: number;
+    kL?: number;
+  };
+
+  /**
+   * Type of distance metric to use
+   */
+  metric?: "deltaE2000" | "deltaE76" | "deltaE94" | "euclidean" | "weighted";
+
+  /**
+   * Weights for weighted RGB distance
+   */
+  weights?: {
+    b?: number;
+    g?: number;
+    r?: number;
+  };
+}
+
+/**
+ * Color input type that can be parsed
+ */
+export type ColorInput = HSL | HSV | LAB | RGB | string | XYZ;
+
+/**
+ * HCT (Hue, Chroma, Tone) color representation
+ */
+export interface HCT {
+  c: number; // Chroma [0, ~150]
+  h: number; // Hue [0, 360)
+  t: number; // Tone [0, 100]
+}
+
+/**
+ * Hexadecimal color representation
+ */
+export type HEX = string;
+
+/**
+ * HSL (Hue, Saturation, Lightness) color representation
+ * h: [0, 360] degrees
+ * s: [0, 100] percentage
+ * l: [0, 100] percentage
+ */
+export interface HSL {
+  h: number;
+  l: number;
+  s: number;
+}
+
+/**
+ * HSV (Hue, Saturation, Value) color representation
+ * Also known as HSB (Hue, Saturation, Brightness)
+ * h: [0, 360] degrees
+ * s: [0, 100] percentage
+ * v: [0, 100] percentage
+ */
+export interface HSV {
+  h: number;
+  s: number;
+  v: number;
+}
+
+/**
+ * LAB color space (CIE L*a*b*)
+ * L: [0, 100] lightness
+ * a: [-128, 127] green-red axis
+ * b: [-128, 127] blue-yellow axis
+ */
+export interface LAB {
+  a: number;
+  b: number;
+  l: number;
+}
+
+/**
+ * Color parsing result
+ */
+export interface ParsedColor {
+  format: ColorFormat;
+  value: HSL | HSV | LAB | RGB | XYZ;
+}
+
+/**
+ * RGB color representation
+ * Values should be in range [0, 255]
+ */
+export interface RGB {
+  b: number;
+  g: number;
+  r: number;
+}
+
+/**
+ * XYZ color space (CIE 1931)
+ * Reference white: D65 illuminant
+ */
+export interface XYZ {
+  x: number;
+  y: number;
+  z: number;
+}
+
+/**
+ * Constants for color space conversions
+ */
+export const ColorConstants = {
+  /**
+   * D65 illuminant reference white point
+   */
+  D65: {
+    X: 95.047,
+    Y: 100.0,
+    Z: 108.883,
+  },
+
+  /**
+   * Epsilon for LAB conversion
+   */
+  EPSILON: 0.008856,
+
+  /**
+   * Kappa for LAB conversion
+   */
+  KAPPA: 903.3,
+} as const;

package/src/color/utils/color_utils.ts

@@ -0,0 +1,292 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// This file is automatically generated. Do not modify it.
+
+import * as mathUtils from "./math_utils.js";
+
+/**
+ * Color science utilities.
+ *
+ * Utility methods for color science constants and color space
+ * conversions that aren't HCT or CAM16.
+ */
+
+const SRGB_TO_XYZ = [
+  [0.41233895, 0.35762064, 0.18051042],
+  [0.2126, 0.7152, 0.0722],
+  [0.01932141, 0.11916382, 0.95034478],
+];
+
+const XYZ_TO_SRGB = [
+  [3.2413774792388685, -1.5376652402851851, -0.49885366846268053],
+  [-0.9691452513005321, 1.8758853451067872, 0.04156585616912061],
+  [0.05562093689691305, -0.20395524564742123, 1.0571799111220335],
+];
+
+const WHITE_POINT_D65 = [95.047, 100.0, 108.883];
+
+/**
+ * Returns the alpha component of a color in ARGB format.
+ */
+export function alphaFromArgb(argb: number): number {
+  return (argb >> 24) & 255;
+}
+
+/**
+ * Converts a color represented in Lab color space into an ARGB
+ * integer.
+ */
+export function argbFromLab(l: number, a: number, b: number): number {
+  const whitePoint = WHITE_POINT_D65;
+  const fy = (l + 16.0) / 116.0;
+  const fx = a / 500.0 + fy;
+  const fz = fy - b / 200.0;
+  const xNormalized = labInvf(fx);
+  const yNormalized = labInvf(fy);
+  const zNormalized = labInvf(fz);
+  const x = xNormalized * whitePoint[0];
+  const y = yNormalized * whitePoint[1];
+  const z = zNormalized * whitePoint[2];
+  return argbFromXyz(x, y, z);
+}
+
+/**
+ * Converts a color from linear RGB components to ARGB format.
+ */
+export function argbFromLinrgb(linrgb: number[]): number {
+  const r = delinearized(linrgb[0]);
+  const g = delinearized(linrgb[1]);
+  const b = delinearized(linrgb[2]);
+  return argbFromRgb(r, g, b);
+}
+
+/**
+ * Converts an L* value to an ARGB representation.
+ *
+ * @param lstar L* in L*a*b*
+ * @return ARGB representation of grayscale color with lightness
+ * matching L*
+ */
+export function argbFromLstar(lstar: number): number {
+  const y = yFromLstar(lstar);
+  const component = delinearized(y);
+  return argbFromRgb(component, component, component);
+}
+
+/**
+ * Converts a color from RGB components to ARGB format.
+ */
+export function argbFromRgb(red: number, green: number, blue: number): number {
+  return (
+    ((255 << 24) |
+      ((red & 255) << 16) |
+      ((green & 255) << 8) |
+      (blue & 255)) >>>
+    0
+  );
+}
+
+/**
+ * Converts a color from ARGB to XYZ.
+ */
+export function argbFromXyz(x: number, y: number, z: number): number {
+  const matrix = XYZ_TO_SRGB;
+  const linearR = matrix[0][0] * x + matrix[0][1] * y + matrix[0][2] * z;
+  const linearG = matrix[1][0] * x + matrix[1][1] * y + matrix[1][2] * z;
+  const linearB = matrix[2][0] * x + matrix[2][1] * y + matrix[2][2] * z;
+  const r = delinearized(linearR);
+  const g = delinearized(linearG);
+  const b = delinearized(linearB);
+  return argbFromRgb(r, g, b);
+}
+
+/**
+ * Returns the blue component of a color in ARGB format.
+ */
+export function blueFromArgb(argb: number): number {
+  return argb & 255;
+}
+
+/**
+ * Delinearizes an RGB component.
+ *
+ * @param rgbComponent 0.0 <= rgb_component <= 100.0, represents
+ * linear R/G/B channel
+ * @return 0 <= output <= 255, color channel converted to regular
+ * RGB space
+ */
+export function delinearized(rgbComponent: number): number {
+  const normalized = rgbComponent / 100.0;
+  let delinearized = 0.0;
+  if (normalized <= 0.0031308) {
+    delinearized = normalized * 12.92;
+  } else {
+    delinearized = 1.055 * Math.pow(normalized, 1.0 / 2.4) - 0.055;
+  }
+  return mathUtils.clampInt(0, 255, Math.round(delinearized * 255.0));
+}
+
+/**
+ * Returns the green component of a color in ARGB format.
+ */
+export function greenFromArgb(argb: number): number {
+  return (argb >> 8) & 255;
+}
+
+/**
+ * Returns whether a color in ARGB format is opaque.
+ */
+export function isOpaque(argb: number): boolean {
+  return alphaFromArgb(argb) >= 255;
+}
+
+/**
+ * Converts a color from ARGB representation to L*a*b*
+ * representation.
+ *
+ * @param argb the ARGB representation of a color
+ * @return a Lab object representing the color
+ */
+export function labFromArgb(argb: number): number[] {
+  const linearR = linearized(redFromArgb(argb));
+  const linearG = linearized(greenFromArgb(argb));
+  const linearB = linearized(blueFromArgb(argb));
+  const matrix = SRGB_TO_XYZ;
+  const x =
+    matrix[0][0] * linearR + matrix[0][1] * linearG + matrix[0][2] * linearB;
+  const y =
+    matrix[1][0] * linearR + matrix[1][1] * linearG + matrix[1][2] * linearB;
+  const z =
+    matrix[2][0] * linearR + matrix[2][1] * linearG + matrix[2][2] * linearB;
+  const whitePoint = WHITE_POINT_D65;
+  const xNormalized = x / whitePoint[0];
+  const yNormalized = y / whitePoint[1];
+  const zNormalized = z / whitePoint[2];
+  const fx = labF(xNormalized);
+  const fy = labF(yNormalized);
+  const fz = labF(zNormalized);
+  const l = 116.0 * fy - 16;
+  const a = 500.0 * (fx - fy);
+  const b = 200.0 * (fy - fz);
+  return [l, a, b];
+}
+
+/**
+ * Linearizes an RGB component.
+ *
+ * @param rgbComponent 0 <= rgb_component <= 255, represents R/G/B
+ * channel
+ * @return 0.0 <= output <= 100.0, color channel converted to
+ * linear RGB space
+ */
+export function linearized(rgbComponent: number): number {
+  const normalized = rgbComponent / 255.0;
+  if (normalized <= 0.040449936) {
+    return (normalized / 12.92) * 100.0;
+  } else {
+    return Math.pow((normalized + 0.055) / 1.055, 2.4) * 100.0;
+  }
+}
+
+/**
+ * Computes the L* value of a color in ARGB representation.
+ *
+ * @param argb ARGB representation of a color
+ * @return L*, from L*a*b*, coordinate of the color
+ */
+export function lstarFromArgb(argb: number): number {
+  const y = xyzFromArgb(argb)[1];
+  return 116.0 * labF(y / 100.0) - 16.0;
+}
+
+/**
+ * Converts a Y value to an L* value.
+ *
+ * L* in L*a*b* and Y in XYZ measure the same quantity, luminance.
+ *
+ * L* measures perceptual luminance, a linear scale. Y in XYZ
+ * measures relative luminance, a logarithmic scale.
+ *
+ * @param y Y in XYZ
+ * @return L* in L*a*b*
+ */
+export function lstarFromY(y: number): number {
+  return labF(y / 100.0) * 116.0 - 16.0;
+}
+
+/**
+ * Returns the red component of a color in ARGB format.
+ */
+export function redFromArgb(argb: number): number {
+  return (argb >> 16) & 255;
+}
+
+/**
+ * Returns the standard white point; white on a sunny day.
+ *
+ * @return The white point
+ */
+export function whitePointD65(): number[] {
+  return WHITE_POINT_D65;
+}
+
+/**
+ * Converts a color from XYZ to ARGB.
+ */
+export function xyzFromArgb(argb: number): number[] {
+  const r = linearized(redFromArgb(argb));
+  const g = linearized(greenFromArgb(argb));
+  const b = linearized(blueFromArgb(argb));
+  return mathUtils.matrixMultiply([r, g, b], SRGB_TO_XYZ);
+}
+
+/**
+ * Converts an L* value to a Y value.
+ *
+ * L* in L*a*b* and Y in XYZ measure the same quantity, luminance.
+ *
+ * L* measures perceptual luminance, a linear scale. Y in XYZ
+ * measures relative luminance, a logarithmic scale.
+ *
+ * @param lstar L* in L*a*b*
+ * @return Y in XYZ
+ */
+export function yFromLstar(lstar: number): number {
+  return 100.0 * labInvf((lstar + 16.0) / 116.0);
+}
+
+function labF(t: number): number {
+  const e = 216.0 / 24389.0;
+  const kappa = 24389.0 / 27.0;
+  if (t > e) {
+    return Math.pow(t, 1.0 / 3.0);
+  } else {
+    return (kappa * t + 16) / 116;
+  }
+}
+
+function labInvf(ft: number): number {
+  const e = 216.0 / 24389.0;
+  const kappa = 24389.0 / 27.0;
+  const ft3 = ft * ft * ft;
+  if (ft3 > e) {
+    return ft3;
+  } else {
+    return (116 * ft - 16) / kappa;
+  }
+}