bot-008-pixel-art-studio

name: bot-008-pixel-art-studio description: Generate pixel art from a text prompt via Pollinations, or convert an uploaded photo into pixel art with hardware presets (NES, SNES, Game Boy, C64, etc). Use for retro/8-bit/16-bit visuals for marketing, social posts, and brand content. Two independent flows — never feed the photo converter on top of Pollinations output.

Pixel Art Studio (BOT-008)

Two flows in one skill, vendored from Synero/pixel-art-studio (MIT). Animated video is intentionally out of scope for this version.

Hard rule: Pollinations output is already pixel art. Never run pixelart.py on top of it.

Outputs

All outputs MUST land under /home/user/artifacts/<project-name>/:

• artifacts/<project>/text2pixel/{slug}_{tech}_{artistic}_{w}.png — generated PNG
• artifacts/<project>/text2pixel/summary.md — prompt, chosen styles, Pollinations URL
• artifacts/<project>/photo2pixel/{source-stem}_{preset}.png — converted PNG
• artifacts/<project>/photo2pixel/summary.md — source path, preset, palette, dither
• artifacts/<project>/error.md — only on clean failure (rate-limit exhausted, missing input)

Setup (run once per session)

cd /home/user/skills/bot-008-pixel-art-studio
pip install -q -r requirements.txt   # Pillow, numpy, scipy, requests

If scipy install fails, the photo converter degrades gracefully (no Sobel edge-aware downsampling, otherwise identical). Note the degradation in summary.md.

Extracting Intent

The user describes what they want in their own words. Extract:

1. Subject — what's in the scene (wizard, cat, city, product shot)
2. Artistic style — how it should feel (cyberpunk, medieval, anime, cozy)
3. Technical style — how pixels should look (NES, SNES, arcade, Game Boy)
4. Has photo? — if yes, take the photo→pixel branch

Don't force the user to pick. If they say "cyberpunk neon city pixel art" — that's the artistic style. If they say "retro 8-bit dragon" — that's the technical style. Only fill what's missing using defaults.

Flow 1 — Text → Pixel Art (Pollinations)

Artistic Styles

Technical Styles

Default recommendation: nes for characters, snes for scenes, arcade for bold posters.

Aspect Ratios

When in doubt: 640x480.

Invocation

python scripts/pixelart_image.py "a wizard in a dark forest" \
  --tech nes --artistic medieval --ratio 640x480 \
  --output-dir artifacts/<project>/text2pixel

The script handles prompt building, Pollinations call, and PNG save. Output path: artifacts/<project>/text2pixel/{slug}_{tech}_{artistic}_{w}.png.

After the call, write artifacts/<project>/text2pixel/summary.md with: prompt, tech_style, artistic_style, resolution, Pollinations URL used, and any seed-swap or rephrase notes.

Pollinations URL Contract

https://image.pollinations.ai/prompt/{url_encoded}?width=W&height=H&nologo=true

Quirks:

• Aggressive caching — same prompt = identical output (seed mostly ignored)
• Rate limit: ~1 request per 60 seconds. On 429 / network error: wait ≥60s, retry once, then fail clean. Do not loop.
• Max effective resolution: ~768×768.
• Anonymous, no API key.

Anti-Hallucination Patterns

Reliable subjects (render cleanly):

• Cyberpunk/neon scenes, rain reflections, urban nights
• Mages/spellcasters with fire or magic particles
• Cats, animals, food, cozy interiors
• Samurai (better than knights for warrior subjects)
• Landscapes

Risky subjects (likely artifacts):

• Knights with raised swords (sword often duplicated, misplaced, or rendered as a building)
• Multi-action descriptions ("running while throwing a shield as the building explodes")
• Many objects clustered near a body

Strategy when a risky subject is requested:

1. Rephrase once toward a safer composition (mage instead of sword-knight; samurai instead of armored warrior).
2. Note the substitution in summary.md so the user understands what changed.
3. If the user explicitly insists, attempt the literal prompt and accept the risk.

Prompt structure that works:

[concrete subject + scene], pixel art, [tech] style, [artistic mods], [mood]

Examples

Flow 2 — Photo → Pixel Art

Presets (14)

Named Palettes

Hardware: NES, C64, ZX_SPECTRUM, PICO_8, GAMEBOY_ORIGINAL, GAMEBOY_POCKET, GAMEBOY_VIRTUALBOY, APPLE_II_LO, APPLE_II_HI, TELETEXT, CGA_MODE4_PAL1, CGA_MODE5_PAL1, MSX, MICROSOFT_WINDOWS_16, MICROSOFT_WINDOWS_PAINT, MONO_BW, MONO_AMBER, MONO_GREEN

Artistic: PASTEL_DREAM, NEON_CYBER, RETRO_WARM, OCEAN_DEEP, FOREST_MOSS, SUNSET_FIRE, ARCTIC_ICE, VINTAGE_ROSE, EARTH_CLAY, ELECTRIC_VIOLET

Dithering Methods

Invocation

python scripts/pixelart.py "$PHOTO_PATH" --preset nes \
  -o artifacts/<project>/photo2pixel/{source-stem}_nes.png

# Or override palette/dither:
python scripts/pixelart.py "$PHOTO_PATH" --palette NEON_CYBER --dither atkinson \
  -o artifacts/<project>/photo2pixel/{source-stem}_neon_atkinson.png

# List options:
python scripts/pixelart.py --list-presets
python scripts/pixelart.py --list-palettes

After the call, write artifacts/<project>/photo2pixel/summary.md with: source photo path, preset chosen, palette, dither method.

When to Override Preset Defaults

• Brand palette match: user mentions a specific palette feel ("neon", "pastel", "vintage rose") → override with the matching named palette.
• Portrait of a person: prefer floyd dither for smoother skin tones; nes or snes preset.
• Logo or graphic with hard edges: prefer none dither; arcade or clean preset.
• Maximum nostalgia: gameboy preset, no overrides.

Default Choices (Headless)

When the user is vague, fall back to these defaults and document the choice in summary.md:

Rules

1. NEVER apply pixelart.py to Pollinations output — they are independent flows.
2. ALWAYS write a summary.md next to the PNG documenting the choices.
3. ALWAYS exit non-zero with error.md on a clean failure rather than hanging.
4. Default to one generation per request — the user can ask for a variation explicitly.
5. Never ask the user a question at runtime; document defaults in summary.md.

Attribution

Vendored from https://github.com/Synero/pixel-art-studio (MIT). See NOTICE in this folder.