k-centroid-scaler 1.1.0 → 1.2.0

package/README.md

@@ -1,22 +1,47 @@
-# K-Centroid Image Scaler - WebAssembly Module
+# K-Centroid Image Scaler & Color Quantizer - WebAssembly Module
 
-A Rust/WebAssembly implementation of the K-Centroid image downscaling algorithm, converted from the original Lua/Aseprite script.
+A Rust/WebAssembly implementation of the K-Centroid image downscaling algorithm and advanced color quantization tools, converted from the original Lua/Aseprite script.
 
-## Algorithm Overview
+## Features
+
+### 1. K-Centroid Image Scaling
+Intelligent downscaling using K-means clustering on image tiles to preserve important colors.
+
+### 2. Color Quantization
+Two high-quality algorithms for reducing color palettes:
+- **Median Cut**: Best quality, ideal for photographs and complex images
+- **K-Means**: Faster processing, great for graphics and illustrations
 
-The K-Centroid scaler uses K-means clustering to intelligently downscale images:
+### 3. Color Analysis with Spatial Sorting
+Advanced color analysis with multiple sorting algorithms:
+- **Z-Order (Morton)**: Groups similar colors using space-filling curves
+- **Hilbert Curve**: Superior locality preservation for color relationships
+- **Hue-based**: Sort by color wheel position
+- **Luminance**: Sort by brightness
+- **Frequency**: Sort by usage percentage
 
+### 4. Dominant Color Extraction
+Automatically identifies and quantizes dominant colors with configurable minimum coverage thresholds.
+
+### 5. Palette Extraction
+Extract dominant colors from any image for analysis or design purposes.
+
+## Algorithm Overview
+
+### K-Centroid Scaling
 1. **Tile Division**: The image is divided into tiles based on the target dimensions
 2. **K-Means Clustering**: Each tile undergoes K-means clustering to identify dominant colors
 3. **Color Selection**: The most dominant color (centroid with most pixels) represents each tile
 4. **Downscaling**: Each pixel in the output image uses the dominant color from its corresponding tile
 
-This approach preserves important color information better than simple averaging, making it ideal for pixel art and images where color fidelity is important.
+### Color Quantization
+- **Median Cut**: Recursively divides the color space to find optimal palette
+- **K-Means**: Clusters similar colors together for palette reduction
+- **Floyd-Steinberg Dithering**: Optional error diffusion for smoother gradients
 
 ## Module Interface
 
-### Main Function
-
+### K-Centroid Resize
 ```rust
 k_centroid_resize(
     image_data: &[u8],      // RGBA image buffer
@@ -29,110 +54,271 @@ k_centroid_resize(
 ) -> ImageResult
 ```
 
-### Return Value
-
-```javascript
-{
-    data: Uint8Array,    // RGBA pixel data
-    width: number,       // Output width
-    height: number       // Output height
-}
+### Color Quantization (Median Cut)
+```rust
+quantize_colors_median_cut(
+    image_data: &[u8],      // RGBA image buffer
+    width: u32,             // Image width
+    height: u32,            // Image height
+    num_colors: u32,        // Target color count (2-256)
+    dithering: bool,        // Apply Floyd-Steinberg dithering
+) -> ImageResult
 ```
 
-## Build Instructions
-
-### Prerequisites
+### Color Quantization (K-Means)
+```rust
+quantize_colors_kmeans(
+    image_data: &[u8],      // RGBA image buffer
+    width: u32,             // Image width
+    height: u32,            // Image height
+    num_colors: u32,        // Target color count (2-256)
+    iterations: u32,        // K-means iterations
+    dithering: bool,        // Apply Floyd-Steinberg dithering
+) -> ImageResult
+```
 
-- Rust toolchain (`curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`)
-- wasm-pack (`curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh`)
+### Palette Extraction
+```rust
+extract_palette(
+    image_data: &[u8],      // RGBA image buffer
+    max_colors: u32,        // Maximum colors to extract
+) -> ColorPalette
+```
 
-### Building
+### Color Analysis with Sorting
+```rust
+analyze_colors(
+    image_data: &[u8],      // RGBA image buffer
+    max_colors: u32,        // Maximum colors to return (capped at 256)
+    sort_method: &str,      // Sorting algorithm
+) -> ColorAnalysis
+```
 
-```bash
-# Make the build script executable
-chmod +x build.sh
+**Sort Methods:**
+- `"z-order"` or `"morton"`: Space-filling curve for color grouping
+- `"hilbert"`: Hilbert curve for better locality preservation
+- `"hue"`: Sort by hue value (color wheel position)
+- `"luminance"` or `"brightness"`: Sort by perceived brightness
+- `"frequency"`: Sort by usage percentage (most to least common)
 
