epaper-dithering

A monorepo containing dithering algorithm implementations for e-paper/e-ink displays in multiple languages.

Packages

Python (packages/python/)

Dithering algorithms for e-paper displays. Published to PyPI as epaper-dithering.

Installation:

pip install epaper-dithering

Usage:

from PIL import Image
from epaper_dithering import dither_image, ColorScheme, DitherMode

img = Image.open("photo.jpg")
dithered = dither_image(img, ColorScheme.BWR, DitherMode.FLOYD_STEINBERG)
dithered.save("output.png")

See packages/python/README.md for detailed documentation.

JavaScript/TypeScript (packages/javascript/)

Dithering algorithms for e-paper displays in TypeScript. Published to npm as @opendisplay/epaper-dithering.

Installation:

npm install @opendisplay/epaper-dithering
# or
bun add @opendisplay/epaper-dithering

Usage (Browser):

import { ditherImage, ColorScheme, DitherMode } from '@opendisplay/epaper-dithering';

// Create ImageBuffer from Canvas
const canvas = document.createElement('canvas');
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,
};

const dithered = ditherImage(imageBuffer, ColorScheme.BWR, DitherMode.FLOYD_STEINBERG);

Usage (Node.js with sharp):

import sharp from 'sharp';
import { ditherImage, ColorScheme, DitherMode } from '@opendisplay/epaper-dithering';

const { data, info } = await sharp('photo.jpg')
  .ensureAlpha()
  .raw()
  .toBuffer({ resolveWithObject: true });

const imageBuffer = {
  width: info.width,
  height: info.height,
  data: new Uint8ClampedArray(data),
};

const dithered = ditherImage(imageBuffer, ColorScheme.BWR, DitherMode.BURKES);

See packages/javascript/README.md for detailed documentation.

Features

• 9 Dithering Algorithms: NONE, BURKES, ORDERED, FLOYD_STEINBERG, ATKINSON, STUCKI, SIERRA, SIERRA_LITE, JARVIS_JUDICE_NINKE
• 6 Color Schemes: MONO, BWR, BWY, BWRY, BWGBRY (Spectra 6), GRAYSCALE_4
• Multiple Languages: Python and JavaScript/TypeScript implementations
• Universal: Works in Python, Node.js, and browser environments
• Type-Safe: Full type coverage in both languages

Development

Python Development

cd packages/python
uv sync --all-extras
uv run pytest tests/ -v
uv run ruff check src/ tests/
uv run mypy src/epaper_dithering

JavaScript Development

cd packages/javascript
bun install
bun test
bun run build

Repository Structure

epaper-dithering/
├── packages/
│   ├── python/          # Python implementation
│   │   ├── src/
│   │   ├── tests/
│   │   └── pyproject.toml
│   └── javascript/      # TypeScript/JavaScript implementation
│       ├── src/
│       ├── tests/
│       └── package.json
├── fixtures/            # Shared test fixtures
│   ├── images/          # Input test images
│   └── expected/        # Expected dithered outputs
├── .github/
│   └── workflows/       # CI/CD for both packages
├── docs/                # Shared documentation
└── README.md

Related Projects

• py-opendisplay: Python library for OpenDisplay BLE e-paper devices

Future Plans

• Base colors on real e-paper display colors (perceptual color matching)
• Add s-curve tone mapping for better contrast
• Rust implementation with bindings for Python/JavaScript/other languages
• Web-based demo/playground