拼豆图纸生成器 · Pindou Pattern Maker

概览

上传一张拼豆成品照片、设计图或已有图纸截图，输出三样：

1. 色号清单 —— 每个 Mard 色号需要多少颗（CSV + Markdown 表）
2. 拼豆图纸 —— HTML 可交互/可打印版 + PNG 图片版
3. 识别报告 —— 尺寸、总颗数、用色数、参数记录

色彩映射基于 Mard 拼豆色卡 v1（221 实色，A1–M15），在 CIELab 空间用 ΔE76 最近邻取色，支持相近色合并、限色数、零星色归并、空格底色自动排除。原理见 references/color-science.md。

不做库存管理（记账、补豆清单不在范围内）。

触发：用户上传图片并问「需要哪些色号 / 每种多少颗」「生成拼豆图纸 / 打印版图纸」「把这张图变成能照着拼的图纸」「识别一下这个拼豆图案」，或英文 perler bead pattern / bead color list / how many beads。
不触发：库存记账与补豆清单；未提供图片的纯文字需求（先要图）。

环境要求

• Python 3.9+（优先用 WorkBuddy 托管 Python）
• 依赖：pip install pillow numpy（numpy 缺失时自动退化为纯 Python 计算，结果一致、较慢）
• 色卡：assets/mard-palette.csv（221 色，随技能分发，勿删）

快速开始

# 已知格数（最准，图纸截图/成品照优先用这个）
python scripts/bead_pattern.py --image 成品.jpg --cols 29 --out ./out --name 小兔子

# 不知道格数 → 照片降采样模式（宽度即格数）
python scripts/bead_pattern.py --image 成品.jpg --width 60 --out ./out

# 手头只有某档套装：只用这套里的色号出图，清单可直接照着备豆
python scripts/bead_pattern.py --image 成品.jpg --cols 29 --set 48 --out ./out

# 改过引擎后的回归自检
python scripts/self_test.py

运行结束打印摘要，并在输出目录写 6 个文件：*-图纸.html、*-图纸.png、*-对比图.png、*-色号清单.csv、*-报告.md、*-result.json。

Agent 工作流（拿到图片后怎么做）

Step 1 · 看图判断类型

• 任意照片（风景/人物/宠物/插画，用户不关心原格数）→ --mode photo（默认），不用问格数
• 已有图纸截图 / 规则拼豆成品（带网格线、格子里印色号，或能看清一颗颗圆豆）→ --mode grid，必须知道列数
• 设计稿/像素图（没有明显网格）→ --mode photo，按期望成品大小定格宽

Step 2 · 问清关键参数（只问缺的，一次最多两个）

1. 期望成品大小（photo 模式唯一要定的）：不答默认 60 格宽。参考：手机挂件 30–40 格，小摆件 50–70 格，大幅挂画 80–120 格
2. 格子长宽/列数：图是图纸截图时必须先问（如 67×56），用户只知道总数就问"横向多少格"。问到就走 grid 模式——这是精度上限的分水岭（依据见 references/accuracy-notes.md）
3. 限色数：一般不问；用户说"豆不多"调到 8–12，说"要细腻"调到 24–30
4. 套装：用户说"我只有 48 色套装 / 我买的是 XX 套装"时加 --set 48（可选档位见参数表）。套装和限色不是一回事——限色是让图纸少用几种颜色，套装是"只从我拥有的这批色号里选"，套装外的颜色会被映射到套装内最接近的色号，颗数不变

grid 模式默认忠实还原（不合并色、不限色数），并自动排除空格底色——格子里印的色号文字与网格线不影响结果，不用再问采样细节。

Step 3 · 运行脚本

python scripts/bead_pattern.py \
  --image <图片路径> --out <输出目录> --name <图纸名> \
  --mode grid --cols 29            # 或 --mode photo --width 60
  [--max-colors 18] [--merge 8] [--min-count 1]
  [--crop 左,上,右,下] [--bg-remove] [--saturate 1.1]

Step 4 · 质检结果（必做）

先看 *-对比图.png（原图 vs 图纸并排），再决定是否调参重跑。常见调整：

更多实测案例（幻影色号、颗数虚多）见 references/troubleshooting.md。

Step 5 · 交付

按优先级展示（HTML 图纸放第一个）：*-图纸.html → *-图纸.png → *-色号清单.csv → *-报告.md。
回复里给出：格数、总颗数、用色数、Top 色号清单（色号 + 颗数表格）。

参数速查

边界与限制

• 普通照片"像不像"取决于格宽：60 格是挂件级精度，80–120 格才像（颗数会到 1 万+）
• 只收录 221 个实色；透明/夜光等特殊色会映射到最近的实色（见 references/palette-notes.md）
• 斜拍/透视明显的照片先用 --crop 框住成品，严重透视请用户摆正重拍
• 超大图（>400 格宽）grid 模式采样慢，photo 模式无压力

深入参考

Files

• scripts/bead_pattern.py —— 主引擎（无网络依赖，本地运行）
• scripts/self_test.py —— 自检脚本（改引擎后跑回归）
• assets/mard-palette.csv —— Mard 色卡 221 色（code,hex）
• examples/ —— 色号清单与报告的文本示例