164 lines
4.2 KiB
Markdown
164 lines
4.2 KiB
Markdown
# Dithering Test Suite
|
||
|
||
Local testing suite for comparing dithering algorithms on the 6-color e-ink display.
|
||
|
||
## Setup
|
||
|
||
```bash
|
||
cd dither_test
|
||
pip install pillow numpy
|
||
```
|
||
|
||
For the interactive preview (optional):
|
||
```bash
|
||
# Tkinter is usually included with Python
|
||
# On Debian/Ubuntu if missing:
|
||
sudo apt-get install python3-tk
|
||
```
|
||
|
||
## Quick Start
|
||
|
||
### Compare all algorithms
|
||
```bash
|
||
python compare.py photo.jpg --html
|
||
# Open dither_output/photo_report.html in browser
|
||
```
|
||
|
||
### Interactive preview
|
||
```bash
|
||
python preview.py photo.jpg
|
||
# Use arrow keys to cycle through algorithms
|
||
```
|
||
|
||
## Tools
|
||
|
||
### `compare.py` - Batch Comparison Tool
|
||
|
||
Generate comparison outputs for multiple dithering algorithms.
|
||
|
||
```bash
|
||
# Compare all algorithms, save individual images
|
||
python compare.py image.jpg
|
||
|
||
# Compare specific algorithms only
|
||
python compare.py image.jpg -a floyd_steinberg atkinson jarvis
|
||
|
||
# Generate visual grid comparison
|
||
python compare.py image.jpg --grid
|
||
|
||
# Generate HTML report (recommended)
|
||
python compare.py image.jpg --html
|
||
|
||
# Side-by-side comparison of two algorithms
|
||
python compare.py image.jpg --side-by-side atkinson pil_fs
|
||
|
||
# With rotation
|
||
python compare.py image.jpg --html -r 90
|
||
|
||
# List available algorithms
|
||
python compare.py --list
|
||
```
|
||
|
||
### `preview.py` - Interactive Preview
|
||
|
||
Real-time preview with keyboard navigation.
|
||
|
||
```bash
|
||
python preview.py image.jpg
|
||
```
|
||
|
||
**Keyboard shortcuts:**
|
||
- `←` / `→` or `A` / `D` - Cycle through algorithms
|
||
- `R` - Rotate image (0° → 90° → 180° → 270°)
|
||
- `S` - Save current result
|
||
- `O` - Open new image
|
||
- `Q` or `Esc` - Quit
|
||
|
||
### `dither_algorithms.py` - Algorithm Library
|
||
|
||
Use in your own scripts:
|
||
|
||
```python
|
||
from dither_algorithms import apply_dithering, get_algorithm_names
|
||
from PIL import Image
|
||
|
||
img = Image.open('photo.jpg')
|
||
dithered = apply_dithering(img, 'atkinson')
|
||
dithered.save('output.png')
|
||
|
||
# List all algorithms
|
||
print(get_algorithm_names())
|
||
```
|
||
|
||
## Available Algorithms
|
||
|
||
### Error Diffusion (spread quantization error to neighbors)
|
||
|
||
| Algorithm | Description |
|
||
|-----------|-------------|
|
||
| `floyd_steinberg` | Classic (1976), good balance of speed and quality |
|
||
| `floyd_steinberg_weighted` | With perceptual color weighting |
|
||
| `atkinson` | Bill Atkinson (Apple), cleaner with 75% error diffusion |
|
||
| `atkinson_weighted` | Atkinson with perceptual weighting |
|
||
| `jarvis` | Jarvis-Judice-Ninke, smoother gradients, slower |
|
||
| `stucki` | Similar to JJN with modified weights |
|
||
| `sierra` | Full Sierra, balanced results |
|
||
| `sierra_lite` | Faster Sierra variant |
|
||
| `burkes` | Simplified two-row diffusion |
|
||
|
||
### Ordered Dithering (threshold matrix pattern)
|
||
|
||
| Algorithm | Description |
|
||
|-----------|-------------|
|
||
| `bayer2` | 2×2 Bayer matrix, visible pattern |
|
||
| `bayer4` | 4×4 Bayer matrix, common choice |
|
||
| `bayer8` | 8×8 Bayer matrix, finer pattern |
|
||
| `bayer4_strong` | 4×4 with increased strength |
|
||
|
||
### PIL Built-in (for reference)
|
||
|
||
| Algorithm | Description |
|
||
|-----------|-------------|
|
||
| `none` | No dithering, nearest color only |
|
||
| `pil_fs` | PIL's Floyd-Steinberg implementation |
|
||
|
||
## Recommendations
|
||
|
||
For **photographic images**: `atkinson` or `floyd_steinberg_weighted`
|
||
- Better color accuracy, smoother gradients
|
||
|
||
For **graphics/illustrations**: `bayer4` or `bayer8`
|
||
- Consistent patterns, no "wormy" artifacts
|
||
|
||
For **high contrast images**: `atkinson`
|
||
- Cleaner edges, less noise in solid areas
|
||
|
||
For **fastest processing**: `sierra_lite` or `pil_fs`
|
||
- Good quality with faster execution
|
||
|
||
## Output
|
||
|
||
Results are saved to `dither_output/` by default:
|
||
|
||
```
|
||
dither_output/
|
||
├── photo_source.png # Prepared source (800×480)
|
||
├── photo_atkinson.png # Each algorithm result
|
||
├── photo_floyd_steinberg.png
|
||
├── ...
|
||
├── photo_grid.png # Grid comparison (--grid)
|
||
└── photo_report.html # HTML report (--html)
|
||
```
|
||
|
||
## 6-Color Palette
|
||
|
||
The e-ink display uses these colors:
|
||
|
||
| Color | RGB |
|
||
|--------|-----|
|
||
| Black | (0, 0, 0) |
|
||
| White | (255, 255, 255) |
|
||
| Yellow | (255, 255, 0) |
|
||
| Red | (255, 0, 0) |
|
||
| Blue | (0, 0, 255) |
|
||
| Green | (0, 255, 0) |
|