smart-downscaler 0.3.4 → 0.3.5

package/README.md

@@ -1,453 +1,264 @@
 # Smart Pixel Art Downscaler
 
-A sophisticated Rust library for intelligent image downscaling with focus on pixel art quality. Combines global palette extraction, region-aware segmentation, and iterative refinement for optimal results.
+A sophisticated Rust library for intelligent image downscaling with focus on pixel art quality.
 
 **Available as both a native Rust library and a WebAssembly module for browser/Node.js usage.**
 
-## What's New in v0.3
 
-### ⚡ Performance Optimizations
+## What's New in v0.3.5
 
-Version 0.3 introduces **preprocessing optimizations** for large images, providing 2-10x speedup while maintaining 80%+ visual quality:
+### ⚡ Performance: Direct LUT Optimization
 
-| Feature | Default | Description |
-|---------|---------|-------------|
-| `max_resolution_mp` | 1.5 | Cap input at 1.5 megapixels (0 = disabled) |
-| `max_color_preprocess` | 16384 | Pre-quantize to 16K unique colors max (0 = disabled) |
+The preprocessing pipeline has been completely rewritten for speed:
 
-```javascript
-const config = new WasmDownscaleConfig();
-config.max_resolution_mp = 1.5;       // Cap at 1.5 megapixels (0 = disabled)
-config.max_color_preprocess = 16384;  // Pre-quantize to 16K colors (0 = disabled)
-```
+| 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      |
 
-### Optimization Strategies
+**Key Optimizations:**
 
-1. **Resolution Capping**: Images larger than `max_resolution_mp` are downscaled using fast nearest-neighbor interpolation before processing. Images are only downsized, never upscaled.
+1. **Direct Lookup Table**: Uses a 64MB flat array to map 24-bit RGB colors to unique indices instantly. No hashing overhead.
 
-2. **Color Pre-Quantization**: Images with more than `max_color_preprocess` unique colors are pre-quantized using fast bit-truncation (RGB555/RGB444) with weighted averaging.
+2. **RGBA-Only Preprocessing**: Resolution capping and quantization now happen strictly in RGBA space before any expensive Oklab math.
 
-3. **Integer Edge Detection**: Uses integer arithmetic for edge detection on preprocessed images for ~2x faster edge computation.
+3. **Oklab Caching**: If color reduction is enabled (default), Oklab conversion is only performed once per unique color, not per pixel.
 
-4. **Optimized Tile Processing**: Reduced allocations and stack-allocated arrays for small palettes (≤64 colors).
+<!---->
 
-## What's New in v0.2
+    const config = new WasmDownscaleConfig();
+    config.max_resolution_mp = 1.5;       // Fast nearest-neighbor cap
+    config.max_color_preprocess = 16384;  // Direct LUT quantization
 
-### 🎨 Oklab Color Space
 
-Version 0.2 introduces **Oklab color space** for all color operations, solving the common problem of desaturated, muddy colors:
+### 🎯 K-Centroid Tile Logic
 
-| Before (RGB Median Cut) | After (Oklab Median Cut) |
-|-------------------------|--------------------------|
-| Colors appear tanned/darkened | True color preservation |
-| Saturated colors become muddy | Vibrant colors maintained |
-| RGB averaging loses chroma | Perceptually uniform blending |
+New `k_centroid` configuration allows finer control over how a source tile is reduced to a single representative color before matching:
 
-### Palette Strategies
+| 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            |
 
-Choose the best strategy for your use case:
+    // Example: Use dominant part for sharper edges
+    config.k_centroid = 2;
+    config.k_centroid_iterations = 2;
 
-```javascript
-const config = new WasmDownscaleConfig();
-config.palette_strategy = 'saturation'; // For vibrant pixel art
-```
 
-| Strategy | Best For | Description |
-|----------|----------|-------------|
-| `oklab` | General use | Default, best overall quality |
-| `saturation` | Vibrant art | Preserves highly saturated colors |
-| `medoid` | Exact colors | Only uses colors from source image |
-| `kmeans` | Small palettes | K-Means++ clustering |
-| `legacy` | Comparison | Original RGB (not recommended) |
+## Configuration Reference
+
+### DownscaleConfig
+
+| 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       |
+
+
+## Command Line Interface
+
+    # Enable Dominant Color mode (sharper details)
+    smart-downscaler input.png output.png --k-centroid 2 --k-centroid-iterations 2
+
+    # Fast mode (reduce preprocessing limits)
+    smart-downscaler input.png output.png --segmentation none --no-refinement
+
 
 ## Features
 
 - **Oklab Color Space**: Modern perceptual color space with superior hue linearity
+
 - **Global Palette Extraction**: Median Cut + K-Means++ refinement
+
 - **Multiple Segmentation Methods**:
+
   - SLIC superpixels for fast, balanced regions
+
   - VTracer-style hierarchical clustering for content-aware boundaries
+
   - Union-find based fast hierarchical clustering
+
 - **Edge-Aware Processing**: Sobel/Scharr edge detection to preserve boundaries
