万物图片转拼豆

目标

输入一张图片，先把它量化成平面像素色号矩阵，再渲染为带时间戳的可交互 HTML 图纸（output/【拼豆图纸】{任务名}-{M月D日}_{H点M分S秒}.html）。

中间产物不是图纸。只有色号矩阵、多规格总览和 HTML 全部生成，任务才完成。

本 skill 不挑素材：宠物、风景、人像、Logo、插画、照片都能做。生图与渲染全部是本地确定性流程，不依赖任何外部生图 / 渲染服务，装好依赖即可离线出图。

工作目录

每次任务使用独立且可指定的绝对路径，建在本次对话的工作区目录下。App 端从插件目录读不到产物，所以工作目录不要放在插件 / 缓存目录里。

<work_dir>/
├── .wip/
│   ├── 原图/原图.<原后缀>
│   ├── 转换图/转换图.png          # 平面像素底稿（原图居中正方化后的结果）
│   ├── 评审/尺寸对比.png          # 五档规格对比卡片，供 AI 核验默认尺寸（不发给用户）
│   └── 运行记录.json
└── output/
    └── 【拼豆图纸】{任务名}-{M月D日}_{H点M分S秒}.html

下载参考图、写日志、生成底稿和 CSV 全部放在该目录的 .wip/；output/ 只放那一个图纸 HTML。脚本默认清理 .wip/过程文件/，需要保留时加 --keep-process。

输入契约

作品主体就是用户提供的图片。先看原图；明显有与主体无关的多余元素时（如截图状态栏、互动栏或大片留白），先裁切，保留完整主体。处理好的图存到 .wip/原图/原图.<原后缀>，用于后续尺寸对比与页面「原图」页签；拿不准时保留原图。

色号由下游 scripts/palette_mard221.csv（MARD 221 色板）映射实现，生图时不传色卡图片。

一键生成

运行前根据画面主体拟一个简短、自然、可辨识的任务名（如「橘猫趴姿」「公司 Logo」），作为 --task-name 传入。

python3 scripts/wanwu_perler.py <图片路径> \
  --work-dir <绝对工作目录> \
  --task-name "<本次任务名>"

常用参数：

• --subject：character（人像）/ prop（物品/风景/宠物，默认）/ character-prop（带道具的人像）。决定页面是否出现画风参考区。
• --boards：板规格档位，每边格数，默认 36 52 78 104 156。
• --default-size：默认打开规格（须是 --boards 之一；缺省优先 78）。
• --max-colors：统一颜色预算，默认 28（≤28 推荐；色越多越接近原图但越费豆）。
• --no-square：不把非正方图居中正方化（可能导致拉伸变形，默认开启正方化）。
• --strip-sticker-border：去掉底部一圈白色贴纸边（默认不处理）。
• --merge-close-colors：合并近色簇，修复同一区域的交错色。
• --keep-process：保留 .wip/过程文件/（默认清理）。

该命令依次完成：

1. 把原图（默认）居中放进透明正方形画布，生成平面底稿 .wip/转换图/转换图.png（保持比例，避免拉伸）。
2. alignment_search.py 从同一底稿生成五档（36/52/78/104/156）色号矩阵（LANCZOS 缩放 + KMeans 减色 + MARD 221 色板 CIELAB 最近邻映射）。
3. build_html_blueprint.py 生成 output/【拼豆图纸】{任务名}-{M月D日}_{H点M分S秒}.html，标题是任务名，副标题是实际渲染时间。页面是「顶栏 → 图纸 → 编辑栏」三站流，手机和电脑同一套：①规格调整（选拼豆板尺寸、颜色数量、色号规格）；②图纸编辑（画笔 / 填充 / 橡皮 / 取色 / 移动逐格改）；③辅助拼豆（照着下豆的进度记录表）。图纸上方切「平面 / 3D」（3D 可模拟烫豆），顶栏「导出」下载带色号用量统计与二维码的 PNG 海报。页面数据、three.js、图片全部内联，是单文件。
4. make_overview.py 生成 .wip/评审/尺寸对比.png（五档 + 原图，2×3 卡片），只供 AI 核验默认展示尺寸，不发给用户。
5. 运行状态与最终路径写入 .wip/运行记录.json，输出列表中 HTML 位于首位。
6. 默认清理 .wip/过程文件/，底稿 转换图.png 保留。

推荐尺寸：先看构图，再核验细节

用户没指定尺寸时，按最终构图给暂定建议：全身且头部占比小的系列优先 104×104；其他全身至少 78×78；半身从 52×52 起；只有以头部为主体的大头特写才考虑 36×36。构图看的是主体在整幅画面里的实际占比。

