epaper-dithering 0.1.0

Dithering algorithms for e-paper/e-ink displays

epaper-dithering

Dithering algorithms optimized for e-ink/e-paper displays with limited color palettes.

Installation

pip install epaper-dithering

Quick Start

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

# Load your image
image = Image.open("photo.jpg")

# Apply dithering for a black/white/red display
dithered = dither_image(image, ColorScheme.BWR, DitherMode.FLOYD_STEINBERG)

# Save result
dithered.save("output.png")

Supported Color Schemes

• MONO - Black and white (1-bit)
• BWR - Black, white, red (3-color)
• BWY - Black, white, yellow (3-color)
• BWRY - Black, white, red, yellow (4-color)
• BWGBRY - Black, white, green, blue, red, yellow (6-color Spectra)
• GRAYSCALE_4 - 4-level grayscale

Dithering Algorithms

Algorithm	Quality	Speed	Best For
NONE	Lowest	Fastest	Testing, simple graphics
ORDERED	Low	Very Fast	Patterns, textures
SIERRA_LITE	Medium	Fast	Quick results
BURKES	Good	Medium	General purpose (default)
FLOYD_STEINBERG	Good	Medium	Popular standard
SIERRA	High	Medium	Balanced quality
ATKINSON	Good	Medium	High contrast, artistic
STUCKI	Very High	Slow	Maximum quality
JARVIS_JUDICE_NINKE	Highest	Slowest	Smooth gradients

Usage Examples

Basic Usage

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

# Load image
img = Image.open("photo.jpg")

# Apply Floyd-Steinberg dithering for BWR display
result = dither_image(img, ColorScheme.BWR, DitherMode.FLOYD_STEINBERG)
result.save("dithered.png")

All Color Schemes

from epaper_dithering import ColorScheme

# Black and white only
dithered = dither_image(img, ColorScheme.MONO)

# Black, white, and red (common for e-paper tags)
dithered = dither_image(img, ColorScheme.BWR)

# Grayscale (4 levels)
dithered = dither_image(img, ColorScheme.GRAYSCALE_4)

# 6-color display (Spectra)
dithered = dither_image(img, ColorScheme.BWGBRY)

Development

# Install with dev dependencies
uv sync --all-extras

# Run tests
uv run pytest tests/ -v

# Run tests with coverage
uv run pytest tests/ --cov=src/epaper_dithering

# Lint
uv run ruff check src/ tests/

# Type check
uv run mypy src/epaper_dithering

Credits

Originally developed as part of py-opendisplay. Extracted to enable reuse across multiple e-paper display projects.