smart-downscaler 0.4.5 → 0.6.0

package/README.md

@@ -1,264 +1,736 @@
 # Smart Pixel Art Downscaler
 
-A sophisticated Rust library for intelligent image downscaling with focus on pixel art quality.
+A high-performance Rust library for intelligent image downscaling with pixel art quality preservation.
 
-**Available as both a native Rust library and a WebAssembly module for browser/Node.js usage.**
+**Available as a native Rust library and WebAssembly module for browser/Node.js.**
 
+[![Version](https://img.shields.io/badge/version-0.5.0-blue.svg)]()
+[![License](https://img.shields.io/badge/license-MIT-green.svg)]()
 
-## What's New in v0.3.5
+---
 
-### ⚡ Performance: Direct LUT Optimization
+## Table of Contents
 
-The preprocessing pipeline has been completely rewritten for speed:
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Configuration Reference](#configuration-reference)
+- [API Reference](#api-reference)
+- [Presets](#presets)
+- [Advanced Usage](#advanced-usage)
+- [Performance Tips](#performance-tips)
+- [Why Oklab?](#why-oklab)
+- [CLI Reference](#cli-reference)
+- [License](#license)
 
-| Old Method (v0.3)              | New Method (v0.3.5)   | Improvement           |
-| ------------------------------ | --------------------- | --------------------- |
-| HashMap Pre-quantization       | **Direct LUT (64MB)** | O(1) Access           |
-| Oklab Conversion on All Pixels | **Cached Oklab**      | \~100x Fewer Math Ops |
-| Iterative Resolution Cap       | **One-pass NN**       | Instant Resizing      |
+---
 
-**Key Optimizations:**
+## Features
 
-1. **Direct Lookup Table**: Uses a 64MB flat array to map 24-bit RGB colors to unique indices instantly. No hashing overhead.
+| Feature | Description |
+|---------|-------------|
+| **Oklab Color Space** | Modern perceptual color space with superior hue linearity |
+| **Multiple Palette Strategies** | 6 different extraction methods for various use cases |
+| **Region Segmentation** | SLIC superpixels, hierarchical clustering, or fast union-find |
+| **Edge-Aware Processing** | Sobel/Scharr detection preserves boundaries |
+| **Spatial Coherence** | Neighbor and region voting for smooth results |
+| **K-Centroid Tile Logic** | Advanced dominant color extraction per tile |
+| **Performance Preprocessing** | Resolution capping and color pre-quantization |
+| **WebAssembly Support** | Full browser compatibility with near-native speed |
 
-2. **RGBA-Only Preprocessing**: Resolution capping and quantization now happen strictly in RGBA space before any expensive Oklab math.
+---
 
-3. **Oklab Caching**: If color reduction is enabled (default), Oklab conversion is only performed once per unique color, not per pixel.
+## Installation
 
-<!---->
+### Rust (Native)
 
-    const config = new WasmDownscaleConfig();
-    config.max_resolution_mp = 1.5;       // Fast nearest-neighbor cap
-    config.max_color_preprocess = 16384;  // Direct LUT quantization
+```toml
+[dependencies]
+smart-downscaler = "0.5.0"
+```
 
+### WebAssembly (npm)
 
-### 🎯 K-Centroid Tile Logic
+```bash
+npm install smart-downscaler
+```
 
-New `k_centroid` configuration allows finer control over how a source tile is reduced to a single representative color before matching:
+### WebAssembly (CDN)
 
-| Mode | Name         | Description                                     | Best For                                      |
-| ---- | ------------ | ----------------------------------------------- | --------------------------------------------- |
-| `1`  | **Average**  | Simple average of all pixels (Default)          | Smooth gradients, noise reduction             |
-| `2`  | **Dominant** | Average of the largest color cluster ($k=2$)    | Sharp edges, separating foreground/background |
-| `3`  | **Foremost** | Average of the "foremost" distinct part ($k=3$) | Complex textures, detailed sprites            |
+```html
+<script type="module">
+  import init, { downscale_rgba, WasmDownscaleConfig } from 'https://unpkg.com/smart-downscaler@0.5.0/smart_downscaler.js';
+</script>
+```
 
-    // Example: Use dominant part for sharper edges
-    config.k_centroid = 2;
-    config.k_centroid_iterations = 2;
+---
+
+## Quick Start
 
+### JavaScript/TypeScript (Browser)
+
+```javascript
+import init, { downscale_rgba, WasmDownscaleConfig } from 'smart-downscaler';
+
+// Initialize WASM module (required once)
+await init();
+
+// Get image data from canvas
+const canvas = document.getElementById('myCanvas');
+const ctx = canvas.getContext('2d');
+const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);
+
+// Create configuration
+const config = new WasmDownscaleConfig();
+config.palette_size = 16;
+config.palette_strategy = 'oklab';
+
+// Downscale to 64x64
+const result = downscale_rgba(
+  imageData.data,        // Uint8ClampedArray (RGBA)
+  imageData.width,       // Source width
+  imageData.height,      // Source height
+  64,                    // Target width
+  64,                    // Target height
+  config                 // Optional config
+);
+
+// Draw result
+const outputData = new ImageData(result.data, result.width, result.height);
+outputCtx.putImageData(outputData, 0, 0);
+
+// Access palette and indices
+console.log('Palette colors:', result.palette_size);
+console.log('Palette RGB data:', result.palette);     // Uint8Array
+console.log('Pixel indices:', result.indices);        // Uint8Array
+```
+
+### Rust (Native)
+
+```rust
+use smart_downscaler::{smart_downscale, DownscaleConfig, Rgb};
+use smart_downscaler::palette::PaletteStrategy;
+
+// Create pixel data (from image crate or manually)
+let pixels: Vec<Rgb> = image.pixels()
+    .map(|p| Rgb::new(p[0], p[1], p[2]))
+    .collect();
+
+// Configure
+let config = DownscaleConfig {
+    palette_size: 16,
+    palette_strategy: PaletteStrategy::OklabMedianCut,
+    ..Default::default()
+};
+
+// Downscale
+let result = smart_downscale(
+    &pixels,
+    source_width,
+    source_height,
+    target_width,
+    target_height,
+    &config,
+);
+
+// Use result
+println!("Output: {}x{}", result.width, result.height);
+println!("Palette: {} colors", result.palette.len());
+```
+
+---
 
 ## Configuration Reference
 
-### DownscaleConfig
+### Complete Parameter List
+
+| Parameter | Type | Default | Range/Values | Description |
+|-----------|------|---------|--------------|-------------|
+| **Palette Settings** |||||
+| `palette_size` | `usize` | `16` | `1-256` | Number of colors in output palette |
+| `palette_strategy` | `string` | `"oklab"` | See [Palette Strategies](#palette-strategies) | Algorithm for palette extraction |
+| `kmeans_iterations` | `usize` | `5` | `0-20` | K-Means refinement passes (0 = disabled) |
+| **Spatial Coherence** |||||
+| `neighbor_weight` | `f32` | `0.3` | `0.0-1.0` | Bias toward colors used by neighboring tiles |
+| `region_weight` | `f32` | `0.2` | `0.0-1.0` | Bias toward colors used in same region |
+| **Refinement** |||||
+| `two_pass_refinement` | `bool` | `true` | `true/false` | Enable iterative smoothing pass |
+| `refinement_iterations` | `usize` | `3` | `0-10` | Number of refinement passes |
+| **Edge Detection** |||||
+| `edge_weight` | `f32` | `0.5` | `0.0-1.0` | Balance between luminance and color edges |
+| **Segmentation** |||||
+| `segmentation_method` | `string` | `"hierarchy_fast"` | See [Segmentation Methods](#segmentation-methods) | Region detection algorithm |
+| `slic_superpixels` | `usize` | `100` | `10-1000` | Number of superpixels (SLIC only) |
+| `slic_compactness` | `f32` | `10.0` | `1.0-40.0` | Shape regularity (SLIC only) |
+| `hierarchy_threshold` | `f32` | `15.0` | `5.0-50.0` | Color distance merge threshold |
+| `hierarchy_min_size` | `usize` | `4` | `1-100` | Minimum region size in pixels |
+| **Performance** |||||
+| `max_resolution_mp` | `f32` | `1.6` | `0.0-10.0` | Resolution cap in megapixels (0 = disabled) |
+| `max_color_preprocess` | `usize` | `16384` | `0-65536` | Pre-quantization limit (0 = disabled) |
+| **Tile Processing** |||||
+| `k_centroid` | `usize` | `1` | `1`, `2`, `3` | Tile color extraction mode |
+| `k_centroid_iterations` | `usize` | `0` | `0-10` | K-Means iterations for tile color |
+
+---
+
+### Palette Strategies
+
+| Strategy | String Value | Description | Best For |
+|----------|--------------|-------------|----------|
+| **Oklab Median Cut** | `"oklab"` | Perceptually uniform color space | General use, balanced results |
+| **Saturation Weighted** | `"saturation"` | Preserves vibrant colors | Colorful artwork, game sprites |
+| **Medoid** | `"medoid"` | Uses only exact source colors | Pixel-perfect reproduction |
+| **K-Means++** | `"kmeans"` | Statistical clustering | Small palettes (4-8 colors) |
+| **Legacy RGB** | `"legacy"` | Classic RGB median cut | Compatibility, comparison |
+| **RGB Bitmask** | `"bitmask"` | Bit-masked clustering | Fast processing, high color counts |
+
+```javascript
+// Examples
+config.palette_strategy = 'oklab';      // Default, recommended
+config.palette_strategy = 'saturation'; // Vibrant colors
+config.palette_strategy = 'medoid';     // Exact source colors only
+config.palette_strategy = 'kmeans';     // Good for tiny palettes
+config.palette_strategy = 'legacy';     // RGB-space (not recommended)
+config.palette_strategy = 'bitmask';    // Fast approximate
+```
+
+---
+
+### Segmentation Methods
+
+| Method | String Value | Description | Performance | Quality |
+|--------|--------------|-------------|-------------|---------|
+| **None** | `"none"` | No region detection | ⚡⚡⚡ Fastest | Basic |
+| **Hierarchy Fast** | `"hierarchy_fast"` | Union-find clustering | ⚡⚡ Fast | Good |
+| **Hierarchy** | `"hierarchy"` | Full hierarchical merge | ⚡ Medium | Better |
+| **SLIC** | `"slic"` | Superpixel segmentation | ⚡ Medium | Best edges |
+
+```javascript
+// Examples
+config.segmentation_method = 'none';           // Speed priority
+config.segmentation_method = 'hierarchy_fast'; // Default, balanced
+config.segmentation_method = 'hierarchy';      // Quality priority
+config.segmentation_method = 'slic';           // Best for photos
+```
+
+---
+
+### K-Centroid Tile Modes
+
+Controls how each source tile is reduced to a single representative color:
+
+| Mode | Value | Description | Best For |
+|------|-------|-------------|----------|
+| **Average** | `1` | Simple weighted average of all pixels | Smooth gradients, noise reduction |
+| **Dominant** | `2` | K-Means (k=2), uses largest cluster | Sharp edges, foreground/background separation |
+| **Foremost** | `3` | K-Means (k=3), finer dominant detection | Complex textures, detailed sprites |
+
+```javascript
+// Mode 1: Average (default) - smooth results
+config.k_centroid = 1;
+config.k_centroid_iterations = 0;
+
+// Mode 2: Dominant - sharper edges
+config.k_centroid = 2;
+config.k_centroid_iterations = 2;
+
+// Mode 3: Foremost - detailed preservation
+config.k_centroid = 3;
+config.k_centroid_iterations = 3;
+```
+
+---
 
-| Field                   | Type   | Default   | Description                   |
-| ----------------------- | ------ | --------- | ----------------------------- |
-| `k_centroid`            | usize  | 1         | 1=Avg, 2=Dominant, 3=Foremost |
-| `k_centroid_iterations` | usize  | 0         | Refinement for tile color     |
-| `max_resolution_mp`     | f32    | 1.6       | Resolution cap (0=disabled)   |
-| `max_color_preprocess`  | usize  | 16384     | LUT Quantization limit        |
-| `segmentation`          | Method | Hierarchy | Region detection method       |
+## API Reference
 
+### Core Functions
+
+#### `downscale(data, width, height, targetWidth, targetHeight, config?)`
+
+Main downscale function accepting `Uint8Array` (RGBA).
+
+```javascript
+const result = downscale(
+  rgbaData,      // Uint8Array - RGBA pixel data
+  800,           // number - Source width
+  600,           // number - Source height  
+  64,            // number - Target width
+  48,            // number - Target height
+  config         // WasmDownscaleConfig? - Optional configuration
+);
+```
 
-## Command Line Interface
+#### `downscale_rgba(data, width, height, targetWidth, targetHeight, config?)`
 
-    # Enable Dominant Color mode (sharper details)
-    smart-downscaler input.png output.png --k-centroid 2 --k-centroid-iterations 2
+Same as `downscale` but accepts `Uint8ClampedArray` (from canvas `getImageData`).
 
-    # Fast mode (reduce preprocessing limits)
-    smart-downscaler input.png output.png --segmentation none --no-refinement
+```javascript
+const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);
+const result = downscale_rgba(
+  imageData.data,  // Uint8ClampedArray
+  imageData.width,
+  imageData.height,
+  64, 64,
+  config
+);
+```
+
+#### `downscale_simple(data, width, height, targetWidth, targetHeight, numColors)`
+
+Simplified API with minimal parameters.
+
+```javascript
+const result = downscale_simple(
+  rgbaData,
+  800, 600,
+  64, 48,
+  16  // Number of palette colors
+);
+```
+
+#### `downscale_with_palette(data, width, height, targetWidth, targetHeight, palette, config?)`
+
+Downscale using a pre-defined palette.
+
+```javascript
+const palette = new Uint8Array([
+  255, 0, 0,      // Red
+  0, 255, 0,      // Green
+  0, 0, 255,      // Blue
+  255, 255, 255,  // White
+]);
+
+const result = downscale_with_palette(
+  rgbaData,
+  800, 600,
+  64, 48,
+  palette,  // Uint8Array - RGB, 3 bytes per color
+  config
+);
+```
+
+---
+
+### Palette Functions
+
+#### `extract_palette_from_image(data, width, height, numColors, iterations, strategy?)`
+
+Extract palette without downscaling.
+
+```javascript
+const palette = extract_palette_from_image(
+  rgbaData,      // Uint8Array - RGBA pixel data
+  800,           // number - Image width (unused but required)
+  600,           // number - Image height (unused but required)
+  16,            // number - Number of colors to extract
+  5,             // number - K-Means iterations
+  'saturation'   // string? - Strategy (optional)
+);
+// Returns: Uint8Array - RGB palette (numColors * 3 bytes)
+```
 
+#### `quantize_to_palette(data, width, height, palette)`
+
+Quantize image to palette without resizing.
 
-## Features
+```javascript
+const result = quantize_to_palette(
+  rgbaData,      // Uint8Array - RGBA pixel data
+  800,           // number - Image width
+  600,           // number - Image height
+  palette        // Uint8Array - RGB palette
+);
+// Returns: WasmDownscaleResult (same size, quantized colors)
+```
 
-- **Oklab Color Space**: Modern perceptual color space with superior hue linearity
+#### `get_palette_strategies()`
 
-- **Global Palette Extraction**: Median Cut + K-Means++ refinement
+Get list of available palette strategies.
 
-- **Multiple Segmentation Methods**:
+```javascript
+const strategies = get_palette_strategies();
+// Returns: ['oklab', 'saturation', 'medoid', 'kmeans', 'legacy', 'bitmask']
+```
 
-  - SLIC superpixels for fast, balanced regions
+---
 
-  - VTracer-style hierarchical clustering for content-aware boundaries
+### Color Analysis Functions
 
-  - Union-find based fast hierarchical clustering
+#### `analyze_colors(data, maxColors, sortMethod)`
 
-- **Edge-Aware Processing**: Sobel/Scharr edge detection to preserve boundaries
+Analyze unique colors in an image.
 
-- **Neighbor-Coherent Assignment**: Spatial coherence through neighbor and region voting
+```javascript
+const analysis = analyze_colors(
+  rgbaData,      // Uint8Array - RGBA pixel data
+  1000,          // number - Max colors to track
+  'frequency'    // string - Sort: 'frequency', 'morton', 'hilbert'
+);
 
-- **Two-Pass Refinement**: Iterative optimization for smooth results
+if (analysis.success) {
+  console.log('Unique colors:', analysis.color_count);
+  console.log('Total pixels:', analysis.total_pixels);
+  
+  // Get individual color
+  const color = analysis.get_color(0);
+  console.log(`Most common: ${color.hex} (${color.percentage.toFixed(1)}%)`);
+  
+  // Get as JSON array
+  const colors = analysis.to_json();
+}
+```
 
-- **WebAssembly Support**: Run in browsers with full performance
+**ColorEntry Properties:**
+| Property | Type | Description |
+|----------|------|-------------|
+| `r` | `u8` | Red component (0-255) |
+| `g` | `u8` | Green component (0-255) |
+| `b` | `u8` | Blue component (0-255) |
+| `count` | `u32` | Number of pixels |
+| `percentage` | `f32` | Percentage of image |
+| `hex` | `string` | Hex color code (`#rrggbb`) |
 
-- **Performance Preprocessing**: Resolution capping and color pre-quantization
+---
 
+### Utility Functions
 
-## Installation
+#### `rgb_to_oklab(r, g, b)`
 
-### Native (Rust)
+Convert RGB to Oklab color space.
 
-Add to your `Cargo.toml`:
+```javascript
+const oklab = rgb_to_oklab(255, 128, 64);
+// Returns: Float32Array [L, a, b]
+// L: 0.0-1.0 (lightness)
+// a: ~-0.4 to 0.4 (green-red)
+// b: ~-0.4 to 0.4 (blue-yellow)
+```
 
-    [dependencies]
-    smart-downscaler = "0.3.5"
+#### `oklab_to_rgb(l, a, b)`
 
+Convert Oklab to RGB.
 
-### WebAssembly (npm)
+```javascript
+const rgb = oklab_to_rgb(0.7, 0.1, 0.05);
+// Returns: Uint8Array [r, g, b]
+```
 
-    npm install smart-downscaler
+#### `get_chroma(r, g, b)`
 
+Get color saturation/colorfulness.
 
-## Quick Start
+```javascript
+const chroma = get_chroma(255, 0, 0);  // Pure red = high chroma
+const gray_chroma = get_chroma(128, 128, 128);  // Gray = 0 chroma
+```
 
-### WebAssembly (Browser)
+#### `get_lightness(r, g, b)`
 
-    import init, { WasmDownscaleConfig, downscale_rgba } from 'smart-downscaler';
+Get perceptual lightness (0.0-1.0).
 
-    await init();
+```javascript
+const lightness = get_lightness(255, 255, 255);  // White = 1.0
+const dark = get_lightness(0, 0, 0);  // Black = 0.0
+```
 
-    // Create config
-    const config = new WasmDownscaleConfig();
+#### `color_distance(r1, g1, b1, r2, g2, b2)`
 
-    // PERFORMANCE: New Direct LUT settings
-    config.max_resolution_mp = 1.5;       // Nearest-neighbor cap (0 = disabled)
-    config.max_color_preprocess = 16384;  // Trigger LUT path if < 16k colors
+Compute perceptual distance between two colors.
 
-    // QUALITY: New K-Centroid settings
-    config.k_centroid = 2;                // 2 = Dominant Color Mode
-    config.k_centroid_iterations = 2;     // Refine the dominant color
+```javascript
+const dist = color_distance(255, 0, 0, 0, 255, 0);  // Red vs Green
+// Returns: f32 - Euclidean distance in Oklab space
+```
 
-    // Standard settings
-    config.palette_size = 16;
-    config.palette_strategy = 'oklab';
+#### `version()`
 
-    // Run
-    const result = downscale_rgba(
-      imageData.data,
-      imageData.width, imageData.height,
-      64, 64, // Target size
-      config
-    );
+Get library version.
 
-    // Draw result
-    const output = new ImageData(result.data, result.width, result.height);
-    ctx.putImageData(output, 0, 0);
+```javascript
+console.log(version());  // "0.5.0"
+```
 
+---
 
-### Configuration Presets
+### Result Object
 
-    // Speed optimized (max_resolution_mp: 1.0, max_color_preprocess: 8192)
-    const fast = WasmDownscaleConfig.fast();
+`WasmDownscaleResult` properties:
 
-    // Best quality (max_resolution_mp: 2.0, max_color_preprocess: 32768)
-    const quality = WasmDownscaleConfig.quality();
+| Property | Type | Description |
+|----------|------|-------------|
+| `width` | `u32` | Output image width |
+| `height` | `u32` | Output image height |
+| `data` | `Uint8ClampedArray` | RGBA pixel data |
+| `palette` | `Uint8Array` | RGB palette (3 bytes per color) |
+| `indices` | `Uint8Array` | Palette index per pixel |
+| `palette_size` | `usize` | Number of colors in palette |
 
-    // Preserve vibrant colors (max_resolution_mp: 1.5, max_color_preprocess: 16384)
-    const vibrant = WasmDownscaleConfig.vibrant();
+**Methods:**
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `rgb_data()` | `Uint8Array` | Get RGB data (no alpha) |
 
-    // Use only exact source colors
-    const exact = WasmDownscaleConfig.exact_colors();
+---
 
+## Presets
 
-## Why Oklab?
+### Built-in Configuration Presets
 
-Traditional RGB-based palette extraction has fundamental problems:
+```javascript
+// Speed optimized
+const fast = WasmDownscaleConfig.fast();
+// palette_size: 16, kmeans_iterations: 3, no refinement, no segmentation
 
+// Best quality
+const quality = WasmDownscaleConfig.quality();
+// palette_size: 32, kmeans_iterations: 10, hierarchy segmentation, k_centroid: 2
 
-### The Problem: RGB Averaging Desaturates Colors
+// Preserve vibrant colors
+const vibrant = WasmDownscaleConfig.vibrant();
+// palette_size: 24, saturation strategy, k_centroid: 2
 
-    Red [255, 0, 0] + Cyan [0, 255, 255] 
-      RGB Average → Gray [127, 127, 127] ❌
+// Use only exact source colors
+const exact = WasmDownscaleConfig.exact_colors();
+// medoid strategy, no k-means refinement
+```
 
-When you average colors in RGB space, saturated colors get pulled toward gray. This is why downscaled images often look "washed out" or "tanned."
+### Preset Comparison
 
+| Preset | Palette | K-Means | Segmentation | K-Centroid | Speed |
+|--------|---------|---------|--------------|------------|-------|
+| `fast()` | 16 | 3 | none | 1 (avg) | ⚡⚡⚡ |
+| `default` | 16 | 5 | hierarchy_fast | 1 (avg) | ⚡⚡ |
+| `vibrant()` | 24 | 8 | hierarchy_fast | 2 (dom) | ⚡ |
+| `quality()` | 32 | 10 | hierarchy | 2 (dom) | 🐢 |
+| `exact_colors()` | 16 | 0 | hierarchy_fast | 1 (avg) | ⚡⚡ |
 
-### The Solution: Oklab Color Space
+---
 
-Oklab is a **perceptually uniform** color space where:
+## Advanced Usage
 
-- Euclidean distance = perceived color difference
+### Custom Palette Workflow
 
-- Averaging preserves hue and saturation
+```javascript
+// 1. Extract palette from reference image
+const referencePalette = extract_palette_from_image(
+  referenceImageData, w, h, 16, 10, 'saturation'
+);
 
-- Interpolations look natural
+// 2. Apply palette to multiple images
+const results = images.map(img => 
+  downscale_with_palette(
+    img.data, img.width, img.height,
+    64, 64,
+    referencePalette,
+    config
+  )
+);
+```
+
+### Batch Processing with Progress
+
+```javascript
+async function batchDownscale(images, config, onProgress) {
+  const results = [];
+  
+  for (let i = 0; i < images.length; i++) {
+    const img = images[i];
+    const result = downscale_rgba(
+      img.data, img.width, img.height,
+      64, 64, config
+    );
+    results.push(result);
+    
+    onProgress((i + 1) / images.length * 100);
+    
+    // Allow UI to update
+    await new Promise(r => setTimeout(r, 0));
+  }
+  
+  return results;
+}
+```
 
-<!---->
+### Analyzing Before Downscaling
 
-    Red (Oklab) + Cyan (Oklab)
-      Oklab Average → Preserves colorfulness ✔
+```javascript
+// Check image characteristics first
+const analysis = analyze_colors(imageData, 10000, 'frequency');
 
+if (!analysis.success) {
+  console.log('Image has more than 10,000 unique colors');
+}
 
-## API Reference
+// Adjust config based on analysis
+const config = new WasmDownscaleConfig();
+
+if (analysis.color_count < 256) {
+  // Already low-color image - use medoid for exact colors
+  config.palette_strategy = 'medoid';
+  config.kmeans_iterations = 0;
+} else {
+  // High-color image - use saturation weighting
+  config.palette_strategy = 'saturation';
+  config.kmeans_iterations = 8;
+}
+```
+
+---
+
+## Performance Tips
+
+### 1. Use Resolution Capping
+
+For images larger than ~2MP, enable resolution capping:
+
+```javascript
+config.max_resolution_mp = 1.5;  // Cap at 1.5 megapixels
+```
+
+### 2. Enable Color Pre-quantization
 
-### WasmDownscaleConfig
+Reduces processing time significantly for high-color images:
 
-    const config = new WasmDownscaleConfig();
+```javascript
+config.max_color_preprocess = 16384;  // Pre-quantize to 16K colors
+```
 
-    // Palette settings
-    config.palette_size = 16;           // Number of output colors
-    config.palette_strategy = 'oklab';  // 'oklab', 'saturation', 'medoid', 'kmeans', 'legacy'
-    config.kmeans_iterations = 5;       // Refinement iterations
+### 3. Choose Appropriate Segmentation
 
-    // Spatial coherence
-    config.neighbor_weight = 0.3;       // [0-1] Prefer neighbor colors
-    config.region_weight = 0.2;         // [0-1] Prefer region colors
+| Image Type | Recommended Segmentation |
+|------------|-------------------------|
+| Icons, sprites | `"none"` |
+| Game art | `"hierarchy_fast"` |
+| Photos | `"slic"` |
+| Complex illustrations | `"hierarchy"` |
 
-    // Refinement
-    config.two_pass_refinement = true;
-    config.refinement_iterations = 3;
+### 4. Reduce Iterations for Speed
 
-    // Edge detection
-    config.edge_weight = 0.5;
+```javascript
+// Fast settings
+config.kmeans_iterations = 3;      // Instead of 5
+config.refinement_iterations = 1;  // Instead of 3
+config.k_centroid_iterations = 1;  // Instead of 2
+```
 
-    // Segmentation
-    config.segmentation_method = 'hierarchy_fast'; // 'none', 'slic', 'hierarchy', 'hierarchy_fast'
+### 5. Use Presets
 
-    // Performance preprocessing
-    config.max_resolution_mp = 1.5;       // Cap resolution at 1.5 megapixels (0 = disabled)
-    config.max_color_preprocess = 16384;  // Pre-quantize to 16K colors max (0 = disabled)
+```javascript
+// For real-time preview
+const previewConfig = WasmDownscaleConfig.fast();
 
-    // Tile Logic
-    config.k_centroid = 1;                // 1=Avg, 2=Dom, 3=Foremost
-    config.k_centroid_iterations = 0;     // Refine the dominant color
+// For final export
+const exportConfig = WasmDownscaleConfig.quality();
+```
 
+---
 
-### Available Functions
+## Why Oklab?
+
+### The Problem: RGB Averaging
+
+When averaging colors in RGB space, saturated colors become desaturated:
 
-| Function                                                           | Description                 |
-| ------------------------------------------------------------------ | --------------------------- |
-| `downscale(data, w, h, tw, th, config?)`                           | Main downscale function     |
-| `downscale_rgba(data, w, h, tw, th, config?)`                      | For Uint8ClampedArray input |
-| `downscale_simple(data, w, h, tw, th, colors)`                     | Simple API                  |
-| `downscale_with_palette(...)`                                      | Use custom palette          |
-| `extract_palette_from_image(data, w, h, colors, iters, strategy?)` | Extract palette only        |
-| `quantize_to_palette(data, w, h, palette)`                         | Quantize without resizing   |
-| `get_palette_strategies()`                                         | List available strategies   |
+```
+Red   [255,   0,   0]
+Cyan  [  0, 255, 255]
+─────────────────────
+RGB Average → Gray [127, 127, 127] ❌
+```
 
+This is why traditional downscalers produce "washed out" results.
+
+### The Solution: Oklab Color Space
 
-### WasmDownscaleResult
+Oklab is a **perceptually uniform** color space where:
 
-    result.width          // Output width
-    result.height         // Output height  
-    result.data           // Uint8ClampedArray (RGBA)
-    result.rgb_data()     // Uint8Array (RGB only)
-    result.palette        // Uint8Array (RGB, 3 bytes per color)
-    result.indices        // Uint8Array (palette index per pixel)
-    result.palette_size   // Number of colors
+- Euclidean distance = perceived color difference
+- Averaging preserves hue and saturation
+- Interpolations look natural
 
+```
+Red  (Oklab)  L=0.63, a=0.22, b=0.13
+Cyan (Oklab)  L=0.91, a=-0.15, b=-0.09
+─────────────────────────────────────
+Oklab Average → Preserves colorfulness ✓
+```
+
+### Visual Comparison
+
+| Method | Result | Issue |
+|--------|--------|-------|
+| RGB Average | Muddy grays | Desaturation |
+| Lab Average | Better, some hue shift | Non-uniform |
+| **Oklab Average** | Vibrant, natural | ✓ Best |
+
+---
+
+## CLI Reference
+
+```bash
+# Basic usage
+smart-downscaler input.png output.png -w 64 -h 64
+
+# With palette size
+smart-downscaler input.png output.png -w 64 -h 64 -c 16
+
+# Quality preset
+smart-downscaler input.png output.png -w 64 -h 64 --preset quality
+
+# Custom configuration
+smart-downscaler input.png output.png \
+  --width 64 \
+  --height 64 \
+  --colors 24 \
+  --strategy saturation \
+  --segmentation hierarchy_fast \
+  --k-centroid 2 \
+  --k-centroid-iterations 2
+
+# Fast mode (no refinement)
+smart-downscaler input.png output.png -w 64 -h 64 \
+  --segmentation none \
+  --no-refinement
+
+# Extract palette only
+smart-downscaler input.png --extract-palette palette.hex -c 16
+```
+
+### CLI Options
+
+| Option | Short | Default | Description |
+|--------|-------|---------|-------------|
+| `--width` | `-w` | *required* | Target width |
+| `--height` | `-h` | *required* | Target height |
+| `--colors` | `-c` | `16` | Palette size |
+| `--strategy` | `-s` | `oklab` | Palette strategy |
+| `--segmentation` | | `hierarchy_fast` | Segmentation method |
+| `--k-centroid` | | `1` | Tile color mode |
+| `--k-centroid-iterations` | | `0` | Tile refinement |
+| `--no-refinement` | | false | Disable two-pass |
+| `--preset` | `-p` | | Use preset (fast/quality/vibrant) |
+| `--extract-palette` | | | Output palette only |
+
+---
 
 ## License
 
-MIT
+MIT License
 
+---
 
 ## Credits
 
-- Oklab color space by Björn Ottosson
-
-- SLIC superpixel algorithm
+- **Oklab color space** by Björn Ottosson
+- **SLIC superpixels** algorithm
+- **K-Means++** initialization
+- **VTracer** hierarchical clustering approach
 
-- K-Means++ initialization
+---
 
-- VTracer hierarchical clustering approach
+## Links
 
+- [GitHub Repository](https://github.com/user/smart-downscaler)
+- [npm Package](https://www.npmjs.com/package/smart-downscaler)
+- [Crates.io](https://crates.io/crates/smart-downscaler)
+- [API Documentation](https://docs.rs/smart-downscaler)

package/package.json

@@ -5,7 +5,7 @@
     "Pixagram"
   ],
   "description": "Intelligent pixel art downscaler with region-aware color quantization",
-  "version": "0.4.5",
+  "version": "0.6.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/smart_downscaler.d.ts

@@ -1,34 +1,18 @@
 /* tslint:disable */
 /* eslint-disable */
 
-/**
- * Result of color analysis
- */
 export class ColorAnalysisResult {
     private constructor();
     free(): void;
     [Symbol.dispose](): void;
-    /**
-     * Get color at index
-     */
     get_color(index: number): ColorEntry | undefined;
-    /**
-     * Get all colors as a flat array: [r, g, b, count(4 bytes), percentage(4 bytes), ...]
-     * Each color is 11 bytes
-     */
     get_colors_flat(): Uint8Array;
-    /**
-     * Get colors as JSON-compatible array
-     */
     to_json(): any;
     readonly color_count: number;
     readonly success: boolean;
     readonly total_pixels: number;
 }
 
-/**
- * A single color entry with statistics
- */
 export class ColorEntry {
     private constructor();
     free(): void;
@@ -52,13 +36,7 @@ export class WasmDownscaleConfig {
     edge_weight: number;
     hierarchy_min_size: number;
     hierarchy_threshold: number;
-    /**
-     * Iterations for tile centroid
-     */
     k_centroid_iterations: number;
-    /**
-     * K-Means centroid mode (1=Avg, 2=Dom, 3=Foremost)
-     */
     k_centroid: number;
     kmeans_iterations: number;
     max_color_preprocess: number;
@@ -88,78 +66,39 @@ export class WasmDownscaleResult {
 }
 
 /**
- * Analyze colors in an image
- *
- * # Arguments
- * * `image_data` - RGBA pixel data
- * * `max_colors` - Maximum number of unique colors to track (stops if exceeded)
- * * `sort_method` - Sorting method: "frequency", "morton", or "hilbert"
- *
- * # Returns
- * ColorAnalysisResult with array of colors (r, g, b, count, percentage, hex)
- * If unique colors exceed max_colors, returns early with success=false
+ * Analyze colors — FIX: uses HashMap<u32, usize> for O(1) lookup (was O(n) linear scan)
  */
 export function analyze_colors(image_data: Uint8Array, max_colors: number, sort_method: string): ColorAnalysisResult;
 
-/**
- * Compute perceptual color distance between two RGB colors
- */
 export function color_distance(r1: number, g1: number, b1: number, r2: number, g2: number, b2: number): number;
 
 export function downscale(image_data: Uint8Array, width: number, height: number, target_width: number, target_height: number, config?: WasmDownscaleConfig | null): WasmDownscaleResult;
 
 export function downscale_rgba(image_data: Uint8ClampedArray, width: number, height: number, target_width: number, target_height: number, config?: WasmDownscaleConfig | null): WasmDownscaleResult;
 
-/**
- * Simple downscale function with minimal parameters
- */
 export function downscale_simple(image_data: Uint8Array, width: number, height: number, target_width: number, target_height: number, num_colors: number): WasmDownscaleResult;
 
 export function downscale_with_palette(image_data: Uint8Array, width: number, height: number, target_width: number, target_height: number, palette_data: Uint8Array, config?: WasmDownscaleConfig | null): WasmDownscaleResult;
 
-/**
- * Extract a color palette from an image without downscaling
- */
 export function extract_palette_from_image(image_data: Uint8Array, _width: number, _height: number, num_colors: number, kmeans_iterations: number, strategy?: string | null): Uint8Array;
 
-/**
- * Get chroma (saturation) of an RGB color
- */
 export function get_chroma(r: number, g: number, b: number): number;
 
-/**
- * Get lightness of an RGB color in Oklab space
- */
 export function get_lightness(r: number, g: number, b: number): number;
 
-/**
- * Get available palette strategies
- */
 export function get_palette_strategies(): Array<any>;
 
 export function init(): void;
 
-/**
- * Log a message to the browser console (for debugging)
- */
 export function log(message: string): void;
 
-/**
- * Convert Oklab to RGB (utility function for JS)
- */
 export function oklab_to_rgb(l: number, a: number, b: number): Uint8Array;
 
 /**
- * Quantize an image to a specific palette without resizing
+ * Quantize to palette — FIX: compute Oklab once per pixel (was twice)
  */
 export function quantize_to_palette(image_data: Uint8Array, width: number, height: number, palette_data: Uint8Array): WasmDownscaleResult;
 
-/**
- * Convert RGB to Oklab (utility function for JS)
- */
 export function rgb_to_oklab(r: number, g: number, b: number): Float32Array;
 
-/**
- * Get library version
- */
 export function version(): string;

package/smart_downscaler_bg.js

@@ -1,6 +1,3 @@
-/**
- * Result of color analysis
- */
 export class ColorAnalysisResult {
     static __wrap(ptr) {
         ptr = ptr >>> 0;
@@ -27,7 +24,6 @@ export class ColorAnalysisResult {
         return ret >>> 0;
     }
     /**
-     * Get color at index
      * @param {number} index
      * @returns {ColorEntry | undefined}
      */
@@ -36,8 +32,6 @@ export class ColorAnalysisResult {
         return ret === 0 ? undefined : ColorEntry.__wrap(ret);
     }
     /**
-     * Get all colors as a flat array: [r, g, b, count(4 bytes), percentage(4 bytes), ...]
-     * Each color is 11 bytes
      * @returns {Uint8Array}
      */
     get_colors_flat() {
@@ -52,7 +46,6 @@ export class ColorAnalysisResult {
         return ret !== 0;
     }
     /**
-     * Get colors as JSON-compatible array
      * @returns {any}
      */
     to_json() {
@@ -72,9 +65,6 @@ export class ColorAnalysisResult {
 }
 if (Symbol.dispose) ColorAnalysisResult.prototype[Symbol.dispose] = ColorAnalysisResult.prototype.free;
 
-/**
- * A single color entry with statistics
- */
 export class ColorEntry {
     static __wrap(ptr) {
         ptr = ptr >>> 0;
@@ -186,7 +176,6 @@ export class WasmDownscaleConfig {
         return ret;
     }
     /**
-     * Iterations for tile centroid
      * @returns {number}
      */
     get k_centroid_iterations() {
@@ -194,7 +183,6 @@ export class WasmDownscaleConfig {
         return ret >>> 0;
     }
     /**
-     * K-Means centroid mode (1=Avg, 2=Dom, 3=Foremost)
      * @returns {number}
      */
     get k_centroid() {
@@ -290,14 +278,12 @@ export class WasmDownscaleConfig {
         wasm.__wbg_set_wasmdownscaleconfig_hierarchy_threshold(this.__wbg_ptr, arg0);
     }
     /**
-     * Iterations for tile centroid
      * @param {number} arg0
      */
     set k_centroid_iterations(arg0) {
         wasm.__wbg_set_wasmdownscaleconfig_k_centroid_iterations(this.__wbg_ptr, arg0);
     }
     /**
-     * K-Means centroid mode (1=Avg, 2=Dom, 3=Foremost)
      * @param {number} arg0
      */
     set k_centroid(arg0) {
@@ -517,16 +503,7 @@ export class WasmDownscaleResult {
 if (Symbol.dispose) WasmDownscaleResult.prototype[Symbol.dispose] = WasmDownscaleResult.prototype.free;
 
 /**
- * Analyze colors in an image
- *
- * # Arguments
- * * `image_data` - RGBA pixel data
- * * `max_colors` - Maximum number of unique colors to track (stops if exceeded)
- * * `sort_method` - Sorting method: "frequency", "morton", or "hilbert"
- *
- * # Returns
- * ColorAnalysisResult with array of colors (r, g, b, count, percentage, hex)
- * If unique colors exceed max_colors, returns early with success=false
+ * Analyze colors — FIX: uses HashMap<u32, usize> for O(1) lookup (was O(n) linear scan)
  * @param {Uint8Array} image_data
  * @param {number} max_colors
  * @param {string} sort_method
@@ -543,7 +520,6 @@ export function analyze_colors(image_data, max_colors, sort_method) {
 }
 
 /**
- * Compute perceptual color distance between two RGB colors
  * @param {number} r1
  * @param {number} g1
  * @param {number} b1
@@ -602,7 +578,6 @@ export function downscale_rgba(image_data, width, height, target_width, target_h
 }
 
 /**
- * Simple downscale function with minimal parameters
  * @param {Uint8Array} image_data
  * @param {number} width
  * @param {number} height
@@ -643,7 +618,6 @@ export function downscale_with_palette(image_data, width, height, target_width,
 }
 
 /**
- * Extract a color palette from an image without downscaling
  * @param {Uint8Array} image_data
  * @param {number} _width
  * @param {number} _height
@@ -663,7 +637,6 @@ export function extract_palette_from_image(image_data, _width, _height, num_colo
 }
 
 /**
- * Get chroma (saturation) of an RGB color
  * @param {number} r
  * @param {number} g
  * @param {number} b
@@ -675,7 +648,6 @@ export function get_chroma(r, g, b) {
 }
 
 /**
- * Get lightness of an RGB color in Oklab space
  * @param {number} r
  * @param {number} g
  * @param {number} b
@@ -687,7 +659,6 @@ export function get_lightness(r, g, b) {
 }
 
 /**
- * Get available palette strategies
  * @returns {Array<any>}
  */
 export function get_palette_strategies() {
@@ -700,7 +671,6 @@ export function init() {
 }
 
 /**
- * Log a message to the browser console (for debugging)
  * @param {string} message
  */
 export function log(message) {
@@ -710,7 +680,6 @@ export function log(message) {
 }
 
 /**
- * Convert Oklab to RGB (utility function for JS)
  * @param {number} l
  * @param {number} a
  * @param {number} b
@@ -722,7 +691,7 @@ export function oklab_to_rgb(l, a, b) {
 }
 
 /**
- * Quantize an image to a specific palette without resizing
+ * Quantize to palette — FIX: compute Oklab once per pixel (was twice)
  * @param {Uint8Array} image_data
  * @param {number} width
  * @param {number} height
@@ -738,7 +707,6 @@ export function quantize_to_palette(image_data, width, height, palette_data) {
 }
 
 /**
- * Convert RGB to Oklab (utility function for JS)
  * @param {number} r
  * @param {number} g
  * @param {number} b
@@ -750,7 +718,6 @@ export function rgb_to_oklab(r, g, b) {
 }
 
 /**
- * Get library version
  * @returns {string}
  */
 export function version() {