+
 - **Neighbor-Coherent Assignment**: Spatial coherence through neighbor and region voting
+
 - **Two-Pass Refinement**: Iterative optimization for smooth results
+
 - **WebAssembly Support**: Run in browsers with full performance
+
 - **Performance Preprocessing**: Resolution capping and color pre-quantization
 
+
 ## Installation
 
 ### Native (Rust)
 
 Add to your `Cargo.toml`:
 
-```toml
-[dependencies]
-smart-downscaler = "0.3"
-```
+    [dependencies]
+    smart-downscaler = "0.3.5"
 
-### WebAssembly (npm)
 
-```bash
-npm install smart-downscaler
-```
+### WebAssembly (npm)
 
-Or use directly in browser:
+    npm install smart-downscaler
 
-```html
-<script type="module">
-  import init, { downscale } from './pkg/web/smart_downscaler.js';
-  await init();
-</script>
-```
 
 ## Quick Start
 
-### Native Rust
-
-```rust
-use smart_downscaler::prelude::*;
-use smart_downscaler::palette::PaletteStrategy;
-
-fn main() {
-    let img = image::open("input.png").unwrap().to_rgb8();
-    
-    // Simple usage
-    let result = downscale(&img, 64, 64, 16);
-    result.save("output.png").unwrap();
-    
-    // Advanced: preserve vibrant colors with preprocessing
-    let config = DownscaleConfig {
-        palette_size: 24,
-        palette_strategy: PaletteStrategy::SaturationWeighted,
-        max_resolution_mp: 1.5,       // Performance: cap at 1.5MP
-        max_color_preprocess: 16384,  // Performance: pre-quantize colors
-        ..Default::default()
-    };
-    
-    let pixels: Vec<Rgb> = img.pixels().map(|&p| p.into()).collect();
-    let result = smart_downscale(&pixels, img.width() as usize, img.height() as usize, 64, 64, &config);
-}
-```
-
 ### WebAssembly (Browser)
 
-```javascript
-import init, { WasmDownscaleConfig, downscale_rgba } from 'smart-downscaler';
+    import init, { WasmDownscaleConfig, downscale_rgba } from 'smart-downscaler';
+
+    await init();
 
-await init();
+    // Create config
+    const config = new WasmDownscaleConfig();
 
-const ctx = canvas.getContext('2d');
-const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);
+    // 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
 
-// Use vibrant preset for saturated colors
-const config = WasmDownscaleConfig.vibrant();
-config.palette_size = 16;
+    // QUALITY: New K-Centroid settings
+    config.k_centroid = 2;                // 2 = Dominant Color Mode
+    config.k_centroid_iterations = 2;     // Refine the dominant color
 
-// Performance settings (already set in presets)
-config.max_resolution_mp = 1.5;
-config.max_color_preprocess = 16384;
+    // Standard settings
+    config.palette_size = 16;
+    config.palette_strategy = 'oklab';
 
-// Or configure manually
-const config2 = new WasmDownscaleConfig();
-config2.palette_size = 16;
-config2.palette_strategy = 'saturation';
-config2.neighbor_weight = 0.3;
-config2.max_resolution_mp = 1.5;
-config2.max_color_preprocess = 16384;
+    // Run
+    const result = downscale_rgba(
+      imageData.data,
+      imageData.width, imageData.height,
+      64, 64, // Target size
+      config
+    );
 
-const result = downscale_rgba(
-  imageData.data,
-  canvas.width,
-  canvas.height,
-  64, 64,
-  config
-);
+    // Draw result
+    const output = new ImageData(result.data, result.width, result.height);
+    ctx.putImageData(output, 0, 0);
 
-const outputData = new ImageData(result.data, result.width, result.height);
-outputCtx.putImageData(outputData, 0, 0);
-```
 
 ### Configuration Presets
 
-```javascript
-// Speed optimized (max_resolution_mp: 1.0, max_color_preprocess: 8192)
-const fast = WasmDownscaleConfig.fast();
+    // Speed optimized (max_resolution_mp: 1.0, max_color_preprocess: 8192)
+    const fast = WasmDownscaleConfig.fast();
 
-// Best quality (max_resolution_mp: 2.0, max_color_preprocess: 32768)
-const quality = WasmDownscaleConfig.quality();
+    // Best quality (max_resolution_mp: 2.0, max_color_preprocess: 32768)
+    const quality = WasmDownscaleConfig.quality();
 
-// Preserve vibrant colors (max_resolution_mp: 1.5, max_color_preprocess: 16384)
-const vibrant = WasmDownscaleConfig.vibrant();
+    // Preserve vibrant colors (max_resolution_mp: 1.5, max_color_preprocess: 16384)
+    const vibrant = WasmDownscaleConfig.vibrant();
+
+    // Use only exact source colors
+    const exact = WasmDownscaleConfig.exact_colors();
 
-// Use only exact source colors
-const exact = WasmDownscaleConfig.exact_colors();
-```
 
 ## Why Oklab?
 
 Traditional RGB-based palette extraction has fundamental problems:
 
