@xivdyetools/core 1.12.4 → 1.12.6

package/dist/services/color/ColorConverter.js

@@ -606,15 +606,36 @@ export class ColorConverter {
     }
     /**
      * Calculate DeltaE between two hex colors using specified formula
+     *
+     * Available formulas:
+     * - cie76: LAB Euclidean (fast, fair accuracy)
+     * - cie2000: CIEDE2000 (industry standard, accurate)
+     * - oklab: OKLAB Euclidean (modern, simpler than cie2000, CSS standard)
+     * - hyab: HyAB hybrid (best for large color differences/palette matching)
+     *
      * @param hex1 First hex color
      * @param hex2 Second hex color
-     * @param formula DeltaE formula to use ('cie76' or 'cie2000')
-     * @returns DeltaE value
+     * @param formula DeltaE formula to use (default: 'cie76')
+     * @returns DeltaE value (scale varies by formula)
      */
     getDeltaE(hex1, hex2, formula = 'cie76') {
-        const lab1 = this.hexToLab(hex1);
-        const lab2 = this.hexToLab(hex2);
-        return formula === 'cie2000' ? this.getDeltaE2000(lab1, lab2) : this.getDeltaE76(lab1, lab2);
+        switch (formula) {
+            case 'cie2000': {
+                const lab1 = this.hexToLab(hex1);
+                const lab2 = this.hexToLab(hex2);
+                return this.getDeltaE2000(lab1, lab2);
+            }
+            case 'oklab':
+                return this.getDeltaE_Oklab(hex1, hex2);
+            case 'hyab':
+                return this.getDeltaE_HyAB(hex1, hex2);
+            case 'cie76':
+            default: {
+                const lab1 = this.hexToLab(hex1);
+                const lab2 = this.hexToLab(hex2);
+                return this.getDeltaE76(lab1, lab2);
+            }
+        }
     }
     /**
      * Static method: Calculate DeltaE using default instance
@@ -622,6 +643,569 @@ export class ColorConverter {
     static getDeltaE(hex1, hex2, formula = 'cie76') {
         return this.getDefault().getDeltaE(hex1, hex2, formula);
     }
+    // ============================================================================
+    // OKLAB-based Color Difference Calculations
+    // ============================================================================
+    /**
+     * Calculate color difference using OKLAB Euclidean distance.
+     *
+     * OKLAB provides better perceptual uniformity than LAB with simpler math
+     * than CIEDE2000. It fixes LAB's blue→purple hue shift issue.
+     *
+     * Adopted by Safari, Photoshop, and CSS Color Level 4.
+     *
+     * Reference: Björn Ottosson (2020) - "A perceptual color space for image processing"
+     *
+     * @param hex1 First color in hex format
+     * @param hex2 Second color in hex format
+     * @returns Distance value (0 = identical, scale ~0-0.5 for typical colors)
+     *
+     * @example getDeltaE_Oklab("#FF0000", "#00FF00") -> ~0.39
+     */
+    getDeltaE_Oklab(hex1, hex2) {
+        const lab1 = this.hexToOklab(hex1);
+        const lab2 = this.hexToOklab(hex2);
+        const dL = lab2.L - lab1.L;
+        const da = lab2.a - lab1.a;
+        const db = lab2.b - lab1.b;
+        return Math.sqrt(dL * dL + da * da + db * db);
+    }
+    /**
+     * Static method: Calculate OKLAB Euclidean distance using default instance
+     */
+    static getDeltaE_Oklab(hex1, hex2) {
+        return this.getDefault().getDeltaE_Oklab(hex1, hex2);
+    }
+    /**
+     * Calculate color difference using HyAB (Hybrid) algorithm.
+     *
+     * HyAB uses taxicab distance for lightness and Euclidean for chroma.
+     * Research shows it outperforms both Euclidean AND CIEDE2000 for large
+     * color differences (>10 units), making it ideal for palette matching.
+     *
+     * Formula: ΔE_HyAB = |L₂ - L₁| + √[(a₂-a₁)² + (b₂-b₁)²]
+     *
+     * Reference: Abasi, Tehran & Fairchild (2019) -
+     * "Distance metrics for very large color differences"
+     *
+     * @param hex1 First color in hex format
+     * @param hex2 Second color in hex format
+     * @param kL Lightness weight (default 1.0). Higher = prioritize lightness matching.
+     *           Use kL > 1 for visibility-critical matching (armor, UI).
+     *           Use kL < 1 to tolerate brightness differences (find vibrant alternatives).
+     * @returns Distance value (0 = identical, scale ~0-1.5 for typical colors)
+     *
+     * @example getDeltaE_HyAB("#FF0000", "#800000") -> ~0.32
+     * @example getDeltaE_HyAB("#FF0000", "#800000", 2.0) -> higher (emphasize brightness)
+     */
+    getDeltaE_HyAB(hex1, hex2, kL = 1.0) {
+        const lab1 = this.hexToOklab(hex1);
+        const lab2 = this.hexToOklab(hex2);
+        // Taxicab distance for lightness (weighted)
+        const dL = Math.abs(lab2.L - lab1.L) * kL;
+        // Euclidean distance for chroma plane
+        const da = lab2.a - lab1.a;
+        const db = lab2.b - lab1.b;
+        const dChroma = Math.sqrt(da * da + db * db);
+        return dL + dChroma;
+    }
+    /**
+     * Static method: Calculate HyAB distance using default instance
+     */
+    static getDeltaE_HyAB(hex1, hex2, kL = 1.0) {
+        return this.getDefault().getDeltaE_HyAB(hex1, hex2, kL);
+    }
+    /**
+     * Calculate color difference using OKLCH with customizable L/C/H weights.
+     *
+     * Allows users to prioritize different color attributes:
+     * - Lightness (L): Brightness/darkness
+     * - Chroma (C): Saturation/vividness
+     * - Hue (H): The actual color (red, blue, green, etc.)
+     *
+     * @param hex1 First color in hex format
+     * @param hex2 Second color in hex format
+     * @param weights Object with kL, kC, kH weights (default 1.0 each)
+     * @returns Distance value (0 = identical, higher = more different)
+     *
+     * @example getDeltaE_OklchWeighted("#FF0000", "#FF8000", { kH: 2.0 }) -> prioritizes hue match
+     */
+    getDeltaE_OklchWeighted(hex1, hex2, weights = {}) {
+        const { kL = 1.0, kC = 1.0, kH = 1.0 } = weights;
+        const lch1 = this.hexToOklch(hex1);
+        const lch2 = this.hexToOklch(hex2);
+        // Lightness difference
+        const dL = (lch2.L - lch1.L) * kL;
+        // Chroma difference
+        const dC = (lch2.C - lch1.C) * kC;
+        // Hue difference with wraparound (circular)
+        let dH = lch2.h - lch1.h;
+        if (dH > 180)
+            dH -= 360;
+        if (dH < -180)
+            dH += 360;
+        // Scale hue by average chroma for perceptual accuracy
+        // (hue differences matter less for desaturated colors)
+        const avgC = (lch1.C + lch2.C) / 2;
+        const dHScaled = (dH / 180) * avgC * kH;
+        return Math.sqrt(dL * dL + dC * dC + dHScaled * dHScaled);
+    }
+    /**
+     * Static method: Calculate OKLCH weighted distance using default instance
+     */
+    static getDeltaE_OklchWeighted(hex1, hex2, weights = {}) {
+        return this.getDefault().getDeltaE_OklchWeighted(hex1, hex2, weights);
+    }
+    // ============================================================================
+    // OKLAB/OKLCH Color Space Conversion (Björn Ottosson, 2020)
+    // ============================================================================
+    /**
+     * Convert sRGB component to linear RGB
+     * Applies inverse gamma companding
+     * @internal
+     */
+    srgbToLinear(c) {
+        const normalized = c / 255;
+        return normalized <= 0.04045 ? normalized / 12.92 : Math.pow((normalized + 0.055) / 1.055, 2.4);
+    }
+    /**
+     * Convert linear RGB component to sRGB
+     * Applies gamma companding
+     * @internal
+     */
+    linearToSrgb(c) {
+        const clamped = Math.max(0, Math.min(1, c));
+        const srgb = clamped <= 0.0031308 ? clamped * 12.92 : 1.055 * Math.pow(clamped, 1 / 2.4) - 0.055;
+        return Math.round(srgb * 255);
+    }
+    /**
+     * Convert RGB to OKLAB color space
+     *
+     * OKLAB is a modern perceptually uniform color space that fixes issues
+     * with CIELAB, particularly for blue colors. Blue + Yellow = Green in OKLAB.
+     *
+     * @param r Red component (0-255)
+     * @param g Green component (0-255)
+     * @param b Blue component (0-255)
+     * @returns OKLAB color with L (0-1), a (~-0.4 to 0.4), b (~-0.4 to 0.4)
+     *
+     * @example rgbToOklab(255, 0, 0) -> { L: 0.628, a: 0.225, b: 0.126 }
+     */
+    rgbToOklab(r, g, b) {
+        if (!isValidRGB(r, g, b)) {
+            throw new AppError(ErrorCode.INVALID_RGB_VALUE, `Invalid RGB values: r=${r}, g=${g}, b=${b}. Values must be 0-255`, 'error');
+        }
+        // Convert sRGB to linear RGB
+        const rLin = this.srgbToLinear(r);
+        const gLin = this.srgbToLinear(g);
+        const bLin = this.srgbToLinear(b);
+        // Linear RGB to LMS (using Oklab's specific matrix)
+        const l = 0.4122214708 * rLin + 0.5363325363 * gLin + 0.0514459929 * bLin;
+        const m = 0.2119034982 * rLin + 0.6806995451 * gLin + 0.1073969566 * bLin;
+        const s = 0.0883024619 * rLin + 0.2817188376 * gLin + 0.6299787005 * bLin;
+        // Apply cube root
+        const lRoot = Math.cbrt(l);
+        const mRoot = Math.cbrt(m);
+        const sRoot = Math.cbrt(s);
+        // LMS to Oklab
+        return {
+            L: round(0.2104542553 * lRoot + 0.793617785 * mRoot - 0.0040720468 * sRoot, 6),
+            a: round(1.9779984951 * lRoot - 2.428592205 * mRoot + 0.4505937099 * sRoot, 6),
+            b: round(0.0259040371 * lRoot + 0.7827717662 * mRoot - 0.808675766 * sRoot, 6),
+        };
+    }
+    /**
+     * Static method: Convert RGB to OKLAB using default instance
+     */
+    static rgbToOklab(r, g, b) {
+        return this.getDefault().rgbToOklab(r, g, b);
+    }
+    /**
+     * Convert OKLAB to RGB color space
+     *
+     * @param L Lightness (0-1)
+     * @param a Green-Red axis (~-0.4 to 0.4)
+     * @param b Blue-Yellow axis (~-0.4 to 0.4)
+     * @returns RGB color with values 0-255
+     *
+     * @example oklabToRgb(0.628, 0.225, 0.126) -> { r: 255, g: 0, b: 0 }
+     */
+    oklabToRgb(L, a, b) {
+        // Oklab to LMS
+        const lRoot = L + 0.3963377774 * a + 0.2158037573 * b;
+        const mRoot = L - 0.1055613458 * a - 0.0638541728 * b;
+        const sRoot = L - 0.0894841775 * a - 1.291485548 * b;
+        // Cube the roots
+        const l = lRoot * lRoot * lRoot;
+        const m = mRoot * mRoot * mRoot;
+        const s = sRoot * sRoot * sRoot;
+        // LMS to linear RGB
+        const rLin = +4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s;
+        const gLin = -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s;
+        const bLin = -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s;
+        // Convert to sRGB
+        return {
+            r: clamp(this.linearToSrgb(rLin), RGB_MIN, RGB_MAX),
+            g: clamp(this.linearToSrgb(gLin), RGB_MIN, RGB_MAX),
+            b: clamp(this.linearToSrgb(bLin), RGB_MIN, RGB_MAX),
+        };
+    }
+    /**
+     * Static method: Convert OKLAB to RGB using default instance
+     */
+    static oklabToRgb(L, a, b) {
+        return this.getDefault().oklabToRgb(L, a, b);
+    }
+    /**
+     * Convert hex color to OKLAB
+     */
+    hexToOklab(hex) {
+        const rgb = this.hexToRgb(hex);
+        return this.rgbToOklab(rgb.r, rgb.g, rgb.b);
+    }
+    /**
+     * Static method: Convert hex to OKLAB using default instance
+     */
+    static hexToOklab(hex) {
+        return this.getDefault().hexToOklab(hex);
+    }
+    /**
+     * Convert OKLAB to hex color
+     */
+    oklabToHex(L, a, b) {
+        const rgb = this.oklabToRgb(L, a, b);
+        return this.rgbToHex(rgb.r, rgb.g, rgb.b);
+    }
+    /**
+     * Static method: Convert OKLAB to hex using default instance
+     */
+    static oklabToHex(L, a, b) {
+        return this.getDefault().oklabToHex(L, a, b);
+    }
+    /**
+     * Convert RGB to OKLCH (cylindrical OKLAB)
+     *
+     * OKLCH expresses OKLAB in cylindrical coordinates for intuitive
+     * hue manipulation. Ideal for gradient interpolation.
+     *
+     * @param r Red component (0-255)
+     * @param g Green component (0-255)
+     * @param b Blue component (0-255)
+     * @returns OKLCH color with L (0-1), C (chroma, 0 to ~0.4), h (hue, 0-360)
+     *
+     * @example rgbToOklch(255, 0, 0) -> { L: 0.628, C: 0.258, h: 29.23 }
+     */
+    rgbToOklch(r, g, b) {
+        const oklab = this.rgbToOklab(r, g, b);
+        // Convert to cylindrical coordinates
+        const C = Math.sqrt(oklab.a * oklab.a + oklab.b * oklab.b);
+        let h = Math.atan2(oklab.b, oklab.a) * (180 / Math.PI);
+        if (h < 0)
+            h += 360;
+        return {
+            L: oklab.L,
+            C: round(C, 6),
+            h: round(h, 4),
+        };
+    }
+    /**
+     * Static method: Convert RGB to OKLCH using default instance
+     */
+    static rgbToOklch(r, g, b) {
+        return this.getDefault().rgbToOklch(r, g, b);
+    }
+    /**
+     * Convert OKLCH to RGB
+     *
+     * @param L Lightness (0-1)
+     * @param C Chroma (0 to ~0.4)
+     * @param h Hue angle (0-360 degrees)
+     * @returns RGB color with values 0-255
+     */
+    oklchToRgb(L, C, h) {
+        // Convert from cylindrical to rectangular coordinates
+        const hRad = h * (Math.PI / 180);
+        const a = C * Math.cos(hRad);
+        const b = C * Math.sin(hRad);
+        return this.oklabToRgb(L, a, b);
+    }
+    /**
+     * Static method: Convert OKLCH to RGB using default instance
+     */
+    static oklchToRgb(L, C, h) {
+        return this.getDefault().oklchToRgb(L, C, h);
+    }
+    /**
+     * Convert hex color to OKLCH
+     */
+    hexToOklch(hex) {
+        const rgb = this.hexToRgb(hex);
+        return this.rgbToOklch(rgb.r, rgb.g, rgb.b);
+    }
+    /**
+     * Static method: Convert hex to OKLCH using default instance
+     */
+    static hexToOklch(hex) {
+        return this.getDefault().hexToOklch(hex);
+    }
+    /**
+     * Convert OKLCH to hex color
+     */
+    oklchToHex(L, C, h) {
+        const rgb = this.oklchToRgb(L, C, h);
+        return this.rgbToHex(rgb.r, rgb.g, rgb.b);
+    }
+    /**
+     * Static method: Convert OKLCH to hex using default instance
+     */
+    static oklchToHex(L, C, h) {
+        return this.getDefault().oklchToHex(L, C, h);
+    }
+    // ============================================================================
+    // LCH Color Space Conversion (Cylindrical CIE LAB)
+    // ============================================================================
+    /**
+     * Convert CIE LAB to LCH (cylindrical LAB)
+     *
+     * LCH expresses LAB in cylindrical coordinates for hue-based operations.
+     *
+     * @param L Lightness (0-100)
+     * @param a Green-Red axis (~-128 to 127)
+     * @param b Blue-Yellow axis (~-128 to 127)
+     * @returns LCH color with L (0-100), C (chroma), h (hue, 0-360)
+     */
+    labToLch(L, a, b) {
+        const C = Math.sqrt(a * a + b * b);
+        let h = Math.atan2(b, a) * (180 / Math.PI);
+        if (h < 0)
+            h += 360;
+        return {
+            L: round(L, 4),
+            C: round(C, 4),
+            h: round(h, 4),
+        };
+    }
+    /**
+     * Static method: Convert LAB to LCH using default instance
+     */
+    static labToLch(L, a, b) {
+        return this.getDefault().labToLch(L, a, b);
+    }
+    /**
+     * Convert LCH to CIE LAB
+     *
+     * @param L Lightness (0-100)
+     * @param C Chroma
+     * @param h Hue angle (0-360 degrees)
+     * @returns LAB color
+     */
+    lchToLab(L, C, h) {
+        const hRad = h * (Math.PI / 180);
+        return {
+            L: round(L, 4),
+            a: round(C * Math.cos(hRad), 4),
+            b: round(C * Math.sin(hRad), 4),
+        };
+    }
+    /**
+     * Static method: Convert LCH to LAB using default instance
+     */
+    static lchToLab(L, C, h) {
+        return this.getDefault().lchToLab(L, C, h);
+    }
+    /**
+     * Convert RGB to LCH
+     */
+    rgbToLch(r, g, b) {
+        const lab = this.rgbToLab(r, g, b);
+        return this.labToLch(lab.L, lab.a, lab.b);
+    }
+    /**
+     * Static method: Convert RGB to LCH using default instance
+     */
+    static rgbToLch(r, g, b) {
+        return this.getDefault().rgbToLch(r, g, b);
+    }
+    /**
+     * Convert LCH to RGB
+     */
+    lchToRgb(L, C, h) {
+        const lab = this.lchToLab(L, C, h);
+        return this.labToRgb(lab.L, lab.a, lab.b);
+    }
+    /**
+     * Static method: Convert LCH to RGB using default instance
+     */
+    static lchToRgb(L, C, h) {
+        return this.getDefault().lchToRgb(L, C, h);
+    }
+    /**
+     * Convert hex color to LCH
+     */
+    hexToLch(hex) {
+        const rgb = this.hexToRgb(hex);
+        return this.rgbToLch(rgb.r, rgb.g, rgb.b);
+    }
+    /**
+     * Static method: Convert hex to LCH using default instance
+     */
+    static hexToLch(hex) {
+        return this.getDefault().hexToLch(hex);
+    }
+    /**
+     * Convert LCH to hex color
+     */
+    lchToHex(L, C, h) {
+        const rgb = this.lchToRgb(L, C, h);
+        return this.rgbToHex(rgb.r, rgb.g, rgb.b);
+    }
+    /**
+     * Static method: Convert LCH to hex using default instance
+     */
+    static lchToHex(L, C, h) {
+        return this.getDefault().lchToHex(L, C, h);
+    }
+    // ============================================================================
+    // HSL Color Space Conversion
+    // ============================================================================
+    /**
+     * Convert RGB to HSL (Hue, Saturation, Lightness)
+     *
+     * HSL is similar to HSV but uses Lightness instead of Value.
+     * Common in design tools like Photoshop, Figma, and CSS.
+     *
+     * @param r Red component (0-255)
+     * @param g Green component (0-255)
+     * @param b Blue component (0-255)
+     * @returns HSL color with h (0-360), s (0-100), l (0-100)
+     *
+     * @example rgbToHsl(255, 0, 0) -> { h: 0, s: 100, l: 50 }
+     */
+    rgbToHsl(r, g, b) {
+        if (!isValidRGB(r, g, b)) {
+            throw new AppError(ErrorCode.INVALID_RGB_VALUE, `Invalid RGB values: r=${r}, g=${g}, b=${b}. Values must be 0-255`, 'error');
+        }
+        // Normalize to 0-1
+        const rNorm = r / 255;
+        const gNorm = g / 255;
+        const bNorm = b / 255;
+        const max = Math.max(rNorm, gNorm, bNorm);
+        const min = Math.min(rNorm, gNorm, bNorm);
+        const delta = max - min;
+        // Calculate Lightness
+        const l = (max + min) / 2;
+        // Calculate Saturation
+        let s = 0;
+        if (delta !== 0) {
+            s = delta / (1 - Math.abs(2 * l - 1));
+        }
+        // Calculate Hue (same as HSV)
+        let h = 0;
+        if (delta !== 0) {
+            if (max === rNorm) {
+                h = ((gNorm - bNorm) / delta + (gNorm < bNorm ? 6 : 0)) * 60;
+            }
+            else if (max === gNorm) {
+                h = ((bNorm - rNorm) / delta + 2) * 60;
+            }
+            else {
+                h = ((rNorm - gNorm) / delta + 4) * 60;
+            }
+        }
+        return {
+            h: round(h, 2),
+            s: round(s * 100, 2),
+            l: round(l * 100, 2),
+        };
+    }
+    /**
+     * Static method: Convert RGB to HSL using default instance
+     */
+    static rgbToHsl(r, g, b) {
+        return this.getDefault().rgbToHsl(r, g, b);
+    }
+    /**
+     * Convert HSL to RGB
+     *
+     * @param h Hue (0-360 degrees)
+     * @param s Saturation (0-100 percent)
+     * @param l Lightness (0-100 percent)
+     * @returns RGB color with values 0-255
+     *
+     * @example hslToRgb(0, 100, 50) -> { r: 255, g: 0, b: 0 }
+     */
+    hslToRgb(h, s, l) {
+        // Normalize
+        const hNorm = this.normalizeHue(h) / 360;
+        const sNorm = clamp(s, 0, 100) / 100;
+        const lNorm = clamp(l, 0, 100) / 100;
+        let r, g, b;
+        if (sNorm === 0) {
+            // Achromatic (gray)
+            r = g = b = lNorm;
+        }
+        else {
+            const q = lNorm < 0.5 ? lNorm * (1 + sNorm) : lNorm + sNorm - lNorm * sNorm;
+            const p = 2 * lNorm - q;
+            r = this.hueToRgbComponent(p, q, hNorm + 1 / 3);
+            g = this.hueToRgbComponent(p, q, hNorm);
+            b = this.hueToRgbComponent(p, q, hNorm - 1 / 3);
+        }
+        return {
+            r: clamp(Math.round(r * 255), RGB_MIN, RGB_MAX),
+            g: clamp(Math.round(g * 255), RGB_MIN, RGB_MAX),
+            b: clamp(Math.round(b * 255), RGB_MIN, RGB_MAX),
+        };
+    }
+    /**
+     * Helper for HSL to RGB conversion
+     * @internal
+     */
+    hueToRgbComponent(p, q, t) {
+        if (t < 0)
+            t += 1;
+        if (t > 1)
+            t -= 1;
+        if (t < 1 / 6)
+            return p + (q - p) * 6 * t;
+        if (t < 1 / 2)
+            return q;
+        if (t < 2 / 3)
+            return p + (q - p) * (2 / 3 - t) * 6;
+        return p;
+    }
+    /**
+     * Static method: Convert HSL to RGB using default instance
+     */
+    static hslToRgb(h, s, l) {
+        return this.getDefault().hslToRgb(h, s, l);
+    }
+    /**
+     * Convert hex color to HSL
+     */
+    hexToHsl(hex) {
+        const rgb = this.hexToRgb(hex);
+        return this.rgbToHsl(rgb.r, rgb.g, rgb.b);
+    }
+    /**
+     * Static method: Convert hex to HSL using default instance
+     */
+    static hexToHsl(hex) {
+        return this.getDefault().hexToHsl(hex);
+    }
+    /**
+     * Convert HSL to hex color
+     */
+    hslToHex(h, s, l) {
+        const rgb = this.hslToRgb(h, s, l);
+        return this.rgbToHex(rgb.r, rgb.g, rgb.b);
+    }
+    /**
+     * Static method: Convert HSL to hex using default instance
+     */
+    static hslToHex(h, s, l) {
+        return this.getDefault().hslToHex(h, s, l);
+    }
 }
 // Default singleton instance for static API compatibility
 // Per Issue #6: Eager initialization to avoid race conditions in concurrent scenarios