| name | pindou |
| description | 拼豆图纸转换工具：将图片转换为拼豆（Perler/Artkal/Hama）图纸。 支持CIEDE2000精准颜色匹配、多品牌色板切换、Floyd-Steinberg/Bayer抖动、 多板拼接、透明背景处理、智能抠图、立体拆件，导出PNG/PDF。 当用户提到拼豆、perler beads、豆豆图纸、像素画转拼豆、熨斗珠、 hama beads、artkal、融合豆、拼拼豆豆、bead pattern时使用。 即使用户只说"帮我把这张图变成拼豆"也应触发。 |
拼豆图纸助手
将任意图片转换为可执行的拼豆（Perler Beads）图纸，支持多品牌色板精确匹配。
脚本位置
所有 Python 脚本在 ~/.claude/skills/pindou/scripts/ 下：
| 脚本 | 用途 |
|---|
convert.py | 主入口，串联完整转换流程 |
color_science.py | CIEDE2000 颜色匹配引擎 |
dithering.py | 抖动算法（Floyd-Steinberg / Bayer） |
grid_render.py | 网格渲染 + PNG 导出 |
dithering.py | 抖动算法（Floyd-Steinberg / Bayer） |
panel_generator.py | 立体拆件面片生成 |
依赖
核心依赖（必须已安装）：
- Python 3.10+
- numpy
- Pillow (PIL)
可选依赖（按需安装）：
rembg：智能抠图（首次使用需下载 ~170MB 模型）
第零步：判断图片类型
收到用户图片后，先用视觉能力判断图片类型，再决定走哪个流程：
| 图片类型 | 特征 | 走哪个流程 |
|---|
| 平面参考图 | 普通照片、插画、像素画、截图等 | → 标准转换流程 |
| 立体拼豆作品 | 照片中能看到拼豆颗粒、立体结构、熨烫痕迹 | → 立体拆件流程 |
| 不确定 | 无法判断 | → 问用户："这张图是要转成平面图纸，还是做立体拆件？" |
识别线索：立体拼豆作品通常有明显的颗粒质感、规整的圆形/方形排列、熨烫后的光泽、多个面片组合的立体结构。
标准转换流程
1. 用户提供图片和参数
从用户的自然语言中提取以下参数：
| 参数 | CLI 标志 | 默认值 | 说明 |
|---|
| 图片路径 | 第一个参数 | (必填) | PNG/JPG/BMP/WebP |
| 板子尺寸 | --board WxH | 58x58 | 每板的宽×高格数 |
| 多板拼接 | --grid RxC | 1x1 | R行×C列（上限5×5） |
| 色板 | --palette NAME | artkal_s | 见下方色板列表 |
| 排除颜色 | --exclude A,B,C | 无 | 逗号分隔的颜色编号 |
| 抖动算法 | --dither floyd|bayer | none | 抖动类型 |
| 抖动强度 | --dither-strength N | 100 | 0-100 |
| 显示模式 | --mode | blocks+numbers | blocks/dots/numbers/blocks+numbers |
| 格子大小 | --cell-size N | 20 | 每格像素数 |
| 参考线间隔 | --ref-lines N | 10 | 每N格画粗线（0=关闭） |
| 色彩替换 | --replace A:B | 无 | 可多次使用 |
| 色调偏移 | --tone-shift warm|cool|bright|dark | 无 | |
| 色调强度 | --tone-strength N | 30 | 0-100 |
| 最大颜色数 | --max-colors N | auto | 0=自动，6-8卡通，15-24照片 |
| 边缘阈值 | --edge-threshold N | 200 | 边缘检测灵敏度 |
| 去背景 | --remove-bg | 否 | 使用 rembg 去除背景 |
| 输出目录 | --output-dir DIR | 自动生成 | |
2. 执行转换
cd ~/.claude/skills/pindou
python3 scripts/convert.py <图片路径> [参数...]
脚本输出 JSON 到 stdout，包含输出文件列表和用量统计。
3. 呈现结果给用户
转换完成后：
- 用 Read 工具展示生成的全局图纸 PNG（让用户直接看到效果）
- 展示用量统计（使用了多少种颜色、每种多少颗）
- 告知输出文件位置
- 询问是否需要调整（换色板、开抖动、替换颜色等）
4. 调整（如需要）
用户可能要求：
- "换成 Hama 色板" → 重跑
--palette hama_midi
- "开抖动" → 重跑
--dither floyd --dither-strength 50
- "这个颜色太多了，我没有 H15 和 H23" → 重跑
--exclude H15,H23
- "导出 PDF" → 重跑加
--pdf
快捷模式
如果用户一句话给了所有参数，直接构造命令执行，不用逐个询问。
示例映射：
| 用户说 | 命令 |
|---|
| "把 pikachu.png 转成拼豆图纸" | convert.py pikachu.png |
| "用 Hama 色板转换 photo.jpg，29x29 小板" | convert.py photo.jpg --board 29x29 --palette hama_midi |
| "2x3 拼接大图，开 Floyd 抖动" | convert.py img.png --grid 2x3 --dither floyd |
| "转换但我没有 S01 S05 S10" | convert.py img.png --exclude S01,S05,S10 |
可用色板
查看所有色板：
python3 scripts/convert.py --list-palettes
查看某色板所有颜色：
python3 scripts/convert.py --list-colors hama_midi
当前内置：
| 名称 | 品牌 | 系列 | 颜色数 |
|---|
artkal_s | Artkal | S 系列 5mm 软豆 | 199 |
hama_midi | Hama | Midi 5mm | 92 |
perler_standard | Perler | Standard 5mm | 103 |
透明图片处理
上传带透明通道的 PNG 时：
- 透明区域自动识别为"不放豆"（空格）
- 空格在图纸中显示为浅灰色
- 用量统计中单独标注空格数量
- 空格不计入总豆数
多板拼接
使用 --grid RxC 指定拼接布局：
- 总尺寸 = 单板尺寸 × 拼接数（如 2x3 × 29x29 = 58x87）
- 输出：1 张全局总览（红色线标注板间分界）+ 每板独立图纸
- 每板图纸标注位置编号（如 "Board R1C2"）
立体拆件流程
当用户要求将物体/角色转换为立体拼豆作品时：
Step 1：分析结构（你来做）
看用户提供的参考图片，分析其3D结构，输出拆件方案 JSON：
{
"name": "造型名称",
"panels": [
{
"id": "body_front",
"name": "躯干正面",
"width": 30,
"height": 40,
"connects_to": ["body_left", "body_right"],
"color_map": {
"regions": [
{"x": 0, "y": 0, "w": 30, "h": 20, "color_hint": "yellow"}
Step 2：用户确认方案
展示拆件方案，让用户确认或调整面片数量、尺寸。
Step 3：生成面片图纸
将确认的方案 JSON 保存为文件，执行：
python3 scripts/panel_generator.py plan.json --palette artkal_s --output-dir ./output/
Step 4：展示结果
展示每个面片的图纸 PNG、卡槽位置、用量统计、组装顺序。
故障排除
| 问题 | 解决 |
|---|
ModuleNotFoundError: No module named 'numpy' | pip3 install numpy Pillow |
| 转换很慢（>5秒） | 减小板子尺寸或检查图片是否过大 |
| 颜色匹配不准 | 色板 RGB 数据可能不精确，尝试换色板 |
| 抠图功能不可用 | 安装 rembg：pip3 install rembg |
