pixel-art

Pixel art w/ era palettes (NES, Game Boy, PICO-8).

SKILL.md

GitHub

Pixel Art

Convert any image into retro pixel art, then optionally animate it into a short MP4 or GIF with era-appropriate effects (rain, fireflies, snow, embers).

Three scripts ship with this skill:

  • scripts/pixel_art.py — photo → pixel-art PNG (Floyd-Steinberg dithering)
  • scripts/pixel_art_video.py — pixel-art PNG → animated MP4 (+ optional GIF)
  • scripts/nft_avatar_generator.py — generate illustrated NFT avatar character (no real face) + mosaic effect

Each is importable or runnable directly. Presets snap to hardware palettes when you want era-accurate colors (NES, Game Boy, PICO-8, etc.), or use adaptive N-color quantization for arcade/SNES-style looks.

When to Use

  • User wants retro pixel art from a source image
  • User asks for NES / Game Boy / PICO-8 / C64 / arcade / SNES styling
  • User wants a short looping animation (rain scene, night sky, snow, etc.)
  • Posters, album covers, social posts, sprites, characters, avatars
  • NFT profile pictures / Twitter PFP with mosaic/pixel effect

NFT Avatar Workflow (no source photo)

When the user wants an NFT-style avatar (Twitter PFP, NFT portrait) and has NO source image:

DO NOT use thispersondoesnotexist.com or any real human photo — user explicitly rejected this. DO NOT use fal.ai image_generate without checking balance first (can fail with "Exhausted balance").

Instead, generate an illustrated cartoon character with PIL first, then apply pixel_art.py on top:

  1. Draw a stylized character using PIL.ImageDraw — hoodie, accessories, bold flat colors, dark background
  2. Apply mosaic effect manually (block average, 10-14px blocks) OR run pixel_art.py --preset neon/arcade
  3. Add neon border, corner accents, glow effects

Key PIL mosaic snippet:

mosaic_size = 12
draw_m = ImageDraw.Draw(mosaic)
for y in range(0, h, mosaic_size):
    for x in range(0, w, mosaic_size):
        block = img.crop((x, y, min(x+mosaic_size,w), min(y+mosaic_size,h)))
        avg = block.resize((1,1), Image.LANCZOS).getpixel((0,0))
        draw_m.rectangle([x, y, min(x+mosaic_size-1,w-1), min(y+mosaic_size-1,h-1)], fill=avg)
        draw_m.rectangle([x, y, min(x+mosaic_size-1,w-1), min(y+mosaic_size-1,h-1)],
                         outline=(0,0,0), width=1)

Recommended presets for NFT PFP: neon (cyberpunk) or arcade (bold). Output at 800x800 minimum.

  • NFT profile picture / Twitter PFP with mosaic/pixel effect

NFT Avatar Mode (no source photo)

When the user wants an NFT-style avatar without providing a source photo, do NOT use a real human face (thispersondoesnotexist or similar). Instead:

  1. Generate an illustrated character using PIL/Pillow drawing primitives (see scripts/nft_avatar_generator.py)
  2. Apply mosaic grid effect manually (block average + grid lines, block_size=12px works well for 800x800)
  3. Optionally chain into pixel_art.py for additional palette reduction

Preferred style for NFT PFP: dark background, hoodie/jacket, gold chain, stylized eyes (cyan iris), sunglasses pushed up, earrings, neon border frame, hexagon background pattern. Colors: dark purple bg, warm skin tone, gold accents, cyan eyes.

Do NOT use real human photos as source for NFT avatars — user explicitly rejected this approach. Use illustrated/cartoon characters only.

Manual Mosaic Effect (without pixel_art.py)

mosaic_size = 12  # px, good for 800x800
draw_m = ImageDraw.Draw(mosaic)
for y in range(0, h, mosaic_size):
    for x in range(0, w, mosaic_size):
        block = img.crop((x, y, min(x+mosaic_size,w), min(y+mosaic_size,h)))
        avg = block.resize((1,1), Image.LANCZOS).getpixel((0,0))
        draw_m.rectangle([x, y, min(x+mosaic_size-1,w-1), min(y+mosaic_size-1,h-1)], fill=avg)
        draw_m.rectangle([x, y, min(x+mosaic_size-1,w-1), min(y+mosaic_size-1,h-1)],
                         outline=(0,0,0), width=1)