交付前读取 .wip/评审/尺寸对比.png，核验推荐尺寸中原图可见的轮廓、主体颜色与文字 / Logo 是否清晰。细节挤在一起、缺格或轮廓不清楚时，升一档再核验；最大档仍不清楚就指出具体部位，提议换图或调整，不宣称细节已保住。

尺寸推荐通过 --default-size 设置，图纸页在对应规格上显示「推荐」标签，用户在页面切换尺寸。玩家主动指定尺寸时按他的要求制作。

完成判据

• .wip/转换图/转换图.png 是平面像素底稿（透明背景、硬边色块）。
• 默认已清理 .wip/过程文件/；加 --keep-process 时保留。
• output/【拼豆图纸】{任务名}-{M月D日}_{H点M分S秒}.html 存在且是单文件，任务名和渲染时间正确。
• .wip/评审/尺寸对比.png 可读取，已确认默认展示尺寸。
• .wip/运行记录.json 标记完成，output/ 里只有这一个图纸 HTML。

依赖

Python 依赖：Pillow、NumPy、OpenCV、scikit-image、scikit-learn、requests。

pip install Pillow numpy opencv-python-headless scikit-image scikit-learn requests

> 注：若与已装环境冲突，可用 opencv-python-headless 替代 opencv-python（无 GUI 依赖，服务器 / 无显示器环境更稳）。

稳定资源

• scripts/palette_mard221.csv：MARD 221 色板（生产对齐用）。
• scripts/palettes/：HTML 图纸页的全品牌色板数据（MARD 9 档套装、国产 4 家对照、海外与 Artkal 12 条线）。
• templates/perler_blueprint/：交互图纸模板（色板切换、颜色数量、编辑态、孤立像素；图纸视图的平面 / 3D 两种看法）。index.html 是页面外壳，build_html_blueprint.py 按外壳里的 /* @include … */ 顺序内联成单个 index.html；templates/vendor/three.min.js 是 3D 看法用的本地打包 three 0.160 + OrbitControls，离线可开。

许可与合规

本 skill 由多个来源组合而成，上架 / 再分发前请逐项确认权利：

1. 图纸渲染层（templates/perler_blueprint/、build_html_blueprint.py、alignment_search.py、three.min.js）：衍生 / 复用自「无畏契约拼豆专家」专家包（作者 Jace，版本 1.2.7）。原包未附 LICENSE 文件，默认保留所有权利。上架前请确认：你是原作者 / 已获授权，或将渲染层替换为自研实现。
2. beadcolors 调色板（scripts/palettes/beadcolors/*.csv）：MIT License，Copyright (c) 2020 maxcleme。可自由再分发，条件是保留以下版权与许可声明。本 skill 已随包移除独立的 LICENSE 文件（部分市场不允许该文件名），故在此保留 MIT 声明原文：

```
MIT License
Copyright (c) 2020 maxcleme

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction...（详见原包）
```

3. 其余脚本（scripts/wanwu_perler.py、web_app.py）为本 skill 自研，可随本 skill 一并分发。

本 skill 仅提供通用「图片→拼豆色号矩阵→交互图纸」能力，不含任何无畏契约专属内容与品牌素材。若图中含第三方品牌 / 角色，请仅个人拼豆使用、勿商用。

网页上传入口（零依赖）

不想走命令行时，本 skill 自带一个纯标准库的本地网页服务，打开浏览器就能拖图转换，无需安装额外框架。

cd <skill目录>
python3 web_app.py                 # 默认 http://127.0.0.1:8500
python3 web_app.py --port 9000    # 指定端口
python3 web_app.py --host 0.0.0.0  # 允许同局域网其他设备访问

启动后浏览器打开地址，页面提供：拖拽 / 点击选择图片、图纸名称、默认打开尺寸（36/52/78/104/156）、主体类型（prop / character / character-prop）、颜色预算（≤28）。点「生成拼豆图纸」后后台自动跑完整管线（约 30–90 秒，大图更久），完成后页面内直接内嵌可交互图纸（可切尺寸 / 改色 / 3D 预览 / 导出海报），并提供新标签打开 / 下载链接。

实现要点：

• web_app.py 仅用 Python 标准库（http.server + threading），无 Flask 等第三方依赖。
• 前端把图片读成 base64 通过 JSON 发给 /convert，服务端后台线程跑 scripts/wanwu_perler.py，前端轮询 /status/<job_id> 直到完成，再加载 /runs/<job_id>/output/<图纸>.html。
• 成功判据以「图纸 HTML 是否生成」为准（部分环境对批量删除有安全拦截，会让清理步骤退出非零，但图纸已产出，仍视为成功）。
• 生成的图纸是单文件 HTML（数据、three.js、图片全部内联），可直接转发或离线打开。
• 不上传任何图片到云端，全部在本地处理。若图中含第三方品牌 / 角色，请仅个人拼豆使用、勿商用。