@xivdyetools/core 1.3.7

package/dist/services/PaletteService.js

@@ -0,0 +1,349 @@
+/**
+ * @xivdyetools/core - Palette Extraction Service
+ *
+ * Extracts dominant colors from pixel data using K-means clustering.
+ * Matches extracted colors to closest FFXIV dyes.
+ *
+ * @module services/PaletteService
+ * @example
+ * ```typescript
+ * import { PaletteService, DyeService, dyeDatabase } from '@xivdyetools/core';
+ *
+ * const paletteService = new PaletteService();
+ * const dyeService = new DyeService(dyeDatabase);
+ *
+ * // Extract 4 dominant colors from pixel data
+ * const palette = paletteService.extractPalette(pixels, 4);
+ *
+ * // Extract and match to dyes in one step
+ * const matches = paletteService.extractAndMatchPalette(pixels, 4, dyeService);
+ * ```
+ */
+import { NoOpLogger } from '../types/index.js';
+import { ColorService } from './ColorService.js';
+// ============================================================================
+// K-Means Clustering Implementation
+// ============================================================================
+/**
+ * Calculate Euclidean distance between two RGB colors
+ */
+function rgbDistance(a, b) {
+    const dr = a.r - b.r;
+    const dg = a.g - b.g;
+    const db = a.b - b.b;
+    return Math.sqrt(dr * dr + dg * dg + db * db);
+}
+/**
+ * Calculate the mean of an array of RGB colors
+ */
+function rgbMean(colors) {
+    if (colors.length === 0) {
+        return { r: 0, g: 0, b: 0 };
+    }
+    let sumR = 0;
+    let sumG = 0;
+    let sumB = 0;
+    for (const c of colors) {
+        sumR += c.r;
+        sumG += c.g;
+        sumB += c.b;
+    }
+    return {
+        r: Math.round(sumR / colors.length),
+        g: Math.round(sumG / colors.length),
+        b: Math.round(sumB / colors.length),
+    };
+}
+/**
+ * K-means++ initialization for better starting centroids
+ * Selects initial centroids that are well-distributed
+ * CORE-PERF-003: Optimized from O(n*k²) to O(n*k) by caching minimum distances
+ */
+function kMeansPlusPlusInit(pixels, k) {
+    if (pixels.length === 0 || k <= 0) {
+        return [];
+    }
+    const centroids = [];
+    // First centroid: random pixel
+    const firstIndex = Math.floor(Math.random() * pixels.length);
+    centroids.push({ ...pixels[firstIndex] });
+    // CORE-PERF-003: Cache minimum distances to avoid O(k) inner loop
+    // Initialize with distance to first centroid
+    const minDistances = new Array(pixels.length);
+    for (let j = 0; j < pixels.length; j++) {
+        minDistances[j] = rgbDistance(pixels[j], centroids[0]);
+    }
+    // Remaining centroids: weighted probability by distance squared
+    for (let i = 1; i < k; i++) {
+        // Calculate total distance (squared) for probability distribution
+        let totalDistanceSquared = 0;
+        for (let j = 0; j < pixels.length; j++) {
+            totalDistanceSquared += minDistances[j] * minDistances[j];
+        }
+        // Select next centroid with probability proportional to distance squared
+        let selectedIndex = 0;
+        if (totalDistanceSquared === 0) {
+            // All remaining pixels are duplicates of centroids
+            selectedIndex = Math.floor(Math.random() * pixels.length);
+        }
+        else {
+            let threshold = Math.random() * totalDistanceSquared;
+            for (let j = 0; j < pixels.length; j++) {
+                threshold -= minDistances[j] * minDistances[j];
+                if (threshold <= 0) {
+                    selectedIndex = j;
+                    break;
+                }
+            }
+        }
+        centroids.push({ ...pixels[selectedIndex] });
+        // CORE-PERF-003: Only compute distance to the NEW centroid and update minimums
+        // This reduces complexity from O(n*k) per iteration to O(n) per iteration
+        const newCentroid = centroids[centroids.length - 1];
+        for (let j = 0; j < pixels.length; j++) {
+            const distToNew = rgbDistance(pixels[j], newCentroid);
+            if (distToNew < minDistances[j]) {
+                minDistances[j] = distToNew;
+            }
+        }
+    }
+    return centroids;
+}
+/**
+ * Assign each pixel to its nearest centroid
+ * Returns array of cluster indices and the clusters themselves
+ */
+function assignToClusters(pixels, centroids) {
+    const assignments = new Array(pixels.length);
+    const clusters = centroids.map(() => []);
+    for (let i = 0; i < pixels.length; i++) {
+        const pixel = pixels[i];
+        let minDist = Infinity;
+        let nearestCluster = 0;
+        for (let j = 0; j < centroids.length; j++) {
+            const dist = rgbDistance(pixel, centroids[j]);
+            if (dist < minDist) {
+                minDist = dist;
+                nearestCluster = j;
+            }
+        }
+        assignments[i] = nearestCluster;
+        clusters[nearestCluster].push(pixel);
+    }
+    return { assignments, clusters };
+}
+/**
+ * Update centroids to be the mean of their clusters
+ * Returns new centroids and the maximum movement distance
+ */
+function updateCentroids(centroids, clusters) {
+    const newCentroids = [];
+    let maxMovement = 0;
+    for (let i = 0; i < centroids.length; i++) {
+        const cluster = clusters[i];
+        if (cluster.length === 0) {
+            // Empty cluster: keep old centroid
+            newCentroids.push({ ...centroids[i] });
+        }
+        else {
+            const newCentroid = rgbMean(cluster);
+            const movement = rgbDistance(centroids[i], newCentroid);
+            if (movement > maxMovement) {
+                maxMovement = movement;
+            }
+            newCentroids.push(newCentroid);
+        }
+    }
+    return { newCentroids, maxMovement };
+}
+/**
+ * Run K-means clustering on pixel data
+ */
+function kMeansClustering(pixels, k, maxIterations, convergenceThreshold) {
+    if (pixels.length === 0) {
+        return { centroids: [], clusterSizes: [] };
+    }
+    // Limit k to number of unique pixels
+    const effectiveK = Math.min(k, pixels.length);
+    // Initialize centroids using K-means++
+    let centroids = kMeansPlusPlusInit(pixels, effectiveK);
+    // Iterate until convergence or max iterations
+    for (let iter = 0; iter < maxIterations; iter++) {
+        // Assign pixels to clusters
+        const { clusters } = assignToClusters(pixels, centroids);
+        // Update centroids
+        const { newCentroids, maxMovement } = updateCentroids(centroids, clusters);
+        centroids = newCentroids;
+        // Check for convergence
+        if (maxMovement < convergenceThreshold) {
+            break;
+        }
+    }
+    // Final assignment to get cluster sizes
+    const { clusters } = assignToClusters(pixels, centroids);
+    const clusterSizes = clusters.map((c) => c.length);
+    return { centroids, clusterSizes };
+}
+// ============================================================================
+// PaletteService Class
+// ============================================================================
+/**
+ * Service for extracting color palettes from images
+ *
+ * Uses K-means clustering to find dominant colors, then matches
+ * them to the closest FFXIV dyes.
+ */
+export class PaletteService {
+    /**
+     * Create a new PaletteService
+     * @param options - Optional configuration including logger
+     */
+    constructor(options = {}) {
+        this.logger = options.logger ?? NoOpLogger;
+    }
+    /**
+     * Sample pixels from an array if it exceeds maxSamples
+     * Uses uniform sampling to maintain color distribution
+     * CORE-PERF-004: Fixed potential out-of-bounds access on last iteration
+     */
+    samplePixels(pixels, maxSamples) {
+        if (pixels.length <= maxSamples) {
+            return pixels;
+        }
+        const step = pixels.length / maxSamples;
+        const samples = [];
+        for (let i = 0; i < maxSamples; i++) {
+            // Clamp index to prevent out-of-bounds access due to floating-point rounding
+            const index = Math.min(Math.floor(i * step), pixels.length - 1);
+            samples.push(pixels[index]);
+        }
+        return samples;
+    }
+    /**
+     * Extract dominant colors from pixel data
+     *
+     * @param pixels - Array of RGB pixel values
+     * @param options - Extraction options (colorCount, maxIterations, etc.)
+     * @returns Array of extracted colors sorted by dominance (most dominant first)
+     *
+     * @example
+     * ```typescript
+     * const pixels = [{ r: 255, g: 0, b: 0 }, { r: 254, g: 1, b: 1 }, ...];
+     * const palette = paletteService.extractPalette(pixels, { colorCount: 4 });
+     * // Returns: [{ color: { r: 255, g: 0, b: 0 }, dominance: 45, pixelCount: 4500 }, ...]
+     * ```
+     */
+    extractPalette(pixels, options = {}) {
+        const opts = { ...PaletteService.DEFAULT_OPTIONS, ...options };
+        // Validate colorCount
+        const colorCount = Math.max(1, Math.min(10, opts.colorCount));
+        // SECURITY: Clamp maxIterations to prevent DoS via algorithmic complexity
+        const maxIterations = Math.max(1, Math.min(100, opts.maxIterations));
+        if (pixels.length === 0) {
+            this.logger.warn('PaletteService.extractPalette: Empty pixel array');
+            return [];
+        }
+        this.logger.info(`Extracting ${colorCount} colors from ${pixels.length} pixels`);
+        // Sample pixels if too many
+        const sampledPixels = this.samplePixels(pixels, opts.maxSamples);
+        // Run K-means clustering
+        const { centroids, clusterSizes } = kMeansClustering(sampledPixels, colorCount, maxIterations, opts.convergenceThreshold);
+        // Calculate total pixels for dominance percentage
+        const totalPixels = clusterSizes.reduce((sum, size) => sum + size, 0);
+        // Build result array
+        const result = centroids.map((color, i) => ({
+            color,
+            dominance: totalPixels > 0 ? Math.round((clusterSizes[i] / totalPixels) * 100) : 0,
+            pixelCount: clusterSizes[i],
+        }));
+        // Sort by dominance (most dominant first)
+        result.sort((a, b) => b.dominance - a.dominance);
+        this.logger.info(`Extracted colors: ${result.map((r) => `${r.dominance}%`).join(', ')}`);
+        return result;
+    }
+    /**
+     * Extract colors from pixel data and match each to the closest FFXIV dye
+     *
+     * @param pixels - Array of RGB pixel values
+     * @param dyeService - DyeService instance for matching
+     * @param options - Extraction options
+     * @returns Array of palette matches sorted by dominance
+     *
+     * @example
+     * ```typescript
+     * const matches = paletteService.extractAndMatchPalette(pixels, dyeService, { colorCount: 4 });
+     * // Returns: [{ extracted: {...}, matchedDye: {...}, distance: 12.3, dominance: 45 }, ...]
+     * ```
+     */
+    extractAndMatchPalette(pixels, dyeService, options = {}) {
+        // Extract palette
+        const extracted = this.extractPalette(pixels, options);
+        // Match each extracted color to closest dye
+        const matches = [];
+        for (const ex of extracted) {
+            // Convert RGB to hex for DyeService
+            const hex = ColorService.rgbToHex(ex.color.r, ex.color.g, ex.color.b);
+            const matchedDye = dyeService.findClosestDye(hex);
+            if (matchedDye) {
+                // Calculate distance between extracted and matched colors
+                const distance = rgbDistance(ex.color, matchedDye.rgb);
+                matches.push({
+                    extracted: ex.color,
+                    matchedDye,
+                    distance,
+                    dominance: ex.dominance,
+                });
+            }
+        }
+        return matches;
+    }
+    /**
+     * Convert flat pixel array (Uint8ClampedArray from canvas) to RGB array
+     * Skips alpha channel
+     *
+     * @param data - Flat array of RGBA values [r, g, b, a, r, g, b, a, ...]
+     * @returns Array of RGB objects
+     */
+    static pixelDataToRGB(data) {
+        const pixels = [];
+        for (let i = 0; i < data.length; i += 4) {
+            pixels.push({
+                r: data[i],
+                g: data[i + 1],
+                b: data[i + 2],
+                // Skip alpha at data[i + 3]
+            });
+        }
+        return pixels;
+    }
+    /**
+     * Filter out near-transparent pixels from RGBA data
+     * Useful for images with transparent backgrounds
+     *
+     * @param data - Flat array of RGBA values
+     * @param alphaThreshold - Minimum alpha to include (0-255, default: 128)
+     * @returns Array of RGB objects for non-transparent pixels
+     */
+    static pixelDataToRGBFiltered(data, alphaThreshold = 128) {
+        const pixels = [];
+        for (let i = 0; i < data.length; i += 4) {
+            const alpha = data[i + 3];
+            if (alpha >= alphaThreshold) {
+                pixels.push({
+                    r: data[i],
+                    g: data[i + 1],
+                    b: data[i + 2],
+                });
+            }
+        }
+        return pixels;
+    }
+}
+/** Default extraction options */
+PaletteService.DEFAULT_OPTIONS = {
+    colorCount: 4,
+    maxIterations: 25,
+    convergenceThreshold: 1.0,
+    maxSamples: 10000,
+};
+//# sourceMappingURL=PaletteService.js.map

