feat(quantization): add color diversity slider for CPC Plus Mode 0 (#315)

- Add colorDiversityAtom (0-100, default 50) for adjustable hue diversity
- Implement getColorDiversityParams() mapping slider to internal params:
  - minHueDistance: 10° → 45°
  - minRgbDistance: 50 → 150
  - hueBucketSize: 45° → 20°
- Add "Color Diversity" section with TuningSlider in dithering settings
- Connect slider to quantization pipeline via config
- Only visible for CPC Plus Mode 0 (16 colors)
- Include reset button to default value (50)
- Add translations for EN, DE, ES

Author: IIIvan37

src/app/store/config/config.ts

@@ -102,9 +102,11 @@ export {
 // Processing
 export {
   autoDistinctMappingAtom,
+  colorDiversityAtom,
   horizontalSmoothingAtom,
   paletteStrategyAtom,
   processorTypeAtom,
+  setColorDiversityAtom,
   setPaletteStrategyAtom,
   setProcessorTypeAtom,
   smoothingAtom

src/app/store/config/processing.ts

@@ -39,6 +39,14 @@ export const paletteStrategyAtom = atom<PaletteStrategy>('exhaustive-contrast')
  */
 export const autoDistinctMappingAtom = atom<boolean>(false)
 
+/**
+ * Color diversity level for CPC Plus Mode 0 quantization (0-100)
+ * 0 = Similar shades (prioritize frequency, allow close hues)
+ * 50 = Balanced (default)
+ * 100 = Distinct hues (maximize color variety)
+ */
+export const colorDiversityAtom = atom<number>(50)
+
 // ============================================================================
 // SETTERS
 // ============================================================================
@@ -62,3 +70,13 @@ export const setPaletteStrategyAtom = atom(
     set(paletteStrategyAtom, payload)
   }
 )
+
+/**
+ * Setter for color diversity
+ */
+export const setColorDiversityAtom = atom(
+  null,
+  (_get, set, payload: number) => {
+    set(colorDiversityAtom, Math.max(0, Math.min(100, payload)))
+  }
+)

src/app/store/preview/pipeline/quantization.ts

@@ -18,6 +18,7 @@ import { getPaletteForHardware } from '@/palettes/cpc-palette'
 import { paletteProcessorAtom } from '../../adapters/processors'
 import {
   autoDistinctMappingAtom,
+  colorDiversityAtom,
   cpcHardwareAtom,
   effectiveModeConfigAtom,
   paletteStrategyAtom
@@ -164,11 +165,14 @@ export const reducedPaletteRawAtom = atom(async (get) => {
   const paletteStrategy = get(paletteStrategyAtom)
   // Read autoDistinctMapping to create dependency (triggers re-processing when toggle changes)
   const autoDistinctMapping = get(autoDistinctMappingAtom)
+  // Read colorDiversity to create dependency (triggers re-processing when slider changes)
+  const colorDiversity = get(colorDiversityAtom)
 
   logger.info('[Preview] Quantizing palette', {
     targetColors,
     paletteStrategy,
     autoDistinctMapping,
+    colorDiversity,
     hardware: cpcHardware
   })
 

src/components/settings-panel/sections/dithering-settings/dithering-settings-view.tsx

@@ -2,10 +2,13 @@
  * Dithering settings view (dumb component)
  */
 
+import { msg } from '@lingui/core/macro'
+import { useLingui } from '@lingui/react'
 import { Trans } from '@lingui/react/macro'
 import { useId } from 'react'
 import Flex from '@/components/ui/flex'
 import { Switch } from '@/components/ui/switch'
+import { TuningSlider } from '../../shared/tuning-slider'
 import styles from '../../tabs/tab.module.css'
 import { DitheringControls } from './dithering-controls'
 import { PaletteStrategySelector } from './palette-strategy-selector/palette-strategy-selector'
@@ -21,6 +24,9 @@ type DitheringSettingsViewProps = Readonly<{
   sourceUniqueColors: number | null
   rasterEnabled: boolean
   isPaletteStrategyDisabled: boolean
+  showColorDiversity: boolean
+  colorDiversity: number
+  onColorDiversityChange: (value: number) => void
 }>
 
 export function DitheringSettingsView({
@@ -33,10 +39,14 @@ export function DitheringSettingsView({
   isDistinctMappingDisabled,
   sourceUniqueColors,
   rasterEnabled,
-  isPaletteStrategyDisabled
+  isPaletteStrategyDisabled,
+  showColorDiversity,
+  colorDiversity,
+  onColorDiversityChange
 }: DitheringSettingsViewProps) {
   const smoothingId = useId()
   const distinctMappingId = useId()
+  const { _ } = useLingui()
 
   return (
     <>
@@ -60,6 +70,52 @@ export function DitheringSettingsView({
         <PaletteStrategySelector />
       </div>
 
+      {showColorDiversity && (
+        <>
+          <div className={styles.separator} />
+
+          <div className={styles.section}>
+            <h3 className={styles.sectionTitle}>
+              <Trans>Diversité des couleurs</Trans>
+            </h3>
+            <p className={styles.description}>
+              <Trans>
+                Ajustez l'équilibre entre fidélité aux couleurs fréquentes et
+                variété des teintes (CPC Plus Mode 0).
+              </Trans>
+            </p>
+
+            <TuningSlider
+              min={0}
+              max={100}
+              step={1}
+              value={colorDiversity}
+              defaultValue={50}
+              onChange={onColorDiversityChange}
+              label={_(
+                msg({
+                  id: 'color.diversity.label',
+                  message: 'Diversité'
+                })
+              )}
+              description={_(
+                msg({
+                  id: 'color.diversity.description',
+                  message: 'Nuances similaires (0) ◄► Teintes distinctes (100)'
+                })
+              )}
+              format={(v) => `${v}`}
+              resetTitle={_(
+                msg({
+                  id: 'color.diversity.reset',
+                  message: 'Réinitialiser à 50'
+                })
+              )}
+            />
+          </div>
+        </>
+      )}
+
       <div className={styles.separator} />
 
       <div

src/components/settings-panel/sections/dithering-settings/dithering-settings.tsx

@@ -5,10 +5,12 @@
 import { useAtom, useAtomValue, useSetAtom } from 'jotai'
 import {
   autoDistinctMappingAtom,
+  colorDiversityAtom,
   cpcHardwareAtom,
   effectiveModeConfigAtom,
   horizontalSmoothingAtom,
-  setAutoDistinctMappingAtom
+  setAutoDistinctMappingAtom,
+  setColorDiversityAtom
 } from '@/app/store/config/config'
 import { sourceUniqueColorsCountAtom } from '@/app/store/preview/preview'
 import { rasterEnabledAtom } from '@/app/store/raster/raster'
@@ -21,6 +23,8 @@ export function DitheringSettings() {
   )
   const autoDistinctMapping = useAtomValue(autoDistinctMappingAtom)
   const setAutoDistinctMapping = useSetAtom(setAutoDistinctMappingAtom)
+  const colorDiversity = useAtomValue(colorDiversityAtom)
+  const setColorDiversity = useSetAtom(setColorDiversityAtom)
   const rasterEnabled = useAtomValue(rasterEnabledAtom)
   const isPaletteStrategyDisabled = usePaletteStrategyDisabled()
   const cpcHardware = useAtomValue(cpcHardwareAtom)
@@ -39,6 +43,10 @@ export function DitheringSettings() {
   const isDistinctMappingActive =
     autoDistinctMapping && showDistinctMapping && !isDistinctMappingDisabled
 
+  // Color diversity slider: only for CPC Plus Mode 0 (16 colors)
+  const showColorDiversity =
+    cpcHardware === 'plus' && modeConfig.nColors === 16 && !rasterEnabled
+
   return (
     <DitheringSettingsView
       horizontalSmoothing={horizontalSmoothing}
@@ -51,6 +59,9 @@ export function DitheringSettings() {
       sourceUniqueColors={sourceUniqueColors}
       rasterEnabled={rasterEnabled}
       isPaletteStrategyDisabled={isPaletteStrategyDisabled}
+      showColorDiversity={showColorDiversity}
+      colorDiversity={colorDiversity}
+      onColorDiversityChange={setColorDiversity}
     />
   )
 }

src/libs/pixsaur-adapter/adapters/color-selection-helpers.ts

@@ -68,6 +68,55 @@ export const HUE_BONUS_WEIGHT = 2
 export const VALUE_THRESHOLD_BRIGHT = 0.5
 
 /** Nombre minimum de couleurs claires parmi les représentants de bucket */
+
+// ============================================================================
+// Color Diversity Configuration
+// ============================================================================
+
+/**
+ * Parameters derived from the color diversity slider (0-100)
+ */
+export interface ColorDiversityParams {
+  /** Minimum hue distance in degrees (10-45) */
+  minHueDistance: number
+  /** Minimum RGB distance (50-150) */
+  minRgbDistance: number
+  /** Hue bucket size in degrees (20-45) */
+  hueBucketSize: number
+}
+
+/**
+ * Maps the color diversity slider (0-100) to internal quantization parameters.
+ *
+ * - 0 = "Similar shades": Allows more similar colors, prioritizes frequency
+ * - 50 = "Balanced": Current default behavior
+ * - 100 = "Distinct hues": Maximizes color variety
+ *
+ * @param diversity - Slider value from 0 to 100
+ * @returns Parameters for color selection algorithms
+ */
+export function getColorDiversityParams(
+  diversity: number
+): ColorDiversityParams {
+  // Clamp to 0-100
+  const d = Math.max(0, Math.min(100, diversity))
+
+  // Linear interpolation for each parameter
+  // diversity 0 -> 100 maps to:
+  // - minHueDistance: 10° -> 45° (low = allow similar hues, high = require distinct)
+  // - minRgbDistance: 50 -> 150 (low = allow close RGB, high = require contrast)
+  // - hueBucketSize: 45° -> 20° (low = fewer families, high = more families)
+
+  const minHueDistance = 10 + (d / 100) * 35 // 10 to 45
+  const minRgbDistance = 50 + (d / 100) * 100 // 50 to 150
+  const hueBucketSize = 45 - (d / 100) * 25 // 45 to 20
+
+  return {
+    minHueDistance: Math.round(minHueDistance),
+    minRgbDistance: Math.round(minRgbDistance),
+    hueBucketSize: Math.round(hueBucketSize)
+  }
+}
 export const MIN_BRIGHT_BUCKET_REPRESENTATIVES = 2
 
 // ============================================================================
@@ -115,24 +164,28 @@ export interface HueBucket {
  * @param frequencyBudget - Nombre max de couleurs à sélectionner
  * @param targetColors - Nombre total de couleurs cible (pour détecter mode 0 vs 1-2)
  * @param calculateDistance - Fonction de distance RGB
+ * @param diversityParams - Optional diversity parameters from slider
  */
 export function selectFrequentColorsWithDiversity(
   colorFrequency: ColorFrequencyItem[],
   selectedConverted: Vector[],
   result: number[],
   frequencyBudget: number,
   targetColors: number | undefined,
-  calculateDistance: DistanceFunction
+  calculateDistance: DistanceFunction,
+  diversityParams?: ColorDiversityParams
 ): void {
   // Distance minimale adaptative selon la taille de la palette cible
+  // Use diversity params if provided, otherwise use defaults
   const minDistance =
     targetColors && targetColors <= CPC_MODE_1_MAX_COLORS
       ? MIN_RGB_DISTANCE_MODE_1_2
-      : MIN_RGB_DISTANCE_MODE_0
+      : (diversityParams?.minRgbDistance ?? MIN_RGB_DISTANCE_MODE_0)
 
   // Pour le mode 0, également exiger une diversité de teinte
   const isMode0 = targetColors && targetColors > CPC_MODE_1_MAX_COLORS
-  const minHueDistance = MIN_HUE_DISTANCE_MODE_0
+  const minHueDistance =
+    diversityParams?.minHueDistance ?? MIN_HUE_DISTANCE_MODE_0
 
   for (
     let i = 1;
@@ -209,7 +262,8 @@ export function selectMaxMinDistanceColors(
   selectedConverted: Vector[],
   result: number[],
   targetColors: number,
-  calculateDistance: DistanceFunction
+  calculateDistance: DistanceFunction,
+  _diversityParams?: ColorDiversityParams
 ): void {
   const remaining = colorFrequency.filter((c) => !result.includes(c.index))
   const additionalColors = targetColors - result.length
@@ -283,21 +337,24 @@ export function selectMaxMinDistanceColors(
  * Utilise des buckets de 45° (~8 familles principales + gris)
  *
  * @param colorFrequency - Couleurs candidates
+ * @param diversityParams - Optional diversity parameters from slider
  * @returns Map des buckets avec leurs couleurs
  */
 export function createHueBuckets(
-  colorFrequency: ColorFrequencyItem[]
+  colorFrequency: ColorFrequencyItem[],
+  diversityParams?: ColorDiversityParams
 ): Map<number | 'gray', ColorFrequencyItem[]> {
   const hueBuckets = new Map<number | 'gray', ColorFrequencyItem[]>()
+  const bucketSize = diversityParams?.hueBucketSize ?? HUE_BUCKET_SIZE_DEGREES
 
   for (const candidate of colorFrequency) {
     const sat = calculateSaturation(candidate.converted)
     const hue = calculateHue(candidate.converted, DELTA_MIN_FOR_HUE)
 
-    // Buckets pour avoir ~8 familles principales
+    // Buckets pour avoir ~8-12 familles principales depending on diversity
     const bucketKey: number | 'gray' =
       sat > SATURATION_THRESHOLD_FOR_HUE && hue >= 0
-        ? Math.floor(hue / HUE_BUCKET_SIZE_DEGREES)
+        ? Math.floor(hue / bucketSize)
         : 'gray'
 
     if (!hueBuckets.has(bucketKey)) {

src/libs/pixsaur-adapter/adapters/regl-processor.ts

@@ -9,6 +9,7 @@ import type REGL from 'regl'
 // Import pour accéder à l'atome de stratégie de palette et auto distinct-mapping
 import {
   autoDistinctMappingAtom,
+  colorDiversityAtom,
   paletteStrategyAtom
 } from '@/app/store/config/config'
 import { adapterLogger, paletteLogger } from '@/core'
@@ -769,6 +770,7 @@ export class ReGLProcessor implements ImageProcessor {
             paletteStrategy:
               paletteStrategy || getDefaultStore().get(paletteStrategyAtom),
             autoDistinctMapping: getDefaultStore().get(autoDistinctMappingAtom),
+            colorDiversity: getDefaultStore().get(colorDiversityAtom),
             gpuOptions: {
               minPixelsForGPU: 128 * 128 // GPU avantageux pour images moyennes+
             }