smart-downscaler 0.6.0 → 0.6.2

package/README.md

@@ -4,7 +4,7 @@ A high-performance Rust library for intelligent image downscaling with pixel art
 
 **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)]()
+[![Version](https://img.shields.io/badge/version-0.6.0-blue.svg)]()
 [![License](https://img.shields.io/badge/license-MIT-green.svg)]()
 
 ---
@@ -35,6 +35,7 @@ A high-performance Rust library for intelligent image downscaling with pixel art
 | **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 |
+| **Rare-Color Preservation** | Saliency weighting + slot reservation keeps small, important colors (lips, eyes) |
 | **Performance Preprocessing** | Resolution capping and color pre-quantization |
 | **WebAssembly Support** | Full browser compatibility with near-native speed |
 
@@ -46,7 +47,7 @@ A high-performance Rust library for intelligent image downscaling with pixel art
 
 ```toml
 [dependencies]
-smart-downscaler = "0.5.0"
+smart-downscaler = "0.6.0"
 ```
 
 ### WebAssembly (npm)
@@ -59,7 +60,7 @@ npm install smart-downscaler
 
 ```html
 <script type="module">
-  import init, { downscale_rgba, WasmDownscaleConfig } from 'https://unpkg.com/smart-downscaler@0.5.0/smart_downscaler.js';
+  import init, { downscale_rgba, WasmDownscaleConfig } from 'https://unpkg.com/smart-downscaler@0.6.0/smart_downscaler.js';
 </script>
 ```
 
@@ -168,8 +169,12 @@ println!("Palette: {} colors", result.palette.len());
 | `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` | `usize` | `1` | `1`, `2`, `3`, `4` | Tile color extraction mode |
 | `k_centroid_iterations` | `usize` | `0` | `0-10` | K-Means iterations for tile color |
+| **Rare-Color Preservation** |||||
+| `color_rarity` | `f32` | `0.0` | `0.0-1.0` | Damps frequency vote so large flat areas stop dominating (`0`=area, `1`=`count^0.5`) |
+| `detail_boost` | `f32` | `0.0` | `0.0-2.0` | Boosts colors in detail-rich regions via a local-contrast saliency map (`0`=off) |
+| `reserve_colors` | `usize` | `0` | `0 - palette_size` | Reserve N palette slots for distinct, important, under-represented source colors (`0`=off) |
 
 ---
 
@@ -224,6 +229,9 @@ Controls how each source tile is reduced to a single representative color:
 | **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 |
+| **Salient** | `4` | K-Means (k=2), keeps a distinctly-more-chromatic minority | Thin colorful features (lips, eyes, makeup) |
+
+> **Note:** Mode `2` (Dominant) snaps a mixed tile to its *larger* cluster, which discards thin minority colors — a tile that is 60% skin / 40% lip becomes pure skin. For faces and other artwork with small colorful features, prefer mode `4`, which keeps the colorful minority when it is non-trivial (≥22% of the tile) and clearly more chromatic than the majority.
 
 ```javascript
 // Mode 1: Average (default) - smooth results
@@ -237,6 +245,10 @@ config.k_centroid_iterations = 2;
 // Mode 3: Foremost - detailed preservation
 config.k_centroid = 3;
 config.k_centroid_iterations = 3;
+
+// Mode 4: Salient - preserve thin colorful features (lips, eyes)
+config.k_centroid = 4;
+config.k_centroid_iterations = 2;
 ```
 
 ---
@@ -447,7 +459,7 @@ const dist = color_distance(255, 0, 0, 0, 255, 0);  // Red vs Green
 Get library version.
 
 ```javascript
-console.log(version());  // "0.5.0"
+console.log(version());  // "0.6.0"
 ```
 
 ---
@@ -496,18 +508,59 @@ const exact = WasmDownscaleConfig.exact_colors();
 
 ### 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) | ⚡⚡ |
+| Preset | Palette | K-Means | Segmentation | K-Centroid | Rare-Color¹ | Speed |
+|--------|---------|---------|--------------|------------|-------------|-------|
+| `fast()` | 16 | 3 | none | 1 (avg) | off | ⚡⚡⚡ |
+| `default` | 16 | 5 | hierarchy_fast | 1 (avg) | off | ⚡⚡ |
+| `vibrant()` | 24 | 8 | hierarchy_fast | 2 (dom) | on (3 slots) | ⚡ |
+| `quality()` | 32 | 10 | hierarchy | 2 (dom) | on (4 slots) | 🐢 |
+| `exact_colors()` | 16 | 0 | hierarchy_fast | 1 (avg) | off | ⚡⚡ |
+
+¹ `vibrant()` and `quality()` enable `reserve_colors` + `detail_boost` + `color_rarity`. For the strongest thin-feature retention (faces), additionally set `k_centroid = 4`.
 
 ---
 
 ## Advanced Usage
 
+### Preserving Rare / Important Colors
+
+Palette extraction is **area-weighted**: a color that covers a large region gets
+many "votes", so small but perceptually important colors — lips, eyes, a logo,
+a colored highlight — are easily merged into the dominant tones (e.g. lips into
+skin) at low palette sizes (16–64). Three knobs counteract this:
+
+| Knob | What it does | When to raise it |
+|------|--------------|------------------|
+| `reserve_colors` | **Hard guarantee.** Reserves N slots, filled with exact source colors that are far from the rest of the palette *and* important. The most reliable fix. | Always, for portraits/artwork with small features. ~`palette_size / 8`. |
+| `detail_boost` | Weights extraction toward colors in **detail-rich regions** using a local-contrast saliency map (measured at the downscale radius, so it targets features thin enough to be averaged away — and picks their *clean* interior color, not muddy edge blends). | When the important color sits in a high-detail area (most facial features). `0.8–1.0`. |
+| `color_rarity` | Damps the frequency vote (`count^p`, `p = 1 − 0.5·rarity`) so large flat regions stop monopolizing the palette. | Mild assist alongside the above. `0.3–0.4`. |
+
+Pair these with `k_centroid = 4` (Salient), which stops the *tile* stage from
+discarding the same minority colors. A correct palette is wasted if a 60% skin /
+40% lip tile is still snapped to skin.
+
+```javascript
+// Recommended for faces / portraits at 16–64 colors
+const config = new WasmDownscaleConfig();
+config.palette_size      = 32;
+config.palette_strategy  = 'oklab';     // honors color_rarity / detail_boost in median-cut
+config.k_centroid        = 4;           // salient tile color (keep colorful minorities)
+config.k_centroid_iterations = 2;
+config.reserve_colors    = 4;           // ~palette_size / 8 — the guarantee
+config.detail_boost      = 0.9;         // saliency targeting
+config.color_rarity      = 0.35;        // frequency damping
+config.neighbor_weight   = 0.18;        // lower = less erosion of thin features
+```
+
+> **Trade-off:** at very small palettes, reserving slots for rare colors costs
+> some gradient smoothness elsewhere. Scale `reserve_colors` with `palette_size`
+> (16→2, 32→4, 64→8) and lean on it harder at the high end.
+>
+> **Strategy note:** `bitmask` ignores frequency weights during its initial
+> split, so with `bitmask` only `reserve_colors` is active. Use `oklab` (or
+> `saturation`) if you also want `color_rarity` / `detail_boost` to shape the
+> main palette.
+
 ### Custom Palette Workflow
 
 ```javascript
@@ -705,7 +758,7 @@ smart-downscaler input.png --extract-palette palette.hex -c 16
 | `--colors` | `-c` | `16` | Palette size |
 | `--strategy` | `-s` | `oklab` | Palette strategy |
 | `--segmentation` | | `hierarchy_fast` | Segmentation method |
-| `--k-centroid` | | `1` | Tile color mode |
+| `--k-centroid` | | `1` | Tile color mode (1=avg, 2=dominant, 3=foremost, 4=salient) |
 | `--k-centroid-iterations` | | `0` | Tile refinement |
 | `--no-refinement` | | false | Disable two-pass |
 | `--preset` | `-p` | | Use preset (fast/quality/vibrant) |

package/package.json

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

package/smart_downscaler.d.ts

@@ -33,6 +33,14 @@ export class WasmDownscaleConfig {
     constructor();
     static quality(): WasmDownscaleConfig;
     static vibrant(): WasmDownscaleConfig;
+    /**
+     * Rare-color preservation: 0.0 = pure area weighting, 1.0 = strong (count^0.5).
+     */
+    color_rarity: number;
+    /**
+     * Detail-color boost via local-contrast saliency. 0.0 = off.
+     */
+    detail_boost: number;
     edge_weight: number;
     hierarchy_min_size: number;
     hierarchy_threshold: number;
@@ -45,6 +53,10 @@ export class WasmDownscaleConfig {
     palette_size: number;
     refinement_iterations: number;
     region_weight: number;
+    /**
+     * Reserve N palette slots for distinct, important, under-represented colors. 0 = off.
+     */
+    reserve_colors: number;
     slic_compactness: number;
     slic_superpixels: number;
     two_pass_refinement: boolean;

package/smart_downscaler_bg.js

@@ -154,6 +154,22 @@ export class WasmDownscaleConfig {
         const ptr = this.__destroy_into_raw();
         wasm.__wbg_wasmdownscaleconfig_free(ptr, 0);
     }
+    /**
+     * Rare-color preservation: 0.0 = pure area weighting, 1.0 = strong (count^0.5).
+     * @returns {number}
+     */
+    get color_rarity() {
+        const ret = wasm.__wbg_get_wasmdownscaleconfig_color_rarity(this.__wbg_ptr);
+        return ret;
+    }
+    /**
+     * Detail-color boost via local-contrast saliency. 0.0 = off.
+     * @returns {number}
+     */
+    get detail_boost() {
+        const ret = wasm.__wbg_get_wasmdownscaleconfig_detail_boost(this.__wbg_ptr);
+        return ret;
+    }
     /**
      * @returns {number}
      */
@@ -238,6 +254,14 @@ export class WasmDownscaleConfig {
         const ret = wasm.__wbg_get_wasmdownscaleconfig_region_weight(this.__wbg_ptr);
         return ret;
     }
+    /**
+     * Reserve N palette slots for distinct, important, under-represented colors. 0 = off.
+     * @returns {number}
+     */
+    get reserve_colors() {
+        const ret = wasm.__wbg_get_wasmdownscaleconfig_reserve_colors(this.__wbg_ptr);
+        return ret >>> 0;
+    }
     /**
      * @returns {number}
      */
@@ -259,6 +283,20 @@ export class WasmDownscaleConfig {
         const ret = wasm.__wbg_get_wasmdownscaleconfig_two_pass_refinement(this.__wbg_ptr);
         return ret !== 0;
     }
+    /**
+     * Rare-color preservation: 0.0 = pure area weighting, 1.0 = strong (count^0.5).
+     * @param {number} arg0
+     */
+    set color_rarity(arg0) {
+        wasm.__wbg_set_wasmdownscaleconfig_color_rarity(this.__wbg_ptr, arg0);
+    }
+    /**
+     * Detail-color boost via local-contrast saliency. 0.0 = off.
+     * @param {number} arg0
+     */
+    set detail_boost(arg0) {
+        wasm.__wbg_set_wasmdownscaleconfig_detail_boost(this.__wbg_ptr, arg0);
+    }
     /**
      * @param {number} arg0
      */
@@ -331,6 +369,13 @@ export class WasmDownscaleConfig {
     set region_weight(arg0) {
         wasm.__wbg_set_wasmdownscaleconfig_region_weight(this.__wbg_ptr, arg0);
     }
+    /**
+     * Reserve N palette slots for distinct, important, under-represented colors. 0 = off.
+     * @param {number} arg0
+     */
+    set reserve_colors(arg0) {
+        wasm.__wbg_set_wasmdownscaleconfig_reserve_colors(this.__wbg_ptr, arg0);
+    }
     /**
      * @param {number} arg0
      */