Note: applying pixel_art.py on top of a small illustrated source (512px) produces tiny files (1-4KB) because the illustration has too few colors — the mosaic collapses. Use 800x800+ source and manual mosaic first, then optionally apply pixel_art for palette reduction.

Workflow

Before generating, confirm the style with the user. Different presets produce very different outputs and regenerating is costly.

Step 1 — Offer a style

Call clarify with 4 representative presets. Pick the set based on what the user asked for — don't just dump all 14.

Default menu when the user's intent is unclear:

clarify(
    question="Which pixel-art style do you want?",
    choices=[
        "arcade — bold, chunky 80s cabinet feel (16 colors, 8px)",
        "nes — Nintendo 8-bit hardware palette (54 colors, 8px)",
        "gameboy — 4-shade green Game Boy DMG",
        "snes — cleaner 16-bit look (32 colors, 4px)",
    ],
)

When the user already named an era (e.g. "80s arcade", "Gameboy"), skip clarify and use the matching preset directly.

Step 2 — Offer animation (optional)

If the user asked for a video/GIF, or the output might benefit from motion, ask which scene:

clarify(
    question="Want to animate it? Pick a scene or skip.",
    choices=[
        "night — stars + fireflies + leaves",
        "urban — rain + neon pulse",
        "snow — falling snowflakes",
        "skip — just the image",
    ],
)

Do NOT call clarify more than twice in a row. One for style, one for scene if animation is on the table. If the user explicitly asked for a specific style and scene in their message, skip clarify entirely.

Step 3 — Generate

Run pixel_art() first; if animation was requested, chain into pixel_art_video() on the result.

Preset Catalog

Preset Era Palette Block Best for
arcade 80s arcade adaptive 16 8px Bold posters, hero art
snes 16-bit adaptive 32 4px Characters, detailed scenes
nes 8-bit NES (54) 8px True NES look
gameboy DMG handheld 4 green shades 8px Monochrome Game Boy
gameboy_pocket Pocket handheld 4 grey shades 8px Mono GB Pocket
pico8 PICO-8 16 fixed 6px Fantasy-console look
c64 Commodore 64 16 fixed 8px 8-bit home computer
apple2 Apple II hi-res 6 fixed 10px Extreme retro, 6 colors
teletext BBC Teletext 8 pure 10px Chunky primary colors
mspaint Windows MS Paint 24 fixed 8px Nostalgic desktop
mono_green CRT phosphor 2 green 6px Terminal/CRT aesthetic
mono_amber CRT amber 2 amber 6px Amber monitor look
neon Cyberpunk 10 neons 6px Vaporwave/cyber
pastel Soft pastel 10 pastels 6px Kawaii / gentle

Named palettes live in scripts/palettes.py (see references/palettes.md for the complete list — 28 named palettes total). Any preset can be overridden:

pixel_art("in.png", "out.png", preset="snes", palette="PICO_8", block=6)

Scene Catalog (for video)

Scene Effects
night Twinkling stars + fireflies + drifting leaves
dusk Fireflies + sparkles
tavern Dust motes + warm sparkles
indoor Dust motes
urban Rain + neon pulse
nature Leaves + fireflies
magic Sparkles + fireflies
storm Rain + lightning
underwater Bubbles + light sparkles
fire Embers + sparkles
snow Snowflakes + sparkles
desert Heat shimmer + dust

Invocation Patterns

Python (import)

import sys
sys.path.insert(0, "/home/teknium/.hermes/skills/creative/pixel-art/scripts")
from pixel_art import pixel_art
from pixel_art_video import pixel_art_video

# 1. Convert to pixel art
pixel_art("/path/to/photo.jpg", "/tmp/pixel.png", preset="nes")

# 2. Animate (optional)
pixel_art_video(
    "/tmp/pixel.png",
    "/tmp/pixel.mp4",
    scene="night",
    duration=6,
    fps=15,
    seed=42,
    export_gif=True,
)

