中文手册 · 更新于 2026 年 10 月 19 日

刺绣打板工作台使用手册

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

日常操作：先掌握这六步

1. 选择图片，设置实际宽度。标志选“标志”，平面插画选“简单插画”，熊图或含纹理图片可先选“照片”。
2. 点击“生成打板”，切换分色图，检查眼睛、嘴、文字是否存在。
3. 需要修正时打开“精修与对照”，选择区域、补画或合并颜色；改局部针法后点“应用区域参数”。
4. 再点“生成打板”，查看针迹图和播放顺序。
5. 下载 DST 和线色表，同时保存项目文件，便于下次继续改。
6. 有参考文件时才导入对照，用完可点“移除参考 DST”。普通生成不要求参考文件。

查看精修按钮完整说明

三类预设与眼睛细节

三类均开启底针、方向跟随图案，并保留你当前填写的图案宽度。照片预设已减轻清理力度，并对有足够尺寸、与周围颜色明显较暗的小区域增加保护。不是语义识别人脸；极小、模糊、低对比的细节仍可能丢失。细节缺失可把合并值降到 0–0.5、平滑关闭，或在精修区补画。改过的旧项目不会自动替换参数，需要重新选择“照片”；若已有分区编辑，请先保存项目，再重新分色。

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. 参数说明

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

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

填针用相邻针迹行覆盖较大的区域；缎面针在窄条两侧交替落针；跑针沿细线走针。引擎依据区域形状和宽度提出针法，某些缎面候选在算法检查后可能退回填针。现在可在“精修与对照”中编辑区域针法、补画、擦除、合并颜色和调整顺序；不提供逐针节点编辑或多图拼版。

7. 怎样看结果

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

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

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

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

8. 下载文件的用途

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

9. 上机之前

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

10. 常见问题

11. 现场演示顺序

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

12. 本地运行与开发

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

# 在源码目录执行；需要 Python

python -m http.server 4173 --directory dist

# 然后打开 http://localhost:4173

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

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

原仓库上游说明保留在 README.md；本中文手册同时保存为 README-中文使用手册.md，网页手册位于 /help/，精修手册位于 /help/precision.html；/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。

图案预设与界面

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

精修操作手册

打开精修网页版。包含参考文件移除、区域画笔、每个按钮的作用及日常建议。