@xivdyetools/core 1.12.4 → 1.12.5

package/dist/services/color/SpectralMixer.js

@@ -0,0 +1,133 @@
+/**
+ * Spectral Color Mixer
+ *
+ * Wrapper for spectral.js library that provides Kubelka-Munk theory-based
+ * realistic pigment/paint mixing. This produces results that closely match
+ * how actual paints and pigments mix in the physical world.
+ *
+ * Key characteristics:
+ * - Based on Kubelka-Munk light absorption/scattering theory
+ * - Simulates how pigments interact with light
+ * - Blue + Yellow = Green (like real paint!)
+ * - Uses spectral reflectance curves (380-750nm)
+ *
+ * @module services/color/SpectralMixer
+ */
+// @ts-expect-error - spectral.js has no type definitions
+import * as spectral from 'spectral.js';
+import { ColorConverter } from './ColorConverter.js';
+/**
+ * Spectral Color Mixer using Kubelka-Munk theory
+ *
+ * Provides realistic paint/pigment color mixing by simulating
+ * how light interacts with pigmented materials.
+ */
+export class SpectralMixer {
+    /**
+     * Mix two colors using Kubelka-Munk spectral mixing
+     *
+     * This produces results similar to mixing physical paints:
+     * - Blue + Yellow = Green (like mixing paints)
+     * - More realistic tinting and shading
+     * - Handles complementary colors naturally
+     *
+     * @param hex1 First hex color
+     * @param hex2 Second hex color
+     * @param ratio Mix ratio (0 = all hex1, 0.5 = equal mix, 1 = all hex2). Default: 0.5
+     * @returns Mixed color as hex
+     *
+     * @example
+     * // Mix blue and yellow to get green
+     * SpectralMixer.mixColors('#0000FF', '#FFFF00') // Returns green-ish color
+     */
+    static mixColors(hex1, hex2, ratio = 0.5) {
+        // Clamp ratio to valid range
+        ratio = Math.max(0, Math.min(1, ratio));
+        // Create spectral Color objects
+        const color1 = new spectral.Color(hex1);
+        const color2 = new spectral.Color(hex2);
+        // Mix using Kubelka-Munk theory
+        // The mix function takes [color, concentration] pairs
+        // We use (1 - ratio) for color1 and ratio for color2
+        const mixed = spectral.mix([color1, 1 - ratio], [color2, ratio]);
+        // Convert to hex string
+        // toString returns hex format by default with gamut mapping
+        const hexResult = mixed.toString({ format: 'hex', method: 'map' });
+        // Normalize to our HexColor format
+        return ColorConverter.normalizeHex(hexResult);
+    }
+    /**
+     * Mix multiple colors using Kubelka-Munk spectral mixing
+     *
+     * @param colors Array of hex colors to mix
+     * @param weights Optional array of weights (defaults to equal weights)
+     * @returns Mixed color as hex
+     *
+     * @example
+     * // Mix three colors
+     * SpectralMixer.mixMultiple(['#FF0000', '#00FF00', '#0000FF'])
+     */
+    static mixMultiple(colors, weights) {
+        if (colors.length === 0) {
+            throw new Error('At least one color is required');
+        }
+        if (colors.length === 1) {
+            return ColorConverter.normalizeHex(colors[0]);
+        }
+        // Use equal weights if not provided
+        const effectiveWeights = weights ?? colors.map(() => 1 / colors.length);
+        // Normalize weights to sum to 1
+        const totalWeight = effectiveWeights.reduce((sum, w) => sum + w, 0);
+        const normalizedWeights = effectiveWeights.map((w) => w / totalWeight);
+        // Create spectral Color objects with weights
+        const colorPairs = colors.map((hex, i) => [
+            new spectral.Color(hex),
+            normalizedWeights[i],
+        ]);
+        // Mix using Kubelka-Munk theory
+        const mixed = spectral.mix(...colorPairs);
+        // Convert to hex string
+        const hexResult = mixed.toString({ format: 'hex', method: 'map' });
+        return ColorConverter.normalizeHex(hexResult);
+    }
+    /**
+     * Generate a gradient palette using spectral mixing
+     *
+     * Creates a series of colors that transition smoothly between
+     * two colors using Kubelka-Munk theory for realistic blending.
+     *
+     * @param hex1 Starting color
+     * @param hex2 Ending color
+     * @param steps Number of colors in the gradient (including start and end)
+     * @returns Array of hex colors
+     *
+     * @example
+     * // Generate a 5-step gradient from red to blue
+     * SpectralMixer.gradient('#FF0000', '#0000FF', 5)
+     */
+    static gradient(hex1, hex2, steps) {
+        if (steps < 2) {
+            throw new Error('Gradient requires at least 2 steps');
+        }
+        const result = [];
+        for (let i = 0; i < steps; i++) {
+            const ratio = i / (steps - 1);
+            result.push(this.mixColors(hex1, hex2, ratio));
+        }
+        return result;
+    }
+    /**
+     * Check if the spectral.js library is available
+     *
+     * @returns true if spectral.js is loaded and functional
+     */
+    static isAvailable() {
+        try {
+            return typeof spectral.Color === 'function' && typeof spectral.mix === 'function';
+        }
+        catch {
+            return false;
+        }
+    }
+}
+//# sourceMappingURL=SpectralMixer.js.map