-# Run the build script
-./build.sh
+**Return Structure:**
+```javascript
+{
+    colors: [{
+        hex: string,        // "#RRGGBB" format
+        percentage: number, // % of image (0-100)
+        count: number,      // Pixel count
+        r: number,          // Red (0-255)
+        g: number,          // Green (0-255)
+        b: number           // Blue (0-255)
+    }],
+    totalColors: number,    // Unique colors found
+    totalPixels: number     // Pixels analyzed
+}
+```
 
-# Or manually:
-wasm-pack build --target web --out-dir pkg
+### Dominant Colors with Auto-Quantization
+```rust
+get_dominant_colors(
+    image_data: &[u8],      // RGBA image buffer
+    num_colors: u32,        // Target dominant colors
+    min_coverage: f32,      // Minimum % coverage threshold
+) -> ColorAnalysis
 ```
 
-## Usage Example
+## Usage Examples
 
+### Basic Color Quantization
 ```javascript
-import init, { process_image } from './pkg/k_centroid_scaler.js';
+import init, { quantize_colors_median_cut } from './pkg/k_centroid_scaler.js';
 
-async function downscaleImage() {
-    // Initialize the WASM module
+async function reduceColors() {
     await init();
     
-    // Get your image data (e.g., from a canvas)
-    const canvas = document.getElementById('myCanvas');
+    // Get image data
+    const canvas = document.getElementById('canvas');
     const ctx = canvas.getContext('2d');
     const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);
     
-    // Process the image
-    const result = process_image(
+    // Reduce to 16 colors with dithering
+    const result = quantize_colors_median_cut(
         imageData.data,
         canvas.width,
         canvas.height,
-        Math.floor(canvas.width / 2),   // Half size
-        Math.floor(canvas.height / 2),
-        4,  // 4 centroids per tile
-        5   // 5 iterations
+        16,     // 16 colors
+        true    // Enable dithering
     );
     
-    // Use the result
+    // Display result
     const outputImageData = new ImageData(
         new Uint8ClampedArray(result.data),
         result.width,
         result.height
     );
+    ctx.putImageData(outputImageData, 0, 0);
+}
+```
+
+### Complete Processing Pipeline
+```javascript
+async function processImage(imageData, width, height) {
+    // Step 1: Downscale
+    const scaled = await downscaleImage(
+        imageData, width, height,
+        width / 2, height / 2,
+        { centroids: 4, iterations: 5 }
+    );
+    
+    // Step 2: Quantize colors
+    const quantized = await quantizeColorsMedianCut(
+        scaled.data,
+        scaled.width,
+        scaled.height,
+        { numColors: 8, dithering: true }
+    );
+    
+    return quantized;
+}
+```
+
+### Extract Color Palette
+```javascript
+async function getPalette(imageData) {
+    const palette = await extractColorPalette(imageData, 16);
+    console.log(`Found ${palette.count} colors:`, palette.colors);
+    // Returns array of {r, g, b} objects
+}
+```
+
+### Analyze Colors with Z-Order Sorting
+```javascript
+async function analyzeColors(imageData) {
+    const { analyze_colors } = await init();
+    
+    // Get up to 256 colors sorted by Z-order (groups similar colors)
+    const analysis = analyze_colors(imageData, 256, 'z-order');
+    
+    // Access color information
+    analysis.colors.forEach(color => {
+        console.log(`${color.hex}: ${color.percentage.toFixed(2)}% (${color.count} pixels)`);
+    });
     
-    // Draw to output canvas
-    const outputCanvas = document.getElementById('output');
-    const outputCtx = outputCanvas.getContext('2d');
-    outputCanvas.width = result.width;
-    outputCanvas.height = result.height;
-    outputCtx.putImageData(outputImageData, 0, 0);
+    // Generate CSS variables
+    const cssVars = analysis.colors
+        .slice(0, 10)  // Top 10 colors
+        .map((c, i) => `--color-${i+1}: ${c.hex};`)
+        .join('\n');
 }
 ```
 
-## Parameters Guide
+### Get Dominant Colors
+```javascript
+async function getDominantPalette(imageData) {
+    const { get_dominant_colors } = await init();
+    
+    // Get 16 dominant colors, ignoring colors below 0.1% coverage
+    const dominant = get_dominant_colors(imageData, 16, 0.1);
+    
+    // Create HTML palette display
+    const paletteHTML = dominant.colors
+        .map(c => `
+            <div style="display: inline-block;">
+                <div style="width: 50px; height: 50px; background: ${c.hex};"></div>
+                <small>${c.percentage.toFixed(1)}%</small>
+            </div>
+        `)
+        .join('');
+}
+```
 
