smart-downscaler 0.6.2 → 0.6.3

package/README.md

@@ -35,7 +35,10 @@ 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) |
+| **Rare-Color Preservation** | Saliency weighting + slot reservation keeps small important colors (lips, eyes) |
+| **Chroma Recovery** | Restores saturation lost to color merging, by perceptual difference |
+| **Skin-Tone Isolation** | Keeps skin and non-skin colors in separate palette domains |
+| **Reusable Preprocessing** | Prepare an image once, downscale to many sizes cheaply |
 | **Performance Preprocessing** | Resolution capping and color pre-quantization |
 | **WebAssembly Support** | Full browser compatibility with near-native speed |
 
@@ -171,10 +174,12 @@ println!("Palette: {} colors", result.palette.len());
 | **Tile Processing** |||||
 | `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) |
+| **Rare-Color & Saturation** |||||
+| `color_rarity` | `f32` | `0.0` | `0.0-1.0` | Damps frequency vote so 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 local-contrast saliency (`0`=off) |
+| `reserve_colors` | `usize` | `0` | `0 - palette_size` | Reserve N slots for distinct, important, under-represented source colors (`0`=off) |
+| `chroma_recovery` | `f32` | `0.0` | `0.0-1.0+` | Restore chroma lost to merging toward source mean chroma, constant hue, gamut-clamped (`0`=off) |
+| `skin_protection` | `f32` | `0.0` | `0.0-1.0` | Isolate skin vs non-skin into separate palette domains + quantization penalty (`0`=off) |
 
 ---
 
@@ -231,7 +236,7 @@ Controls how each source tile is reduced to a single representative color:
 | **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.
+> **Note:** Mode `2` (Dominant) snaps a mixed tile to its *larger* cluster, discarding thin minority colors — a tile that is 60% skin / 40% lip becomes pure skin. For faces and 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
@@ -323,6 +328,36 @@ const result = downscale_with_palette(
 
 ---
 
+### Prepare / Reuse Functions
+
+#### `prepare(data, width, height, config?)` / `prepare_rgba(data, width, height, config?)`
+
+Run target-independent work (resolution cap, color pre-quantization, segmentation)
+once and return a reusable handle. `prepare` takes `Uint8Array`; `prepare_rgba` takes
+`Uint8ClampedArray` (from canvas `getImageData`).
+
+```javascript
+const prepared = prepare_rgba(imageData.data, imageData.width, imageData.height, config);
+// prepared.width / prepared.height — dimensions after any resolution cap
+prepared.free(); // release WASM memory when finished
+```
+
+#### `downscale_prepared(prepared, targetWidth, targetHeight, config?)`
+
+Downscale a prepared image. The optional `config` overrides per-target knobs
+(`palette_size`, `k_centroid`, `chroma_recovery`, `skin_protection`, …); preprocess
+and segmentation settings always come from prepare time.
+
+```javascript
+const result = downscale_prepared(prepared, 128, 128, sizeConfig);
+```
+
+#### `downscale_prepared_with_palette(prepared, targetWidth, targetHeight, palette, config?)`
+
+As above, with a caller-supplied `Uint8Array` RGB palette.
+
+---
+
 ### Palette Functions
 
 #### `extract_palette_from_image(data, width, height, numColors, iterations, strategy?)`
@@ -508,58 +543,140 @@ const exact = WasmDownscaleConfig.exact_colors();
 
 ### Preset Comparison
 
-| Preset | Palette | K-Means | Segmentation | K-Centroid | Rare-Color¹ | Speed |
-|--------|---------|---------|--------------|------------|-------------|-------|
+| Preset | Palette | K-Means | Segmentation | K-Centroid | Rare/Sat/Skin¹ | 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) | 🐢 |
+| `vibrant()` | 24 | 8 | hierarchy_fast | 2 (dom) | reserve+rarity+chroma(0.7) | ⚡ |
+| `quality()` | 32 | 10 | hierarchy | 2 (dom) | reserve+rarity+chroma(0.6)+skin(0.5) | 🐢 |
 | `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`.
+¹ For the strongest thin-feature retention on faces, additionally set `k_centroid = 4`.
 
 ---
 
 ## Advanced Usage
 
+### Reusing Preprocessing Across Sizes (Performance)
+
+Resolution capping, color pre-quantization, and region segmentation depend only on
+the **source** image, not the target size. When you downscale the same source to
+several sizes (e.g. multiple previews), repeating that work each time is wasted.
+`prepare` runs it **once**; `downscale_prepared` then only does palette extraction
+and tiling per size.
+
+```javascript
+import init, { prepare_rgba, downscale_prepared, WasmDownscaleConfig } from 'smart-downscaler';
+await init();
+
+const base = new WasmDownscaleConfig();
+base.segmentation_method = 'hierarchy_fast';
+base.max_resolution_mp = 2.048;
+base.max_color_preprocess = 4096;
+
+// Once per source image:
+const prepared = prepare_rgba(imageData.data, imageData.width, imageData.height, base);
+
+// Many times, cheaply — palette_size and target size may differ each call:
+for (const { w, h, colors } of sizes) {
+  const cfg = new WasmDownscaleConfig();
+  cfg.palette_size = colors;
+  cfg.k_centroid = 4;
+  cfg.reserve_colors = Math.round(colors / 8);
+  cfg.chroma_recovery = 0.6;
+  cfg.skin_protection = 0.5;
+  const result = downscale_prepared(prepared, w, h, cfg);
+  // ... use result ...
+}
+
+prepared.free(); // release WASM memory when done (also freed on GC)
+```
+
+**Contract:** the prepared image fixes `max_resolution_mp`, `max_color_preprocess`,
+and `segmentation_*` at prepare time. `downscale_prepared` overlays per-target knobs
+(`palette_size`, `k_centroid`, `chroma_recovery`, `skin_protection`, …) but never
+re-runs preprocessing or segmentation. Change any of the prepare-time settings →
+call `prepare` again. `prepare` / `prepare_rgba` and `downscale_prepared` /
+`downscale_prepared_with_palette` mirror the one-shot functions.
+
+In Rust:
+
+```rust
+use smart_downscaler::{prepare_image, smart_downscale_prepared, DownscaleConfig};
+
+let prepared = prepare_image(&pixels, w, h, &config);          // once
+let small = smart_downscale_prepared(&prepared, 128, 128, &config_s);  // reuse
+let large = smart_downscale_prepared(&prepared, 256, 256, &config_l);  // reuse
+```
+
 ### 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:
+Palette extraction is **area-weighted**: a color covering a large region gets many
+"votes", so small but important colors — lips, eyes, a logo, a highlight — easily
+merge into dominant tones at low palette sizes (16–64). Counteract this with:
 
 | 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`. |
