smart-downscaler 0.3.0 → 0.3.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pixagram
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -4,6 +4,33 @@ 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
+
+### ⚡ Performance Optimizations
+
+Version 0.3 introduces **preprocessing optimizations** for large images, providing 2-10x speedup while maintaining 80%+ visual quality:
+
+| 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) |
+
+```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)
+```
+
+### Optimization Strategies
+
+1. **Resolution Capping**: Images larger than `max_resolution_mp` are downscaled using fast nearest-neighbor interpolation before processing. Images are only downsized, never upscaled.
+
+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.
+
+3. **Integer Edge Detection**: Uses integer arithmetic for edge detection on preprocessed images for ~2x faster edge computation.
+
+4. **Optimized Tile Processing**: Reduced allocations and stack-allocated arrays for small palettes (≤64 colors).
+
 ## What's New in v0.2
 
 ### 🎨 Oklab Color Space
@@ -45,6 +72,7 @@ config.palette_strategy = 'saturation'; // For vibrant pixel art
 - **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
 
@@ -54,7 +82,7 @@ Add to your `Cargo.toml`:
 
 ```toml
 [dependencies]
-smart-downscaler = "0.2"
+smart-downscaler = "0.3"
 ```
 
 ### WebAssembly (npm)
@@ -87,10 +115,12 @@ fn main() {
     let result = downscale(&img, 64, 64, 16);
     result.save("output.png").unwrap();
     
-    // Advanced: preserve vibrant colors
+    // 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()
     };
     
@@ -113,11 +143,17 @@ const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);
 const config = WasmDownscaleConfig.vibrant();
 config.palette_size = 16;
 