-### `centroids` (2-16)
-- **Lower values (2-4)**: Stronger color quantization, more stylized results
-- **Higher values (8-16)**: Better color preservation, closer to original
+### Export Color Analysis Results
+```javascript
+// Export as JSON
+const colorData = {
+    palette: analysis.colors.map(c => ({
+        hex: c.hex,
+        rgb: [c.r, c.g, c.b],
+        usage: c.percentage
+    }))
+};
 
-### `iterations` (1-20)
-- **Lower values (1-3)**: Faster processing, less accurate clustering
-- **Higher values (10-20)**: More accurate color selection, slower processing
+// Export as CSS custom properties
+const css = `:root {
+${analysis.colors.slice(0, 20).map((c, i) => 
+    `  --palette-${i}: ${c.hex}; /* ${c.percentage.toFixed(1)}% */`
+).join('\n')}
+}`;
 
-## Behavior Notes
+// Export as SCSS/Sass variables
+const scss = analysis.colors.slice(0, 20)
+    .map((c, i) => `$color-${i}: ${c.hex};`)
+    .join('\n');
+```
 
-1. **Deterministic Results**: Uses a fixed random seed (1) for consistent K-means initialization
-2. **Dominant Color Selection**: Always selects the centroid with the most assigned pixels
-3. **Tile Processing**: Each tile is processed independently, maintaining local color characteristics
-4. **Edge Handling**: Properly handles edge tiles that may be smaller than the standard tile size
+## Parameter Guidelines
 
-## Performance Considerations
+### Quantization Method Selection
+- **Median Cut**: Use for photographs, natural images, gradients
+- **K-Means**: Use for graphics, logos, illustrations with flat colors
 
-- **Complexity**: O(n × k × i) where n = pixels per tile, k = centroids, i = iterations
-- **Memory**: Lightweight, processes tiles individually
-- **WebAssembly Optimizations**: 
-  - Compiled with size optimizations (`opt-level = "z"`)
-  - Link-time optimization enabled
-  - Optional wasm-opt post-processing
+### `num_colors` (2-256)
+- **2-4**: Extreme stylization, poster effect
+- **8-16**: Retro gaming aesthetic
+- **32-64**: Good balance of quality and compression
+- **128-256**: Near-original quality with reduced file size
 
-## Differences from Original Lua Version
+### `dithering` (true/false)
+- **Enable**: For smooth gradients and photographs
+- **Disable**: For pixel art or when crisp edges are needed
 
-1. **Output**: Returns only the downscaled image (not the intermediate K-tiles visualization)
-2. **Language**: Rust provides better performance and type safety
-3. **Platform**: Runs in browsers via WebAssembly instead of Aseprite
-4. **Interface**: Direct buffer manipulation instead of Aseprite API calls
+### `iterations` (K-Means only, 1-50)
+- **5-10**: Fast processing, good results
+- **20-30**: Better color accuracy
+- **40-50**: Maximum quality, slower processing
 
-## License
+## Performance Optimizations
 
-Converted to Rust/WebAssembly for web usage. Original algorithm from Aseprite Lua script.
+### Algorithm Complexity
+- **Median Cut**: O(n log n) where n = unique colors
+- **K-Means**: O(n × k × i) where n = pixels, k = colors, i = iterations
+- **Dithering**: O(w × h) single pass through image
+
+### WebAssembly Optimizations
+- K-means++ initialization for better convergence
+- Weighted color averaging based on pixel frequency
+- Efficient color distance calculations
+- Floyd-Steinberg dithering with minimal memory overhead
+
+## Build Instructions
+
+### Prerequisites
+- Rust toolchain (`curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`)
+- wasm-pack (`curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh`)
+
+### Building
+```bash
+chmod +x build.sh
+./build.sh
+```
+
+## Comparison: Quantization Methods
+
+| Method | Best For | Speed | Quality | Dithering Support |
+|--------|----------|-------|---------|-------------------|
+| Median Cut | Photos, gradients | Medium | Excellent | Yes |
+| K-Means | Graphics, logos | Fast | Very Good | Yes |
+| K-Centroid Resize | Downscaling | Fast | Good | No |
+
+## Advanced Features
+
+### Custom Initialization
+The K-means algorithm uses K-means++ initialization for optimal starting centroids, ensuring better convergence and more consistent results.
+
+### Weighted Clustering
+Colors are weighted by their frequency in the image, ensuring common colors are better represented in the final palette.
+
+### Error Diffusion
+Floyd-Steinberg dithering distributes quantization errors to neighboring pixels, creating smoother gradients with limited colors.
+
+## License
+Converted to Rust/WebAssembly for web usage. Original K-Centroid algorithm from Aseprite Lua script.

