拼豆图纸

---
name: bead-board
description: 把照片，或用代码画出来的原创想法，变成真能动手做的拼豆图纸。交付逐颗可改的网页编辑器、按实际大小打印的 PDF（每颗 5 毫米，带网格、行列号和黑白也能看清的符号）、各色豆子数量，以及熨好后的效果图。当有人想要拼豆图纸、把宠物或孩子的照片做成拼豆、熨烫豆图案、给课堂准备手工图纸时使用。
version: 1.1.0
---

# 拼豆图纸

你做的是一张真正要放到桌上用的图纸。样式和算法都在文件里：`assets/engine.cjs`、`assets/editor.html`、`scripts/make.mjs`。不要重写它们，也不要自己另画 PDF。颜色名称和设计规范见 `references/style.md`。

全程在对方自己的电脑上运行，只需要 Node 18 以上，不用安装别的东西，一次大约一秒。

## 对方只想要成品时

来要图纸的人大多不懂技术。所有设置都由你完成。一次性用大白话问完，不要对他们说“量化”“抖动”“色板”“JSON”“终端”这类词。

只问需求里还没说的：
1. 想做什么？发来一张照片，或者描述一下。
2. 做多大？可以这样说：“小方块，横着 29 颗，大约 14.5 厘米，一两个小时能摆完”；或者“大块，横着 57 颗，大约 28.5 厘米，要摆很久”。
3. 手上有哪些豆子？一般的套装，或者告诉你具体有哪些颜色。

交付时把文件夹给对方，用一两句话说明：打开 `index.html` 可以改任何一颗豆；打印 `pattern.pdf` 时选“实际大小”或“100%”。除非对方问，否则不要展示命令。

还要用自己的大白话说清楚这一句：**颜色只是近似，熨烫效果和打印尺寸都还没有在真实纸张上试过。** PDF 的尺寸是从文件里量的，不是从打印出来的纸上量的，也没有人真的熨过成品。请对方先量那条 10 厘米的线，再拿一小块试熨。PDF 第一页和编辑器的豆子清单旁边也写着这句话。

如果没人能回答，就直接做：29 × 29、大全盒颜色、能去背景就去背景、清理零散的豆子。用一句话列出你的假设。

## 版权角色：礼貌地婉拒

不做别人拥有版权的角色、吉祥物或标志的图案，不管是说名字、描述长相还是发截图。语气要友好，并提出做原创：

> 这个角色属于它的创作者，我不能做成图纸。不过我很乐意给你做一个属于你自己的：告诉我你喜欢它哪一点，我来画一个有同样感觉的原创小家伙。

对方自己的宠物、孩子、房子、茶杯的照片都可以。真人照片要确认对方有权使用。不要使用任何商业拼豆品牌的色名或色号，这里的颜色名都是我们自己起的。

## 需要的信息

- **内容：** 图片文件（PNG、JPG；Mac 上还支持 HEIC、WebP、GIF），或者由你来画的一段描述。
- **板子大小：** 横向 × 纵向的颗数，默认 29 × 29。
- **颜色：** 现成的几组：`big-box`（49 色）、`first-box`（16 色）、`soft`、`earth`、`greys`；或者对方实际拥有的颜色。
- **可选：** 标题、纸张（默认 `a4`，也可以 `letter`）、最多用几种颜色、迷你豆。

## 步骤

### 从照片开始

```
node scripts/make.mjs --image photo.jpg --board 29x29 --title "团子" --max-colors 12 --lang zh --out tuanzi
```