+// Performance settings (already set in presets)
+config.max_resolution_mp = 1.5;
+config.max_color_preprocess = 16384;
+
 // 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;
 
 const result = downscale_rgba(
   imageData.data,
@@ -134,13 +170,13 @@ outputCtx.putImageData(outputData, 0, 0);
 ### Configuration Presets
 
 ```javascript
-// Speed optimized
+// Speed optimized (max_resolution_mp: 1.0, max_color_preprocess: 8192)
 const fast = WasmDownscaleConfig.fast();
 
-// Best quality
+// Best quality (max_resolution_mp: 2.0, max_color_preprocess: 32768)
 const quality = WasmDownscaleConfig.quality();
 
-// Preserve vibrant colors
+// Preserve vibrant colors (max_resolution_mp: 1.5, max_color_preprocess: 16384)
 const vibrant = WasmDownscaleConfig.vibrant();
 
 // Use only exact source colors
@@ -169,7 +205,7 @@ Oklab is a **perceptually uniform** color space where:
 
 ```
 Red (Oklab) + Cyan (Oklab)
-  Oklab Average → Preserves colorfulness ✓
+  Oklab Average → Preserves colorfulness ✔
 ```
 
 ### Visual Comparison
@@ -206,6 +242,10 @@ 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)
 ```
 
 ### Available Functions
@@ -255,6 +295,20 @@ smart-downscaler input.png output.png \
 
 ## 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)
 
 1. Convert all pixels to Oklab color space
@@ -300,13 +354,16 @@ score(color) = oklab_distance(color, tile_avg) × (1 - neighbor_bias - region_bi
 
 ## Performance
 
-Typical performance (single-threaded):
+Typical performance (single-threaded, with preprocessing enabled):
+
+| 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 |
 
-| Image Size | Target Size | Palette | Time |
-|------------|-------------|---------|------|
-| 256×256 | 32×32 | 16 | ~50ms |
-| 512×512 | 64×64 | 32 | ~200ms |
-| 1024×1024 | 128×128 | 32 | ~800ms |
+**Note**: Performance improvements are most significant for large images (>1MP) due to resolution capping.
 
 Enable `parallel` feature for multi-threaded processing.
 
@@ -325,6 +382,8 @@ Enable `parallel` feature for multi-threaded processing.
 | `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
 
@@ -362,6 +421,26 @@ 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

package/package.json

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

package/smart_downscaler.d.ts

@@ -1,121 +1,194 @@
 /* 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;
+    [Symbol.dispose](): void;
+    readonly b: number;
+    readonly count: number;
+    readonly g: number;
+    readonly hex: string;
+    readonly percentage: number;
+    readonly r: number;
+}
+
+/**
+ * Configuration options for the downscaler (JavaScript-compatible)
+ */
 export class WasmDownscaleConfig {
-  free(): void;
-  [Symbol.dispose](): void;
-  /**
-   * Create a new configuration with default values
-   */
-  constructor();
-  /**
-   * Create configuration optimized for speed
-   */
-  static fast(): WasmDownscaleConfig;
-  /**
-   * Create configuration optimized for quality
-   */
-  static quality(): WasmDownscaleConfig;
-  /**
-   * Create configuration optimized for vibrant colors
-   */
-  static vibrant(): WasmDownscaleConfig;
-  /**
-   * Create configuration that uses only exact image colors (medoid)
-   */
-  static exact_colors(): WasmDownscaleConfig;
-  /**
-   * Number of colors in the output palette (default: 16)
-   */
-  palette_size: number;
-  /**
-   * K-Means iterations for palette refinement (default: 5)
-   */
-  kmeans_iterations: number;
-  /**
-   * Weight for neighbor color coherence [0.0, 1.0] (default: 0.3)
-   */
-  neighbor_weight: number;
-  /**
-   * Weight for region membership coherence [0.0, 1.0] (default: 0.2)
-   */
-  region_weight: number;
-  /**
-   * Enable two-pass refinement (default: true)
-   */
-  two_pass_refinement: boolean;
-  /**
-   * Maximum refinement iterations (default: 3)
-   */
-  refinement_iterations: number;
-  /**
-   * Edge weight in tile color computation (default: 0.5)
-   */
-  edge_weight: number;
-  /**
-   * For SLIC: approximate number of superpixels (default: 100)
-   */
-  slic_superpixels: number;
-  /**
-   * For SLIC: compactness factor (default: 10.0)
-   */
-  slic_compactness: number;
-  /**
-   * For hierarchy: merge threshold (default: 15.0)
-   */
-  hierarchy_threshold: number;
-  /**
-   * For hierarchy: minimum region size (default: 4)
-   */
-  hierarchy_min_size: number;
-  /**
-   * Get the segmentation method
-   */
-  segmentation_method: string;
-  /**
-   * Get the palette extraction strategy
-   */
-  palette_strategy: string;
+    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)
+     */
+    kmeans_iterations: number;
+    /**
+     * Maximum unique colors for preprocessing (default: 16384, 0 = disabled)
+     */
+    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;
+    /**
+     * 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 RGB pixel data as Uint8Array (without alpha)
-   */
-  rgb_data(): Uint8Array;
-  /**
-   * Get palette color at index as [r, g, b]
-   */
-  get_palette_color(index: number): Uint8Array;
-  /**
-   * Get output width
-   */
-  readonly width: number;
-  /**
-   * Get output height
-   */
-  readonly height: number;
-  /**
-   * Get RGBA pixel data as Uint8ClampedArray (for ImageData)
-   */
-  readonly data: Uint8ClampedArray;
-  /**
-   * Get palette as Uint8Array (RGB, 3 bytes per color)
-   */
-  readonly palette: Uint8Array;
-  /**
-   * Get palette indices for each pixel
-   */
-  readonly indices: Uint8Array;
-  /**
-   * Get number of colors in palette
-   */
-  readonly palette_size: number;
+    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;
 }
 
+/**
+ * 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;
+
+/**
+ * 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;
+
 /**
  * Main downscaling function for WebAssembly
  *
@@ -152,6 +225,16 @@ export function downscale_with_palette(image_data: Uint8Array, width: number, he
  */
 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
  */
@@ -167,11 +250,21 @@ export function init(): void;
  */
 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
  */

package/smart_downscaler.js

@@ -1,5 +1,9 @@
+/* @ts-self-types="./smart_downscaler.d.ts" */
+
 import * as wasm from "./smart_downscaler_bg.wasm";
-export * from "./smart_downscaler_bg.js";
 import { __wbg_set_wasm } from "./smart_downscaler_bg.js";
 __wbg_set_wasm(wasm);
 wasm.__wbindgen_start();
+export {
+    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";