Improve color extraction with global ANSI matching, hue synthesis, and monochrome support

Author: bjarneo

src/utils/color-extraction/color-analysis.js

@@ -9,6 +9,8 @@ import {
     ANSI_HUE_ARRAY,
     BRIGHT_COLOR_LIGHTNESS_BOOST,
     BRIGHT_COLOR_SATURATION_BOOST,
+    SYNTHESIS_SCORE_THRESHOLD,
+    ANSI_MIN_SATURATION_FOR_MATCH,
 } from './constants.js';
 
 /**
@@ -164,20 +166,33 @@ export function findForegroundColor(colors, lightMode, usedIndices) {
 
 /**
  * Calculates color quality score for ANSI color selection
- * Prioritizes hue accuracy, then favors more saturated colors
+ * Balances hue accuracy, saturation preference, and lightness suitability
+ * Lower score = better match
  *
  * @param {{h: number, s: number, l: number}} hsl - HSL color values
  * @param {number} targetHue - Target hue (0-360)
  * @returns {number} Score (lower is better)
  */
 export function calculateColorScore(hsl, targetHue) {
-    const hueDiff = calculateHueDistance(hsl.h, targetHue) * 3;
-    const saturationPenalty = hsl.s < MIN_CHROMATIC_SATURATION ? 50 : 0;
-    const saturationReward = (100 - hsl.s) / 2;
-    const lightnessPenalty =
-        hsl.l < TOO_DARK_THRESHOLD || hsl.l > TOO_BRIGHT_THRESHOLD ? 10 : 0;
+    // Hue accuracy - primary factor
+    const hueScore = calculateHueDistance(hsl.h, targetHue) * 2.5;
 
-    return hueDiff + saturationPenalty + saturationReward + lightnessPenalty;
+    // Saturation preference - strongly prefer chromatic colors
+    let satScore;
+    if (hsl.s < ANSI_MIN_SATURATION_FOR_MATCH) satScore = 80;
+    else if (hsl.s < 20) satScore = 40;
+    else if (hsl.s < 30) satScore = 15;
+    else satScore = Math.max(0, (50 - hsl.s) * 0.3);
+
+    // Lightness suitability - prefer mid-range, penalize extremes
+    let lightnessScore;
+    if (hsl.l < TOO_DARK_THRESHOLD)
+        lightnessScore = (TOO_DARK_THRESHOLD - hsl.l) * 2.5;
+    else if (hsl.l > TOO_BRIGHT_THRESHOLD)
+        lightnessScore = (hsl.l - TOO_BRIGHT_THRESHOLD) * 2;
+    else lightnessScore = Math.abs(hsl.l - 55) * 0.2;
+
+    return hueScore + satScore + lightnessScore;
 }
 
 /**
@@ -208,12 +223,19 @@ export function findBestColorMatch(targetHue, colorPool, usedIndices) {
 
 /**
  * Generates a lighter version of a color for bright ANSI slots
+ * Scales the boost based on available headroom to avoid washing out bright colors
  * @param {string} hexColor - Base hex color
  * @returns {string} Lightened hex color
  */
 export function generateBrightVersion(hexColor) {
     const hsl = getColorHSL(hexColor);
-    const newLightness = Math.min(100, hsl.l + BRIGHT_COLOR_LIGHTNESS_BOOST);
+    // Scale boost based on available headroom so bright colors don't wash out
+    const headroom = 90 - hsl.l;
+    const boost = Math.max(
+        5,
+        Math.min(BRIGHT_COLOR_LIGHTNESS_BOOST, headroom * 0.6)
+    );
+    const newLightness = Math.min(90, hsl.l + boost);
     const newSaturation = Math.min(100, hsl.s * BRIGHT_COLOR_SATURATION_BOOST);
     return hslToHex(hsl.h, newSaturation, newLightness);
 }
@@ -242,3 +264,92 @@ export function sortColorsByLightness(colors) {
         })
         .sort((a, b) => a.lightness - b.lightness);
 }
+
+/**
+ * Synthesizes an ANSI color when no good match exists in the image
+ * Uses the average saturation and lightness of already-assigned colors
+ * to create a color that fits the palette's visual mood
+ *
+ * @param {number} targetHue - Target ANSI hue (0-360)
+ * @param {string[]} existingColors - Already-assigned ANSI colors
+ * @returns {string} Synthesized hex color
+ */
+export function synthesizeAnsiColor(targetHue, existingColors) {
+    let totalS = 0,
+        totalL = 0,
+        count = 0;
+
+    for (const color of existingColors) {
+        if (!color) continue;
+        const hsl = getColorHSL(color);
+        if (hsl.s >= ANSI_MIN_SATURATION_FOR_MATCH) {
+            totalS += hsl.s;
+            totalL += hsl.l;
+            count++;
+        }
+    }
+
+    // Fall back to reasonable defaults if no reference colors
+    const avgS = count > 0 ? totalS / count : 50;
+    const avgL = count > 0 ? totalL / count : 55;
+
+    // Clamp to ensure the synthesized color is visually clear
+    const synS = Math.max(35, Math.min(75, avgS));
+    const synL = Math.max(40, Math.min(70, avgL));
+
+    return hslToHex(targetHue, synS, synL);
+}
+
+/**
+ * Finds optimal ANSI color assignments using global greedy matching
+ * Instead of assigning colors sequentially (red first, then green, etc.),
+ * this finds the globally best (ANSI slot, color) pair at each step,
+ * preventing earlier slots from stealing good matches from later ones
+ *
+ * @param {string[]} colorPool - Available colors to choose from
+ * @param {Set<number>} usedIndices - Already used color indices
+ * @returns {Array<{poolIndex: number, score: number}|null>} Assignment for each ANSI slot (0-5)
+ */
+export function findOptimalAnsiAssignment(colorPool, usedIndices) {
+    // Pre-compute and sort scores for all (ANSI slot, color) pairs
+    const allScores = ANSI_HUE_ARRAY.map(targetHue => {
+        return colorPool
+            .map((color, poolIndex) => {
+                if (usedIndices.has(poolIndex))
+                    return {poolIndex, score: Infinity};
+                const hsl = getColorHSL(color);
+                return {poolIndex, score: calculateColorScore(hsl, targetHue)};
+            })
+            .sort((a, b) => a.score - b.score);
+    });
+
+    const assignments = new Array(6).fill(null);
+    const assignedPoolIndices = new Set(usedIndices);
+
+    // Iteratively assign the globally best pair
+    for (let round = 0; round < 6; round++) {
+        let bestAnsi = -1;
+        let bestPoolIndex = -1;
+        let bestScore = Infinity;
+
+        for (let a = 0; a < 6; a++) {
+            if (assignments[a] !== null) continue;
+            // Find best unassigned candidate for this slot
+            for (const candidate of allScores[a]) {
+                if (assignedPoolIndices.has(candidate.poolIndex)) continue;
+                if (candidate.score < bestScore) {
+                    bestScore = candidate.score;
+                    bestAnsi = a;
+                    bestPoolIndex = candidate.poolIndex;
+                }
+                break; // First unassigned is best (list is sorted)
+            }
+        }
+
+        if (bestAnsi === -1) break;
+        assignments[bestAnsi] = {poolIndex: bestPoolIndex, score: bestScore};
+        assignedPoolIndices.add(bestPoolIndex);
+    }
+
+    return assignments;
+}