常用选项：
- `--lang zh`：编辑器和 PDF 都用中文，中文标题的字形已内置，打印不会缺字。
- `--palette first-box`，或者直接列出：`--palette "雪白,墨黑,番茄,#7FB2A0:海玻璃"`
- `--max-colors 12`：大多数人手上的颜色比想象的少。照片从 8 到 14 色开始。
- `--background auto|keep|remove`：`auto` 会去掉纯色背景、保留复杂背景，输出里的 `background` 会说明结果。
- `--cleanup 0|1|2`：1 清理零散的单颗豆，但保留眼睛和小亮点；2 更彻底。
- `--dither 0.5`：加杂点混合颜色，0 到 1。摆起来费事，对方想要更像照片时才用。
- `--fit cover`：铺满板子并裁边，而不是显示完整画面。
- `--paper letter`、`--sheet ink`（只印符号，省墨）、`--pitch 2.6`（迷你豆）、`--note "..."`。

### 从想法开始

由你自己一格一格画。小板子上这样做效果最好：29 颗的时候，每一颗都是一个决定。写一个 JSON 文件：

```json
{"title":"茶杯","note":"原创图案。","legend":{"k":"espresso","w":"snow","r":"tomato"},
 "rows":["..kkkk..","..kwwk..","..krrk..","..kkkk.."]}
```

图例里没有的字符就是空格子。颜色用 `references/style.md` 里的名字，或 `#rrggbb`。然后运行：

```
node scripts/make.mjs --grid drawing.json --lang zh --out teacup
```

画得好看的几条经验：
- 一颗宽的深色描边最清楚。暖色主体用深棕，比纯黑好看。
- 眼睛两颗宽、两到三颗高，再放一颗浅色做高光。
- 条纹和阴影用主色的深一号，不要另起一种颜色。
- 所有部分都要边挨边连着。只有角碰角的豆，或者飘在空中的细节（比如热气），熨完会掉。输出里的 `looseBeads` 必须是 0，除非对方接受。
- 对称的形状可以用代码画：写一半，再镜像。

画满整幅的场景，比如海上的小船：
- **把整块板铺满。** 天空和海水也要用真豆子摆，空白格就是光板子，成品上会留一个洞。29 × 29 就是正好 29 行、每行 29 个字符，输出里的 `emptySquares` 应该是 0。
- **先铺背景，再把主体画上去。** 用代码先把每行填成天和海，再把主体的豆子写在上面，这样每行长度不会错。
- **浅色主体要看得见。** 白帆、白云、雪人、白天鹅放在浅色天空上就没了。可以选中等深度的天空（用 `sky` 或 `denim`，别用 `ice`），或者给浅色主体描一圈一颗宽的 `pebble` 或 `denim` 边，也可以两样都做。不要让 `snow`、`cream`、`fog` 直接贴着 `ice`、`lilac`、`rice`。然后把 `finished-preview.png` 缩到缩略图大小看一眼，主体的边不见了，就是太淡。
- **背景色看主体来定：** 深色或暖色主体配 `ice` 或 `butter`；浅色主体配 `sky`、`denim` 或 `midnight`。背景用两三条色带（海用 `cobalt` 和 `sky`），不要撒杂点。波浪用同一行里重复的小台阶最清楚，不要零散放豆。
- **告诉对方要用多少豆。** 铺满背景常常占一半以上（一次测试的小船 841 颗里有 435 颗是背景）。把数字告诉对方，如果不想买那么多，可以提供不铺背景的版本。
- **画出来的图用几种颜色：** 对方说了数量（“十种左右”）就不要超过，并说明选了哪几种。只有在本来就要问别的问题时，才顺便问有哪些颜色。数量看输出里的 `colours`。

照片的情况：如果高光变成一块乱糟糟的斑，就减小 `--max-colors`、用 `--cleanup 2`，或在编辑器里用“填充”手动修。没有单独关掉高光的开关。

### 每次都要做

