Pindou Transcoder（拼豆图片转码）
Overview
把任意图片转换为可实际拼接的拼豆图纸：像素化采样 → 品牌色板最近邻匹配 → 相似色合并 →（可选）背景去除 → 颗数统计，并渲染带坐标、色号、用量图例的 PNG 图纸，同时导出 CSV 源数据与 JSON 统计。
使用方法
基本命令：
python scripts/pindou_convert.py <input.png> -o <输出目录> --size 60 --brand "MARD 291 色"
完整参数：
| 参数 | 默认值 | 说明 |
|---|---|---|
image |
必填 | 输入图片（PNG/JPG，含透明通道最佳） |
-o, --output-dir |
当前目录 | 输出目录 |
--size |
29 | 最长边格数 10-300，另一边按宽高比自动计算 |
--brand |
"MARD 291 色" | 可选：MARD 221 色 / MARD 291 色 / COCO / 漫漫 / 盼盼 / 咪小窝 |
--mode |
dominant | dominant=主色采样（线条清晰）/ average=平均色（照片柔和） |
--threshold |
40 | 相似色合并阈值 0-100；越大颜色越少、图越"平" |
--remove-background |
关 | 去除背景（边缘主色检测 + 泛洪），透明背景 PNG 效果最好 |
--legend |
list | 图例样式 list / pill |
--no-coords |
关 | 不显示行列坐标 |
--no-stats |
关 | 不显示底部用量图例 |
--base-name |
图片名 | 输出文件名前缀 |
输出三个文件：<name>-pattern.png（图纸）、<name>-pattern.csv（每格十六进制色，透明格为 TRANSPARENT）、<name>-stats.json（色号用量清单）。
参数选择建议
- 像素画 / 图标 / 卡通图：
--size 30~80 --mode dominant，源图自带清晰色块时效果最佳。 - 照片：
--size 60~120 --mode average --threshold 50~60，合并更多相似色以减少购买色号种类。 - 人像/贴纸去底：
--remove-background，仅当主体不贴满画布边缘时有效（算法从四边检测背景主色）。 - 尺寸上限：微信/设备渲染安全上限约 200×200 格；超过后图纸文件很大且拼制难度高，无特殊需求不建议。
- 对账：
stats.json的totalCount即所需拼豆总颗数；每种颜色count为该色颗数。
编程调用（Python）
import sys
sys.path.insert(0, r"<skill目录>/scripts")
from pindou_convert import convert_image, render_pattern, export_csv, build_bead_usage
result = convert_image("input.png", size=60, brand="COCO", mode="dominant",
similarity_threshold=40, remove_bg=False)
w, h = render_pattern(result, "pattern.png") # PNG 图纸
export_csv(result, "pattern.csv") # CSV 源数据
usage = build_bead_usage(result["grid"], result["brand"]) # [{code, hex, count}]
# result 字典字段：grid(rows×cols, cell={key,color,isExternal}), columns, rows,
# colorCounts, totalCount, palette, brand, brandName
常见问题排查
- 白底变米色/杂色：算法有 #FEFFFF 纯白特判，正常不会出现；若源图白底偏灰，先在图片处理中提亮再转。
- 细节丢失：增大
--size，或把--threshold降到 0-20。 - 颜色种类太多：增大
--threshold（如 60）或改用--mode average。 - 背景去除不干净：要求主体与背景色差明显；纯色/透明背景效果最好，复杂照片背景不建议开启。
- 色号显示 "?"：说明该色不在当前品牌色板（291 色为全集，正常不会出现）；检查
--brand拼写。
资源清单
scripts/pindou_convert.py— 核心转换脚本（CLI + 可导入函数）scripts/extract_palette.py— 从 TS 源文件重新提取色板到 assets/palette.json 的维护工具（仅 TS 色板更新时使用）assets/palette.json— 291 色 × 5 品牌色号映射（MARD/COCO/漫漫/盼盼/咪小窝）
