从提示词到精灵资产:proper-pixel-art附带脚本ppa_gen自动生成16位像素画实战
从提示词到精灵资产:proper-pixel-art附带脚本ppa_gen自动生成16位像素画实战
proper-pixel-art 是一个把 AI 生成的高分辨率"伪像素"图片还原为真实分辨率像素画(pixel art)的开源工具,而仓库自带的 scripts/ppa_gen.py 脚本更是把"提示词 → 精灵资产"整条流水线一步打通:调用 OpenAI 图片模型生成图像,再自动执行 pixelate 像素化处理,最终输出可直接用于游戏的 16 位像素画。本文带你用这个脚本从零生成属于自己的像素精灵资产。
🎯 一条命令搞定:ppa_gen 的工作流程
很多人用 AI 画"像素风"图片时都会遇到同一个问题:模型生成的图分辨率很高,但像素网格歪歪扭扭、还带噪点,根本不是能直接进游戏的精灵资产(sprite asset)。
ppa_gen 脚本就是为了解决这个问题:
uv run python scripts/ppa_gen.py --prompt "A 16 bit pixel art robot"
它的内部流程只有三步(见 scripts/ppa_gen.py 中的 generate_images 与 process_image 函数):
- 生成:把
--prompt提示词发给 gpt-image-2 模型,得到原图; - 像素化:调用库里的
pixelate函数(proper_pixel_art/image.py),检测图像隐含的像素网格(mesh),还原成真正的像素画; - 落盘:按时间戳保存两份文件,
*_original.png(AI 原图)和*_pixelated.png(像素化结果)。
下面这只蝙蝠就是 AI 生成的"伪像素"图——放大后能看到网格明显不规则:
⚙️ 三步完成环境配置
第 1 步:获取仓库
git clone https://gitcode.com/gh_mirrors/pr/proper-pixel-art
cd proper-pixel-art
第 2 步:安装依赖
脚本依赖 openai 和 python-dotenv 两个额外的库,用 uv 一条命令装齐:
uv sync --group scripts
第 3 步:配置 API Key
在项目根目录新建 .env 文件,写入你的 OpenAI API Key:
OPENAI_API_KEY=sk-your-api-key-here
完整说明可参考 scripts/README.md。如果 Key 配置有误,脚本会直接报 OPENAI_API_KEY not found in environment 错误,按提示检查 .env 即可。
🎮 5 个最实用的参数
| 参数 | 默认值 | 作用 |
|---|---|---|
--prompt |
必填 | 提示词,描述你想生成的像素画 |
--size |
1024x1024 |
生成尺寸,可选 1024x1536、1536x1024、auto |
--n |
1 |
一次生成几张图(1-10),方便抽卡对比 |
-c / --colors |
自动 | 调色板色数(1-256),如 -c 16 限制为 16 色 |
-s / --scale-result |
不缩放 | 结果放大倍数,如 -s 10 让像素更大更清晰 |
-t / --transparent |
关 | 输出透明背景,精灵资产必备 |
-o / --output-dir |
当前目录 | 输出目录 |
一次生成 2 张透明背景的机器人精灵,完整命令如下:
uv run python scripts/ppa_gen.py \
--prompt "A 16 bit pixel art robot character with a transparent background" \
--scale-result 10 \
--transparent \
--n 2
💡 提示词技巧:直接决定成品质量
官方文档(scripts/README.md 的 Tips 一节)给出了两条经验之谈:
- 加上 "16 bit pixel art" 字样。提示模型向网格对齐的像素风格靠拢,网格越规整,后续 mesh 检测越准;
- 生成角色时要求透明背景("with a transparent background"),再配合
-t参数,输出的精灵可以直接叠在场景上。
效果对比感受一下——AI 生成的 16 位像素恶魔:
横版场景图同样适用,16:10 比例的像素山景非常适合做游戏背景:
🔍 幕后原理:从噪点图到真实像素网格
ppa_gen 的"像素化"步骤其实是 proper-pixel-art 核心算法的入口。算法会对 AI 生成的 blob 这类带噪点的图先做 Canny 边缘检测、Hough 直线变换,找出隐含的像素网格:
同一个例子处理前(左为输入,右为还原后的真实像素分辨率结果):
每个网格单元取一个代表色重建图像,噪点、错位、杂色全部被"归位",得到的才是真正的 16 位像素画。
📦 输出文件与调参建议
运行成功后,输出目录会出现带时间戳的文件对:
20261116_101036_original.png # AI 原图
20261116_101036_pixelated.png # 像素化结果
调参小建议:
-c是最常需要微调的参数,结果偏糊或偏碎时,试几个不同色数(8 / 16 / 32);- 网格检测不理想时,可以调大
-u(--initial-upscale)帮助识别像素边缘; - 想批量抽卡就加大
--n,一次生成多张挑最好的。
除了 ppa_gen,仓库的 scripts/gen_outputs.py 脚本还能把 tests/cases.py 里的所有用例重新跑一遍,方便你对照 assets/ 目录下的官方示例(bat、blob、demon、pumpkin、mountain)验证算法改动——这也是理解每种输入类型的最佳参考资料。
✅ 小结
| 需求 | 做法 |
|---|---|
| 快速出一张像素画 | ppa_gen.py --prompt "A 16 bit pixel art ..." |
| 生成游戏精灵 | 加 -t 透明背景 + 提示词要求 transparent background |
| 想要经典 16 色风格 | 加 -c 16 |
| 对比多个方案 | 加 --n 4 批量生成 |
一条命令、两个参数,从提示词到可交付的 16 位像素精灵资产,proper-pixel-art 的 ppa_gen 脚本确实把"AI 出图 → 游戏素材"这条路铺得又短又平。