smart-downscaler 0.5.0 → 0.6.1

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.5.0",
+  "version": "0.6.1",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -14,13 +14,11 @@
   "files": [
     "smart_downscaler_bg.wasm",
     "smart_downscaler.js",
-    "smart_downscaler_bg.js",
     "smart_downscaler.d.ts"
   ],
   "main": "smart_downscaler.js",
   "types": "smart_downscaler.d.ts",
   "sideEffects": [
-    "./smart_downscaler.js",
     "./snippets/*"
   ],
   "keywords": [

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;
@@ -49,16 +33,18 @@ export class WasmDownscaleConfig {
     constructor();
     static quality(): WasmDownscaleConfig;
     static vibrant(): WasmDownscaleConfig;
-    edge_weight: number;
-    hierarchy_min_size: number;
-    hierarchy_threshold: number;
     /**
-     * Iterations for tile centroid
+     * Rare-color preservation: 0.0 = pure area weighting, 1.0 = strong (count^0.5).
      */
-    k_centroid_iterations: number;
+    color_rarity: number;
     /**
-     * K-Means centroid mode (1=Avg, 2=Dom, 3=Foremost)
+     * Detail-color boost via local-contrast saliency. 0.0 = off.
      */
+    detail_boost: number;
+    edge_weight: number;
+    hierarchy_min_size: number;
+    hierarchy_threshold: number;
+    k_centroid_iterations: number;
     k_centroid: number;
     kmeans_iterations: number;
     max_color_preprocess: number;
@@ -67,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;
@@ -88,78 +78,159 @@ 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;
 
+export function rgb_to_oklab(r: number, g: number, b: number): Float32Array;
+
+export function version(): string;
+
+export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+export interface InitOutput {
+    readonly memory: WebAssembly.Memory;
+    readonly __wbg_coloranalysisresult_free: (a: number, b: number) => void;
+    readonly __wbg_colorentry_free: (a: number, b: number) => void;
+    readonly __wbg_get_wasmdownscaleconfig_color_rarity: (a: number) => number;
+    readonly __wbg_get_wasmdownscaleconfig_detail_boost: (a: number) => number;
+    readonly __wbg_get_wasmdownscaleconfig_edge_weight: (a: number) => number;
+    readonly __wbg_get_wasmdownscaleconfig_hierarchy_min_size: (a: number) => number;
+    readonly __wbg_get_wasmdownscaleconfig_hierarchy_threshold: (a: number) => number;
+    readonly __wbg_get_wasmdownscaleconfig_k_centroid: (a: number) => number;
+    readonly __wbg_get_wasmdownscaleconfig_k_centroid_iterations: (a: number) => number;
+    readonly __wbg_get_wasmdownscaleconfig_kmeans_iterations: (a: number) => number;
+    readonly __wbg_get_wasmdownscaleconfig_max_color_preprocess: (a: number) => number;
+    readonly __wbg_get_wasmdownscaleconfig_max_resolution_mp: (a: number) => number;
+    readonly __wbg_get_wasmdownscaleconfig_neighbor_weight: (a: number) => number;
+    readonly __wbg_get_wasmdownscaleconfig_palette_size: (a: number) => number;
+    readonly __wbg_get_wasmdownscaleconfig_refinement_iterations: (a: number) => number;
+    readonly __wbg_get_wasmdownscaleconfig_region_weight: (a: number) => number;
+    readonly __wbg_get_wasmdownscaleconfig_reserve_colors: (a: number) => number;
+    readonly __wbg_get_wasmdownscaleconfig_slic_compactness: (a: number) => number;
+    readonly __wbg_get_wasmdownscaleconfig_slic_superpixels: (a: number) => number;
+    readonly __wbg_get_wasmdownscaleconfig_two_pass_refinement: (a: number) => number;
+    readonly __wbg_set_wasmdownscaleconfig_color_rarity: (a: number, b: number) => void;
+    readonly __wbg_set_wasmdownscaleconfig_detail_boost: (a: number, b: number) => void;
+    readonly __wbg_set_wasmdownscaleconfig_edge_weight: (a: number, b: number) => void;
+    readonly __wbg_set_wasmdownscaleconfig_hierarchy_min_size: (a: number, b: number) => void;
+    readonly __wbg_set_wasmdownscaleconfig_hierarchy_threshold: (a: number, b: number) => void;
+    readonly __wbg_set_wasmdownscaleconfig_k_centroid: (a: number, b: number) => void;
+    readonly __wbg_set_wasmdownscaleconfig_k_centroid_iterations: (a: number, b: number) => void;
+    readonly __wbg_set_wasmdownscaleconfig_kmeans_iterations: (a: number, b: number) => void;
+    readonly __wbg_set_wasmdownscaleconfig_max_color_preprocess: (a: number, b: number) => void;
+    readonly __wbg_set_wasmdownscaleconfig_max_resolution_mp: (a: number, b: number) => void;
+    readonly __wbg_set_wasmdownscaleconfig_neighbor_weight: (a: number, b: number) => void;
+    readonly __wbg_set_wasmdownscaleconfig_palette_size: (a: number, b: number) => void;
+    readonly __wbg_set_wasmdownscaleconfig_refinement_iterations: (a: number, b: number) => void;
+    readonly __wbg_set_wasmdownscaleconfig_region_weight: (a: number, b: number) => void;
+    readonly __wbg_set_wasmdownscaleconfig_reserve_colors: (a: number, b: number) => void;
+    readonly __wbg_set_wasmdownscaleconfig_slic_compactness: (a: number, b: number) => void;
+    readonly __wbg_set_wasmdownscaleconfig_slic_superpixels: (a: number, b: number) => void;
+    readonly __wbg_set_wasmdownscaleconfig_two_pass_refinement: (a: number, b: number) => void;
+    readonly __wbg_wasmdownscaleconfig_free: (a: number, b: number) => void;
+    readonly __wbg_wasmdownscaleresult_free: (a: number, b: number) => void;
+    readonly analyze_colors: (a: any, b: number, c: number, d: number) => [number, number, number];
+    readonly color_distance: (a: number, b: number, c: number, d: number, e: number, f: number) => number;
+    readonly coloranalysisresult_color_count: (a: number) => number;
+    readonly coloranalysisresult_get_color: (a: number, b: number) => number;
+    readonly coloranalysisresult_get_colors_flat: (a: number) => any;
+    readonly coloranalysisresult_success: (a: number) => number;
+    readonly coloranalysisresult_to_json: (a: number) => [number, number, number];
+    readonly coloranalysisresult_total_pixels: (a: number) => number;
+    readonly colorentry_b: (a: number) => number;
+    readonly colorentry_count: (a: number) => number;
+    readonly colorentry_g: (a: number) => number;
+    readonly colorentry_hex: (a: number) => [number, number];
+    readonly colorentry_percentage: (a: number) => number;
+    readonly colorentry_r: (a: number) => number;
+    readonly downscale: (a: any, b: number, c: number, d: number, e: number, f: number) => [number, number, number];
+    readonly downscale_rgba: (a: any, b: number, c: number, d: number, e: number, f: number) => [number, number, number];
+    readonly downscale_simple: (a: any, b: number, c: number, d: number, e: number, f: number) => [number, number, number];
+    readonly downscale_with_palette: (a: any, b: number, c: number, d: number, e: number, f: any, g: number) => [number, number, number];
+    readonly extract_palette_from_image: (a: any, b: number, c: number, d: number, e: number, f: number, g: number) => [number, number, number];
+    readonly get_chroma: (a: number, b: number, c: number) => number;
+    readonly get_lightness: (a: number, b: number, c: number) => number;
+    readonly get_palette_strategies: () => any;
+    readonly init: () => void;
+    readonly log: (a: number, b: number) => void;
+    readonly oklab_to_rgb: (a: number, b: number, c: number) => any;
+    readonly quantize_to_palette: (a: any, b: number, c: number, d: any) => [number, number, number];
+    readonly rgb_to_oklab: (a: number, b: number, c: number) => any;
+    readonly version: () => [number, number];
+    readonly wasmdownscaleconfig_exact_colors: () => number;
+    readonly wasmdownscaleconfig_fast: () => number;
+    readonly wasmdownscaleconfig_new: () => number;
+    readonly wasmdownscaleconfig_palette_strategy: (a: number) => [number, number];
+    readonly wasmdownscaleconfig_quality: () => number;
+    readonly wasmdownscaleconfig_segmentation_method: (a: number) => [number, number];
+    readonly wasmdownscaleconfig_set_palette_strategy: (a: number, b: number, c: number) => void;
+    readonly wasmdownscaleconfig_set_segmentation_method: (a: number, b: number, c: number) => void;
+    readonly wasmdownscaleconfig_vibrant: () => number;
+    readonly wasmdownscaleresult_data: (a: number) => any;
+    readonly wasmdownscaleresult_height: (a: number) => number;
+    readonly wasmdownscaleresult_indices: (a: number) => any;
+    readonly wasmdownscaleresult_palette: (a: number) => any;
+    readonly wasmdownscaleresult_palette_size: (a: number) => number;
+    readonly wasmdownscaleresult_rgb_data: (a: number) => any;
+    readonly wasmdownscaleresult_width: (a: number) => number;
+    readonly __wbindgen_exn_store: (a: number) => void;
+    readonly __externref_table_alloc: () => number;
+    readonly __wbindgen_externrefs: WebAssembly.Table;
+    readonly __wbindgen_malloc: (a: number, b: number) => number;
+    readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
+    readonly __externref_table_dealloc: (a: number) => void;
+    readonly __wbindgen_free: (a: number, b: number, c: number) => void;
+    readonly __wbindgen_start: () => void;
+}
+
+export type SyncInitInput = BufferSource | WebAssembly.Module;
+
 /**
- * Convert RGB to Oklab (utility function for JS)
+ * Instantiates the given `module`, which can either be bytes or
+ * a precompiled `WebAssembly.Module`.
+ *
+ * @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
+ *
+ * @returns {InitOutput}
  */
-export function rgb_to_oklab(r: number, g: number, b: number): Float32Array;
+export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
 
 /**
- * Get library version
+ * If `module_or_path` is {RequestInfo} or {URL}, makes a request and
+ * for everything else, calls `WebAssembly.instantiate` directly.
+ *
+ * @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
+ *
+ * @returns {Promise<InitOutput>}
  */
-export function version(): string;
+export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;