+
 ### The Problem: RGB Averaging Desaturates Colors
 
-```
-Red [255, 0, 0] + Cyan [0, 255, 255] 
-  RGB Average → Gray [127, 127, 127] ❌
-```
+    Red [255, 0, 0] + Cyan [0, 255, 255] 
+      RGB Average → Gray [127, 127, 127] ❌
 
 When you average colors in RGB space, saturated colors get pulled toward gray. This is why downscaled images often look "washed out" or "tanned."
 
+
 ### The Solution: Oklab Color Space
 
 Oklab is a **perceptually uniform** color space where:
+
 - Euclidean distance = perceived color difference
+
 - Averaging preserves hue and saturation
+
 - Interpolations look natural
 
-```
-Red (Oklab) + Cyan (Oklab)
-  Oklab Average → Preserves colorfulness ✔
-```
+<!---->
 
-### Visual Comparison
+    Red (Oklab) + Cyan (Oklab)
+      Oklab Average → Preserves colorfulness ✔
 
-| Issue | RGB Median Cut | Oklab Median Cut |
-|-------|----------------|------------------|
-| Saturated colors | Become muddy | Stay vibrant |
-| Gradients | Shift in hue | Stay consistent |
-| Dark colors | Get darker | Accurate lightness |
-| Overall look | Desaturated | True to source |
 
 ## API Reference
 
 ### WasmDownscaleConfig
 
-```javascript
-const config = new WasmDownscaleConfig();
-
-// 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
-
-// Spatial coherence
-config.neighbor_weight = 0.3;       // [0-1] Prefer neighbor colors
-config.region_weight = 0.2;         // [0-1] Prefer region colors
-
-// Refinement
-config.two_pass_refinement = true;
-config.refinement_iterations = 3;
-
-// Edge detection
-config.edge_weight = 0.5;
+    const config = new WasmDownscaleConfig();
 
-// Segmentation
-config.segmentation_method = 'hierarchy_fast'; // 'none', 'slic', 'hierarchy', 'hierarchy_fast'
+    // 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
 
-// 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)
-```
+    // Spatial coherence
+    config.neighbor_weight = 0.3;       // [0-1] Prefer neighbor colors
+    config.region_weight = 0.2;         // [0-1] Prefer region colors
 
-### Available Functions
-
-| 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 |
-
-### WasmDownscaleResult
-
-```javascript
-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
-```
-
-## Command Line Interface
-
-```bash
-# Basic usage
-smart-downscaler input.png output.png -w 64 -h 64
-
-# With saturation preservation
-smart-downscaler input.png output.png -w 64 -h 64 --palette-strategy saturation
-
-# Using exact source colors only
-smart-downscaler input.png output.png -w 64 -h 64 --palette-strategy medoid -p 24
-
-# Full options
-smart-downscaler input.png output.png \
-  -w 128 -h 128 \
-  -p 32 \
-  --palette-strategy saturation \
-  --segmentation hierarchy-fast \
-  --neighbor-weight 0.4
-```
-
-## Algorithm Details
-
-### 0. Preprocessing (v0.3)
-
-Before main processing, large images are optimized:
-
-1. **Resolution Capping**: If pixels > `max_resolution_mp × 1,000,000`:
-   - Scale factor = sqrt(max_resolution_mp / current_mp)
-   - Downscale using nearest-neighbor interpolation
-   - Only downsizes (never upscales)
-
-2. **Color Pre-Quantization**: If unique colors > `max_color_preprocess`:
-   - Build hash-based color histogram
-   - Apply bit truncation (RGB555 or RGB444)
-   - Map colors to weighted bucket averages
-
-### 1. Palette Extraction (Oklab Median Cut)
+    // Refinement
+    config.two_pass_refinement = true;
+    config.refinement_iterations = 3;
 
-1. Convert all pixels to Oklab color space
-2. Build weighted color histogram
-3. Apply Median Cut to partition Oklab space
-4. For each bucket, compute centroid in Oklab
-5. Convert centroids back to RGB
-6. Refine with K-Means++ in Oklab space
+    // Edge detection
+    config.edge_weight = 0.5;
 
-### 2. Saturation-Weighted Strategy
+    // Segmentation
+    config.segmentation_method = 'hierarchy_fast'; // 'none', 'slic', 'hierarchy', 'hierarchy_fast'
 
-When using `saturation` strategy:
-```
-effective_weight = pixel_count × (1 + chroma × 2)
-```
+    // 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)
 
-This boosts the influence of highly saturated colors during Median Cut partitioning.
+    // Tile Logic
+    config.k_centroid = 1;                // 1=Avg, 2=Dom, 3=Foremost
+    config.k_centroid_iterations = 0;     // Refine the dominant color
 
-### 3. Medoid Strategy
 
