pixel-art

像素艺术

将任意图像转换为复古像素艺术，还可以选择添加符合时代风格的特效（雨、萤火虫、雪、余烬），制作成短 MP4 或 GIF 动画。

此技能包含两个脚本：

• scripts/pixel_art.py — 照片 → 像素艺术 PNG（Floyd-Steinberg 抖动）
• scripts/pixel_art_video.py — 像素艺术 PNG → 动画 MP4（+ 可选 GIF）

每个脚本都可导入或直接运行。需要符合时代风格的颜色时，可选择贴合硬件调色板的预设（NES、Game Boy、PICO-8 等）；也可以使用自适应 N 色量化，呈现街机/SNES 风格。

适用场景

• 用户想将源图像转换为复古像素艺术
• 用户要求 NES / Game Boy / PICO-8 / C64 / 街机 / SNES 风格
• 用户想要短循环动画（雨景、夜空、雪景等）
• 海报、专辑封面、社交媒体帖子、精灵图、角色、头像

工作流

生成前，先与用户确认风格。不同预设会产生截然不同的效果，重新生成成本较高。

第 1 步 — 提供风格选项

调用 clarify，提供 4 个有代表性的预设。根据用户的需求选择预设组合，不要直接列出全部 14 个。

用户意图不明确时的默认菜单：

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)",
    ],
)

如果用户已经指定了某个时代风格（例如“80 年代街机”“Gameboy”），则跳过 clarify，直接使用相应预设。

第 2 步 — 提供动画选项（可选）

如果用户要求制作视频/GIF，或输出可能适合加入动态效果，请询问想要哪种场景：

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",
    ],
)

不要连续调用 clarify 超过两次。一次用于确认风格；如果考虑制作动画，再调用一次确认场景。如果用户已在消息中明确指定了风格和场景，则完全跳过 clarify。

第 3 步 — 生成

先运行 pixel_art()；如果用户要求制作动画，则将结果传入 pixel_art_video()。

预设目录

预设	时代	调色板	像素块	适用场景
arcade	80 年代街机	自适应 16 色	8px	醒目的海报、主视觉图
snes	16 位	自适应 32 色	4px	角色、细节丰富的场景
nes	8 位	NES（54 色）	8px	真实 NES 风格
gameboy	DMG 掌机	4 种绿色	8px	单色 Game Boy 风格
gameboy_pocket	Pocket 掌机	4 种灰色	8px	单色 GB Pocket 风格
pico8	PICO-8	固定 16 色	6px	Fantasy Console 风格
c64	Commodore 64	固定 16 色	8px	8 位家用电脑风格
apple2	Apple II 高分辨率	固定 6 色	10px	极致复古，仅 6 种颜色
teletext	BBC Teletext	8 种纯色	10px	粗犷的原色风格
mspaint	Windows MS Paint	固定 24 色	8px	怀旧桌面风格
mono_green	CRT 荧光屏	2 种绿色	6px	终端/CRT 美学
mono_amber	CRT 琥珀色	2 种琥珀色	6px	琥珀色显示器风格
neon	赛博朋克	10 种霓虹色	6px	蒸汽波/赛博风格
pastel	柔和粉彩	10 种粉彩色	6px	可爱/柔和风格

命名调色板位于 scripts/palettes.py（完整列表见 references/palettes.md，共 28 种命名调色板）。任何预设都可以覆盖：

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

场景目录（用于视频）

场景	效果
night	闪烁的星星 + 萤火虫 + 飘落的树叶
dusk	萤火虫 + 闪光
tavern	尘埃微粒 + 温暖的闪光
indoor	尘埃微粒
urban	雨 + 霓虹灯脉动
nature	树叶 + 萤火虫
magic	闪光 + 萤火虫
storm	雨 + 闪电
underwater	气泡 + 光点闪烁
fire	余烬 + 闪光
snow	雪花 + 闪光
desert	热浪扭曲 + 尘埃

调用方式

Python（导入）

import sys
import os
sys.path.insert(0, os.path.expanduser("~/.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
out = os.path.expanduser("~/.hermes/cache/scratch")
pixel_art("/path/to/photo.jpg", f"{out}/pixel.png", preset="nes")

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

CLI

cd ~/.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

流程设计理由

像素转换：

1. 增强对比度、色彩和锐度（调色板越小，增强幅度越大）
2. 进行色调分级，以在量化前简化色调区域
3. 使用 Image.NEAREST 按 block 缩小图像（保留硬朗像素，不进行插值）
4. 使用 Floyd-Steinberg 抖动进行量化——使用自适应 N 色调色板或命名硬件调色板
5. 使用 Image.NEAREST 放大回原尺寸

缩小后再量化，可让抖动与最终像素网格对齐。 如果在缩小前量化，误差扩散就会浪费在最终会消失的细节上。

视频叠加：

• 每个计时周期都会复制基础帧（静态背景）
• 叠加逐帧无状态的粒子绘制（每种效果使用一个函数）
• 通过 ffmpeg libx264 -pix_fmt yuv420p -crf 18 编码
• 可选生成 GIF，使用 palettegen + paletteuse

依赖项

• Python 3.9+
• Pillow（pip install Pillow）
• PATH 中需有 ffmpeg（仅生成视频时需要——Hermes 会安装此软件包）

注意事项

• 调色板键区分大小写（"NES"、"PICO_8"、"GAMEBOY_ORIGINAL"）。
• 极小的源图像（宽度 <100px）在使用 8-10px 的块时会变得模糊。如果源图像很小，请先放大。
• block 或 palette 为小数时会导致量化失败——请使用正整数。
• 动画粒子数量针对约 640x480 的画布进行了调整。对于非常大的图像，可以考虑使用不同的种子再处理一次，以调整密度。
• mono_green / mono_amber 会强制设置 color=0.0（去饱和）。如果覆盖此设置并保留色度，双色调色板可能会在平滑区域产生条纹。
• clarify 循环：每轮最多调用两次（先确定风格，再确定场景）。不要反复让用户做选择。

验证

• 已在输出路径创建 PNG
• 可见清晰的方形像素块，尺寸与预设的块大小一致
• 颜色数量与预设相符（目测图像，或运行 Image.open(p).getcolors()）
• 视频是有效的 MP4（ffprobe 可以打开），且文件大小不为零

署名

pixel_art_video.py 中的命名硬件调色板和程序化动画循环移植自 pixel-art-studio （MIT）。详情请参阅此技能目录中的 ATTRIBUTION.md。