pixel-art
Pixel art w/ era palettes (NES, Game Boy, PICO-8).
SKILL.mdskills/creative/pixel-art/SKILL.md
GitHubPixel 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:
- Draw a stylized character using
PIL.ImageDraw— hoodie, accessories, bold flat colors, dark background - Apply mosaic effect manually (block average, 10-14px blocks) OR run
pixel_art.py --preset neon/arcade - 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:
- Generate an illustrated character using PIL/Pillow drawing primitives (see
scripts/nft_avatar_generator.py) - Apply mosaic grid effect manually (block average + grid lines, block_size=12px works well for 800x800)
- Optionally chain into
pixel_art.pyfor 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:
- Boost contrast/color/sharpness (stronger for smaller palettes)
- Posterize to simplify tonal regions before quantization
- Downscale by
blockwithImage.NEAREST(hard pixels, no interpolation) - Quantize with Floyd-Steinberg dithering — against either an adaptive N-color palette OR a named hardware palette
- 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 withcurl -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.pydirectly 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_visionandvision_analyzetools 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.comorpicsum.photosinstead. - Fractional
blockorpalettewill 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_amberforcecolor=0.0(desaturate). If you override and keep chroma, the 2-color palette can produce stripes on smooth regions.clarifyloop: 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 (
ffprobecan 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.