-Instead of computing centroids (averages), selects the actual image color closest to the centroid. Guarantees output palette contains only exact source colors.
-
-### 4. Region Pre-Segmentation
-
-Before downscaling, identifies coherent regions:
-- **SLIC**: Fast, regular superpixels
-- **Hierarchy**: Content-aware boundaries
-- **Hierarchy Fast**: O(α(n)) union-find
-
-### 5. Edge-Aware Tile Computation
-
-```
-weight(pixel) = 1 / (1 + edge_strength × edge_weight)
-```
-
-Reduces influence of transitional edge pixels.
-
-### 6. Neighbor-Coherent Assignment
-
-```
-score(color) = oklab_distance(color, tile_avg) × (1 - neighbor_bias - region_bias)
-```
-
-## Performance
-
-Typical performance (single-threaded, with preprocessing enabled):
+### Available Functions
 
-| Image Size | Target Size | Palette | Time (v0.3) | Time (v0.2) |
-|------------|-------------|---------|-------------|-------------|
-| 256×256 | 32×32 | 16 | ~40ms | ~50ms |
-| 512×512 | 64×64 | 32 | ~150ms | ~200ms |
-| 1024×1024 | 128×128 | 32 | ~400ms | ~800ms |
-| 2048×2048 | 256×256 | 32 | ~600ms | ~3200ms |
+| 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   |
 
-**Note**: Performance improvements are most significant for large images (>1MP) due to resolution capping.
 
-Enable `parallel` feature for multi-threaded processing.
+### WasmDownscaleResult
 
-## Configuration Reference
+    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
 
-### DownscaleConfig (Rust)
-
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `palette_size` | usize | 16 | Output colors |
-| `palette_strategy` | PaletteStrategy | OklabMedianCut | Extraction method |
-| `kmeans_iterations` | usize | 5 | Refinement iterations |
-| `neighbor_weight` | f32 | 0.3 | Neighbor coherence |
-| `region_weight` | f32 | 0.2 | Region coherence |
-| `two_pass_refinement` | bool | true | Enable refinement |
-| `refinement_iterations` | usize | 3 | Max iterations |
-| `segmentation` | SegmentationMethod | Hierarchy | Pre-segmentation |
-| `edge_weight` | f32 | 0.5 | Edge influence |
-| `max_resolution_mp` | f32 | 1.5 | Max megapixels before downscale (0 = disabled) |
-| `max_color_preprocess` | usize | 16384 | Max unique colors before quantize (0 = disabled) |
-
-### PaletteStrategy
-
-| Value | Description |
-|-------|-------------|
-| `OklabMedianCut` | Default, best general quality |
-| `SaturationWeighted` | Preserves vibrant colors |
-| `Medoid` | Exact source colors only |
-| `KMeansPlusPlus` | K-Means++ clustering |
-| `LegacyRgb` | Original RGB (not recommended) |
-
-## Troubleshooting
-
-### Colors still look desaturated
-
-Try increasing palette size or using `saturation` strategy:
-```javascript
-config.palette_size = 24;  // Up from 16
-config.palette_strategy = 'saturation';
-```
-
-### Want exact source colors
-
-Use medoid strategy with no K-Means refinement:
-```javascript
-config.palette_strategy = 'medoid';
-config.kmeans_iterations = 0;
-```
-
-### Output looks noisy
-
-Increase neighbor weight for smoother results:
-```javascript
-config.neighbor_weight = 0.5;  // Up from 0.3
-config.two_pass_refinement = true;
-```
-
-### Processing too slow for large images
-
-Reduce preprocessing limits:
-```javascript
-config.max_resolution_mp = 1.0;       // Aggressive cap
-config.max_color_preprocess = 8192;   // Fewer colors
-// Or use the 'fast' preset
-const config = WasmDownscaleConfig.fast();
-```
-
-### Want maximum quality (ignore performance)
-
-Disable preprocessing by setting limits to 0:
-```javascript
-config.max_resolution_mp = 0;         // Disable resolution capping
-config.max_color_preprocess = 0;      // Disable color pre-quantization
-// Or use the 'quality' preset which has higher limits
-const config = WasmDownscaleConfig.quality();
-```
 
 ## License
 
 MIT
 
+
 ## Credits
 
 - Oklab color space by Björn Ottosson
+
 - SLIC superpixel algorithm
+
 - K-Means++ initialization
+
 - VTracer hierarchical clustering approach
+

package/package.json

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

package/smart_downscaler.d.ts

@@ -41,140 +41,49 @@ export class ColorEntry {
     readonly r: number;
 }
 