package/dist/services/PaletteService.js.map

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

package/dist/services/PresetService.d.ts

@@ -0,0 +1,196 @@
+/**
+ * @xivdyetools/core - Preset Service
+ *
+ * Manages preset color palettes for FFXIV glamours.
+ * Provides themed color combinations for jobs, seasons, events, and aesthetics.
+ *
+ * @module services/PresetService
+ * @example
+ * ```typescript
+ * import { PresetService, presetData, DyeService, dyeDatabase } from '@xivdyetools/core';
+ *
+ * const presetService = new PresetService(presetData);
+ * const dyeService = new DyeService(dyeDatabase);
+ *
+ * // Get all job presets
+ * const jobPresets = presetService.getPresetsByCategory('jobs');
+ *
+ * // Get a preset with resolved dye objects
+ * const rdmPreset = presetService.getPresetWithDyes('job-rdm', dyeService);
+ * ```
+ */
+import type { PresetData, PresetPalette, PresetCategory, CategoryMeta, ResolvedPreset, Dye } from '../types/index.js';
+/**
+ * Interface for DyeService to resolve dye IDs to Dye objects
+ * Using interface to avoid circular dependency
+ */
+interface IDyeService {
+    getDyeById(id: number): Dye | null;
+}
+/**
+ * Service for managing preset color palettes
+ *
+ * @example
+ * ```typescript
+ * const presetService = new PresetService(presetData);
+ *
+ * // List categories
+ * const categories = presetService.getCategories();
+ *
+ * // Get presets by category
+ * const jobPresets = presetService.getPresetsByCategory('jobs');
+ *
+ * // Search presets
+ * const results = presetService.searchPresets('red');
+ * ```
+ */
+export declare class PresetService {
+    private data;
+    private presetById;
+    /**
+     * Initialize the preset service with preset data
+     * @param presetData - Preset data object (import from presets.json)
+     */
+    constructor(presetData: PresetData);
+    /**
+     * Get all preset categories with metadata
+     * @returns Array of category metadata with IDs
+     *
+     * @example
+     * ```typescript
+     * const categories = presetService.getCategories();
+     * // [{ id: 'jobs', name: 'FFXIV Jobs', description: '...', icon: '⚔️' }, ...]
+     * ```
+     */
+    getCategories(): (CategoryMeta & {
+        id: string;
+    })[];
+    /**
+     * Get metadata for a specific category
+     * @param category - Category identifier
+     * @returns Category metadata or undefined if not found
+     */
+    getCategoryMeta(category: PresetCategory): CategoryMeta | undefined;
+    /**
+     * Get all presets
+     * @returns Array of all preset palettes
+     */
+    getAllPresets(): PresetPalette[];
+    /**
+     * Get all presets in a specific category
+     * @param category - Category to filter by
+     * @returns Array of presets in that category
+     *
+     * @example
+     * ```typescript
+     * const jobPresets = presetService.getPresetsByCategory('jobs');
+     * // Returns all job-themed presets (RDM, BLM, WHM, etc.)
+     * ```
+     */
+    getPresetsByCategory(category: PresetCategory): PresetPalette[];
+    /**
+     * Get a specific preset by ID
+     * @param id - Preset identifier (e.g., "job-rdm")
+     * @returns Preset or undefined if not found
+     *
+     * @example
+     * ```typescript
+     * const rdm = presetService.getPreset('job-rdm');
+     * if (rdm) {
+     *   console.log(rdm.name); // "Red Mage"
+     *   console.log(rdm.dyes); // [5738, 13115, 13117, 5729]
+     * }
+     * ```
+     */
+    getPreset(id: string): PresetPalette | undefined;
+    /**
+     * Get preset count by category
+     * @returns Map of category to preset count
+     */
+    getPresetCountByCategory(): Map<PresetCategory, number>;
+    /**
+     * Search presets by name or tags
+     * @param query - Search query (case-insensitive)
+     * @returns Array of matching presets
+     *
+     * @example
+     * ```typescript
+     * // Search by name
+     * const results = presetService.searchPresets('red');
+     * // Returns: Red Mage, Blood Red themed presets, etc.
+     *
+     * // Search by tag
+     * const tankResults = presetService.searchPresets('tank');
+     * // Returns: Paladin, Warrior, Dark Knight, Gunbreaker
+     * ```
+     */
+    searchPresets(query: string): PresetPalette[];
+    /**
+     * Search presets by tag (exact match)
+     * @param tag - Tag to search for (case-insensitive)
+     * @returns Array of presets with that tag
+     */
+    getPresetsByTag(tag: string): PresetPalette[];
+    /**
+     * Get a random preset, optionally filtered by category
+     * @param category - Optional category to filter by
+     * @returns Random preset, or undefined if no presets exist
+     *
+     * @example
+     * ```typescript
+     * // Random from all presets
+     * const random = presetService.getRandomPreset();
+     *
+     * // Random job preset
+     * const randomJob = presetService.getRandomPreset('jobs');
+     * ```
+     */
+    getRandomPreset(category?: PresetCategory): PresetPalette | undefined;
+    /**
+     * Get preset with resolved Dye objects
+     * Requires a DyeService instance to resolve dye IDs to full Dye objects
+     *
+     * @param id - Preset identifier
+     * @param dyeService - DyeService instance for resolving dye IDs
+     * @returns Resolved preset with full Dye objects, or undefined if preset not found
+     *
+     * @example
+     * ```typescript
+     * const dyeService = new DyeService(dyeDatabase);
+     * const resolved = presetService.getPresetWithDyes('job-rdm', dyeService);
+     *
+     * if (resolved) {
+     *   resolved.resolvedDyes.forEach(dye => {
+     *     if (dye) {
+     *       console.log(`${dye.name}: ${dye.hex}`);
+     *     }
+     *   });
+     * }
+     * ```
+     */
+    getPresetWithDyes(id: string, dyeService: IDyeService): ResolvedPreset | undefined;
+    /**
+     * Resolve multiple presets with their Dye objects
+     * @param presets - Array of presets to resolve
+     * @param dyeService - DyeService instance for resolving dye IDs
+     * @returns Array of resolved presets
+     */
+    resolvePresets(presets: PresetPalette[], dyeService: IDyeService): ResolvedPreset[];
+    /**
+     * Get data version
+     * @returns Version string from preset data
+     */
+    getVersion(): string;
+    /**
+     * Get last update timestamp
+     * @returns ISO date string of last update
+     */
+    getLastUpdated(): string;
+    /**
+     * Get total number of presets
+     * @returns Total preset count
+     */
+    getPresetCount(): number;
+}
+export {};
+//# sourceMappingURL=PresetService.d.ts.map