CLI

cd /home/teknium/.hermes/skills/creative/pixel-art/scripts

python pixel_art.py in.jpg out.png --preset gameboy
python pixel_art.py in.jpg out.png --preset snes --palette PICO_8 --block 6

python pixel_art_video.py out.png out.mp4 --scene night --duration 6 --gif

Pipeline Rationale

Pixel conversion:

  1. Boost contrast/color/sharpness (stronger for smaller palettes)
  2. Posterize to simplify tonal regions before quantization
  3. Downscale by block with Image.NEAREST (hard pixels, no interpolation)
  4. Quantize with Floyd-Steinberg dithering — against either an adaptive N-color palette OR a named hardware palette
  5. Upscale back with Image.NEAREST

Quantizing AFTER downscale keeps dithering aligned with the final pixel grid. Quantizing before would waste error-diffusion on detail that disappears.

Video overlay:

  • Copies the base frame each tick (static background)
  • Overlays stateless-per-frame particle draws (one function per effect)
  • Encodes via ffmpeg libx264 -pix_fmt yuv420p -crf 18
  • Optional GIF via palettegen + paletteuse

Dependencies

  • Python 3.9+
  • Pillow (pip install Pillow)
  • ffmpeg on PATH (only needed for video — Hermes installs package this)

Source Images

When the user doesn't provide a photo and asks you to find one:

  • Best source for portrait/face NFT: https://thispersondoesnotexist.com/ — returns a 1024×1024 AI-generated face, perfect for pixel art conversion. Download with curl -sL https://thispersondoesnotexist.com/ -o face.jpg
  • Unsplash blocks bots (returns 403/Access Denied). Picsum (picsum.photos) works but returns landscapes/objects, not faces.
  • For NFT PFP use cases, AI-generated faces avoid copyright issues entirely.

Multi-Style Comparison Workflow

When the user hasn't picked a style, generate 3 variants and let them choose visually — it's faster than asking:

for preset in ["neon", "arcade", "snes"]:
    pixel_art(src, f"/tmp/nft_{preset}.png", preset=preset)
# Send all 3 as MEDIA: files

Good default trio for NFT/PFP: neon (cyberpunk), arcade (bold retro), snes (detailed).

Pitfalls

  • NFT avatar source: Never use real human photos (thispersondoesnotexist etc.) for NFT PFP generation — user rejected this. Use illustrated characters only (nft_avatar_generator.py).
  • Small illustrated source → tiny output file: Applying pixel_art.py directly on a small (512px) PIL-drawn illustration produces 1-4KB files because the illustration already has very few colors — the quantizer collapses everything. Fix: use 800x800+ source, apply manual mosaic first, then optionally chain pixel_art for palette reduction.
  • fal.ai image_generate: May fail with "Exhausted balance" — have a PIL fallback ready.
  • Pallet keys are case-sensitive ("NES", "PICO_8", "GAMEBOY_ORIGINAL").
  • Very small sources (<100px wide) collapse under 8-10px blocks. Upscale the source first if it's tiny.
  • browser_vision and vision_analyze tools may return 401 auth errors — don't rely on them to preview/validate source images. Just download and process directly.
  • Unsplash blocks automated access (returns "Access Denied: BotStopper"). Use thispersondoesnotexist.com or picsum.photos instead.
  • Fractional block or palette will break quantization — keep them positive ints.
  • Animation particle counts are tuned for ~640x480 canvases. On very large images you may want a second pass with a different seed for density.
  • mono_green / mono_amber force color=0.0 (desaturate). If you override and keep chroma, the 2-color palette can produce stripes on smooth regions.
  • clarify loop: call it at most twice per turn (style, then scene). Don't pepper the user with more picks.

Verification

  • PNG is created at the output path
  • Clear square pixel blocks visible at the preset's block size
  • Color count matches preset (eyeball the image or run Image.open(p).getcolors())
  • Video is a valid MP4 (ffprobe can open it) with non-zero size

Attribution

Named hardware palettes and the procedural animation loops in pixel_art_video.py are ported from pixel-art-studio (MIT). See ATTRIBUTION.md in this skill directory for details.