pindou-pattern-from-image

把任意一张图（插画、照片、地图、Logo、二次元老婆、emoji、社媒截图）转成可实际拼的拼豆图纸（拼拼豆豆 / perler / HAMA 通用）。

一句话能做什么

./scripts/run.sh convert photo.jpg ./out
# ./out 里得到一张 PNG:  色块 + 色号 + 行/列 header + 底部紧凑配色表
#                                       ——打开就能照着拼，附赠购物清单

适用场景

• "把这张图转成拼豆图纸"/"做一张拼豆图"/"帮我绣这个"
• "我需要几袋 XX 色的豆子"/"购物清单"/"shopping list"
• "实物长什么样"/"拼完长啥样"（预览图）
• 任意输入：插画、矢量、照片、地图、Logo、emoji、社媒截图

快速开始

# 把仓库 clone 下来
git clone https://github.com/Pinkoceans/pindou-pattern-from-image.git
cd pindou-pattern-from-image

# 直接用（run.sh 会自动准备 Pillow venv，无需手动 pip install）
./scripts/run.sh convert path/to/your/image.jpg ./out

第一次运行会下载 Pillow（已缓存到 ~/.cache/pindou-pattern/venv），稍等一下就好。

支持的子命令

子命令	作用
convert / all	完整流水线：把图转成拼豆图纸（默认）
multi	多面板图：自动检测一张图里的 N 个独立图案（适用于 Minecraft 方块纸模展开、贴纸集）。每个图案独立量化，共享色卡
3d	3D 立体拼豆：自动识别实物图的分层，每层出一张拼豆图 + 拼装预览
quantize	仅量化到板尺寸 + 配色（中间产物）
pattern	仅出图纸（PNG 或 SVG）
realistic	仅出 3D 立体豆预览
preview	仅出平面圆点图（备用）
palette	列出 bundled palettes

常用参数

参数	默认	备注
--board	auto	不传则按图片自动推荐 29 / 52 / 73 / 100 板
--cell-px	32	图纸每格像素（越大色号越清楚）
--no-labels / --no-grid / --no-header / --no-legend	关闭	各种图面元素开关
--with-realistic	off	额外生成 3D 立体豆预览（默认只出图纸）
--realistic-cell-px	24	3D 预览每豆像素

自动推荐板尺寸

不传 --board 时，按颜色复杂度 + 长宽比自动选：

颜色复杂度	板尺寸档
≤ 8 色（logo / 图标）	29
9–32 色（一般插画）	52
33–96 色（细节丰富的插画）	73
> 96 色（照片 / 写实）	100

横图→长方形板（如 100×73），竖图→长方形板（如 73×100）。

实物图（样品图）说明

你拼完拼豆作品后想看真实成品长啥样，自己拍一张照片——那才是真正的"样品图"。

本工具的 "--with-realistic" 输出的是程序渲染的"立体豆预览"：帮你大致预览拼完后的样子，不能代替真实照片。

局限性

• 照片类输入：每 cell 均值会"糊"，细节丢失严重。建议先把图做成"像素风"再传进来。
• 没有 dithering：连续渐变（如天空）会出 banding。
• 多面板检测：仅识别高饱和度色块；纯黑白 + 微小色点的图案可能漏检。
• 3D 分层检测：仅在"棱柱形"作品上可靠（城堡、房子、堆叠方块）。球形/曲面作品检测不到分层，需要手动 --layers N。

依赖

• Python 3.8+
• Pillow（自动安装）

许可

MIT