+| `reserve_colors` | **Hard guarantee.** Reserves N slots filled with exact source colors that are far from the rest of the palette *and* important. Most reliable fix. | Always, for portraits. ~`palette_size / 8`. |
+| `detail_boost` | Weights extraction toward **detail-rich regions** via a local-contrast saliency map (measured at the downscale radius, so it targets features thin enough to be averaged away). | When the important color is in a high-detail area. `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.
+Pair these with `k_centroid = 4` (Salient) so the *tile* stage doesn't discard the
+same minority colors a correct palette preserved.
+
+### Restoring Saturation (Chroma Recovery)
+
+Averaging colors in Oklab during median-cut/k-means pulls the result *inward* — the
+mean of two hues is less colorful than either. `chroma_recovery` undoes this **by
+perceptual difference**: each palette color is pushed back toward the count-weighted
+**mean chroma of the source colors it represents**, at constant hue and lightness,
+then clamped to the sRGB gamut. It only ever *increases* saturation, never reduces it.
+
+```javascript
+config.chroma_recovery = 0.6;  // 0 = off, ~0.6 natural, 1.0 = full restoration, >1 = punchy
+```
+
+This is a global de-wash that fixes the "muddy" look of low-palette output; it is
+independent of (and composes with) the rare-color knobs above.
+
+### Isolating Skin Tones
+
+Skin clusters tightly in the YCbCr chroma plane (`80 ≤ Cb ≤ 120`, `133 ≤ Cr ≤ 173`).
+With `skin_protection > 0`, skin and non-skin colors are extracted in **separate
+domains** — a single palette bucket never mixes the two, so skin never picks up a
+muddy blend with hair/background and vice-versa. Palette slots are split between the
+domains by population (each guaranteed at least one). The same value also acts as a
+**quantization penalty**: a skin tile prefers skin palette colors, a non-skin tile
+prefers non-skin.
+
+```javascript
+config.skin_protection = 0.5;  // 0 = off, ~0.5 typical
+```
+
+> Lips are reddish and usually pass the skin test, so they live in the *skin* domain
+> — `skin_protection` won't separate lips from skin. Use `reserve_colors` /
+> `k_centroid = 4` for that; they operate *within* the skin domain, so the two
+> features compose: skin gets its own budget, and a distinct lip is preserved inside it.
+
+### Recommended Config for Faces / Portraits
 
 ```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.palette_strategy  = 'oklab';     // honors color_rarity / detail_boost
