init

.gitignore

@@ -0,0 +1 @@
+*.pyc

.vscode/settings.json

@@ -0,0 +1,6 @@
+{
+    "files.exclude": {
+        "__pycache__": true,
+        "**/__pycache__": true
+    }
+}

CLAUDE.md

@@ -0,0 +1,58 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What This Is
+
+An e-ink photo frame that runs on a Raspberry Pi Zero 2W. It fetches photos from an Immich server, checks Home Assistant for presence (only displays when someone is home), and renders them on a Waveshare 7.3" 6-color e-Paper display (800x480, ACeP technology with Black/White/Yellow/Red/Blue/Green).
+
+## Deployment
+
+```bash
+./sync.sh          # rsync src/ to andras@192.168.0.81:~/frame/
+```
+
+On the Pi:
+```bash
+cd ~/frame
+python3 display.py                          # default: photos of Me,Ruby
+python3 display.py --album "Album Name"     # from specific album
+python3 display.py -o 90                    # portrait mode (90° or 270°)
+python3 display.py --saturation 1.5 --contrast 1.1 --gamma 0.85
+```
+
+## Architecture
+
+**`src/display.py`** — Entry point. Orchestrates the pipeline:
+1. Checks time (skips between midnight–7am)
+2. Checks Home Assistant presence (skips if nobody home)
+3. Fetches a random photo from Immich (by people or album)
+4. Sends to e-ink display driver
+
+**`src/lib/immich.py`** — Immich API client. Key behaviors:
+- `PhotoHistory` tracks displayed photos in `photo_history.json` to avoid repeats (resets after 7 days)
+- `_pick_weighted_random()` biases selection: 50% chance favorites, 50% chance recent (last 7 days), otherwise random
+- Filters photos by orientation (portrait/landscape) based on EXIF data including rotation tags
+- Downloads preview-size thumbnails, not originals
+
+**`src/lib/homeassistant.py`** — Simple Home Assistant REST client for presence detection.
+
+**`src/lib/waveshare_epd/epd7in3e.py`** — Modified Waveshare driver. The `getbuffer()` method handles the full image pipeline:
+- Center-crops to 800x480 (or 480x800)
+- Enhances saturation/contrast/gamma for e-ink (defaults: saturation=1.4, contrast=1.2, gamma=0.9)
+- Atkinson dithering to 6-color palette using numba JIT
+- Packs into 4-bit-per-pixel buffer (two pixels per byte)
+
+**`src/lib/waveshare_epd/epdconfig.py`** — GPIO/SPI hardware config. **Critical: PWR pin is BCM 27** (not default 18).
+
+**`src/lib/progress.py`** — Simple terminal progress bar.
+
+## Key Constraints
+
+- **Always call `epd.sleep()` after display** — the driver uses a try/finally pattern for this
+- **Display refresh takes 12-15 seconds** — the BUSY pin polling handles this
+- **No test suite** — this is a hardware project; test by deploying to the Pi
+- **Dependencies on Pi**: `python3-pil python3-opencv python3-numba python3-smbus spidev gpiozero`
+- **Config via environment variables**: `IMMICH_URL`, `IMMICH_API_KEY`, `HA_URL`, `HA_TOKEN` (with hardcoded defaults in display.py)
+- **Uses only stdlib `urllib`** — no requests library; the Immich client uses `urllib.request` directly
+- `sys.path.append` is used to add `lib/` to the path from display.py

README.md

@@ -0,0 +1,20 @@
+## Installation
+
+sudo raspi-confi
+- Enable SPI
+
+```sh
+sudo apt update
+sudo apt upgrade
+sudo apt install -y python3-pip python3-pil python3-opencv python3-smbus python3-numba
+sudo swapoff -a
+sudo systemctl mask swap.target
+sudo systemctl disable --now bluetooth
+```
+
+Reduce journald writes
+Edit /etc/systemd/journald.conf:
+
+```
+Storage=volatile
+```

dither_test/README.md

@@ -0,0 +1,164 @@
+# 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) |

dither_test/__init__.py

@@ -0,0 +1,16 @@
+# Dithering Test Suite for 6-Color E-Ink Display
+from .dither_algorithms import (
+    apply_dithering,
+    get_algorithm_names,
+    DITHER_ALGORITHMS,
+    PALETTE_RGB,
+    PALETTE_NAMES,
+)
+
+__all__ = [
+    'apply_dithering',
+    'get_algorithm_names',
+    'DITHER_ALGORITHMS',
+    'PALETTE_RGB',
+    'PALETTE_NAMES',
+]

dither_test/compare.py

