# 刺绣打板工作台使用手册

在线地址：https://cixiu-workbench-20261018.pages.dev

## 1. 这个网站能做什么

选择一张图片，设置实际尺寸和分色数量，生成刺绣针迹，查看原图、分色图和针迹图，播放缝纫顺序，最后导出 DST。页面是中文工作台，不需要账户，也不用安装打板软件。图片在当前浏览器内处理，没有上传图片的服务端接口。首次打开需要网络加载网页。

当前采用 Heatstitch 的规则打板算法，没有调用大模型。适合演示图案转换、参数调整和针迹导出；生成文件仍需在相应机器、面料与衬料上试绣。页面不模拟张力、面料变形或真实绣线交织。

## 2. 第一次使用：先跑通示例

1. 在电脑浏览器打开在线地址，尽量让窗口宽一些。
2. 点击左侧“载入花朵示例”。中间出现原图，左侧显示“花朵示例.svg”。
3. 保持默认参数：宽度 80 毫米、最多 6 种线色、小区域合并 3 平方毫米、平滑关闭、去背景和匹配绣线颜色勾选；行距 0.4 毫米、针长 4 毫米、方向跟随图案、生成底针勾选。
4. 点击“生成打板”。底部先显示“正在分色”，再显示“正在生成针迹”。不要在此时更换图片。
5. 完成后自动切换至针迹图，右侧显示实际针数、针迹尺寸、换色和跳针统计。
6. 点击“分色图”，检查背景是否正确去除、细节是否保留。点击“原图”比较，再返回“针迹图”。
7. 点击“播放针迹”查看缝纫顺序。播放过程中按钮变为“暂停”。旁边的“播放速度”可选择 0.05、0.1、0.25、0.5、1、2、4、8 倍；细看走针时可用 0.05 或 0.1 倍，默认 1 倍；播放中切换会从当前位置继续，不需要重新生成。可以拖动进度条，或点击“从头查看”。
8. 点击“下载 DST”，再点击“下载线色表”。两份文件应一起保留。
9. 下载“打板参数”，方便之后照着重新设置。需要展示图片时，切换到目标视图并点击“下载当前预览图”。

默认值是演示起点，不是针对所有面料的工艺标准。

## 3. 使用自己的图片

点击“选择图片”，从电脑选择 PNG、JPG、WebP 或 SVG。PNG 适合透明背景标志，JPG 适合已有照片，SVG 在本工作台中先栅格化，再走图片打板流程，并非直接按矢量路径编译。SVG 应自带尺寸与图形，不依赖外部图片、字体或样式。

单张文件限制为 20 MB；源图最长边超过 1200 像素时，会缩小到最长边 1200 像素供算法处理。比例保持不变。输入尽量使用清晰、颜色分明、背景干净的图案。复杂照片、渐变、细字和发丝不一定能准确保留。

选择新图会清空上一张图的结果。如果参数已改变，旧预览可以查看，但导出按钮会禁用；重新生成后才能导出，避免参数和文件不一致。本版本会在此浏览器保存最近一个项目，刷新后点击“继续上次项目”恢复；重要内容请同时下载项目文件备份。

## 4. 页面各部分

界面采用浅灰工具布局。默认只显示图片、图案宽度、最多线色和生成按钮；小区域合并、平滑、去背景、行距、针长、方向与底针位于左侧“高级设置”中。第一次使用无需展开，默认值已填好。顶部按“选择图片 → 生成打板 → 下载 DST”标出当前步骤。“下载当前预览图”和“下载打板参数”位于右侧“其他导出”中。

- 左侧：选择图片、输入尺寸、分色与针迹参数。
- 中间：原图 / 分色图 / 针迹图三个视图；针迹播放、跳针开关、进度条和状态提示。
- 右侧：针数、实际针迹尺寸、换色次数、跳针指令、剪线次数、线色表及四种导出。
- 顶部“使用手册”：打开本说明的网页版。

小屏幕上区域会自动换行，主要演示建议使用电脑。

## 5. 参数说明

