@opendisplay/epaper-dithering 2.1.4 → 4.0.0

package/README.md

@@ -1,15 +1,20 @@
 # @opendisplay/epaper-dithering
 
-High-quality dithering algorithms for e-paper/e-ink displays, implemented in TypeScript. Works in both browser and Node.js environments.
+[![npm](https://img.shields.io/npm/v/@opendisplay/epaper-dithering?style=flat-square)](https://www.npmjs.com/package/@opendisplay/epaper-dithering)
+
+High-quality dithering algorithms for e-paper/e-ink displays, powered by a Rust/WASM core. Works in both browser and Node.js environments.
 
 ## Features
 
+- **Rust/WASM Core**: Compiled Rust logic bundled inline — no async init, no external files, works everywhere
 - **9 Dithering Algorithms**: From fast ordered dithering to high-quality error diffusion
-- **6 Color Schemes**: MONO, BWR, BWY, BWRY, BWGBRY (Spectra 6), GRAYSCALE_4
-- **Universal**: Works in browser (Canvas API) and Node.js (with sharp/jimp)
-- **Zero Dependencies**: Pure TypeScript, no image library dependencies
-- **Fast**: Optimized typed array operations
-- **Type-Safe**: Full TypeScript support with exported types
+- **8 Color Schemes**: MONO, BWR, BWY, BWRY, BWGBRY (Spectra 6), GRAYSCALE\_4/8/16
+- **Measured Palettes**: Use real display-calibrated colors for accurate dithering (SPECTRA\_7\_3\_6COLOR\_V2, BWRY\_3\_97, and more)
+- **OKLab Color Matching**: Weighted Cartesian OKLab — preserves hue without the achromatic-attractor bug that plagues LCH-weighted approaches
+- **Pre-dither Adjustments**: Per-image exposure, saturation, shadows, highlights, dynamic-range compression, and gamut compression — all orthogonal knobs
+- **Serpentine Scanning**: Alternates row direction to eliminate directional artifacts
+- **Universal**: Works in browser (Canvas API) and Node.js (≥18)
+- **Zero Dependencies**: WASM binary bundled inline, no image library required
 
 ## Installation
 
@@ -17,8 +22,6 @@ High-quality dithering algorithms for e-paper/e-ink displays, implemented in Typ
 npm install @opendisplay/epaper-dithering
 # or
 bun add @opendisplay/epaper-dithering
-# or
-yarn add @opendisplay/epaper-dithering
 ```
 
 ## Quick Start
@@ -28,12 +31,10 @@ yarn add @opendisplay/epaper-dithering
 ```typescript
 import { ditherImage, ColorScheme, DitherMode } from '@opendisplay/epaper-dithering';
 
-// Load image
 const img = new Image();
 img.src = 'photo.jpg';
 await img.decode();
 
-// Convert to ImageBuffer
 const canvas = document.createElement('canvas');
 canvas.width = img.width;
 canvas.height = img.height;
@@ -41,157 +42,130 @@ const ctx = canvas.getContext('2d')!;
 ctx.drawImage(img, 0, 0);
 const imageData = ctx.getImageData(0, 0, img.width, img.height);
 
-const imageBuffer = {
-  width: imageData.width,
-  height: imageData.height,
-  data: imageData.data,
-};
-
-// Dither
 const dithered = ditherImage(
-  imageBuffer,
+  { width: imageData.width, height: imageData.height, data: imageData.data },
   ColorScheme.BWR,
-  DitherMode.FLOYD_STEINBERG
+  { mode: DitherMode.FLOYD_STEINBERG },
 );
 
 // Render result
-const resultCanvas = document.createElement('canvas');
-resultCanvas.width = dithered.width;
-resultCanvas.height = dithered.height;
-const resultCtx = resultCanvas.getContext('2d')!;
-const resultData = resultCtx.createImageData(dithered.width, dithered.height);
-
+const out = ctx.createImageData(dithered.width, dithered.height);
 for (let i = 0; i < dithered.indices.length; i++) {
-  const color = dithered.palette[dithered.indices[i]];
-  resultData.data[i * 4] = color.r;
-  resultData.data[i * 4 + 1] = color.g;
-  resultData.data[i * 4 + 2] = color.b;
-  resultData.data[i * 4 + 3] = 255;
+  const c = dithered.palette[dithered.indices[i]];
+  out.data[i * 4] = c.r; out.data[i * 4 + 1] = c.g;
+  out.data[i * 4 + 2] = c.b; out.data[i * 4 + 3] = 255;
 }
+ctx.putImageData(out, 0, 0);
+```
+
+### Measured Palettes
 
-resultCtx.putImageData(resultData, 0, 0);
-document.body.appendChild(resultCanvas);
+Standard `ColorScheme` values use ideal sRGB colors (e.g. white = 255,255,255). Real e-paper displays reflect significantly less light. Use a measured `ColorPalette` for accurate dithering:
+
+```typescript
+import { ditherImage, SPECTRA_7_3_6COLOR, BWRY_3_97 } from '@opendisplay/epaper-dithering';
+
+// Automatically applies tone compression to fit the display's actual dynamic range
+const dithered = ditherImage(imageBuffer, SPECTRA_7_3_6COLOR, { mode: DitherMode.BURKES });
 ```
 
+Available measured palettes: `SPECTRA_7_3_6COLOR_V2`, `SPECTRA_7_3_6COLOR`, `BWRY_3_97`, `MONO_4_26`, `BWRY_4_2`, `SOLUM_BWR`, `HANSHOW_BWR`, `HANSHOW_BWY`.
+
 ### Node.js (with sharp)
 
 ```typescript
 import sharp from 'sharp';
 import { ditherImage, ColorScheme, DitherMode } from '@opendisplay/epaper-dithering';
 
-// Load image
 const { data, info } = await sharp('photo.jpg')
   .ensureAlpha()
   .raw()
   .toBuffer({ resolveWithObject: true });
 
-const imageBuffer = {
-  width: info.width,
-  height: info.height,
-  data: new Uint8ClampedArray(data),
-};
-
-// Dither
-const dithered = ditherImage(imageBuffer, ColorScheme.BWR, DitherMode.BURKES);
+const dithered = ditherImage(
+  { width: info.width, height: info.height, data: new Uint8ClampedArray(data) },
+  ColorScheme.BWR,
+  { mode: DitherMode.BURKES },
+);
 
-// Convert back to RGBA
 const rgbaBuffer = Buffer.alloc(dithered.width * dithered.height * 4);
 for (let i = 0; i < dithered.indices.length; i++) {
-  const color = dithered.palette[dithered.indices[i]];
-  rgbaBuffer[i * 4] = color.r;
-  rgbaBuffer[i * 4 + 1] = color.g;
-  rgbaBuffer[i * 4 + 2] = color.b;
-  rgbaBuffer[i * 4 + 3] = 255;
+  const c = dithered.palette[dithered.indices[i]];
+  rgbaBuffer[i * 4] = c.r; rgbaBuffer[i * 4 + 1] = c.g;
+  rgbaBuffer[i * 4 + 2] = c.b; rgbaBuffer[i * 4 + 3] = 255;
 }
 
-// Save
-await sharp(rgbaBuffer, {
-  raw: {
-    width: dithered.width,
-    height: dithered.height,
-    channels: 4,
-  },
-})
+await sharp(rgbaBuffer, { raw: { width: dithered.width, height: dithered.height, channels: 4 } })
   .png()
   .toFile('dithered.png');
 ```
 
 ## API Reference
 
-### `ditherImage(image, colorScheme, mode?)`
+### `ditherImage(image, colorScheme, options?)`
 
-Apply dithering algorithm to image for e-paper display.
+```typescript
+ditherImage(image: ImageBuffer, palette: ColorScheme | ColorPalette, options?: DitherOptions): PaletteImageBuffer
+```
+
+| `options` field | Type | Default | Description |
+|---|---|---|---|
+| `mode` | `DitherMode` | `BURKES` | Dithering algorithm |
+| `serpentine` | `boolean` | `true` | Alternate row direction to reduce artifacts |
+| `exposure` | `number` | `1.0` | Linear-RGB exposure multiplier. `2.0` = +1 stop, `0.5` = −1 stop |
+| `saturation` | `number` | `1.0` | OKLab saturation multiplier. `0.0` = grayscale, `>1` = boost. Hue-preserving |
+| `shadows` | `number` | `0.0` | Shadow lift strength (S-curve lower half). `0.0` = off, `1.0` = strong |
+| `highlights` | `number` | `0.0` | Highlight compression strength (S-curve upper half). `0.0` = off, `1.0` = strong |
+| `tone` | `number \| 'auto' \| 'off'` | `'auto'` | Dynamic range compression. `'auto'` = histogram-based; numeric = fixed strength. Ignored for `ColorScheme` |
+| `gamut` | `number \| 'auto' \| 'off'` | `'auto'` | Pre-dither gamut compression. `'auto'` = activate when image exceeds palette gamut; numeric = fixed. Ignored for `ColorScheme` |
 
-**Parameters:**
-- `image: ImageBuffer` - Input image in RGBA format
-- `colorScheme: ColorScheme` - Target e-paper color scheme
-- `mode?: DitherMode` - Dithering algorithm (default: `DitherMode.BURKES`)
+Pre-processing pipeline: `exposure → saturation → shadows/highlights → tone → gamut → dither`. Each step is a no-op at its identity value.
 
-**Returns:** `PaletteImageBuffer` - Palette-indexed image with color information
+Returns `PaletteImageBuffer`.
 
 ### Color Schemes
 
 ```typescript
 enum ColorScheme {
-  MONO = 0,          // Black & White (2 colors)
-  BWR = 1,           // Black, White, Red (3 colors)
-  BWY = 2,           // Black, White, Yellow (3 colors)
-  BWRY = 3,          // Black, White, Red, Yellow (4 colors)
-  BWGBRY = 4,        // Black, White, Green, Blue, Red, Yellow (6 colors)
-  GRAYSCALE_4 = 5,   // 4-level grayscale
+  MONO         = 0,  // Black & White (2 colors)
+  BWR          = 1,  // Black, White, Red (3 colors)
+  BWY          = 2,  // Black, White, Yellow (3 colors)
+  BWRY         = 3,  // Black, White, Red, Yellow (4 colors)
+  BWGBRY       = 4,  // Black, White, Green, Blue, Red, Yellow (6 colors)
+  GRAYSCALE_4  = 5,  // 4-level grayscale
+  GRAYSCALE_8  = 6,  // 8-level grayscale
+  GRAYSCALE_16 = 7,  // 16-level grayscale
 }
 ```
 
 ### Dither Modes
 
-```typescript
-enum DitherMode {
-  NONE = 0,                  // No dithering (direct palette mapping)
-  BURKES = 1,                // Burkes (default - good quality/speed balance)
-  ORDERED = 2,               // Ordered (4×4 Bayer matrix - fast)
-  FLOYD_STEINBERG = 3,       // Floyd-Steinberg (most popular)
-  ATKINSON = 4,              // Atkinson (classic Macintosh style)
-  STUCKI = 5,                // Stucki (high quality)
-  SIERRA = 6,                // Sierra (high quality)
-  SIERRA_LITE = 7,           // Sierra Lite (fast)
-  JARVIS_JUDICE_NINKE = 8,   // Jarvis-Judice-Ninke (highest quality, slowest)
-}
-```
-
-## Algorithm Comparison
-
-| Algorithm | Quality | Speed | Use Case |
-|-----------|---------|-------|----------|
-| NONE | Lowest | Fastest | Testing, solid colors |
-| ORDERED | Low | Very Fast | Simple images, patterns |
-| SIERRA_LITE | Medium | Fast | Quick previews |
-| BURKES | Good | Medium | **Default - best balance** |
-| FLOYD_STEINBERG | Good | Medium | Popular choice, smooth gradients |
-| ATKINSON | Good | Medium | Classic retro aesthetic |
-| SIERRA | High | Medium | Detailed images |
-| STUCKI | Very High | Slow | Photos, high detail |
-| JARVIS_JUDICE_NINKE | Highest | Slowest | Maximum quality |
+| Mode | Quality | Speed | Notes |
+|---|---|---|---|
+| `NONE` | — | Fastest | Direct palette mapping |
+| `ORDERED` | Low | Very fast | 4×4 Bayer matrix |
+| `SIERRA_LITE` | Medium | Fast | 3-neighbor kernel |
+| `FLOYD_STEINBERG` | Good | Medium | Most popular |
+| `BURKES` | Good | Medium | **Default** |
+| `ATKINSON` | Good | Medium | Classic Mac aesthetic |
+| `SIERRA` | High | Medium | — |
+| `STUCKI` | Very high | Slow | — |
+| `JARVIS_JUDICE_NINKE` | Highest | Slowest | — |
 
-## Types
+### Types
 
 ```typescript
-interface RGB {
-  r: number; // 0-255
-  g: number; // 0-255
-  b: number; // 0-255
-}
-
 interface ImageBuffer {
   width: number;
   height: number;
-  data: Uint8ClampedArray; // RGBA format
+  data: Uint8ClampedArray; // RGBA, row-major
 }
 
 interface PaletteImageBuffer {
   width: number;
   height: number;
-  indices: Uint8Array;      // Palette index per pixel
-  palette: RGB[];           // Available colors
+  indices: Uint8Array; // palette index per pixel
+  palette: RGB[];      // sRGB colors
 }
 
 interface ColorPalette {
@@ -200,32 +174,35 @@ interface ColorPalette {
 }
 ```
 
-## Helper Functions
+## Preview Tool
 
-### `getPalette(scheme: ColorScheme): ColorPalette`
+An interactive browser tool for comparing dithering modes and palettes:
 
-Get color palette for a color scheme.
+**Hosted** (always latest release): https://opendisplay.github.io/epaper-dithering/
 
-### `getColorCount(scheme: ColorScheme): number`
-
-Get number of colors in a color scheme.
+**Local** (against your working branch):
+```bash
+cd packages/javascript
+bun run dev
+# → http://localhost:3456/dev.html
+```
 
-### `fromValue(value: number): ColorScheme`
+Features: drag & drop or paste from clipboard, live re-render on every setting change, timing display, palette swatch preview.
 
-Create ColorScheme from firmware integer value (0-5).
+## Development
 
-## Performance
+```bash
+bun install
 
-Expected performance on an 800×600 image:
-- **ORDERED**: ~50ms
-- **SIERRA_LITE**: ~100ms
-- **BURKES/FLOYD_STEINBERG**: ~150ms
-- **SIERRA/ATKINSON**: ~200ms
-- **STUCKI/JARVIS**: ~300ms
+# When Rust source changes, rebuild the WASM (from repo root):
+wasm-pack build packages/rust/wasm --target bundler --out-dir ../../javascript/src/wasm-core
 
-Performance varies by device and JavaScript engine.
+bun run test        # vitest
+bun run build       # tsup → dist/
+bun run type-check
+```
 
 ## Related Projects
 
-- **Python**: [`epaper-dithering`](https://pypi.org/project/epaper-dithering/) - Python implementation
-- **OpenDisplay**: [`py-opendisplay`](https://github.com/OpenDisplay-org/py-opendisplay) - Python library for OpenDisplay BLE Devices
+- **Python**: [`epaper-dithering`](https://pypi.org/project/epaper-dithering/) — Python package, shares the same Rust core
+- **OpenDisplay**: [`py-opendisplay`](https://github.com/OpenDisplay-org/py-opendisplay) — Python library for OpenDisplay BLE devices