@@ -0,0 +1,512 @@
+#!/usr/bin/env python3
+"""
+Dithering Comparison Tool for 6-Color E-Ink Display
+
+Generates side-by-side comparisons of different dithering algorithms
+to help select the best option for your images.
+
+Usage:
+    python compare.py image.jpg                    # Compare all algorithms
+    python compare.py image.jpg -a floyd_steinberg atkinson  # Compare specific
+    python compare.py image.jpg --grid             # Generate grid comparison
+    python compare.py image.jpg --html             # Generate HTML report
+    python compare.py --list                       # List available algorithms
+"""
+
+import argparse
+import os
+import sys
+import time
+from pathlib import Path
+from typing import List, Optional
+
+from PIL import Image
+
+from dither_algorithms import (
+    DITHER_ALGORITHMS,
+    apply_dithering,
+    get_algorithm_names,
+    PALETTE_RGB,
+)
+
+# Display dimensions
+DISPLAY_WIDTH = 800
+DISPLAY_HEIGHT = 480
+
+
+def prepare_image(image_path: str, orientation: int = 0) -> Image.Image:
+    """Load and prepare image for the display dimensions."""
+    img = Image.open(image_path).convert('RGB')
+
+    # Apply rotation
+    if orientation == 90:
+        img = img.transpose(Image.Transpose.ROTATE_270)
+    elif orientation == 180:
+        img = img.transpose(Image.Transpose.ROTATE_180)
+    elif orientation == 270:
+        img = img.transpose(Image.Transpose.ROTATE_90)
+
+    # Calculate scaling to fit display
+    target_w, target_h = DISPLAY_WIDTH, DISPLAY_HEIGHT
+    scale = min(target_w / img.width, target_h / img.height)
+    new_w = int(img.width * scale)
+    new_h = int(img.height * scale)
+
+    # Resize with high-quality resampling
+    img = img.resize((new_w, new_h), Image.Resampling.LANCZOS)
+
+    # Center on white canvas
+    canvas = Image.new('RGB', (target_w, target_h), (255, 255, 255))
+    x = (target_w - new_w) // 2
+    y = (target_h - new_h) // 2
+    canvas.paste(img, (x, y))
+
+    return canvas
+
+
+def run_comparison(
+    image_path: str,
+    algorithms: Optional[List[str]] = None,
+    output_dir: str = 'dither_output',
+    orientation: int = 0,
+) -> dict:
+    """
+    Run dithering comparison and save results.
+
+    Returns dict with algorithm names as keys and tuples of (output_path, duration) as values.
+    """
+    if algorithms is None:
+        algorithms = get_algorithm_names()
+
+    # Prepare output directory
+    output_path = Path(output_dir)
+    output_path.mkdir(parents=True, exist_ok=True)
+
+    # Get base name for outputs
+    base_name = Path(image_path).stem
+
+    # Load and prepare source image
+    print(f"Loading and preparing: {image_path}")
+    source = prepare_image(image_path, orientation)
+
+    # Save prepared source for reference
+    source_out = output_path / f"{base_name}_source.png"
+    source.save(source_out)
+    print(f"  Saved prepared source: {source_out}")
+
+    results = {}
+
+    for algo_name in algorithms:
+        if algo_name not in DITHER_ALGORITHMS:
+            print(f"  Warning: Unknown algorithm '{algo_name}', skipping")
+            continue
+
+        algo_info = DITHER_ALGORITHMS[algo_name]
+        print(f"  Processing: {algo_info['name']}...", end=' ', flush=True)
+
+        start_time = time.time()
+        dithered = apply_dithering(source, algo_name)
+        duration = time.time() - start_time
+
+        out_file = output_path / f"{base_name}_{algo_name}.png"
+        dithered.save(out_file)
+
+        results[algo_name] = (str(out_file), duration)
+        print(f"{duration:.2f}s -> {out_file}")
+
+    return results
+
+
+def create_comparison_grid(
+    image_path: str,
+    algorithms: Optional[List[str]] = None,
+    output_dir: str = 'dither_output',
+    orientation: int = 0,
+    cols: int = 3,
+) -> str:
+    """Create a single image with all algorithms in a grid layout."""
+    if algorithms is None:
+        algorithms = get_algorithm_names()
+
+    output_path = Path(output_dir)
+    output_path.mkdir(parents=True, exist_ok=True)
+
+    base_name = Path(image_path).stem
+    source = prepare_image(image_path, orientation)
+
+    # Calculate grid dimensions
+    n_images = len(algorithms) + 1  # +1 for source
+    rows = (n_images + cols - 1) // cols
+
+    # Thumbnail size (scaled down for grid)
+    thumb_w = DISPLAY_WIDTH // 2
+    thumb_h = DISPLAY_HEIGHT // 2
+    padding = 10
+    label_height = 30
+
+    # Create grid canvas
+    grid_w = cols * (thumb_w + padding) + padding
+    grid_h = rows * (thumb_h + label_height + padding) + padding
+    grid = Image.new('RGB', (grid_w, grid_h), (240, 240, 240))
+
+    # Import for text rendering
+    try:
+        from PIL import ImageDraw, ImageFont
+        draw = ImageDraw.Draw(grid)
+        try:
+            font = ImageFont.truetype("/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf", 16)
+        except:
+            font = ImageFont.load_default()
+    except ImportError:
+        draw = None
+        font = None
+
+    def add_to_grid(img: Image.Image, label: str, idx: int):
+        row = idx // cols
+        col = idx % cols
+        x = padding + col * (thumb_w + padding)
+        y = padding + row * (thumb_h + label_height + padding)
+
+        # Resize for thumbnail
+        thumb = img.resize((thumb_w, thumb_h), Image.Resampling.LANCZOS)
+        grid.paste(thumb, (x, y + label_height))
+
+        # Add label
+        if draw:
+            draw.text((x + 5, y + 5), label, fill=(0, 0, 0), font=font)
+
+    # Add source image first
+    add_to_grid(source, "Original (Prepared)", 0)
+
+    # Process and add each algorithm
+    for i, algo_name in enumerate(algorithms, 1):
+        if algo_name not in DITHER_ALGORITHMS:
+            continue
+        algo_info = DITHER_ALGORITHMS[algo_name]
+        print(f"  Grid: {algo_info['name']}...")
+        dithered = apply_dithering(source, algo_name)
+        add_to_grid(dithered, algo_info['name'], i)
+
+    # Save grid
+    grid_file = output_path / f"{base_name}_grid.png"
+    grid.save(grid_file)
+    print(f"Grid saved: {grid_file}")
+
+    return str(grid_file)
+
+
+def create_side_by_side(
+    image_path: str,
+    algo1: str,
+    algo2: str,
+    output_dir: str = 'dither_output',
+    orientation: int = 0,
+) -> str:
+    """Create a side-by-side comparison of two algorithms."""
+    output_path = Path(output_dir)
+    output_path.mkdir(parents=True, exist_ok=True)
+
+    base_name = Path(image_path).stem
+    source = prepare_image(image_path, orientation)
+
+    info1 = DITHER_ALGORITHMS[algo1]
+    info2 = DITHER_ALGORITHMS[algo2]
+
+    print(f"  Processing {info1['name']}...")
+    img1 = apply_dithering(source, algo1)
+
+    print(f"  Processing {info2['name']}...")
+    img2 = apply_dithering(source, algo2)
+
+    # Create side-by-side
+    padding = 20
+    label_h = 40
+    width = DISPLAY_WIDTH * 2 + padding * 3
+    height = DISPLAY_HEIGHT + padding * 2 + label_h
+
+    canvas = Image.new('RGB', (width, height), (240, 240, 240))
+    canvas.paste(img1, (padding, padding + label_h))
+    canvas.paste(img2, (DISPLAY_WIDTH + padding * 2, padding + label_h))
+
+    # Add labels
+    try:
+        from PIL import ImageDraw, ImageFont
+        draw = ImageDraw.Draw(canvas)
+        try:
+            font = ImageFont.truetype("/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf", 20)
+        except:
+            font = ImageFont.load_default()
+
+        draw.text((padding + 10, padding + 5), info1['name'], fill=(0, 0, 0), font=font)
+        draw.text((DISPLAY_WIDTH + padding * 2 + 10, padding + 5), info2['name'], fill=(0, 0, 0), font=font)
+    except ImportError:
+        pass
+
+    out_file = output_path / f"{base_name}_{algo1}_vs_{algo2}.png"
+    canvas.save(out_file)
+    print(f"Side-by-side saved: {out_file}")
+
+    return str(out_file)
+
+
+def generate_html_report(
+    image_path: str,
+    results: dict,
+    output_dir: str = 'dither_output',
+) -> str:
+    """Generate an HTML report for easy comparison."""
+    output_path = Path(output_dir)
+    base_name = Path(image_path).stem
+
+    html = f"""<!DOCTYPE html>
+<html>
+<head>
+    <title>Dithering Comparison: {base_name}</title>
+    <style>
+        body {{
+            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+            background: #1a1a2e;
+            color: #eee;
+            margin: 0;
+            padding: 20px;
+        }}
+        h1 {{ color: #00d9ff; margin-bottom: 10px; }}
+        .subtitle {{ color: #888; margin-bottom: 30px; }}
+        .grid {{
+            display: grid;
+            grid-template-columns: repeat(auto-fill, minmax(420px, 1fr));
+            gap: 20px;
+        }}
+        .card {{
+            background: #16213e;
+            border-radius: 12px;
+            overflow: hidden;
+            box-shadow: 0 4px 20px rgba(0,0,0,0.3);
+        }}
+        .card img {{
+            width: 100%;
+            height: auto;
+            display: block;
+            cursor: pointer;
+            transition: transform 0.2s;
+        }}
+        .card img:hover {{ transform: scale(1.02); }}
+        .card-info {{
+            padding: 15px;
+        }}
+        .card-title {{
+            font-size: 18px;
+            font-weight: 600;
+            color: #00d9ff;
+            margin-bottom: 5px;
+        }}
+        .card-desc {{
+            font-size: 13px;
+            color: #888;
+            margin-bottom: 8px;
+        }}
+        .card-time {{
+            font-size: 12px;
+            color: #666;
+        }}
+        .source-card {{
+            grid-column: 1 / -1;
+            max-width: 850px;
+        }}
+        .source-card img {{ max-width: 800px; }}
+        .palette {{
+            display: flex;
+            gap: 10px;
+            margin: 20px 0;
+            padding: 15px;
+            background: #16213e;
+            border-radius: 8px;
+            width: fit-content;
+        }}
+        .color-swatch {{
+            width: 40px;
+            height: 40px;
+            border-radius: 6px;
+            border: 2px solid #333;
+        }}
+        .fullscreen {{
+            display: none;
+            position: fixed;
+            top: 0;
+            left: 0;
+            width: 100%;
+            height: 100%;
+            background: rgba(0,0,0,0.95);
+            z-index: 1000;
+            justify-content: center;
+            align-items: center;
+        }}
+        .fullscreen img {{
+            max-width: 95%;
+            max-height: 95%;
+        }}
+        .fullscreen.active {{ display: flex; }}
+    </style>
+</head>
+<body>
+    <h1>Dithering Algorithm Comparison</h1>
+    <p class="subtitle">Source: {image_path}</p>
+
+    <h3>6-Color Palette</h3>
+    <div class="palette">
+"""
+
+    for i, (color, name) in enumerate(zip(PALETTE_RGB, ['Black', 'White', 'Yellow', 'Red', 'Blue', 'Green'])):
+        r, g, b = color
+        html += f'        <div class="color-swatch" style="background: rgb({r},{g},{b});" title="{name}"></div>\n'
+
+    html += """    </div>
+
+    <h3>Results</h3>
+    <div class="grid">
+        <div class="card source-card">
+            <img src="{base_name}_source.png" alt="Prepared Source" onclick="showFullscreen(this)">
+            <div class="card-info">
+                <div class="card-title">Original (Prepared)</div>
+                <div class="card-desc">Source image resized to 800x480 with LANCZOS resampling</div>
+            </div>
+        </div>
+"""
+
+    for algo_name, (out_path, duration) in results.items():
+        algo_info = DITHER_ALGORITHMS[algo_name]
+        filename = Path(out_path).name
+        html += f"""
+        <div class="card">
+            <img src="{filename}" alt="{algo_info['name']}" onclick="showFullscreen(this)">
+            <div class="card-info">
+                <div class="card-title">{algo_info['name']}</div>
+                <div class="card-desc">{algo_info['description']}</div>
+                <div class="card-time">Processing time: {duration:.2f}s</div>
+            </div>
+        </div>
+"""
+
+    html += """
+    </div>
+
+    <div class="fullscreen" onclick="hideFullscreen()">
+        <img src="" id="fullscreen-img">
+    </div>
+
+    <script>
+        function showFullscreen(img) {
+            document.getElementById('fullscreen-img').src = img.src;
+            document.querySelector('.fullscreen').classList.add('active');
+        }
+        function hideFullscreen() {
+            document.querySelector('.fullscreen').classList.remove('active');
+        }
+        document.addEventListener('keydown', (e) => {
+            if (e.key === 'Escape') hideFullscreen();
+        });
+    </script>
+</body>
+</html>
+"""
+
+    html_file = output_path / f"{base_name}_report.html"
+    html_file.write_text(html.replace('{base_name}', base_name))
+    print(f"HTML report saved: {html_file}")
+
+    return str(html_file)
+
+
+def list_algorithms():
+    """Print available algorithms with descriptions."""
+    print("\nAvailable Dithering Algorithms:")
+    print("=" * 70)
+    for name, info in DITHER_ALGORITHMS.items():
+        print(f"\n  {name}")
+        print(f"    Name: {info['name']}")
+        print(f"    {info['description']}")
+    print()
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description='Compare dithering algorithms for 6-color e-ink display',
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  python compare.py photo.jpg                     # Compare all algorithms
+  python compare.py photo.jpg -a atkinson pil_fs  # Compare specific algorithms
+  python compare.py photo.jpg --grid              # Generate grid comparison
+  python compare.py photo.jpg --html              # Generate HTML report
+  python compare.py photo.jpg --side-by-side atkinson floyd_steinberg
+  python compare.py --list                        # List available algorithms
+        """
+    )
+
+    parser.add_argument('image', nargs='?', help='Input image file')
+    parser.add_argument('-a', '--algorithms', nargs='+',
+                        help='Specific algorithms to compare (default: all)')
+    parser.add_argument('-o', '--output', default='dither_output',
+                        help='Output directory (default: dither_output)')
+    parser.add_argument('--orientation', '-r', type=int, default=0,
+                        choices=[0, 90, 180, 270],
+                        help='Rotate image (degrees)')
+    parser.add_argument('--grid', action='store_true',
+                        help='Generate grid comparison image')
+    parser.add_argument('--html', action='store_true',
+                        help='Generate HTML comparison report')
+    parser.add_argument('--side-by-side', nargs=2, metavar=('ALGO1', 'ALGO2'),
+                        help='Create side-by-side comparison of two algorithms')
+    parser.add_argument('--list', action='store_true',
+                        help='List available algorithms')
+
+    args = parser.parse_args()
+
+    if args.list:
+        list_algorithms()
+        return
+
+    if not args.image:
+        parser.error("Image file is required (unless using --list)")
+
+    if not os.path.exists(args.image):
+        print(f"Error: File not found: {args.image}")
+        sys.exit(1)
+
+    print(f"\n{'='*60}")
+    print(f"Dithering Comparison Test Suite")
+    print(f"{'='*60}\n")
+
+    if args.side_by_side:
+        create_side_by_side(
+            args.image,
+            args.side_by_side[0],
+            args.side_by_side[1],
+            args.output,
+            args.orientation
+        )
+    elif args.grid:
+        create_comparison_grid(
+            args.image,
+            args.algorithms,
+            args.output,
+            args.orientation
+        )
+    else:
+        results = run_comparison(
+            args.image,
+            args.algorithms,
+            args.output,
+            args.orientation
+        )
+
+        if args.html:
+            generate_html_report(args.image, results, args.output)
+
+    print(f"\n{'='*60}")
+    print(f"Done! Output saved to: {args.output}/")
+    print(f"{'='*60}\n")
+
+
+if __name__ == '__main__':
+    main()

dither_test/dither_algorithms.py

@@ -0,0 +1,563 @@
+"""
+Dithering algorithms for 6-color e-ink display testing.
+
+Includes multiple error-diffusion and ordered dithering algorithms
+for comparison testing.
+"""
+
+import numpy as np
+from PIL import Image
+from typing import Tuple, List
+
+from numba import jit
+
+# 6-color ACeP palette (RGB format)
+PALETTE_RGB = [
+    (0, 0, 0),        # BLACK
+    (255, 255, 255),  # WHITE
+    (255, 255, 0),    # YELLOW
+    (255, 0, 0),      # RED
+    (0, 0, 255),      # BLUE
+    (0, 255, 0),      # GREEN
+]
+
+PALETTE_NAMES = ['Black', 'White', 'Yellow', 'Red', 'Blue', 'Green']
+
+
+def create_pil_palette_image() -> Image.Image:
+    """Create a PIL palette image for quantization."""
+    pal_image = Image.new("P", (1, 1))
+    flat_palette = []
+    for color in PALETTE_RGB:
+        flat_palette.extend(color)
+    # Pad to 256 colors (768 values)
+    flat_palette.extend([0] * (768 - len(flat_palette)))
+    pal_image.putpalette(flat_palette)
+    return pal_image
+
+
+def find_nearest_color(pixel: np.ndarray, palette: np.ndarray) -> Tuple[int, np.ndarray]:
+    """Find the nearest palette color using Euclidean distance."""
+    distances = np.sqrt(np.sum((palette - pixel) ** 2, axis=1))
+    idx = np.argmin(distances)
+    return idx, palette[idx]
+
+
+def find_nearest_color_weighted(pixel: np.ndarray, palette: np.ndarray) -> Tuple[int, np.ndarray]:
+    """Find nearest color using perceptually-weighted distance (human eye sensitivity)."""
+    # Weights based on human perception: Green > Red > Blue
+    weights = np.array([0.299, 0.587, 0.114])
+    diff = palette - pixel
+    weighted_diff = diff * weights
+    distances = np.sqrt(np.sum(weighted_diff ** 2, axis=1))
+    idx = np.argmin(distances)
+    return idx, palette[idx]
+
+
+# =============================================================================
+# Error Diffusion Dithering Algorithms
+# =============================================================================
+
+def dither_floyd_steinberg(image: Image.Image, weighted: bool = False) -> Image.Image:
+    """
+    Floyd-Steinberg dithering (1976).
+
+    Classic error diffusion algorithm with distribution:
+        * 7/16
+    3/16 5/16 1/16
+    """
+    img = np.array(image.convert('RGB'), dtype=np.float64)
+    height, width = img.shape[:2]
+    palette = np.array(PALETTE_RGB, dtype=np.float64)
+    find_fn = find_nearest_color_weighted if weighted else find_nearest_color
+
+    for y in range(height):
+        for x in range(width):
+            old_pixel = img[y, x].copy()
+            _, new_pixel = find_fn(old_pixel, palette)
+            img[y, x] = new_pixel
+            error = old_pixel - new_pixel
+
+            if x + 1 < width:
+                img[y, x + 1] += error * 7 / 16
+            if y + 1 < height:
+                if x > 0:
+                    img[y + 1, x - 1] += error * 3 / 16
+                img[y + 1, x] += error * 5 / 16
+                if x + 1 < width:
+                    img[y + 1, x + 1] += error * 1 / 16
+
+    img = np.clip(img, 0, 255).astype(np.uint8)
+    return Image.fromarray(img, 'RGB')
+
+
+def dither_jarvis_judice_ninke(image: Image.Image, weighted: bool = False) -> Image.Image:
+    """
+    Jarvis, Judice, and Ninke dithering (1976).
+
+    Spreads error over a larger area (12 pixels):
+            * 7 5
+    3 5 7 5 3
+    1 3 5 3 1
+    All divided by 48.
+    """
+    img = np.array(image.convert('RGB'), dtype=np.float64)
+    height, width = img.shape[:2]
+    palette = np.array(PALETTE_RGB, dtype=np.float64)
+    find_fn = find_nearest_color_weighted if weighted else find_nearest_color
+
+    for y in range(height):
+        for x in range(width):
+            old_pixel = img[y, x].copy()
+            _, new_pixel = find_fn(old_pixel, palette)
+            img[y, x] = new_pixel
+            error = old_pixel - new_pixel
+
+            # Row 0 (current row)
+            if x + 1 < width:
+                img[y, x + 1] += error * 7 / 48
+            if x + 2 < width:
+                img[y, x + 2] += error * 5 / 48
+
+            # Row 1
+            if y + 1 < height:
+                for dx, w in [(-2, 3), (-1, 5), (0, 7), (1, 5), (2, 3)]:
+                    if 0 <= x + dx < width:
+                        img[y + 1, x + dx] += error * w / 48
+
+            # Row 2
+            if y + 2 < height:
+                for dx, w in [(-2, 1), (-1, 3), (0, 5), (1, 3), (2, 1)]:
+                    if 0 <= x + dx < width:
+                        img[y + 2, x + dx] += error * w / 48
+
+    img = np.clip(img, 0, 255).astype(np.uint8)
+    return Image.fromarray(img, 'RGB')
+
+
+def dither_stucki(image: Image.Image, weighted: bool = False) -> Image.Image:
+    """
+    Stucki dithering (1981).
+
+    Similar to JJN but with different weights:
+            * 8 4
+    2 4 8 4 2
+    1 2 4 2 1
+    All divided by 42.
+    """
+    img = np.array(image.convert('RGB'), dtype=np.float64)
+    height, width = img.shape[:2]
+    palette = np.array(PALETTE_RGB, dtype=np.float64)
+    find_fn = find_nearest_color_weighted if weighted else find_nearest_color
+
+    for y in range(height):
+        for x in range(width):
+            old_pixel = img[y, x].copy()
+            _, new_pixel = find_fn(old_pixel, palette)
+            img[y, x] = new_pixel
+            error = old_pixel - new_pixel
+
+            if x + 1 < width:
+                img[y, x + 1] += error * 8 / 42
+            if x + 2 < width:
+                img[y, x + 2] += error * 4 / 42
+
+            if y + 1 < height:
+                for dx, w in [(-2, 2), (-1, 4), (0, 8), (1, 4), (2, 2)]:
+                    if 0 <= x + dx < width:
+                        img[y + 1, x + dx] += error * w / 42
+
+            if y + 2 < height:
+                for dx, w in [(-2, 1), (-1, 2), (0, 4), (1, 2), (2, 1)]:
+                    if 0 <= x + dx < width:
+                        img[y + 2, x + dx] += error * w / 42
+
+    img = np.clip(img, 0, 255).astype(np.uint8)
+    return Image.fromarray(img, 'RGB')
+
+
+def dither_atkinson(image: Image.Image, weighted: bool = False) -> Image.Image:
+    """
+    Atkinson dithering (Bill Atkinson, Apple).
+
+    Only diffuses 6/8 of the error (loses some detail but reduces noise):
+        * 1 1
+    1 1 1
+      1
+    All divided by 8 (but only 6/8 total error diffused).
+    """
+    img = np.array(image.convert('RGB'), dtype=np.float64)
+    height, width = img.shape[:2]
+    palette = np.array(PALETTE_RGB, dtype=np.float64)
+    find_fn = find_nearest_color_weighted if weighted else find_nearest_color
+
+    for y in range(height):
+        for x in range(width):
+            old_pixel = img[y, x].copy()
+            _, new_pixel = find_fn(old_pixel, palette)
+            img[y, x] = new_pixel
+            error = old_pixel - new_pixel
+
+            # Distribute 1/8 to each of 6 neighbors
+            if x + 1 < width:
+                img[y, x + 1] += error / 8
+            if x + 2 < width:
+                img[y, x + 2] += error / 8
+
+            if y + 1 < height:
+                if x > 0:
+                    img[y + 1, x - 1] += error / 8
+                img[y + 1, x] += error / 8
+                if x + 1 < width:
+                    img[y + 1, x + 1] += error / 8
+
+            if y + 2 < height:
+                img[y + 2, x] += error / 8
+
+    img = np.clip(img, 0, 255).astype(np.uint8)
+    return Image.fromarray(img, 'RGB')
+
+
+def dither_sierra(image: Image.Image, weighted: bool = False) -> Image.Image:
+    """
+    Sierra dithering (Frankie Sierra).
+
+    Full Sierra (Sierra-3):
+            * 5 3
+    2 4 5 4 2
+      2 3 2
+    All divided by 32.
+    """
+    img = np.array(image.convert('RGB'), dtype=np.float64)
+    height, width = img.shape[:2]
+    palette = np.array(PALETTE_RGB, dtype=np.float64)
+    find_fn = find_nearest_color_weighted if weighted else find_nearest_color
+
+    for y in range(height):
+        for x in range(width):
+            old_pixel = img[y, x].copy()
+            _, new_pixel = find_fn(old_pixel, palette)
+            img[y, x] = new_pixel
+            error = old_pixel - new_pixel
+
+            if x + 1 < width:
+                img[y, x + 1] += error * 5 / 32
+            if x + 2 < width:
+                img[y, x + 2] += error * 3 / 32
+
+            if y + 1 < height:
+                for dx, w in [(-2, 2), (-1, 4), (0, 5), (1, 4), (2, 2)]:
+                    if 0 <= x + dx < width:
+                        img[y + 1, x + dx] += error * w / 32
+
+            if y + 2 < height:
+                for dx, w in [(-1, 2), (0, 3), (1, 2)]:
+                    if 0 <= x + dx < width:
+                        img[y + 2, x + dx] += error * w / 32
+
+    img = np.clip(img, 0, 255).astype(np.uint8)
+    return Image.fromarray(img, 'RGB')
+
+
+def dither_sierra_lite(image: Image.Image, weighted: bool = False) -> Image.Image:
+    """
+    Sierra Lite (Sierra-2-4A) - faster variant.
+
+        * 2
+    1 1
+    All divided by 4.
+    """
+    img = np.array(image.convert('RGB'), dtype=np.float64)
+    height, width = img.shape[:2]
+    palette = np.array(PALETTE_RGB, dtype=np.float64)
+    find_fn = find_nearest_color_weighted if weighted else find_nearest_color
+
+    for y in range(height):
+        for x in range(width):
+            old_pixel = img[y, x].copy()
+            _, new_pixel = find_fn(old_pixel, palette)
+            img[y, x] = new_pixel
+            error = old_pixel - new_pixel
+
+            if x + 1 < width:
+                img[y, x + 1] += error * 2 / 4
+
+            if y + 1 < height:
+                if x > 0:
+                    img[y + 1, x - 1] += error * 1 / 4
+                img[y + 1, x] += error * 1 / 4
+
+    img = np.clip(img, 0, 255).astype(np.uint8)
+    return Image.fromarray(img, 'RGB')
+
+
+def dither_burkes(image: Image.Image, weighted: bool = False) -> Image.Image:
+    """
+    Burkes dithering.
+
+        * 8 4
+    2 4 8 4 2
+    All divided by 32.
+    """
+    img = np.array(image.convert('RGB'), dtype=np.float64)
+    height, width = img.shape[:2]
+    palette = np.array(PALETTE_RGB, dtype=np.float64)
+    find_fn = find_nearest_color_weighted if weighted else find_nearest_color
+
+    for y in range(height):
+        for x in range(width):
+            old_pixel = img[y, x].copy()
+            _, new_pixel = find_fn(old_pixel, palette)
+            img[y, x] = new_pixel
+            error = old_pixel - new_pixel
+
+            if x + 1 < width:
+                img[y, x + 1] += error * 8 / 32
+            if x + 2 < width:
+                img[y, x + 2] += error * 4 / 32
+
+            if y + 1 < height:
+                for dx, w in [(-2, 2), (-1, 4), (0, 8), (1, 4), (2, 2)]:
+                    if 0 <= x + dx < width:
+                        img[y + 1, x + dx] += error * w / 32
+
+    img = np.clip(img, 0, 255).astype(np.uint8)
+    return Image.fromarray(img, 'RGB')
+
+
+# =============================================================================
+# Ordered Dithering Algorithms
+# =============================================================================
+
+def get_bayer_matrix(n: int) -> np.ndarray:
+    """Generate a Bayer matrix of size 2^n x 2^n."""
+    if n == 0:
+        return np.array([[0]])
+    smaller = get_bayer_matrix(n - 1)
+    size = 2 ** (n - 1)
+    result = np.zeros((2 ** n, 2 ** n))
+    result[:size, :size] = 4 * smaller
+    result[:size, size:] = 4 * smaller + 2
+    result[size:, :size] = 4 * smaller + 3
+    result[size:, size:] = 4 * smaller + 1
+    return result
+
+
+def dither_ordered_bayer(image: Image.Image, matrix_size: int = 4, strength: float = 1.0) -> Image.Image:
+    """
+    Ordered dithering using Bayer matrix.
+
+    Args:
+        image: Input image
+        matrix_size: Size of Bayer matrix (2, 4, 8, or 16)
+        strength: Dithering strength multiplier (0.0-2.0)
+    """
+    img = np.array(image.convert('RGB'), dtype=np.float64)
+    height, width = img.shape[:2]
+    palette = np.array(PALETTE_RGB, dtype=np.float64)
+
+    # Get appropriate Bayer matrix
+    n = {2: 1, 4: 2, 8: 3, 16: 4}.get(matrix_size, 2)
+    bayer = get_bayer_matrix(n)
+    bayer_size = bayer.shape[0]
+
+    # Normalize Bayer matrix to -0.5 to 0.5 range, then scale
+    bayer_normalized = (bayer / (bayer_size ** 2) - 0.5) * strength * 128
+
+    result = np.zeros_like(img)
+
+    for y in range(height):
+        for x in range(width):
+            threshold = bayer_normalized[y % bayer_size, x % bayer_size]
+            adjusted_pixel = img[y, x] + threshold
+            adjusted_pixel = np.clip(adjusted_pixel, 0, 255)
+            _, new_pixel = find_nearest_color(adjusted_pixel, palette)
+            result[y, x] = new_pixel
+
+    return Image.fromarray(result.astype(np.uint8), 'RGB')
+
+
+_NUMBA_PALETTE = np.array([
+    [0, 0, 0], [255, 255, 255], [255, 255, 0],
+    [255, 0, 0], [0, 0, 255], [0, 255, 0],
+], dtype=np.float64)
+_NUMBA_WEIGHTS = np.array([0.299, 0.587, 0.114], dtype=np.float64)
+
+@jit(nopython=True)
+def _numba_find_nearest(r, g, b, palette, weights):
+    best_idx = 0
+    best_dist = 1e10
+    for i in range(palette.shape[0]):
+        dr = (palette[i, 0] - r) * weights[0]
+        dg = (palette[i, 1] - g) * weights[1]
+        db = (palette[i, 2] - b) * weights[2]
+        dist = dr * dr + dg * dg + db * db
+        if dist < best_dist:
+            best_dist = dist
+            best_idx = i
+    return best_idx
+
+@jit(nopython=True)
+def _numba_atkinson(img, palette, weights):
+    height, width = img.shape[0], img.shape[1]
+    for y in range(height):
+        for x in range(width):
+            old_r, old_g, old_b = img[y, x, 0], img[y, x, 1], img[y, x, 2]
+            idx = _numba_find_nearest(old_r, old_g, old_b, palette, weights)
+            new_r, new_g, new_b = palette[idx, 0], palette[idx, 1], palette[idx, 2]
+            img[y, x, 0], img[y, x, 1], img[y, x, 2] = new_r, new_g, new_b
+            err_r = (old_r - new_r) / 8.0
+            err_g = (old_g - new_g) / 8.0
+            err_b = (old_b - new_b) / 8.0
+            if x + 1 < width:
+                img[y, x + 1, 0] += err_r
+                img[y, x + 1, 1] += err_g
+                img[y, x + 1, 2] += err_b
+            if x + 2 < width:
+                img[y, x + 2, 0] += err_r
+                img[y, x + 2, 1] += err_g
+                img[y, x + 2, 2] += err_b
+            if y + 1 < height:
+                if x > 0:
+                    img[y + 1, x - 1, 0] += err_r
+                    img[y + 1, x - 1, 1] += err_g
+                    img[y + 1, x - 1, 2] += err_b
+                img[y + 1, x, 0] += err_r
+                img[y + 1, x, 1] += err_g
+                img[y + 1, x, 2] += err_b
+                if x + 1 < width:
+                    img[y + 1, x + 1, 0] += err_r
+                    img[y + 1, x + 1, 1] += err_g
+                    img[y + 1, x + 1, 2] += err_b
+            if y + 2 < height:
+                img[y + 2, x, 0] += err_r
+                img[y + 2, x, 1] += err_g
+                img[y + 2, x, 2] += err_b
+    return img
+
+def dither_atkinson_numba(image: Image.Image) -> Image.Image:
+    """Numba-accelerated Atkinson dithering with perceptual weighting (~150x faster)."""
+    img = np.array(image.convert('RGB'), dtype=np.float64)
+    img = _numba_atkinson(img, _NUMBA_PALETTE, _NUMBA_WEIGHTS)
+    img = np.clip(img, 0, 255).astype(np.uint8)
+    return Image.fromarray(img, 'RGB')
+
+
+# =============================================================================
+# PIL Built-in (for comparison)
+# =============================================================================
+
+def dither_pil_floyd_steinberg(image: Image.Image) -> Image.Image:
+    """PIL's built-in Floyd-Steinberg dithering for comparison."""
+    pal_image = create_pil_palette_image()
+    img = image.convert('RGB')
+    quantized = img.quantize(dither=Image.Dither.FLOYDSTEINBERG, palette=pal_image)
+    return quantized.convert('RGB')
+
+
+def dither_pil_none(image: Image.Image) -> Image.Image:
+    """PIL quantization with no dithering (nearest color only)."""
+    pal_image = create_pil_palette_image()
+    img = image.convert('RGB')
+    quantized = img.quantize(dither=Image.Dither.NONE, palette=pal_image)
+    return quantized.convert('RGB')
+
+
+# =============================================================================
+# Algorithm Registry
+# =============================================================================
+
+DITHER_ALGORITHMS = {
+    'none': {
+        'name': 'No Dithering (PIL)',
+        'func': dither_pil_none,
+        'description': 'Simple nearest-color quantization without error diffusion',
+    },
+    'pil_fs': {
+        'name': 'Floyd-Steinberg (PIL)',
+        'func': dither_pil_floyd_steinberg,
+        'description': 'PIL built-in Floyd-Steinberg implementation',
+    },
+    'floyd_steinberg': {
+        'name': 'Floyd-Steinberg',
+        'func': dither_floyd_steinberg,
+        'description': 'Classic error diffusion (1976), good balance of speed and quality',
+    },
+    'floyd_steinberg_weighted': {
+        'name': 'Floyd-Steinberg (Weighted)',
+        'func': lambda img: dither_floyd_steinberg(img, weighted=True),
+        'description': 'Floyd-Steinberg with perceptual color weighting',
+    },
+    'atkinson': {
+        'name': 'Atkinson',
+        'func': dither_atkinson,
+        'description': 'Bill Atkinson (Apple), diffuses only 75% of error for cleaner results',
+    },
+    'atkinson_weighted': {
+        'name': 'Atkinson (Weighted)',
+        'func': lambda img: dither_atkinson(img, weighted=True),
+        'description': 'Atkinson with perceptual color weighting',
+    },
+    'atkinson_fast': {
+        'name': 'Atkinson (Numba Fast)',
+        'func': dither_atkinson_numba,
+        'description': 'Numba-accelerated Atkinson (~150x faster, requires numba)',
+    },
+    'jarvis': {
+        'name': 'Jarvis-Judice-Ninke',
+        'func': dither_jarvis_judice_ninke,
+        'description': 'Larger diffusion kernel (1976), smoother gradients but slower',
+    },
+    'stucki': {
+        'name': 'Stucki',
+        'func': dither_stucki,
+        'description': 'Similar to JJN with modified weights (1981)',
+    },
+    'sierra': {
+        'name': 'Sierra',
+        'func': dither_sierra,
+        'description': 'Full Sierra dithering, balanced results',
+    },
+    'sierra_lite': {
+        'name': 'Sierra Lite',
+        'func': dither_sierra_lite,
+        'description': 'Faster Sierra variant with smaller kernel',
+    },
+    'burkes': {
+        'name': 'Burkes',
+        'func': dither_burkes,
+        'description': 'Simplified two-row error diffusion',
+    },
+    'bayer2': {
+        'name': 'Ordered (Bayer 2x2)',
+        'func': lambda img: dither_ordered_bayer(img, matrix_size=2),
+        'description': 'Ordered dithering with 2x2 Bayer matrix',
+    },
+    'bayer4': {
+        'name': 'Ordered (Bayer 4x4)',
+        'func': lambda img: dither_ordered_bayer(img, matrix_size=4),
+        'description': 'Ordered dithering with 4x4 Bayer matrix',
+    },
+    'bayer8': {
+        'name': 'Ordered (Bayer 8x8)',
+        'func': lambda img: dither_ordered_bayer(img, matrix_size=8),
+        'description': 'Ordered dithering with 8x8 Bayer matrix',
+    },
+    'bayer4_strong': {
+        'name': 'Ordered (Bayer 4x4 Strong)',
+        'func': lambda img: dither_ordered_bayer(img, matrix_size=4, strength=1.5),
+        'description': 'Bayer 4x4 with increased dithering strength',
+    },
+}
+
+
+def get_algorithm_names() -> List[str]:
+    """Return list of available algorithm names."""
+    return list(DITHER_ALGORITHMS.keys())
+
+
+def apply_dithering(image: Image.Image, algorithm: str) -> Image.Image:
+    """Apply the specified dithering algorithm to an image."""
+    if algorithm not in DITHER_ALGORITHMS:
+        raise ValueError(f"Unknown algorithm: {algorithm}. Available: {get_algorithm_names()}")
+    return DITHER_ALGORITHMS[algorithm]['func'](image)