1. 运行 `node scripts/check.mjs <文件夹>`，修好它报的问题。它会直接从 PDF 里量豆距、纸张尺寸和那条 10 厘米的线。
2. 看 `finished-preview.png`：能认出是什么吗？认不出就调板子大小、颜色数或重画，再跑一遍。给对方看之前就要做这一步。
3. PDF 每一页都要看，`index.html` 也要打开，尽量看电脑和手机两种宽度。要自动操作页面时，在临时文件夹 `npm install playwright`（需要时设置 NODE_PATH）。常用的页面元素：板子是 `#board`，颜色是 `#tray` 和 `#list`，警告行是 `#warn`，工具是 `[data-tool="paint"]` 这类，视图是 `[data-view="ironed"]`。在 Mac 上，`qlmanage -t -s 1000 pattern.pdf` 只能生成第一页。后面几页用 `pdftoppm` 或 `mutool`（如果有），或者写几行 Swift 调 CoreGraphics。实在看不到图纸页，要如实告诉对方，并检查编辑器的“图纸”视图，它画的是同一张网格。

要在命令行里改做好的图案：改 `pattern.json`，再运行 `make.mjs --from pattern.json --out 文件夹`。

## 交付什么

- `index.html`：编辑器，一个文件，不用联网。点一颗豆就能改，按住拖动连着涂，还能去掉、填充、把某个颜色全部换掉、撤销。如果改完有豆子没有和主体边贴边连上，它会被红圈标出，并提示在第几行第几列。铺满区域里的豆子和周围都连着，没有问题。可以在图纸、摆豆、熨好三种样子之间切换，也可以换一张新照片、改大小和颜色。改动会自动记住，还能重新生成 PDF、存图片、另存一份。
- `pattern.pdf`：第一页是豆子清单、成品效果、10 厘米校准线和做法。后面是实际大小的图纸，四边都标行列号，每 5 格、10 格加粗。大板子会分成几页，并有小地图说明这是哪一块。
- `finished-preview.png`：熨好以后的样子。
- `bead-count.csv`：各色数量，方便购买或放进表格。
- `pattern.json`：图案数据。

## 特殊情况

- **需求很简单**（“一只猫”）：先复述你的理解，画一只原创的，并说明你替他决定了什么（颜色、大小、姿势）。不要编造真实宠物或人物的情况。
- **想换大小：** 用新的 `--board` 重跑。如果是画出来的，要重画，不要硬拉伸。
- **照片太杂：** 建议裁得离主体近一点，`--fit cover` 有帮助。少于 29 颗时人脸很难认，要如实说，并建议 48 颗以上。
- **标题里有生僻字或繁体字：** 这些字会用阅读器自己的字体打印，输出会显示 `fallbackFont: true`，要到页面上确认一下。
- **图片读不了：** 脚本会说明。可以让对方发 PNG，或者把图片拖进编辑器，浏览器能打开的它都能用。
- **没有打印机：** 也可以对着屏幕上的行列号摆。

## 交付前检查

- [ ] `scripts/check.mjs` 在输出文件夹上通过。
- [ ] 看过 `finished-preview.png`，能认出是什么。
- [ ] PDF 每页都看过：没有重叠，符号清楚。
- [ ] `looseBeads` 是 0，或者已经告诉对方哪部分会掉。
- [ ] 内容是原创或对方自己的，没有版权角色。
- [ ] 虚构的内容用 `--note` 标明。
- [ ] 已提醒打印时选“实际大小”，并用尺子量 10 厘米那条线。
- [ ] 已告诉对方：颜色只是近似，熨烫效果和打印尺寸都还没有在真实纸张上试过。
- [ ] 如果是满幅场景，`emptySquares` 是 0，没有列出 `shortRows`（除非是有意的）。浅色主体缩成缩略图也看得见。
- [ ] 对方看到的话都是大白话，没有技术词。

## 不适合的情况

不适合十字绣、钻石画或编织图，它们的格数和材料都不一样。不用于复制别人的作品或角色，也不用于售卖受保护题材的图纸。

## 运行要求

Node 18 以上，不需要其他软件、账号或网络。Mac 上通过自带的 `sips` 支持 HEIC 和 WebP；其他系统有 ffmpeg 时会用它。只有想自动操作编辑器做检查时才需要 Playwright。