package/dist/services/PresetService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PresetService.d.ts","sourceRoot":"","sources":["../../src/services/PresetService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EACV,UAAU,EACV,aAAa,EACb,cAAc,EACd,YAAY,EACZ,cAAc,EACd,GAAG,EACJ,MAAM,mBAAmB,CAAC;AAE3B;;;GAGG;AACH,UAAU,WAAW;IACnB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC;CACpC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,IAAI,CAAa;IACzB,OAAO,CAAC,UAAU,CAA6B;IAE/C;;;OAGG;gBACS,UAAU,EAAE,UAAU;IAUlC;;;;;;;;;OASG;IACH,aAAa,IAAI,CAAC,YAAY,GAAG;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,EAAE;IAOlD;;;;OAIG;IACH,eAAe,CAAC,QAAQ,EAAE,cAAc,GAAG,YAAY,GAAG,SAAS;IAQnE;;;OAGG;IACH,aAAa,IAAI,aAAa,EAAE;IAIhC;;;;;;;;;;OAUG;IACH,oBAAoB,CAAC,QAAQ,EAAE,cAAc,GAAG,aAAa,EAAE;IAI/D;;;;;;;;;;;;;OAaG;IACH,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IAIhD;;;OAGG;IACH,wBAAwB,IAAI,GAAG,CAAC,cAAc,EAAE,MAAM,CAAC;IAYvD;;;;;;;;;;;;;;;OAeG;IACH,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,EAAE;IAc7C;;;;OAIG;IACH,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,EAAE;IAS7C;;;;;;;;;;;;;OAaG;IACH,eAAe,CAAC,QAAQ,CAAC,EAAE,cAAc,GAAG,aAAa,GAAG,SAAS;IAcrE;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,iBAAiB,CAAC,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,WAAW,GAAG,cAAc,GAAG,SAAS;IAYlF;;;;;OAKG;IACH,cAAc,CAAC,OAAO,EAAE,aAAa,EAAE,EAAE,UAAU,EAAE,WAAW,GAAG,cAAc,EAAE;IAWnF;;;OAGG;IACH,UAAU,IAAI,MAAM;IAIpB;;;OAGG;IACH,cAAc,IAAI,MAAM;IAIxB;;;OAGG;IACH,cAAc,IAAI,MAAM;CAGzB"}