EDP Optimize

Interactive demo 📦📦 📦

A JavaScript library for reducing image colors and dithering them to fit (color) eInk displays with optimal visual quality.

We are using it for our eInk picture frames at paperlesspaper.

The library works with both front end js (using the Browser Canvas API) and node.js (using node-canvas)

Blogpost

Btw. you can order our new Spectra 6 eInk picture frame here. 🎉

Supported Displays

• AcEP
• Spectra 6

You can easily add your own displays and use custom color tables.

Features

• Dithering Algorithms: Multiple high-quality dithering options to improve color blending and gradients.
• Color Calibration: Match device-specific color characteristics for more accurate results.

Installation

npm install epdoptimize

Usage Example

<canvas id="inputCanvas" />
<canvas id="ditheredCanvas" />
<canvas id="ditheredCanvasWithDeviceColors" />

import { ditherImage, getDefaultPalettes, getDeviceColors } from 'epdoptimize';

// Access the canvas elements
const inputCanvas = document.getElementById("inputCanvas");
const ditheredCanvas =  document.getElementById("ditheredCanvas");
const ditheredCanvasWithDeviceColors =  document.getElementById("ditheredCanvasWithDeviceColors");

const palette = getDefaultPalettes('spectra6');
const spectra6colors = getDeviceColors('spectra6'); // Spectra 6 color set (can be default, spectra6 or acep)

const options = {
  algorithm: 'floydSteinberg',
  palette,
};

// Dither the image
const dithered = ditherImage(inputCanvas, ditheredCanvas, options);

// Convert the colors to the displays native colors
const prepared = replaceColors(ditheredCanvas,ditheredCanvasWithDeviceColors {
    originalColors: palette,
    replaceColors: spectra6colors
});

Dithering Options

| Option | Type | Default | Description | | ------------------------ | ---------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | ditheringType | string | "errorDiffusion" | The main dithering algorithm. Options: errorDiffusion, ordered, random, quantizationOnly. | | errorDiffusionMatrix | string | "floydSteinberg" | Error diffusion kernel. Options: floydSteinberg, falseFloydSteinberg, jarvis, stucki, burkes, sierra3, sierra2, sierra2-4a. | | serpentine | boolean | false | If true, alternates scan direction for each row (serpentine scanning) in error diffusion. | | orderedDitheringType | string | "bayer" | Type of ordered dithering. Currently only bayer is supported. | | orderedDitheringMatrix | [number, number] | [4, 4] | Size of the Bayer matrix for ordered dithering. | | randomDitheringType | string | "blackAndWhite" | Type of random dithering. Options: blackAndWhite, rgb. | | palette | string/array | "default" | Palette to use for quantization. Can be a string (predefined) or a custom array of colors. | | sampleColorsFromImage | boolean | false | If true, generates palette by sampling colors from the image. | | numberOfSampleColors | number | 10 | Number of colors to sample from the image if sampleColorsFromImage is true. |

Add these options to your ditherImage call to customize dithering behavior for your use case.

How It Works

Color Calibration

eInk displays often render colors less vibrantly than their digital values suggest (e.g., a device red like #ff0000 may appear duller in reality). By calibrating with real-world color measurements, the library ensures that dithering and color reduction use the actual appearance of colors on your target display. After processing, you can map the calibrated colors back to the device's required values.

Dithering Algorithms

Dithering helps create the illusion of intermediate colors by distributing quantization errors across neighboring pixels. This is especially important for eInk displays with limited color palettes.

Available Diffusion Algorithms

| Algorithm | Description | | ----------------------- | -------------------------------------------------------------------------------------------------- | | floydSteinberg | Classic Floyd-Steinberg error diffusion. Distributes error to four neighbors. Visually pleasing. | | falseFloydSteinberg | Simplified Floyd-Steinberg. Distributes error to three neighbors. Faster, slightly different look. | | jarvis | Jarvis, Judice, and Ninke. Spreads error over three rows for smooth gradients, more blurring. | | stucki | Similar to Jarvis, different weights. Balances smoothness and sharpness. | | burkes | Simplified Stucki. Fewer neighbors, less computation, good results. | | sierra3 | Sierra-3 (original). High-quality, less blurring than Jarvis. | | sierra2 | Reduced Sierra-3. Fewer neighbors, faster, less diffusion. | | sierra2-4a | Lightweight, fast. Distributes error to three neighbors. Good for speed-critical use. |

Using Your Own Colors

You can use your own custom color palette by passing an array of colors to the palette option. Colors should be provided as hex strings (e.g., #FF0000).

Example:

const myPalette = [
  "#000000", // black
  "#FFFFFF", // white
  "#FF0000", // red
  "#00FF00", // green
  "#0000FF", // blue
];

const options = {
  ditheringType: "errorDiffusion",
  palette: myPalette,
};

const dithered = ditherImage(image, options);

Resources

• paperlesspaper

Credits

• Dither me this
• Inkify

Contributions and feedback are welcome!