Excel拼豆图 · 拼豆像素图纸 → Excel 施工图

把一张拼豆像素图纸翻译成「一张 Excel 表 = 一份可施工的底稿」：

• 一个单元格 = 一个像素 = 一颗豆子
• 单元格底色 = 该像素的颜色，格内文字 = 色号（或统一标记）
• 原图的相对位置与整体图案一比一保留，不做缩放、不做重排

最后逐格回读校验，确保每个坐标上的颜色与图纸完全一致。

第 0 步（必做）：先确认像素密度档位

动手前先问用户要哪一档。 密度决定网格尺寸、纯色数上限和全部量化参数，
选错后面全是白工 —— 这是本技能最优先的交互环节。

反问话术、按图特征给建议的对照表、成本提醒话术 —— 见
references/density-guide.md §5。核心一句：

> 格数按平方增长：104×104 是 52×52 的 4 倍格子、4 倍豆子、约 4 倍摆豆时间。

选好档位后，一条 --density 就把尺寸、色数上限、量化参数、单元格尺寸全部锁定：

python scripts/bead.py image --image 图纸.png --density 52 -o 拼豆图纸.xlsx

纯色上限是硬约束：给了 --density 25，输出就不会超过 5 色 —— 超出的颜色走
层次合并（每次并掉代价最小的一对）压到上限，不是简单丢弃。

技能速览

环境准备

依赖这几个库。优先使用受管虚拟环境（该环境已内置下列版本，无需安装）：

~/.workbuddy/binaries/python/envs/default/Scripts/python.exe   # Windows
~/.workbuddy/binaries/python/envs/default/bin/python           # macOS / Linux
  → pillow 12.3.0 / numpy 2.5.1 / openpyxl 3.1.5 / opencv-python 5.0.0

opencv-python 只在「插画颜色量化」的连通域过滤环节用到（清除碎块、水印）。
缺了不会报错，脚本会自动跳过那一步 —— 只是杂色会多留一些。

仅在受管环境缺库时才安装，且固定版本（避免拉到被投毒的最新版）：

python -c "import PIL, numpy, openpyxl; print('ok')" \
  || python -m pip install "pillow==12.3.0" "numpy==2.5.1" "openpyxl==3.1.5"

脚本内部已处理 Windows 控制台的 UTF-8 输出问题，无需额外设置 PYTHONIOENCODING。

三个核心概念

色号的两种来源

1. 用户提供（首选）：图纸图例、用户手上的豆子色卡、用户明确给出的清单。
   跨品牌色号不通用，不得凭记忆编造品牌色号。
2. 自动归纳（图纸不带色号时）：由 make_palette.py from-image 按用量从多到少
   编号 P01、P02…… 这是「第 N 种颜色」的意思，不是任何品牌的真实色号，
   换色时按 HEX 一比一对应即可。

先分清：图纸是「工程网格」还是「插画」

这一步决定了走哪条路，判断错了后面全错：

不要对插画硬走网格还原：它没有规则网格，拟合出来的行列数是假的。

插画 / 照片：颜色量化 → 像素化

第一步：量化成 ≤K 种纯色

推荐：一条 --density 让所有量化参数随档位自动匹配（色数、滤波核、面积权重、碎块阈值）：

python scripts/quantize_image.py --image 插画.jpg --density 52 \
    -o 量化图.png --palette-out palette.json --report 颜色报告.md --side-by-side 对比.png

它等价于下面这组手调参数（这就是「52×52 / ≤8 色」的实际含义）：

python scripts/quantize_image.py --image 插画.jpg -k 12 --max-colors 8 \
    --median 9 --denoise-radius 2 --merge-de 5.0 --area-weight 0.25 \
    --min-region-ratio 0.000185 \
    -o 量化图.png --palette-out palette.json --report 颜色报告.md --side-by-side 对比.png

手调各参数的含义见下方参数表；密度档位下的推荐值随档位变化，
所以除非有明确理由，优先用 --density，别抄上面这组数字去做 104 档。

输出的 量化图.png 是纯色填充的（无渐变、无半透明），palette.json 里的
P01、P02… 可直接喂给 grid_to_excel.py。

三个必须踩过的坑（都实测过）：

1. 色数不是越少越好，-k 也不是直接给目标值。 直接 -k 8 时，K-means 会把
   「两个黑」各占一个簇，挤出米白上衣；而 -k 9 --max-colors 8 先过分割再按面积归并，
   米白才能独立成色。过分割 + 面积加权归并 > 直接 K 色。

2. --min-region-ratio 要跟目标密度挂钩，而不是取一个固定值。 眼高光只有约 78px²，
   阈值给到 128px² 眼珠就变成纯黑。老版本固定用 0.00006（92 万像素图约 51px²），
   但同一个数在 104 档太松（放过噪点）、在 25 档太严（留不住该留的色块）。
   现在按 0.5 / n²（半格面积）推导：小于半格的内容在输出网格里根本无法被表达，
   压掉它属于降噪而非丢信息。--min-region-passes 仍别调大，多轮会逐轮啃掉
   夹在大色块间的小细节。