-/**
- * Configuration options for the downscaler (JavaScript-compatible)
- */
 export class WasmDownscaleConfig {
     free(): void;
     [Symbol.dispose](): void;
-    /**
-     * Create configuration that uses only exact image colors (medoid)
-     */
     static exact_colors(): WasmDownscaleConfig;
-    /**
-     * Create configuration optimized for speed
-     */
     static fast(): WasmDownscaleConfig;
-    /**
-     * Create a new configuration with default values
-     */
     constructor();
-    /**
-     * Create configuration optimized for quality
-     */
     static quality(): WasmDownscaleConfig;
-    /**
-     * Create configuration optimized for vibrant colors
-     */
     static vibrant(): WasmDownscaleConfig;
-    /**
-     * Edge weight in tile color computation (default: 0.5)
-     */
     edge_weight: number;
-    /**
-     * For hierarchy: minimum region size (default: 4)
-     */
     hierarchy_min_size: number;
-    /**
-     * For hierarchy: merge threshold (default: 15.0)
-     */
     hierarchy_threshold: number;
     /**
-     * K-Means iterations for palette refinement (default: 5)
+     * Iterations for tile centroid
      */
-    kmeans_iterations: number;
+    k_centroid_iterations: number;
     /**
-     * Maximum unique colors for preprocessing (default: 16384, 0 = disabled)
+     * K-Means centroid mode (1=Avg, 2=Dom, 3=Foremost)
      */
+    k_centroid: number;
+    kmeans_iterations: number;
     max_color_preprocess: number;
-    /**
-     * Maximum resolution in megapixels for preprocessing (default: 1.5, 0 = disabled)
-     */
     max_resolution_mp: number;
-    /**
-     * Weight for neighbor color coherence [0.0, 1.0] (default: 0.3)
-     */
     neighbor_weight: number;
-    /**
-     * Number of colors in the output palette (default: 16)
-     */
     palette_size: number;
-    /**
-     * Maximum refinement iterations (default: 3)
-     */
     refinement_iterations: number;
-    /**
-     * Weight for region membership coherence [0.0, 1.0] (default: 0.2)
-     */
     region_weight: number;
-    /**
-     * For SLIC: compactness factor (default: 10.0)
-     */
     slic_compactness: number;
-    /**
-     * For SLIC: approximate number of superpixels (default: 100)
-     */
     slic_superpixels: number;
-    /**
-     * Number of K-Means clusters for local tile refinement (0 or 1 = disabled, average only)
-     */
-    tile_kmeans_clusters: number;
-    /**
-     * Number of K-Means iterations for local tile refinement
-     */
-    tile_kmeans_iterations: number;
-    /**
-     * Enable two-pass refinement (default: true)
-     */
     two_pass_refinement: boolean;
-    /**
-     * Get the palette extraction strategy
-     */
     palette_strategy: string;
-    /**
-     * Get the segmentation method
-     */
     segmentation_method: string;
 }
 
-/**
- * Result of downscaling operation
- */
 export class WasmDownscaleResult {
     private constructor();
     free(): void;
     [Symbol.dispose](): void;
-    /**
-     * Get palette color at index as [r, g, b]
-     */
-    get_palette_color(index: number): Uint8Array;
-    /**
-     * Get RGB pixel data as Uint8Array (without alpha)
-     */
     rgb_data(): Uint8Array;
-    /**
-     * Get RGBA pixel data as Uint8ClampedArray (for ImageData)
-     */
     readonly data: Uint8ClampedArray;
-    /**
-     * Get output height
-     */
     readonly height: number;
-    /**
-     * Get palette indices for each pixel
-     */
     readonly indices: Uint8Array;
-    /**
-     * Get palette as Uint8Array (RGB, 3 bytes per color)
-     */
     readonly palette: Uint8Array;
-    /**
-     * Get number of colors in palette
-     */
     readonly palette_size: number;
-    /**
-     * Get output width
-     */
     readonly width: number;
 }
 