| 参数 | 初始值 / 范围 | 作用与调整方式 |
|---|---|---|
| 图案宽度 | 80 毫米；10–200 | 输入画布的物理宽度，高度按原图比例计算。图案四周留白多时，实际针迹宽度会小于输入宽度。 |
| 最多线色 | 6；2–16 | 控制分色上限。实际色数可能少于设定值。色数越多，颜色细节可能越丰富，但换色、区域与计算量可能增加。 |
| 合并小区域 | 3 平方毫米；0–30 | 小于阈值的色块会并入附近区域。细字或小色块丢失时降低；杂点太多时提高。0 表示关闭面积合并。 |
| 照片平滑 | 关闭 / 轻度 / 中度 | 平滑照片纹理，减少细碎区域。标志与线稿一般先关闭。 |
| 去除边缘连通背景 | 开启 | 识别与图片边缘连通的背景区域并不生成针迹。不是语义抠图；主体接触边缘或背景复杂时可能误删。 |
| 匹配预置绣线颜色 | 开启 | 通过算法匹配预置 Brother 线色。屏幕 RGB 不保证等于手上实物绣线。 |
| 填针行距 | 0.4 毫米；0.2–1.5 | 相邻填针行之间的距离，同时用于缎面间距设置。越小通常越密、针数越多；不能无限减小。 |
| 填针针长 | 4 毫米；1–6 | 填针分段的目标针长。不是所有针迹的统一长度：弯曲、锁针、跑针等会采用各自规则。 |
| 填针方向 | 跟随图案 / 0° / 45° / 90° / 135° | 自动模式参考图像结构；固定方向适合对比排针方向。角度不是整幅图旋转。 |
| 生成底针 | 开启 | 允许算法在适用区域先生成支撑底针。小区域可能不加底针，开启不意味着每个色块都有底针。 |

隐藏的引擎设置沿用 Heatstitch 稳定机织面料与 40 号线的默认配置，包括拉伸补偿、区域重叠与剪线阈值。本页面没有面料选择器，不会自动适配针织面料、毛绒面料或特殊绣线。

## 6. 什么是填针、缎面针与跑针

填针用相邻针迹行覆盖较大的区域；缎面针在窄条两侧交替落针；跑针沿细线走针。引擎依据区域形状和宽度提出针法，某些缎面候选在算法检查后可能退回填针。当前页面不提供手工区域针法编辑、画笔修图、轮廓描绘或多图拼版。

## 7. 怎样看结果

先看分色图，再看针迹图。分色图没有的区域通常不会被正确绣出。检查背景、线条、文字、相邻色块和孔洞，然后看针迹是否存在明显空隙、过密叠加或长距离跳针。

“显示跳针”用虚线标出移动，不等于实际一定留下该长度的浮线；剪线指令及机器解释也会影响结果。换色次数与线色数不同，通常一个色块缝完后才换色；同一种 RGB 可能出现在多个缝纫色块。

进度条表示内部针迹记录进度，包括缝纫、跳针、换色等；右侧“针数”仅统计缝纫针。播放速度用于展示，不是预计机器时间。PNG 下载保存当前视图与当前进度，想保存完整针迹图时先把滑块拖到最右边。

页面会将生成针迹写成 DST 再读回，核对缝纫针数。如果一致，页面才会启用 DST 下载链接。这只验证文件编码链路的一项一致性，不是机器兼容、走线或工艺合格证明。

## 8. 下载文件的用途

| 文件 | 用途 |
|---|---|
| 图案名.dst | 机器针迹文件，保存运动与换色等指令。不携带 RGB 线色。 |
| 图案名.线色表.csv | 按缝纫色块顺序记录 RGB。可用 Excel 或文本编辑器打开，供人工配线参考。 |
| 图案名.png | 当前视图和进度的预览图。不是实绣照片，也不是机器文件。 |
| 图案名.打板参数.json | 输入名称、分色与针迹参数、统计记录。供查阅与手动重设，本页面尚无参数导入按钮。 |

建议为每次演示建立一个文件夹，将原图、DST、线色表、参数和预览图放在一起。浏览器重复下载时可能自动加“(1)”等后缀，这不是新的参数版本。

## 9. 上机之前