+config.k_centroid        = 4;           // salient tile color
 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.chroma_recovery   = 0.6;         // restore saturation lost to merging
+config.skin_protection   = 0.5;         // separate skin / non-skin
 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.
+> **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
 

package/package.json

@@ -1,11 +1,10 @@
 {
   "name": "smart-downscaler",
-  "type": "module",
   "collaborators": [
     "Pixagram"
   ],
   "description": "Intelligent pixel art downscaler with region-aware color quantization",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -14,15 +13,10 @@
   "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": [
     "pixel-art",
     "image-processing",
@@ -30,4 +24,4 @@
     "quantization",
     "wasm"
   ]
-}
+}

package/smart_downscaler.d.ts

@@ -33,6 +33,10 @@ export class WasmDownscaleConfig {
     constructor();
     static quality(): WasmDownscaleConfig;
     static vibrant(): WasmDownscaleConfig;
+    /**
+     * Restore chroma lost to merging (constant hue, gamut-clamped). 0.0 = off, ~0.6 natural.
+     */
+    chroma_recovery: number;
     /**
      * Rare-color preservation: 0.0 = pure area weighting, 1.0 = strong (count^0.5).
      */
@@ -57,6 +61,10 @@ export class WasmDownscaleConfig {
      * Reserve N palette slots for distinct, important, under-represented colors. 0 = off.
      */
     reserve_colors: number;
+    /**
+     * Isolate skin tones from non-skin (separate domains + mismatch penalty). 0.0 = off, ~0.5.
+     */
+    skin_protection: number;
     slic_compactness: number;
     slic_superpixels: number;
     two_pass_refinement: boolean;
@@ -77,6 +85,22 @@ export class WasmDownscaleResult {
     readonly width: number;
 }
 
+/**
+ * Opaque handle holding the prepared (preprocessed + segmented) source image.
+ * Build with [`prepare`] / [`prepare_rgba`], reuse with [`downscale_prepared`].
+ *
+ * The segmentation is fixed at prepare time from the config you pass. Palette
+ * size and target dimensions may differ on every [`downscale_prepared`] call.
+ * If you change resolution / color-preprocess / segmentation settings, prepare again.
+ */
+export class WasmPreparedImage {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    readonly height: number;
+    readonly width: number;
+}
+
 /**
  * Analyze colors — FIX: uses HashMap<u32, usize> for O(1) lookup (was O(n) linear scan)
  */
@@ -86,6 +110,19 @@ export function color_distance(r1: number, g1: number, b1: number, r2: number, g
 
 export function downscale(image_data: Uint8Array, width: number, height: number, target_width: number, target_height: number, config?: WasmDownscaleConfig | null): WasmDownscaleResult;
 
+/**
+ * Downscale a prepared image. Pass an optional `config` to override per-target
+ * knobs (palette_size, k_centroid, chroma_recovery, skin_protection, …). The
+ * preprocess/segmentation settings always come from prepare time. When `config`
+ * is omitted, the prepare-time config is reused as-is.
+ */
+export function downscale_prepared(prepared: WasmPreparedImage, target_width: number, target_height: number, config?: WasmDownscaleConfig | null): WasmDownscaleResult;
+
+/**
+ * Downscale a prepared image with a caller-supplied palette.
+ */
+export function downscale_prepared_with_palette(prepared: WasmPreparedImage, target_width: number, target_height: number, palette_data: Uint8Array, 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;
 
 export function downscale_simple(image_data: Uint8Array, width: number, height: number, target_width: number, target_height: number, num_colors: number): WasmDownscaleResult;
@@ -106,6 +143,16 @@ export function log(message: string): void;
 
 export function oklab_to_rgb(l: number, a: number, b: number): Uint8Array;
 
+/**
+ * Prepare from a `Uint8Array` (RGBA).
+ */
+export function prepare(image_data: Uint8Array, width: number, height: number, config?: WasmDownscaleConfig | null): WasmPreparedImage;
+
+/**
+ * Prepare from a `Uint8ClampedArray` (canvas `getImageData`).
+ */
+export function prepare_rgba(image_data: Uint8ClampedArray, width: number, height: number, config?: WasmDownscaleConfig | null): WasmPreparedImage;
+
 /**
  * Quantize to palette — FIX: compute Oklab once per pixel (was twice)
  */