src/utils/color-extraction/constants.js

@@ -13,10 +13,10 @@
 export const ANSI_PALETTE_SIZE = 16;
 
 /** Number of dominant colors to extract from image for analysis */
-export const DOMINANT_COLORS_TO_EXTRACT = 32;
+export const DOMINANT_COLORS_TO_EXTRACT = 48;
 
 /** Cache version number - increment when cache format changes */
-export const CACHE_VERSION = 1;
+export const CACHE_VERSION = 2;
 
 // ============================================================================
 // COLOR DETECTION THRESHOLDS
@@ -97,9 +97,18 @@ export const DARK_COLOR_THRESHOLD = 50;
 /** Base saturation for subtle balanced palettes (0-100) */
 export const SUBTLE_PALETTE_SATURATION = 28;
 
-/** Saturation for monochrome palette colors (0-100) */
+/** Saturation for monochrome palette neutral colors like color8/15 (0-100) */
 export const MONOCHROME_SATURATION = 5;
 
+/** Saturation for ANSI colors 1-6 in monochrome palettes - enough to distinguish hues (0-100) */
+export const MONOCHROME_ANSI_SATURATION = 30;
+
+/** Saturation for bright ANSI colors 9-14 in monochrome palettes (0-100) */
+export const MONOCHROME_ANSI_BRIGHT_SATURATION = 40;
+
+/** How much the image's tonal tint influences monochrome ANSI hues (0-1) */
+export const MONOCHROME_TINT_STRENGTH = 0.15;
+
 /** Saturation multiplier for color8 in monochrome (0-1) */
 export const MONOCHROME_COLOR8_SATURATION_FACTOR = 0.5;
 
@@ -109,6 +118,16 @@ export const BRIGHT_COLOR_LIGHTNESS_BOOST = 18;
 /** Saturation multiplier for bright ANSI colors (9-14) */
 export const BRIGHT_COLOR_SATURATION_BOOST = 1.1;
 
+// ============================================================================
+// ANSI COLOR MATCHING
+// ============================================================================
+
+/** Score threshold above which a synthesized color is used instead of a poor match */
+export const SYNTHESIS_SCORE_THRESHOLD = 180;
+
+/** Minimum saturation for a color to be considered a valid ANSI match */
+export const ANSI_MIN_SATURATION_FOR_MATCH = 12;
+
 // ============================================================================
 // STANDARD ANSI COLOR HUES
 // ============================================================================
@@ -138,7 +157,7 @@ export const ANSI_HUE_ARRAY = [
 // ============================================================================
 
 /** Maximum image dimension for fast processing (pixels) */
-export const IMAGE_SCALE_SIZE = 200;
+export const IMAGE_SCALE_SIZE = 300;
 
 /** Minimum pixels to sample for reliable color extraction */
 export const MIN_PIXELS_TO_SAMPLE = 1000;

src/utils/color-extraction/index.js

@@ -8,10 +8,9 @@
 import {DOMINANT_COLORS_TO_EXTRACT} from './constants.js';
 import {getCacheKey, loadCachedPalette, savePaletteToCache} from './cache.js';
 import {extractDominantColors} from './median-cut.js';
-import {isMonochromeImage, hasLowColorDiversity} from './color-analysis.js';
+import {isMonochromeImage} from './color-analysis.js';
 import {
     generateChromaticPalette,
-    generateSubtleBalancedPalette,
     generateMonochromePalette,
     generateMonochromaticPalette,
     generatePastelPalette,
@@ -117,16 +116,8 @@ export async function extractColorsWithImageMagick(
                     'Detected monochrome image - generating grayscale palette'
                 );
                 palette = generateMonochromePalette(dominantColors, lightMode);
-            } else if (hasLowColorDiversity(dominantColors)) {
-                log.info('Detected low diversity - generating subtle palette');
-                palette = generateSubtleBalancedPalette(
-                    dominantColors,
-                    lightMode
-                );
             } else {
-                log.info(
-                    'Detected diverse image - generating chromatic palette'
-                );
+                log.info('Generating chromatic palette');
                 palette = generateChromaticPalette(dominantColors, lightMode);
             }
         }