先在兼容的刺绣文件查看器或机器软件里打开 DST，确认尺寸、针数、方向、色块顺序和绣框范围。按线色表人工配线，再用相同面料、衬料和线做试绣。根据实际出现的露底、拥挤、变形、断线等问题修改参数并重新生成。网页不保证所有机器对剪线指令解释一致，也不提供机器发送功能。

## 10. 常见问题

| 问题 | 处理方法 |
|---|---|
| 生成按钮不可点 | 先载入有效图片。若读取失败，检查格式或重新导出为 PNG。 |
| 没有生成可绣区域 | 关闭去背景；降低小区域合并阈值；增加图案尺寸。逐项调整并观察。 |
| 主体被去掉 | 主体可能接触边缘；关闭去背景，用透明 PNG 或在外部先处理背景。 |
| 小字、细线丢失 | 降低小区域阈值，关闭平滑，增大尺寸；极细线仍可能无法识别。 |
| 针数太多 / 计算慢 | 减少线色、增加小区域合并阈值、减小尺寸，或适当增加行距。避免连续点击。 |
| 改参数后下载不可点 | 这是防止导出旧结果的限制，点击“生成打板”重新计算。 |
| 下载的 DST 颜色不同 | DST 没有 RGB 线色，查看器可能显示默认色。配合 CSV 使用。 |
| 宽度不是输入值 | 输入值对应整个图片画布；去背景、留白和补偿会改变针迹包围盒。 |
| SVG 读取失败 | 将外部资源嵌入文件，写明尺寸，或用绘图软件导出 PNG。 |
| 刷新后图片消失 | 点击左侧“继续上次项目”；若浏览器存储不可用，可打开此前下载的项目文件。 |
| 网站首次加载慢 | 需下载浏览器代码，等待加载完成；图片生成由本机计算。 |

## 11. 现场演示顺序

先用花朵示例演示完整流程，保持默认参数，展示三种视图和针迹回放，下载 DST 与线色表。再选择自己的标志图案，修改宽度与最多线色并重新生成，展示结果变化。最后打开已下载 DST 的查看器，说明这是实际针迹文件。不要把网页预览称为实绣效果。

## 12. 本地运行与开发

源码目录：sites/heatstitch-demo。已有构建在 dist。

```powershell
# 在源码目录执行；需要 Python
python -m http.server 4173 --directory dist
# 然后打开 http://localhost:4173
```

不要直接双击 index.html：Web Worker 与模块加载需要 HTTP 服务。只发送压缩包不会自动产生公网地址；公网使用上面的在线地址，或将 dist 部署到静态网站主机。

```powershell
# 开发：需要 Node.js 和 npm
npm install
npm run dev
# 构建
npm run build
# 核心测试
npx vitest run tests/image.test.ts tests/digitize.test.ts tests/writers.test.ts --maxWorkers=1
```

本工作台入口为 src/workbench.ts，界面样式为 src/workbench.css，网页骨架为 index.html。算法位于 src/image、src/digitize，文件编解码位于 src/writers 与 src/parsers。

## 13. 参考项目与接入范围

