@fimbul-works/vec-color/dist/analyze.d.ts

A comprehensive, type-safe color manipulation library for TypeScript that provides a wide range of color space conversions, blending operations, and accessibility utilities.

import { Vec3 } from "@fimbul-works/vec";
export type ColorClassification = {
    temperature: "warm" | "cool" | "neutral";
    intensity: "vivid" | "pastel" | "dark" | "light" | "medium";
    category: string;
};
/**
 * Calculates an approximate perceptual color difference using a weighted RGB comparison
 * This is a fast approximation that weighs green more heavily than red or blue to match human perception
 * Trade speed for accuracy: use this when performance is critical and approximate results are acceptable
 * Based on the redmean color difference algorithm
 * @param colorA - First color as Vec3 RGB (each channel from 0 to 1)
 * @param colorB - Second color as Vec3 RGB (each channel from 0 to 1)
 * @returns A value between 0 and 1, where 1 means identical colors and 0 means maximum perceptual difference
 */
export declare function calculateColorSimilarityFast(A: Vec3, B: Vec3): number;
/**
 * Calculates precise perceptual color difference using CIE Delta E 2000
 * This is the most accurate color difference algorithm, accounting for human perception
 * characteristics in different color ranges. Uses LAB color space for calculations.
 * Trade accuracy for speed: use this when precision is more important than performance
 * @param colorA - First color as Vec3 RGB (each channel from 0 to 1)
 * @param colorB - Second color as Vec3 RGB (each channel from 0 to 1)
 * @returns A value between 0 and 1, where 1 means identical colors and 0 means maximum perceptual difference
 * Internally uses CIEDE2000 algorithm which has a non-linear relationship to human perception
 */
export declare function calculateColorSimilarityLab(rgb1: Vec3, rgb2: Vec3): number;
/**
 * Calculates the relative luminance of a color according to WCAG 2.0 specifications
 * This is used in determining contrast ratios for accessibility compliance
 * @param color - Input color as Vec3 RGB (each channel from 0 to 1)
 * @returns A value between 0 and 1, where 0 is darkest and 1 is brightest
 * @see https://www.w3.org/WAI/GL/wiki/Relative_luminance
 */
export declare function relativeLuminance(color: Vec3): number;
/**
 * Calculates the contrast ratio between two colors according to WCAG 2.0 specifications
 * @param color1 - First color as Vec3 RGB (each channel from 0 to 1)
 * @param color2 - Second color as Vec3 RGB (each channel from 0 to 1)
 * @returns A value between 1 and 21, where 1 means no contrast and 21 means maximum contrast
 * @see https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html
 */
export declare function contrastRatio(color1: Vec3, color2: Vec3): number;
/**
 * Calculates perceived brightness based on human perception
 * Different from luminance as it accounts for human color sensitivity
 * Uses perceived brightness formula (ITU-R BT.709)
 * @param color Input color as Vec3 RGB
 * @returns Perceived brightness value (0 to 1)
 */
export declare function perceivedBrightness(color: Vec3): number;
/**
 * Checks if a color combination meets WCAG contrast requirements for accessibility
 * @param foreground - Foreground color as Vec3 RGB (each channel from 0 to 1)
 * @param background - Background color as Vec3 RGB (each channel from 0 to 1)
 * @param level - WCAG compliance level to check ("AA" or "AAA")
 * @param isLargeText - Whether the text is considered "large" by WCAG standards
 * @returns boolean indicating whether the combination meets WCAG requirements
 */
export declare function meetsWCAGRequirements(foreground: Vec3, background: Vec3, level?: "AA" | "AAA", isLargeText?: boolean): boolean;
/**
 * Calculate CIEDE2000 color difference
 * @param lab1 - First color as Vec3 LAB (each channel from 0 to 1)
 * @param lab2 - Second color as Vec3 LAB (each channel from 0 to 1)
 * @returns
 */
export declare function deltaE2000(lab1: Vec3, lab2: Vec3): number;
/**
 * Finds dominant colors in a set of colors using k-means clustering
 * @param colors Array of colors as Vec3 RGB
 * @param count Number of dominant colors to find (default: 5)
 * @returns Array of dominant colors as Vec3 RGB
 */
export declare function findDominantColors(colors: Vec3[], count?: number): Vec3[];
/**
 * Classifies a color into basic categories
 * @param color Color as Vec3 RGB
 * @returns Object containing color classifications
 */
export declare function classifyColor(color: Vec3): ColorClassification;
/**
 * Sorts colors by various attributes
 * @param colors Array of colors to sort
 * @param by Attribute to sort by ('hue', 'saturation', 'lightness', 'temperature')
 * @returns Sorted array of colors
 */
export declare function sortColors(colors: Vec3[], by?: "hue" | "saturation" | "lightness" | "temperature"): Vec3[];
/**
 * Creates a color distance matrix for a set of colors
 * @param colors Array of colors to analyze
 * @returns 2D array of perceptual color differences
 */
export declare function colorDistanceMatrix(colors: Vec3[]): number[][];