package/dist/services/color/SpectralMixer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SpectralMixer.js","sourceRoot":"","sources":["../../../src/services/color/SpectralMixer.ts"],"names":[],"mappings":"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"}

package/dist/types/index.d.ts

@@ -20,7 +20,7 @@ export { NoOpLogger, ConsoleLogger } from '@xivdyetools/logger/library';
 /**
  * @deprecated Removed in v2.0.0. Import directly from '@xivdyetools/types' instead.
  */
-export type { RGB, HSV, LAB, HexColor, DyeId, Hue, Saturation } from '@xivdyetools/types';
+export type { RGB, HSV, LAB, OKLAB, OKLCH, LCH, HSL, HexColor, DyeId, Hue, Saturation } from '@xivdyetools/types';
 /**
  * @deprecated Removed in v2.0.0. Import directly from '@xivdyetools/types' instead.
  */

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;GAEG;AACH,YAAY,EAAE,MAAM,EAAE,MAAM,6BAA6B,CAAC;AAC1D;;GAEG;AACH,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAMxE;;GAEG;AACH,YAAY,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAC1F;;GAEG;AACH,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC9F;;GAEG;AACH,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAEpF;;GAEG;AACH,YAAY,EAAE,GAAG,EAAE,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAE1F;;GAEG;AACH,YAAY,EACV,cAAc,EACd,mBAAmB,EACnB,mBAAmB,EACnB,yBAAyB,EACzB,sBAAsB,EACtB,OAAO,EACP,MAAM,EACN,IAAI,GACL,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAE3F;;GAEG;AACH,YAAY,EACV,cAAc,EACd,YAAY,EACZ,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,cAAc,EACd,UAAU,EACV,eAAe,EACf,gBAAgB,EAChB,6BAA6B,EAC7B,aAAa,EACb,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,EACpB,kBAAkB,EAClB,YAAY,EACZ,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AAE5B;;GAEG;AACH,YAAY,EACV,YAAY,EACZ,UAAU,EACV,WAAW,EACX,gBAAgB,EAChB,UAAU,EACV,UAAU,EACV,oBAAoB,EACpB,WAAW,EACX,oBAAoB,EACpB,gBAAgB,EAChB,4BAA4B,EAC5B,qBAAqB,EACrB,WAAW,EACX,QAAQ,EACR,YAAY,EACZ,eAAe,EACf,gBAAgB,GACjB,MAAM,oBAAoB,CAAC;AAE5B;;GAEG;AACH,YAAY,EACV,WAAW,EACX,UAAU,EACV,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EACf,SAAS,EACT,eAAe,GAChB,MAAM,oBAAoB,CAAC;AAE5B;;GAEG;AACH,YAAY,EACV,UAAU,EACV,cAAc,EACd,cAAc,EACd,MAAM,EACN,eAAe,EACf,OAAO,EACP,OAAO,EACP,UAAU,EACV,gBAAgB,GACjB,MAAM,oBAAoB,CAAC;AAE5B;;GAEG;AACH,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACzD;;GAEG;AACH,YAAY,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD;;GAEG;AACH,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAClF;;GAEG;AACH,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;GAEG;AACH,YAAY,EAAE,MAAM,EAAE,MAAM,6BAA6B,CAAC;AAC1D;;GAEG;AACH,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAMxE;;GAEG;AACH,YAAY,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAClH;;GAEG;AACH,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC9F;;GAEG;AACH,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAEpF;;GAEG;AACH,YAAY,EAAE,GAAG,EAAE,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAE1F;;GAEG;AACH,YAAY,EACV,cAAc,EACd,mBAAmB,EACnB,mBAAmB,EACnB,yBAAyB,EACzB,sBAAsB,EACtB,OAAO,EACP,MAAM,EACN,IAAI,GACL,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAE3F;;GAEG;AACH,YAAY,EACV,cAAc,EACd,YAAY,EACZ,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,cAAc,EACd,UAAU,EACV,eAAe,EACf,gBAAgB,EAChB,6BAA6B,EAC7B,aAAa,EACb,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,EACpB,kBAAkB,EAClB,YAAY,EACZ,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AAE5B;;GAEG;AACH,YAAY,EACV,YAAY,EACZ,UAAU,EACV,WAAW,EACX,gBAAgB,EAChB,UAAU,EACV,UAAU,EACV,oBAAoB,EACpB,WAAW,EACX,oBAAoB,EACpB,gBAAgB,EAChB,4BAA4B,EAC5B,qBAAqB,EACrB,WAAW,EACX,QAAQ,EACR,YAAY,EACZ,eAAe,EACf,gBAAgB,GACjB,MAAM,oBAAoB,CAAC;AAE5B;;GAEG;AACH,YAAY,EACV,WAAW,EACX,UAAU,EACV,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EACf,SAAS,EACT,eAAe,GAChB,MAAM,oBAAoB,CAAC;AAE5B;;GAEG;AACH,YAAY,EACV,UAAU,EACV,cAAc,EACd,cAAc,EACd,MAAM,EACN,eAAe,EACf,OAAO,EACP,OAAO,EACP,UAAU,EACV,gBAAgB,GACjB,MAAM,oBAAoB,CAAC;AAE5B;;GAEG;AACH,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACzD;;GAEG;AACH,YAAY,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD;;GAEG;AACH,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAClF;;GAEG;AACH,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/version.d.ts

@@ -7,5 +7,5 @@
  * Current library version
  * Automatically synced with package.json version
  */
-export declare const VERSION = "1.12.4";
+export declare const VERSION = "1.12.5";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -7,5 +7,5 @@
  * Current library version
  * Automatically synced with package.json version
  */
-export const VERSION = '1.12.4';
+export const VERSION = '1.12.5';
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@xivdyetools/core",
-    "version": "1.12.4",
+    "version": "1.12.5",
     "description": "Core color algorithms and dye database for XIV Dye Tools",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
@@ -77,7 +77,8 @@
     },
     "dependencies": {
         "@xivdyetools/logger": "^1.0.2",
-        "@xivdyetools/types": "^1.6.1"
+        "@xivdyetools/types": "^1.6.1",
+        "spectral.js": "^3.0.0"
     },
     "lint-staged": {
         "*.ts": [
@@ -85,4 +86,4 @@
             "prettier --write"
         ]
     }
-}
+}