@@ -197,25 +106,8 @@ export function analyze_colors(image_data: Uint8Array, max_colors: number, sort_
  */
 export function color_distance(r1: number, g1: number, b1: number, r2: number, g2: number, b2: number): number;
 
-/**
- * Main downscaling function for WebAssembly
- *
- * # Arguments
- * * `image_data` - RGBA pixel data as Uint8Array or Uint8ClampedArray
- * * `width` - Source image width
- * * `height` - Source image height
- * * `target_width` - Output image width
- * * `target_height` - Output image height
- * * `config` - Optional configuration (uses defaults if not provided)
- *
- * # Returns
- * WasmDownscaleResult containing the downscaled image data
- */
 export function downscale(image_data: Uint8Array, width: number, height: number, target_width: number, target_height: number, config?: WasmDownscaleConfig | null): WasmDownscaleResult;
 
-/**
- * Downscale with RGBA input directly from ImageData
- */
 export function downscale_rgba(image_data: Uint8ClampedArray, width: number, height: number, target_width: number, target_height: number, config?: WasmDownscaleConfig | null): WasmDownscaleResult;
 
 /**
@@ -223,9 +115,6 @@ export function downscale_rgba(image_data: Uint8ClampedArray, width: number, hei
  */
 export function downscale_simple(image_data: Uint8Array, width: number, height: number, target_width: number, target_height: number, num_colors: number): WasmDownscaleResult;
 
-/**
- * Downscale with a pre-defined palette
- */
 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;
 
 /**
@@ -248,9 +137,6 @@ export function get_lightness(r: number, g: number, b: number): number;
  */
 export function get_palette_strategies(): Array<any>;
 
-/**
- * Initialize panic hook for better error messages in browser console
- */
 export function init(): void;
 
 /**

package/smart_downscaler_bg.js

@@ -146,9 +146,6 @@ export class ColorEntry {
 }
 if (Symbol.dispose) ColorEntry.prototype[Symbol.dispose] = ColorEntry.prototype.free;
 
-/**
- * Configuration options for the downscaler (JavaScript-compatible)
- */
 export class WasmDownscaleConfig {
     static __wrap(ptr) {
         ptr = ptr >>> 0;
@@ -168,7 +165,6 @@ export class WasmDownscaleConfig {
         wasm.__wbg_wasmdownscaleconfig_free(ptr, 0);
     }
     /**
-     * Edge weight in tile color computation (default: 0.5)
      * @returns {number}
      */
     get edge_weight() {
@@ -176,7 +172,6 @@ export class WasmDownscaleConfig {
         return ret;
     }
     /**
-     * For hierarchy: minimum region size (default: 4)
      * @returns {number}
      */
     get hierarchy_min_size() {
@@ -184,7 +179,6 @@ export class WasmDownscaleConfig {
         return ret >>> 0;
     }
     /**
-     * For hierarchy: merge threshold (default: 15.0)
      * @returns {number}
      */
     get hierarchy_threshold() {
@@ -192,7 +186,22 @@ export class WasmDownscaleConfig {
         return ret;
     }
     /**
-     * K-Means iterations for palette refinement (default: 5)
+     * Iterations for tile centroid
+     * @returns {number}
+     */
+    get k_centroid_iterations() {
+        const ret = wasm.__wbg_get_wasmdownscaleconfig_k_centroid_iterations(this.__wbg_ptr);
+        return ret >>> 0;
+    }
+    /**
+     * K-Means centroid mode (1=Avg, 2=Dom, 3=Foremost)
+     * @returns {number}
+     */
+    get k_centroid() {
+        const ret = wasm.__wbg_get_wasmdownscaleconfig_k_centroid(this.__wbg_ptr);
+        return ret >>> 0;
+    }
+    /**
      * @returns {number}
      */
     get kmeans_iterations() {
@@ -200,7 +209,6 @@ export class WasmDownscaleConfig {
         return ret >>> 0;
     }
     /**
-     * Maximum unique colors for preprocessing (default: 16384, 0 = disabled)
      * @returns {number}
      */
     get max_color_preprocess() {
@@ -208,7 +216,6 @@ export class WasmDownscaleConfig {
         return ret >>> 0;
     }
     /**
-     * Maximum resolution in megapixels for preprocessing (default: 1.5, 0 = disabled)
      * @returns {number}
      */
     get max_resolution_mp() {
@@ -216,7 +223,6 @@ export class WasmDownscaleConfig {
         return ret;
     }
     /**
-     * Weight for neighbor color coherence [0.0, 1.0] (default: 0.3)
      * @returns {number}
      */
     get neighbor_weight() {
@@ -224,7 +230,6 @@ export class WasmDownscaleConfig {
         return ret;
     }
     /**
-     * Number of colors in the output palette (default: 16)
      * @returns {number}
      */
     get palette_size() {
@@ -232,7 +237,6 @@ export class WasmDownscaleConfig {
         return ret >>> 0;
     }
     /**
-     * Maximum refinement iterations (default: 3)
      * @returns {number}
      */
     get refinement_iterations() {
@@ -240,7 +244,6 @@ export class WasmDownscaleConfig {
         return ret >>> 0;
     }
     /**
-     * Weight for region membership coherence [0.0, 1.0] (default: 0.2)
      * @returns {number}
      */
     get region_weight() {
@@ -248,7 +251,6 @@ export class WasmDownscaleConfig {
         return ret;
     }
     /**
-     * For SLIC: compactness factor (default: 10.0)
      * @returns {number}
      */
     get slic_compactness() {
@@ -256,7 +258,6 @@ export class WasmDownscaleConfig {
         return ret;
     }
     /**
-     * For SLIC: approximate number of superpixels (default: 100)
      * @returns {number}
      */
     get slic_superpixels() {
@@ -264,23 +265,6 @@ export class WasmDownscaleConfig {
         return ret >>> 0;
     }
     /**
-     * Number of K-Means clusters for local tile refinement (0 or 1 = disabled, average only)
-     * @returns {number}
-     */
-    get tile_kmeans_clusters() {
-        const ret = wasm.__wbg_get_wasmdownscaleconfig_tile_kmeans_clusters(this.__wbg_ptr);
-        return ret >>> 0;
-    }
-    /**
-     * Number of K-Means iterations for local tile refinement
-     * @returns {number}
-     */
-    get tile_kmeans_iterations() {
-        const ret = wasm.__wbg_get_wasmdownscaleconfig_tile_kmeans_iterations(this.__wbg_ptr);
-        return ret >>> 0;
-    }
-    /**
-     * Enable two-pass refinement (default: true)
      * @returns {boolean}
      */
     get two_pass_refinement() {
@@ -288,112 +272,98 @@ export class WasmDownscaleConfig {
         return ret !== 0;
     }
     /**
-     * Edge weight in tile color computation (default: 0.5)
      * @param {number} arg0
      */
     set edge_weight(arg0) {
         wasm.__wbg_set_wasmdownscaleconfig_edge_weight(this.__wbg_ptr, arg0);
     }
     /**
-     * For hierarchy: minimum region size (default: 4)
      * @param {number} arg0
      */
     set hierarchy_min_size(arg0) {
         wasm.__wbg_set_wasmdownscaleconfig_hierarchy_min_size(this.__wbg_ptr, arg0);
     }
     /**
-     * For hierarchy: merge threshold (default: 15.0)
      * @param {number} arg0
      */
     set hierarchy_threshold(arg0) {
         wasm.__wbg_set_wasmdownscaleconfig_hierarchy_threshold(this.__wbg_ptr, arg0);
     }
     /**
-     * K-Means iterations for palette refinement (default: 5)
+     * 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) {
+        wasm.__wbg_set_wasmdownscaleconfig_k_centroid(this.__wbg_ptr, arg0);
+    }
+    /**
      * @param {number} arg0
      */
     set kmeans_iterations(arg0) {
         wasm.__wbg_set_wasmdownscaleconfig_kmeans_iterations(this.__wbg_ptr, arg0);
     }
     /**
-     * Maximum unique colors for preprocessing (default: 16384, 0 = disabled)
      * @param {number} arg0
      */
     set max_color_preprocess(arg0) {
         wasm.__wbg_set_wasmdownscaleconfig_max_color_preprocess(this.__wbg_ptr, arg0);
     }
     /**
-     * Maximum resolution in megapixels for preprocessing (default: 1.5, 0 = disabled)
      * @param {number} arg0
      */
     set max_resolution_mp(arg0) {
         wasm.__wbg_set_wasmdownscaleconfig_max_resolution_mp(this.__wbg_ptr, arg0);
     }
     /**
-     * Weight for neighbor color coherence [0.0, 1.0] (default: 0.3)
      * @param {number} arg0
      */
     set neighbor_weight(arg0) {
         wasm.__wbg_set_wasmdownscaleconfig_neighbor_weight(this.__wbg_ptr, arg0);
     }
     /**
-     * Number of colors in the output palette (default: 16)
      * @param {number} arg0
      */
     set palette_size(arg0) {
         wasm.__wbg_set_wasmdownscaleconfig_palette_size(this.__wbg_ptr, arg0);
     }
     /**
-     * Maximum refinement iterations (default: 3)
      * @param {number} arg0
      */
     set refinement_iterations(arg0) {
         wasm.__wbg_set_wasmdownscaleconfig_refinement_iterations(this.__wbg_ptr, arg0);
     }
     /**
-     * Weight for region membership coherence [0.0, 1.0] (default: 0.2)
      * @param {number} arg0
      */
     set region_weight(arg0) {
         wasm.__wbg_set_wasmdownscaleconfig_region_weight(this.__wbg_ptr, arg0);
     }
     /**
-     * For SLIC: compactness factor (default: 10.0)
      * @param {number} arg0
      */
     set slic_compactness(arg0) {
         wasm.__wbg_set_wasmdownscaleconfig_slic_compactness(this.__wbg_ptr, arg0);
     }
     /**
-     * For SLIC: approximate number of superpixels (default: 100)
      * @param {number} arg0
      */
     set slic_superpixels(arg0) {
         wasm.__wbg_set_wasmdownscaleconfig_slic_superpixels(this.__wbg_ptr, arg0);
     }
     /**
-     * Number of K-Means clusters for local tile refinement (0 or 1 = disabled, average only)
-     * @param {number} arg0
-     */
-    set tile_kmeans_clusters(arg0) {
-        wasm.__wbg_set_wasmdownscaleconfig_tile_kmeans_clusters(this.__wbg_ptr, arg0);
-    }
-    /**
-     * Number of K-Means iterations for local tile refinement
-     * @param {number} arg0
-     */
-    set tile_kmeans_iterations(arg0) {
-        wasm.__wbg_set_wasmdownscaleconfig_tile_kmeans_iterations(this.__wbg_ptr, arg0);
-    }
-    /**
-     * Enable two-pass refinement (default: true)
      * @param {boolean} arg0
      */
     set two_pass_refinement(arg0) {
         wasm.__wbg_set_wasmdownscaleconfig_two_pass_refinement(this.__wbg_ptr, arg0);
     }
     /**
-     * Create configuration that uses only exact image colors (medoid)
      * @returns {WasmDownscaleConfig}
      */
     static exact_colors() {
@@ -401,16 +371,12 @@ export class WasmDownscaleConfig {
         return WasmDownscaleConfig.__wrap(ret);
     }
     /**
-     * Create configuration optimized for speed
      * @returns {WasmDownscaleConfig}
      */
     static fast() {
         const ret = wasm.wasmdownscaleconfig_fast();
         return WasmDownscaleConfig.__wrap(ret);
     }
-    /**
-     * Create a new configuration with default values
-     */
     constructor() {
         const ret = wasm.wasmdownscaleconfig_new();
         this.__wbg_ptr = ret >>> 0;
@@ -418,7 +384,6 @@ export class WasmDownscaleConfig {
         return this;
     }
     /**
-     * Get the palette extraction strategy
      * @returns {string}
      */
     get palette_strategy() {
@@ -434,7 +399,6 @@ export class WasmDownscaleConfig {
         }
     }
     /**
-     * Create configuration optimized for quality
      * @returns {WasmDownscaleConfig}
      */
     static quality() {
@@ -442,7 +406,6 @@ export class WasmDownscaleConfig {
         return WasmDownscaleConfig.__wrap(ret);
     }
     /**
-     * Get the segmentation method
      * @returns {string}
      */
     get segmentation_method() {
@@ -458,7 +421,6 @@ export class WasmDownscaleConfig {
         }
     }
     /**
-     * Set the palette extraction strategy
      * @param {string} strategy
      */
     set palette_strategy(strategy) {
@@ -467,7 +429,6 @@ export class WasmDownscaleConfig {
         wasm.wasmdownscaleconfig_set_palette_strategy(this.__wbg_ptr, ptr0, len0);
     }
     /**
-     * Set the segmentation method
      * @param {string} method
      */
     set segmentation_method(method) {
@@ -476,7 +437,6 @@ export class WasmDownscaleConfig {
         wasm.wasmdownscaleconfig_set_segmentation_method(this.__wbg_ptr, ptr0, len0);
     }
     /**
-     * Create configuration optimized for vibrant colors
      * @returns {WasmDownscaleConfig}
      */
     static vibrant() {
@@ -486,9 +446,6 @@ export class WasmDownscaleConfig {
 }
 if (Symbol.dispose) WasmDownscaleConfig.prototype[Symbol.dispose] = WasmDownscaleConfig.prototype.free;
 
-/**
- * Result of downscaling operation
- */
 export class WasmDownscaleResult {
     static __wrap(ptr) {
         ptr = ptr >>> 0;
@@ -508,7 +465,6 @@ export class WasmDownscaleResult {
         wasm.__wbg_wasmdownscaleresult_free(ptr, 0);
     }
     /**
-     * Get RGBA pixel data as Uint8ClampedArray (for ImageData)
      * @returns {Uint8ClampedArray}
      */
     get data() {
@@ -516,16 +472,6 @@ export class WasmDownscaleResult {
         return ret;
     }
     /**
-     * Get palette color at index as [r, g, b]
-     * @param {number} index
-     * @returns {Uint8Array}
-     */
-    get_palette_color(index) {
-        const ret = wasm.wasmdownscaleresult_get_palette_color(this.__wbg_ptr, index);
-        return ret;
-    }
-    /**
-     * Get output height
      * @returns {number}
      */
     get height() {
@@ -533,7 +479,6 @@ export class WasmDownscaleResult {
         return ret >>> 0;
     }
     /**
-     * Get palette indices for each pixel
      * @returns {Uint8Array}
      */
     get indices() {
@@ -541,7 +486,6 @@ export class WasmDownscaleResult {
         return ret;
     }
     /**
-     * Get palette as Uint8Array (RGB, 3 bytes per color)
      * @returns {Uint8Array}
      */
     get palette() {
@@ -549,7 +493,6 @@ export class WasmDownscaleResult {
         return ret;
     }
     /**
-     * Get number of colors in palette
      * @returns {number}
      */
     get palette_size() {
@@ -557,7 +500,6 @@ export class WasmDownscaleResult {
         return ret >>> 0;
     }
     /**
-     * Get RGB pixel data as Uint8Array (without alpha)
      * @returns {Uint8Array}
      */
     rgb_data() {
@@ -565,7 +507,6 @@ export class WasmDownscaleResult {
         return ret;
     }
     /**
-     * Get output width
      * @returns {number}
      */
     get width() {
@@ -617,18 +558,6 @@ export function color_distance(r1, g1, b1, r2, g2, b2) {
 }
 
 /**
- * Main downscaling function for WebAssembly
- *
- * # Arguments
- * * `image_data` - RGBA pixel data as Uint8Array or Uint8ClampedArray
- * * `width` - Source image width
- * * `height` - Source image height
- * * `target_width` - Output image width
- * * `target_height` - Output image height
- * * `config` - Optional configuration (uses defaults if not provided)
- *
- * # Returns
- * WasmDownscaleResult containing the downscaled image data
  * @param {Uint8Array} image_data
  * @param {number} width
  * @param {number} height
@@ -651,7 +580,6 @@ export function downscale(image_data, width, height, target_width, target_height
 }
 
 /**
- * Downscale with RGBA input directly from ImageData
  * @param {Uint8ClampedArray} image_data
  * @param {number} width
  * @param {number} height
@@ -692,7 +620,6 @@ export function downscale_simple(image_data, width, height, target_width, target
 }
 
 /**
- * Downscale with a pre-defined palette
  * @param {Uint8Array} image_data
  * @param {number} width
  * @param {number} height
@@ -768,9 +695,6 @@ export function get_palette_strategies() {
     return ret;
 }
 
-/**
- * Initialize panic hook for better error messages in browser console
- */
 export function init() {
     wasm.init();
 }