3. 水印和眼睛高光面积相同，纯按面积分不开。 水印必须用 --mask 显式圈定。

> 实现上还有一条：合并后的标签重映射必须在 Lab 空间做。用 RGB 欧氏距离会把
> 浅灰 (#E6E4E5) 错配到肤色 (#F8D3B9) 这类「色相不同、RGB 距离更近」的颜色上，
> 导致连帽衫被染成肉色。

第二步：像素化成 n×n 网格

量化图是纯色块、没有格线，probe 依然探测不到网格，所以要手工钉死均匀网格：

# --uniform = 强制均匀网格，跳过格线探测。量化图没有格线，必须加这个
python scripts/pattern_to_grid.py image --image 量化图.png --palette palette.json \
    --density 52 --uniform -o grid.json --csv grid.csv --preview preview.png

⚠️ 这里的 --uniform 不是可选项。 量化图是平铺色块，没有格线，
探测器会把色块边界误判成网格线，然后用这些「假格线」的中位距推出完全错误的格子尺寸。
实测：25×25 的量化图被推成 11.22px 格宽，平均 ΔE 冲到 33.94、550/625 格被标为不确定。
加上 --uniform 后 ΔE = 0.0。

同一条判据也已内建为兜底：探测格数与指定值偏差超过 max(2, 指定的 25%) 时，
自动判定探测不可信并改用均匀网格（会打印警告说明）。但仍建议显式写 --uniform。

需要精确控制采样起点时（图纸有留白/边距），手工给定更稳：

# pitch = 图片宽(或高) ÷ n，起始固定在 0,0
python scripts/pattern_to_grid.py image --image 量化图.png --palette palette.json \
    --rows 52 --cols 52 --x0 0 --y0 0 --pitch 17.73 --pitch-y 17.73 \
    -o grid.json --csv grid.csv --preview preview.png

如果原图的豆子排列本身就是规则的，一格 = 原图一个豆子是最忠实的粒度
（用原图豆子间距反推 n）。此时采样 ΔE 会是 0.0。

第三步：照常出 Excel

python scripts/bead.py grid --grid grid.json --palette palette.json --density 52 \
    -o 拼豆图纸.xlsx --pack-size 1000

固定品牌色板适配低密度档位（手上一盒 24 色，却要做 25×25 的 ≤5 色）——
在网格层按用量+色差归并，代表色取原色号，不凭空造色：

python scripts/pattern_to_grid.py resize --grid grid.json --size 25 \
    --palette 色板.json --max-colors 5 -o grid25.json --report 重采样报告.md

密度档位：--density

--density 会做三件事：识别阶段按 N×N 采样 → 渲染阶段校验确是 N×N（不符即报错退出）
→ 校验阶段再核对一次。完整联动表与设计依据见 references/density-guide.md。

工程网格图纸换密度：不要直接改 --density，而要告诉它原图本身是多少格：

# 原图 48×48，想输出 104×104
python scripts/bead.py image --image 图纸.png --native-size 48 --density 104 -o 拼豆图纸.xlsx

它先按 48×48 无损提取，再在网格层重采样到 104×104。直接按 104 去像素层硬采会整体错位，
而且 ΔE 仍是 0.0，从数值上根本看不出问题。

⚠️ 想提升还原度就重新走量化，别放大已有网格。 把 52×52 的网格 resize 到 104×104，
得到的是「格子数 ×4、信息量不变」——每格拆成 4 格、颜色原封不动，摆豆时间涨 4 倍而清晰度不变。
正确做法是回原图重跑：quantize_image.py --image 原图.jpg --density 104。
（升采样只用于适配更大规格的拼豆板，见 references/density-guide.md §4。）

拼豆板换算：按 29×29 方板算，需要 ceil(N/29)² 块 —— 25→1 块、52→4 块、78→9 块、104→16 块。
Excel 里每 29 格画一条粗分界线，就是「换板位置」的标记（--board 可改，--board 0 关闭）。

两类输入：带色号 / 不带色号

A. 图纸带色号 —— 提供色板（首选，结果最可信）

python scripts/bead.py image --image 图纸.png --palette 色板.json --density 52 -o 拼豆图纸.xlsx

⚠️ 带色板时颜色数由色板决定，档位管不住。色板色数超过档位上限时会主动提醒并给出精简命令；
跨品牌色号不通用，不会替你改写色号。

B. 图纸不带色号 —— 不提供 --palette，自动归纳颜色

python scripts/bead.py image --image 图纸.png --density 52 -o 拼豆图纸.xlsx

流程会自动多走一步：先按原色提取网格 → 按色差（CIEDE2000）把近似色聚成一类 →
按用量从多到少编号 P01、P02…… → 用这套自动色号重映射一遍。

调参：

两种填充方式的取舍（渲染层决定）：

输出：4 张工作表

材料清单怎么算

• 数量：该色号在图纸中占多少格 = 要多少颗豆
• 占比：数量 / 总豆数
• 建议备豆量：ceil(数量 × (1 + 损耗率))，损耗率由 --loss-rate 控制，默认 0.05（+5%）
• 给 --pack-size 500 时，备注列会额外换算成「约 N 包（按 500 颗/包）」

坐标映射

数据区从 B2 起（--no-axis 时从 A1 起）。A 列为行号、第 1 行为列号，
与 R{n}C{m} 一一对应，方便按行摆豆。冻结窗格在 B2，滚动时坐标尺常驻。

一条命令跑完（推荐）

python scripts/bead.py image --image 图纸.png --palette 色板.json --density 52 \
    -o 拼豆图纸.xlsx

它会依次执行「解析图纸 → 生成 Excel → 逐格校验」，校验不通过退出码为 1，
并在 bead_work/ 留下 grid.json、网格 CSV、还原预览图、网格标注图、校验报告与差异图。
（走 --native-size 时还会多一份重采样报告，含格一致率分布。）

其他入口：bead.py text（符号图纸文本）、bead.py grid（已有 grid.json 只做渲染）、
bead.py density（查档位表）。

分步执行（需要微调时）

# ① 建色板（四选一）
python scripts/make_palette.py starter -o palette.json                    # 通用示意色板快速起步
python scripts/make_palette.py add --palette palette.json \
       --entries "H01|白色|#FFFFFF|O;H02|黑色|#1A1A1A|X"                  # 手工录入
python scripts/make_palette.py from-pixels --image 图纸.png \
       --boxes "40,600,20,20;80,600,20,20" --codes "H01,H02" -o palette.json  # 从图例色块采样
python scripts/make_palette.py from-image --grid grid.json --density 52 \
       -o palette.json --report 色号归纳报告.md                          # 不带色号：自动归纳编号 + 档位色数上限

# ② 先探测几何，确认行列数对不对（强烈建议）
python scripts/pattern_to_grid.py probe --image 图纸.png --overlay probe.png

# ③ 提取网格（插画/量化图务必加 --uniform；工程图按原网格数提取）
python scripts/pattern_to_grid.py image --image 图纸.png --palette palette.json \
       --density 52 --uniform -o grid.json --csv grid.csv --preview preview.png

# ③b 已有网格要换密度 → 网格层重采样（工程图切换档位走这条）
python scripts/pattern_to_grid.py resize --grid grid.json --size 78 \
       --palette palette.json --max-colors 14 \
       -o grid78.json --report 重采样报告.md --preview preview78.png

# ④ 渲染 Excel
python scripts/grid_to_excel.py --grid grid.json --palette palette.json \
       -o 拼豆图纸.xlsx --cell-size 24 --show-label code --board 29 --size 52

# ⑤ 逐格校验（必做）
python scripts/verify_excel.py --excel 拼豆图纸.xlsx --grid grid.json \
       --palette palette.json --report 校验报告.md --diff-image 差异图.png --size 52

脚本清单

识别几何参数（probe / image 通用）：
--density、--uniform（无格线的插画/量化图必加）、
--crop x,y,w,h、--rotate 90/180/270、--flip h/v/both、--rows、--cols、
--x0、--y0、--pitch、--pitch-y、--square、
--method auto/lines/edges、--dark、--chroma、--min-pitch、--max-pitch、
--inset、--bin、--max-de、--metric、--drop-bg。

质量门禁（不可跳过）

门禁一：verify_excel.py 退出码必须为 0

它做五件事：

1. 数据区行列数 = 网格行列数（给了 --size 时同时核对尺寸）
2. 每个单元格的实际底色 = 该坐标应有的颜色（精确相等）
3. 格内色号文字与底色一致
4. 「材料清单」数量与网格统计一致（旧版「色号统计」同样识别）
5. 「色号图」逐格核对：底色与格内色号都对得上

不通过时输出 差异图.png：全灰代表完全一致，品红框标出的就是出错的格子。

门禁二：识别准确度要看图，不能只看 ΔE

这是最容易踩的坑：verify_excel 只证明「Excel 忠实还原了网格」，不证明「网格识别对了」。

整体错位时，每个采样点仍然落在某个真实豆色上，ΔE 会低到 0.0、uncertain 也是 0，
但图案已经错了几十格。实测一张带图例的图纸：错位 230 格（8.5%），平均 ΔE 仍是 0.0。

所以开工前必须把这两个中间产物和原图并排比对：

另外要如实汇报：平均/最大 ΔE、uncertain 格数、以及识别阶段的全部 warning
（bead.py 会在结尾把它们重新打出来，因为它们不会被一致性校验覆盖）。

门禁三：密度不足要被量化，而不是靠感觉

还原度不够时，用户最需要的是「换哪一档」而不是一句「效果就这样了」。三个可查的指标：

这三项都只是「参考信号」，最终仍以还原预览图/网格标注图与原图并排比对为准（门禁二）。

常见问题速查

交叉校验（强烈建议）

图纸图例通常会标注每个色号的数量，且合计等于「所需豆子数量」。
把这个数量当作容量约束做全局最小色差分配，可以自动修复水印/偏色造成的误判，
并让结果与图例完全自洽 —— 这是比 ΔE 阈值更硬的校验。

分配完成后，按 ΔE 从大到小排序人工复核前 30 格，再跑 verify_excel.py 收尾。

参考文件