package/k_centroid_scaler.js

@@ -200,6 +200,16 @@ function takeObject(idx) {
     return ret;
 }
 
+function getArrayJsValueFromWasm0(ptr, len) {
+    ptr = ptr >>> 0;
+    const mem = getDataViewMemory0();
+    const result = [];
+    for (let i = ptr; i < ptr + 4 * len; i += 4) {
+        result.push(takeObject(mem.getUint32(i, true)));
+    }
+    return result;
+}
+
 function passArray8ToWasm0(arg, malloc) {
     const ptr = malloc(arg.length * 1, 1) >>> 0;
     getUint8ArrayMemory0().set(arg, ptr / 1);
@@ -266,6 +276,34 @@ export function extract_palette(image_data, max_colors) {
     return ColorPalette.__wrap(ret);
 }
 
+/**
+ * @param {Uint8Array} image_data
+ * @param {number} max_colors
+ * @param {string} sort_method
+ * @returns {ColorAnalysis}
+ */
+export function analyze_colors(image_data, max_colors, sort_method) {
+    const ptr0 = passArray8ToWasm0(image_data, wasm.__wbindgen_export_1);
+    const len0 = WASM_VECTOR_LEN;
+    const ptr1 = passStringToWasm0(sort_method, wasm.__wbindgen_export_1, wasm.__wbindgen_export_2);
+    const len1 = WASM_VECTOR_LEN;
+    const ret = wasm.analyze_colors(ptr0, len0, max_colors, ptr1, len1);
+    return ColorAnalysis.__wrap(ret);
+}
+
+/**
+ * @param {Uint8Array} image_data
+ * @param {number} num_colors
+ * @param {number} min_coverage
+ * @returns {ColorAnalysis}
+ */
+export function get_dominant_colors(image_data, num_colors, min_coverage) {
+    const ptr0 = passArray8ToWasm0(image_data, wasm.__wbindgen_export_1);
+    const len0 = WASM_VECTOR_LEN;
+    const ret = wasm.get_dominant_colors(ptr0, len0, num_colors, min_coverage);
+    return ColorAnalysis.__wrap(ret);
+}
+
 /**
  * @param {Uint8Array} data
  * @param {number} width
@@ -283,6 +321,150 @@ export function process_image(data, width, height, target_width, target_height,
     return takeObject(ret);
 }
 
+const ColorAnalysisFinalization = (typeof FinalizationRegistry === 'undefined')
+    ? { register: () => {}, unregister: () => {} }
+    : new FinalizationRegistry(ptr => wasm.__wbg_coloranalysis_free(ptr >>> 0, 1));
+
+export class ColorAnalysis {
+
+    static __wrap(ptr) {
+        ptr = ptr >>> 0;
+        const obj = Object.create(ColorAnalysis.prototype);
+        obj.__wbg_ptr = ptr;
+        ColorAnalysisFinalization.register(obj, obj.__wbg_ptr, obj);
+        return obj;
+    }
+
+    __destroy_into_raw() {
+        const ptr = this.__wbg_ptr;
+        this.__wbg_ptr = 0;
+        ColorAnalysisFinalization.unregister(this);
+        return ptr;
+    }
+
+    free() {
+        const ptr = this.__destroy_into_raw();
+        wasm.__wbg_coloranalysis_free(ptr, 0);
+    }
+    /**
+     * @returns {number}
+     */
+    get total_colors() {
+        const ret = wasm.__wbg_get_coloranalysis_total_colors(this.__wbg_ptr);
+        return ret >>> 0;
+    }
+    /**
+     * @param {number} arg0
+     */
+    set total_colors(arg0) {
+        wasm.__wbg_set_coloranalysis_total_colors(this.__wbg_ptr, arg0);
+    }
+    /**
+     * @returns {number}
+     */
+    get total_pixels() {
+        const ret = wasm.__wbg_get_coloranalysis_total_pixels(this.__wbg_ptr);
+        return ret >>> 0;
+    }
+    /**
+     * @param {number} arg0
+     */
+    set total_pixels(arg0) {
+        wasm.__wbg_set_coloranalysis_total_pixels(this.__wbg_ptr, arg0);
+    }
+    /**
+     * @returns {any[]}
+     */
+    get colors() {
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            wasm.coloranalysis_colors(retptr, this.__wbg_ptr);
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            var v1 = getArrayJsValueFromWasm0(r0, r1).slice();
+            wasm.__wbindgen_export_3(r0, r1 * 4, 4);
+            return v1;
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+        }
+    }
+}
+if (Symbol.dispose) ColorAnalysis.prototype[Symbol.dispose] = ColorAnalysis.prototype.free;
+
+const ColorInfoFinalization = (typeof FinalizationRegistry === 'undefined')
+    ? { register: () => {}, unregister: () => {} }
+    : new FinalizationRegistry(ptr => wasm.__wbg_colorinfo_free(ptr >>> 0, 1));
+
+export class ColorInfo {
+
+    __destroy_into_raw() {
+        const ptr = this.__wbg_ptr;
+        this.__wbg_ptr = 0;
+        ColorInfoFinalization.unregister(this);
+        return ptr;
+    }
+
+    free() {
+        const ptr = this.__destroy_into_raw();
+        wasm.__wbg_colorinfo_free(ptr, 0);
+    }
+    /**
+     * @returns {string}
+     */
+    get hex() {
+        let deferred1_0;
+        let deferred1_1;
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            wasm.colorinfo_hex(retptr, this.__wbg_ptr);
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            deferred1_0 = r0;
+            deferred1_1 = r1;
+            return getStringFromWasm0(r0, r1);
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+            wasm.__wbindgen_export_3(deferred1_0, deferred1_1, 1);
+        }
+    }
+    /**
+     * @returns {number}
+     */
+    get percentage() {
+        const ret = wasm.colorinfo_percentage(this.__wbg_ptr);
+        return ret;
+    }
+    /**
+     * @returns {number}
+     */
+    get count() {
+        const ret = wasm.colorinfo_count(this.__wbg_ptr);
+        return ret >>> 0;
+    }
+    /**
+     * @returns {number}
+     */
+    get r() {
+        const ret = wasm.colorinfo_r(this.__wbg_ptr);
+        return ret;
+    }
+    /**
+     * @returns {number}
+     */
+    get g() {
+        const ret = wasm.colorinfo_g(this.__wbg_ptr);
+        return ret;
+    }
+    /**
+     * @returns {number}
+     */
+    get b() {
+        const ret = wasm.colorinfo_b(this.__wbg_ptr);
+        return ret;
+    }
+}
+if (Symbol.dispose) ColorInfo.prototype[Symbol.dispose] = ColorInfo.prototype.free;
+
 const ColorPaletteFinalization = (typeof FinalizationRegistry === 'undefined')
     ? { register: () => {}, unregister: () => {} }
     : new FinalizationRegistry(ptr => wasm.__wbg_colorpalette_free(ptr >>> 0, 1));
