hermes-agent/skills/creative/pixel-art/SKILL.md

---
name: pixel-art
description: Convert images into retro pixel art using named presets (arcade, snes) with Floyd-Steinberg dithering. Arcade is bold and chunky; SNES is cleaner with more detail retention.
version: 1.2.0
author: dodo-reach
license: MIT
metadata:
  hermes:
    tags: [creative, pixel-art, arcade, snes, retro, image]
    category: creative
---

# Pixel Art

Convert any image into retro-style pixel art. One function with named presets that select different aesthetics:

- `arcade` — 16-color palette, 8px blocks. Bold, chunky, high-impact. 80s/90s arcade cabinet feel.
- `snes` — 32-color palette, 4px blocks. Cleaner 16-bit console look with more detail retention.

The core pipeline is identical across presets — what changes is palette size, block size, and the strength of contrast/color/posterize pre-processing. All presets use Floyd-Steinberg dithering applied AFTER downscale so error diffusion aligns with the final pixel grid.

## When to Use

- User wants retro pixel art from a source image
- Posters, album covers, social posts, sprites, characters, backgrounds
- Subject can tolerate aggressive simplification (arcade) or benefits from retained detail (snes)

## Preset Picker

| Preset | Palette | Block | Best for |
|--------|---------|-------|----------|
| `arcade` | 16 colors | 8px | Posters, hero images, bold covers, simple subjects |
| `snes` | 32 colors | 4px | Characters, sprites, detailed illustrations, photos |

Default is `arcade` for maximum stylistic punch. Switch to `snes` when the subject has detail worth preserving.

## Procedure

1. Pick a preset (`arcade` or `snes`) based on the aesthetic you want.
2. Boost contrast, color, and sharpness using the preset's enhancement values.
3. Lightly posterize the image to simplify tonal regions before quantization.
4. Downscale to `w // block` by `h // block` with `Image.NEAREST`.
5. Quantize the reduced image to the preset's palette size with Floyd-Steinberg dithering.
6. Upscale back to the original size with `Image.NEAREST`.
7. Save the output as PNG.

## Code

```python
from PIL import Image, ImageEnhance, ImageOps

PRESETS = {
    "arcade": {
        "contrast": 1.8,
        "color": 1.5,
        "sharpness": 1.2,
        "posterize_bits": 5,
        "block": 8,
        "palette": 16,
    },
    "snes": {
        "contrast": 1.6,
        "color": 1.4,
        "sharpness": 1.2,
        "posterize_bits": 6,
        "block": 4,
        "palette": 32,
    },
}


def pixel_art(input_path, output_path, preset="arcade", **overrides):
    """
    Convert an image to retro pixel art.

    Args:
        input_path: path to source image
        output_path: path to save the resulting PNG
        preset: "arcade" or "snes"
        **overrides: optionally override any preset field
                     (contrast, color, sharpness, posterize_bits, block, palette)

    Returns:
        The resulting PIL.Image.
    """
    if preset not in PRESETS:
        raise ValueError(
            f"Unknown preset {preset!r}. Choose from: {sorted(PRESETS)}"
        )

    cfg = {**PRESETS[preset], **overrides}

    img = Image.open(input_path).convert("RGB")

    # Stylistic boost — stronger for smaller palettes
    img = ImageEnhance.Contrast(img).enhance(cfg["contrast"])
    img = ImageEnhance.Color(img).enhance(cfg["color"])
    img = ImageEnhance.Sharpness(img).enhance(cfg["sharpness"])

    # Light posterization separates tonal regions before quantization
    img = ImageOps.posterize(img, cfg["posterize_bits"])

    w, h = img.size
    block = cfg["block"]
    small = img.resize(
        (max(1, w // block), max(1, h // block)),
        Image.NEAREST,
    )

    # Quantize AFTER downscaling so dithering aligns with the final pixel grid
    quantized = small.quantize(
        colors=cfg["palette"], dither=Image.FLOYDSTEINBERG
    )
    result = quantized.resize((w, h), Image.NEAREST)

    result.save(output_path, "PNG")
    return result
```

## Example Usage

```python
# Bold arcade look (default)
pixel_art("/path/to/image.jpg", "/path/to/arcade.png")

# Cleaner SNES look with more detail
pixel_art("/path/to/image.jpg", "/path/to/snes.png", preset="snes")

# Override individual parameters — e.g. tighter palette with SNES block size
pixel_art(
    "/path/to/image.jpg",
    "/path/to/custom.png",
    preset="snes",
    palette=16,
)
```

## Why This Order Works

Floyd-Steinberg dithering distributes quantization error to adjacent pixels. Applying it AFTER downscaling keeps that error diffusion aligned with the reduced pixel grid, so each dithered pixel maps cleanly to a final enlarged block. Quantizing before downscaling wastes the dithering pattern on full-resolution detail that disappears during resize.

A light posterization step before downscaling improves separation between tonal regions, which helps photographic inputs read as stylized pixel art instead of simple pixelated photos.

Stronger pre-processing (higher contrast/color) pairs with smaller palettes because fewer colors have to carry the whole image. SNES runs softer enhancements because 32 colors can represent gradients and mid-tones directly.

## Pitfalls

- `arcade` 8px blocks are aggressive and can destroy fine detail — use `snes` for subjects that need retention
- Busy photographs can become noisy under `snes` because the larger palette preserves small variations — use `arcade` to flatten them
- Very small source images (<~100px wide) may collapse under 8px blocks. `max(1, w // block)` guards against zero dimensions, but output will be visually degenerate.
- Fractional overrides for `block` or `palette` will break quantization — keep them as positive integers.

## Verification

Output is correct if:

- A PNG file is created at the output path
- The image shows clear square pixel blocks at the preset's block size
- Dithering is visible in gradients
- The palette is limited to approximately the preset's color count
- The overall look matches the targeted era (arcade or SNES)

## Dependencies

- Python 3
- Pillow

```bash
pip install Pillow
```