smart-downscaler 0.3.10 → 0.4.0

package/README.md

@@ -4,27 +4,6 @@ A sophisticated Rust library for intelligent image downscaling with focus on pix
 
 **Available as both a native Rust library and a WebAssembly module for browser/Node.js usage.**
 
-
-## What's New in v0.3.5
-
-### ⚡ Performance: Direct LUT Optimization
-
-The preprocessing pipeline has been completely rewritten for speed:
-
-| 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      |
-
-**Key Optimizations:**
-
-1. **Direct Lookup Table**: Uses a 64MB flat array to map 24-bit RGB colors to unique indices instantly. No hashing overhead.
-
-2. **RGBA-Only Preprocessing**: Resolution capping and quantization now happen strictly in RGBA space before any expensive Oklab math.
-
-3. **Oklab Caching**: If color reduction is enabled (default), Oklab conversion is only performed once per unique color, not per pixel.
-
 <!---->
 
     const config = new WasmDownscaleConfig();
@@ -261,4 +240,98 @@ MIT
 - K-Means++ initialization
 
 - VTracer hierarchical clustering approach
-
+Smart Pixel Art DownscalerA 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.4.0🐞 Critical Fix: Large Image StabilityFixed an integer overflow issue that caused large images (typically > 0.5MP) to render as a solid brown/dark color. The accumulation pipeline now uses 64-bit integers for correctness while preserving the speed of the fixed-point arithmetic.⚡ Performance: Direct LUT OptimizationThe preprocessing pipeline has been completely rewritten for speed:Old Method (v0.3)New Method (v0.4.0)ImprovementHashMap Pre-quantizationDirect LUT (64MB)O(1) AccessOklab Conversion on All PixelsCached Oklab~100x Fewer Math OpsIterative Resolution CapOne-pass NNInstant ResizingKey Optimizations:Direct Lookup Table: Uses a 64MB flat array to map 24-bit RGB colors to unique indices instantly. No hashing overhead.RGBA-Only Preprocessing: Resolution capping and quantization now happen strictly in RGBA space before any expensive Oklab math.Oklab Caching: If color reduction is enabled (default), Oklab conversion is only performed once per unique color, not per pixel.<!---->const config = new WasmDownscaleConfig();
+config.max_resolution_mp = 1.5;       // Fast nearest-neighbor cap
+config.max_color_preprocess = 16384;  // Direct LUT quantization
+🎯 K-Centroid Tile LogicNew k_centroid configuration allows finer control over how a source tile is reduced to a single representative color before matching:ModeNameDescriptionBest For1AverageSimple average of all pixels (Default)Smooth gradients, noise reduction2DominantAverage of the largest color cluster ($k=2$)Sharp edges, separating foreground/background3ForemostAverage of the "foremost" distinct part ($k=3$)Complex textures, detailed sprites// Example: Use dominant part for sharper edges
+config.k_centroid = 2;
+config.k_centroid_iterations = 2;
+Configuration ReferenceDownscaleConfigFieldTypeDefaultDescriptionk_centroidusize11=Avg, 2=Dominant, 3=Foremostk_centroid_iterationsusize0Refinement for tile colormax_resolution_mpf321.6Resolution cap (0=disabled)max_color_preprocessusize16384LUT Quantization limitsegmentationMethodHierarchyRegion detection methodCommand 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
+FeaturesOklab Color Space: Modern perceptual color space with superior hue linearityGlobal Palette Extraction: Median Cut + K-Means++ refinementMultiple Segmentation Methods:SLIC superpixels for fast, balanced regionsVTracer-style hierarchical clustering for content-aware boundariesUnion-find based fast hierarchical clusteringEdge-Aware Processing: Sobel/Scharr edge detection to preserve boundariesNeighbor-Coherent Assignment: Spatial coherence through neighbor and region votingTwo-Pass Refinement: Iterative optimization for smooth resultsWebAssembly Support: Run in browsers with full performancePerformance Preprocessing: Resolution capping and color pre-quantizationInstallationNative (Rust)Add to your Cargo.toml:[dependencies]
+smart-downscaler = "0.4.0"
+WebAssembly (npm)npm install smart-downscaler
+Quick StartWebAssembly (Browser)import init, { WasmDownscaleConfig, downscale_rgba } from 'smart-downscaler';
+
+await init();
+
+// Create config
+const config = new WasmDownscaleConfig();
+
+// 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
+
+// QUALITY: New K-Centroid settings
+config.k_centroid = 2;                // 2 = Dominant Color Mode
+config.k_centroid_iterations = 2;     // Refine the dominant color
+
+// Standard settings
+config.palette_size = 16;
+config.palette_strategy = 'oklab';
+
+// Run
+const result = downscale_rgba(
+  imageData.data,
+  imageData.width, imageData.height,
+  64, 64, // Target size
+  config
+);
+
+// Draw result
+const output = new ImageData(result.data, result.width, result.height);
+ctx.putImageData(output, 0, 0);
+Configuration Presets// 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();
+
+// 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();
+Why Oklab?Traditional RGB-based palette extraction has fundamental problems:The Problem: RGB Averaging Desaturates ColorsRed [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 SpaceOklab is a perceptually uniform color space where:Euclidean distance = perceived color differenceAveraging preserves hue and saturationInterpolations look natural<!---->Red (Oklab) + Cyan (Oklab)
+  Oklab Average → Preserves colorfulness ✔
+API ReferenceWasmDownscaleConfigconst 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;
+
+// Segmentation
+config.segmentation_method = 'hierarchy_fast'; // 'none', 'slic', 'hierarchy', 'hierarchy_fast'
+
+// 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)
+
+// Tile Logic
+config.k_centroid = 1;                // 1=Avg, 2=Dom, 3=Foremost
+config.k_centroid_iterations = 0;     // Refine the dominant color
+Available FunctionsFunctionDescriptiondownscale(data, w, h, tw, th, config?)Main downscale functiondownscale_rgba(data, w, h, tw, th, config?)For Uint8ClampedArray inputdownscale_simple(data, w, h, tw, th, colors)Simple APIdownscale_with_palette(...)Use custom paletteextract_palette_from_image(data, w, h, colors, iters, strategy?)Extract palette onlyquantize_to_palette(data, w, h, palette)Quantize without resizingget_palette_strategies()List available strategiesWasmDownscaleResultresult.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
+LicenseMITCreditsOklab color space by Björn OttossonSLIC superpixel algorithmK-Means++ initializationVTracer hierarchical clustering approach

package/package.json

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

package/smart_downscaler.d.ts

@@ -1,49 +1,44 @@
 /* tslint:disable */
 /* eslint-disable */
 
+/**
+ * Result of color analysis
+ */
 export class ColorAnalysisResult {
     private constructor();
     free(): void;
     [Symbol.dispose](): void;
-    getColor(index: number): ColorEntry | undefined;
-    getColorsFlat(): Uint8Array;
-    toJson(): any;
-    readonly colorCount: number;
+    /**
+     * 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 totalPixels: number;
+    readonly total_pixels: number;
 }
 
+/**
+ * A single color entry with statistics
+ */
 export class ColorEntry {
     private constructor();
     free(): void;
     [Symbol.dispose](): void;
+    readonly b: number;
+    readonly count: number;
+    readonly g: number;
     readonly hex: string;
-    b: number;
-    count: number;
-    g: number;
-    percentage: number;
-    r: number;
-}
-
-export class SmartDownscaler {
-    free(): void;
-    [Symbol.dispose](): void;
-    constructor();
-    process(image_data: Uint8Array, width: number, height: number, target_width: number, target_height: number): WasmDownscaleResult;
-    set_edge_weight(weight: number): void;
-    set_hierarchy_params(threshold: number): void;
-    set_k_centroid(k: number): void;
-    set_k_centroid_iterations(iterations: number): void;
-    set_kmeans_iterations(iterations: number): void;
-    set_max_color_preprocess(count: number): void;
-    set_max_resolution(mp: number): void;
-    set_neighbor_weight(weight: number): void;
-    set_palette_size(size: number): void;
-    set_palette_strategy(strategy: number): void;
-    set_refinement_iterations(iterations: number): void;
-    set_region_weight(weight: number): void;
-    set_segmentation_method(method: number): void;
-    set_slic_params(region_size: number, _compactness: number, _iterations: number): void;
+    readonly percentage: number;
+    readonly r: number;
 }
 
 export class WasmDownscaleConfig {
@@ -53,55 +48,118 @@ export class WasmDownscaleConfig {
     static fast(): WasmDownscaleConfig;
     constructor();
     static quality(): WasmDownscaleConfig;
-    set_edge_weight(weight: number): void;
-    set_hierarchy_params(threshold: number): void;
-    set_k_centroid(k: number): void;
-    set_k_centroid_iterations(iterations: number): void;
-    set_kmeans_iterations(iterations: number): void;
-    set_max_color_preprocess(count: number): void;
-    set_max_resolution(mp: number): void;
-    set_neighbor_weight(weight: number): void;
-    set_palette_size(size: number): void;
-    set_palette_strategy(strategy: number): void;
-    set_refinement_iterations(iterations: number): void;
-    set_region_weight(weight: number): void;
-    set_segmentation_method(method: number): void;
-    set_slic_params(region_size: number, _compactness: number, _iterations: number): void;
     static vibrant(): WasmDownscaleConfig;
+    edge_weight: number;
+    hierarchy_min_size: number;
+    hierarchy_threshold: number;
+    /**
+     * Iterations for tile centroid
+     */
+    k_centroid_iterations: number;
+    /**
+     * K-Means centroid mode (1=Avg, 2=Dom, 3=Foremost)
+     */
+    k_centroid: number;
+    kmeans_iterations: number;
+    max_color_preprocess: number;
+    max_resolution_mp: number;
+    neighbor_weight: number;
+    palette_size: number;
+    refinement_iterations: number;
+    region_weight: number;
+    slic_compactness: number;
+    slic_superpixels: number;
+    two_pass_refinement: boolean;
+    palette_strategy: string;
+    segmentation_method: string;
 }
 
 export class WasmDownscaleResult {
     private constructor();
     free(): void;
     [Symbol.dispose](): void;
-    get_indices(): Uint8Array;
-    get_palette_data(): Uint8Array;
-    get_rgba_data(): Uint8Array;
-    height(): number;
-    width(): number;
-    palette_size: number;
+    rgb_data(): Uint8Array;
+    readonly data: Uint8ClampedArray;
+    readonly height: number;
+    readonly indices: Uint8Array;
+    readonly palette: Uint8Array;
+    readonly palette_size: number;
+    readonly width: number;
 }
 
+/**
+ * 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
+ */
 export function analyze_colors(image_data: Uint8Array, max_colors: number, sort_method: string): ColorAnalysisResult;
 
 /**
- * Standard downscaling
+ * Compute perceptual color distance between two RGB colors
  */
-export function downscale_rgba(image_data: Uint8Array, width: number, height: number, target_width: number, target_height: number, config: WasmDownscaleConfig): WasmDownscaleResult;
+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;
 
 /**
- * Downscaling with a specific palette
+ * Extract a color palette from an image without downscaling
  */
-export function downscale_with_palette(image_data: Uint8Array, width: number, height: number, target_width: number, target_height: number, palette_flat: Uint8Array, config: WasmDownscaleConfig): WasmDownscaleResult;
+export function extract_palette_from_image(image_data: Uint8Array, _width: number, _height: number, num_colors: number, kmeans_iterations: number, strategy?: string | null): Uint8Array;
 
 /**
- * Extract palette from image
+ * Get chroma (saturation) of an RGB color
  */
-export function extract_palette_from_image(image_data: Uint8Array, width: number, height: number, num_colors: number, kmeans_iterations: number): Uint8Array;
+export function get_chroma(r: number, g: number, b: number): number;
 
 /**
- * Quantize image to palette (No resizing)
+ * Get lightness of an RGB color in Oklab space
  */
-export function quantize_to_palette(image_data: Uint8Array, width: number, height: number, palette_flat: Uint8Array): WasmDownscaleResult;
+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
+ */
+export function quantize_to_palette(image_data: Uint8Array, width: number, height: number, palette_data: Uint8Array): WasmDownscaleResult;
+
+/**
+ * Convert RGB to Oklab (utility function for JS)
+ */
+export function rgb_to_oklab(r: number, g: number, b: number): Float32Array;
+
+/**
+ * Get library version
+ */
 export function version(): string;

package/smart_downscaler.js

@@ -5,5 +5,5 @@ import { __wbg_set_wasm } from "./smart_downscaler_bg.js";
 __wbg_set_wasm(wasm);
 wasm.__wbindgen_start();
 export {
-    ColorAnalysisResult, ColorEntry, SmartDownscaler, WasmDownscaleConfig, WasmDownscaleResult, analyze_colors, downscale_rgba, downscale_with_palette, extract_palette_from_image, quantize_to_palette, version
+    ColorAnalysisResult, ColorEntry, WasmDownscaleConfig, WasmDownscaleResult, analyze_colors, color_distance, downscale, downscale_rgba, downscale_simple, downscale_with_palette, extract_palette_from_image, get_chroma, get_lightness, get_palette_strategies, init, log, oklab_to_rgb, quantize_to_palette, rgb_to_oklab, version
 } from "./smart_downscaler_bg.js";