@@ -312,7 +494,7 @@ export class ColorPalette {
      * @returns {number}
      */
     get count() {
-        const ret = wasm.__wbg_get_colorpalette_count(this.__wbg_ptr);
+        const ret = wasm.__wbg_get_coloranalysis_total_colors(this.__wbg_ptr);
         return ret >>> 0;
     }
     /**
@@ -369,27 +551,27 @@ export class ImageResult {
      * @returns {number}
      */
     get width() {
-        const ret = wasm.__wbg_get_colorpalette_count(this.__wbg_ptr);
+        const ret = wasm.__wbg_get_coloranalysis_total_colors(this.__wbg_ptr);
         return ret >>> 0;
     }
     /**
      * @param {number} arg0
      */
     set width(arg0) {
-        wasm.__wbg_set_imageresult_width(this.__wbg_ptr, arg0);
+        wasm.__wbg_set_coloranalysis_total_colors(this.__wbg_ptr, arg0);
     }
     /**
      * @returns {number}
      */
     get height() {
-        const ret = wasm.__wbg_get_imageresult_height(this.__wbg_ptr);
+        const ret = wasm.__wbg_get_coloranalysis_total_pixels(this.__wbg_ptr);
         return ret >>> 0;
     }
     /**
      * @param {number} arg0
      */
     set height(arg0) {
-        wasm.__wbg_set_imageresult_height(this.__wbg_ptr, arg0);
+        wasm.__wbg_set_coloranalysis_total_pixels(this.__wbg_ptr, arg0);
     }
     /**
      * @returns {Uint8Array}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "k-centroid-scaler",
   "type": "module",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "files": [
     "k_centroid_scaler_bg.wasm",
     "k_centroid_scaler.js"