- [Heatstitch](https://github.com/pfedan/heatstitch)：本网站实际使用的浏览器打板、分色、针法选择及 DST 编解码代码，保留 MIT 许可证。工作台界面为本次新建中文界面。
- [Heatstitch PR #26](https://github.com/pfedan/heatstitch/pull/26)：图片转针迹流程的参考来源，该功能已在采用的主分支代码中。
- [pyembroidery](https://github.com/EmbroidePy/pyembroidery)：参考针迹命令与文件读写核对思路。它是读写库，不负责把照片识别成绣花区域；网页不运行 Python 后端。
- [Ink/Stitch](https://github.com/inkstitch/inkstitch)：参考可调整的机器刺绣工作流程与针法术语。未嵌入其 Inkscape 扩展，也未复制其 GPL 代码。
- [PEmbroider](https://github.com/CreativeInquiry/PEmbroider)：参考“生成后可视化、再导出”的计算刺绣流程。未嵌入 Java / Processing 运行环境，也未复制其代码。

原仓库上游说明保留在 README.md；本中文手册同时保存为 README-中文使用手册.md，网页手册位于 public/manual.html。


## 新增功能：局部检查、逐针播放与项目保存

### 缩放、平移与落针位置

- 在预览画布上滚动鼠标滚轮，以指针位置为中心缩放；按住鼠标左键拖动平移。工具栏的加减按钮也可缩放，范围为适应画布大小的 25%–1600%。
- 点击“适应画布”恢复居中和 100%。100% 是适应画布比例，并非实物尺寸；真实尺寸以右侧毫米统计为准。
- 点击“上一针”“下一针”逐个检查实际缝纫落针点，会跳过跳针、换色等非缝纫指令。先点击画布取得键盘焦点，也可用左右方向键逐针查看、数字 0 恢复画布。
- “落针标记”以蓝色圆点表示当前落针位置，未播完时最近 8 针以蓝色突出。取消勾选可查看原始线色。

### 按每秒针数播放

- “每秒针数”默认 100，可输入 1–2000 的整数。实际播放速度 = 每秒针数 × 倍速，与整幅图的针数无关。
- 倍速支持 0.05、0.1、0.25、0.5、1、2、4、8。想非常慢地查看，可设为每秒 10 针、0.1 倍，即每秒 1 针；每秒 1 针配 0.05 倍即每 20 秒前进一针。
- 播放中改速度会从当前位置继续；暂停再播放也继续。拖动进度条、切换视图或逐针操作会暂停播放。后台标签页不累积未观看的播放时间。
- 进度显示实际缝纫针数，同时附上内部指令位置；倍速仅用于演示，不表示机器的真实生产时间。

### 线色与色块检查

- 点击右侧某条线色，或使用画布下方“查看线色”选择某个色块，只显示该色块的针迹。
- 点击“播放当前色块”从该色块第一针开始，播完自动停止。逐针按钮也限制在当前色块内。
- 选择“全部线色”回到整幅图。重复 RGB 可能属于不同缝纫色块，按缝纫顺序分别列出。
- 筛选和播放只影响预览，不改变生成针迹、线色表和 DST。修改打板参数仍需重新生成。

### 完整资料包

- 点击右侧“下载完整资料包 ZIP”，一次下载 DST、线色表 CSV、完整针迹图 PNG、打板参数 JSON、处理后原图 PNG、可恢复项目文件和简短使用说明。
- 资料包中的针迹图始终包含全部线色和完整进度，自动居中，不受当前缩放或色块筛选影响。单独“下载当前预览图”仍保存当前画面与进度。
- ZIP 采用标准未压缩格式，文件可能较大。PNG 是预览，不是实绣照片；上机仍需核对与试绣。

### 保存与重新打开项目

- 左侧“保存项目文件”下载 `.stitch.json`，包含处理后原图、分色图、工作台参数、完整针迹和 RGB 线色。使用“打开项目文件”可在此工作台恢复，无需重新打板；也可跨浏览器、跨电脑使用。
- 项目打开后默认居中显示完整针迹，不恢复临时缩放、速度或色块筛选。没有生成过的项目只恢复图片和参数。
- 参数修改后也可保存项目；再次打开会提示重新生成，并停用旧结果导出，避免设置与针迹不一致。
- 当前图片载入、生成完成和有效参数修改后，会自动将最近一个项目保存到此浏览器。刷新网页后点击“继续上次项目”恢复。此功能是本机保存，不是云端账户或历史项目列表。
- 浏览器禁止存储、空间不足、清除网站数据、使用隐私模式或更换浏览器时，本机保存可能不可用，请下载项目文件备份。项目文件最大 50 MB，记录最多 100 万条；图片保存为最长边不超过 1200 像素的 PNG。
- 项目仅用于本工作台，不能作为原版 Heatstitch 项目直接打开；机器使用 DST。

### 图案预设与界面

- 左侧“图案预设”提供“标志”“简单插画”“照片”。切换后会填入对应分色、平滑、去背景和针迹参数，保留输入宽度；随后点击“生成打板”。照片预设默认不去背景。
- 手动改参数后显示“自定义”。预设只是起点，不保证所有图案或面料的效果。
- 右侧下载区域保持可见，下方统计和线色独立滚动；小屏幕自动换行。辅助字号及对比度已经提高。