图解workout-guide图像处理流水线:906张PNG如何批量转为干净透明SVG(sharp + potrace + svgo)
图解workout-guide图像处理流水线:906张PNG如何批量转为干净透明SVG(sharp + potrace + svgo)
workout-guide 是一个包含 302 个开源动作插画的 npm 包,每个动作提供 3 帧一致的透明线条图,共 906 张 512×512 的 PNG 源图。本文图解它的图像处理流水线:如何用 sharp、potrace 和 svgo 三个工具,把这 906 张 PNG 一键批量转换成干净、透明、可缩放的 SVG 矢量图。
📦 背景:为什么要把 906 张 PNG 全部矢量化成 SVG?
在 packages/workout-guide/assets/ 目录下,每个动作对应一个文件夹(如 push-up/),内含 frame-1.png、frame-2.png、frame-3.png 三帧,以及对应的三帧 .svg 矢量版。
对开发者和最终用户来说,SVG 版带来了几个实打实的好处:
- 任意缩放不失真:512×512 的位图放大到 4K 会发虚,SVG 则永远锐利
- 可用 CSS 控制颜色:SVG 内部是单一
<path>元素,一行fill就能换配色 - 可组合复用:项目自己的社交卡片生成脚本 scripts/sync-site-assets.mjs 会直接解析 SVG 的
<path>内容,把动作插图拼进 OG 分享图里——这在纯 PNG 上根本做不到
🔄 流水线全景:一条命令串起三个工具
整条流水线由 npm script assets:vectorize(见 package.json)触发:
npm run assets:vectorize
它执行 scripts/vectorize-assets.mjs,逻辑非常薄:
const pngs = await findPngs(assetsRoot);
for (const [index, png] of pngs.entries()) {
await vectorizePng(png, png.replace(/\.png$/i, '.svg'));
if ((index + 1) % 100 === 0) console.log(`Vectorized ${index + 1}/${pngs.length} frames.`);
}
真正的重活全在 scripts/lib/vectorize-png.mjs 里,每张图经历三个阶段:sharp 提取蒙版 → potrace 描摹矢量 → svgo 压缩优化。
🔍 第一步:sharp 提取 Alpha 蒙版
所有源图都是白色线条 + 透明背景的 PNG。流水线并不关心像素内容,只关心"哪里不透明"。vectorize-png.mjs 的 vectorizePng 函数先做防御性检查:
const metadata = await sharp(inputPath).metadata();
if (!metadata.hasAlpha) {
throw new Error(`${inputPath} must have an alpha channel to be vectorized.`);
}
没有 Alpha 通道的图会被直接报错拒收——因为这类图根本没有"透明区域"可言,描摹出来必然是一整块矩形。
检查通过后,sharp 执行三步链式处理:
extractChannel('alpha'):只取 Alpha 通道,黑白二值化"形状轮廓"negate():反转颜色,让线条变黑、背景变白——这是 potrace 的经典输入格式(深色为填充区)- 输出为 PNG buffer,交给描摹器
这一步的巧妙之处在于:potrace 是纯黑白位图描摹器,不懂"半透明"和 RGB 颜色。用 Alpha 通道做中间媒介,任何配色的透明 PNG 都能统一喂给它。
✒️ 第二步:potrace 把蒙版描摹成矢量
描摹参数集中定义在 TRACE_OPTIONS 中,每个参数都有明确意图:
const TRACE_OPTIONS = {
alphaMax: 1,
background: potrace.Potrace.COLOR_TRANSPARENT,
color: '#fff',
optCurve: true,
optTolerance: 0.2,
threshold: 128,
turdSize: 0,
};
COLOR_TRANSPARENT:SVG 背景保持透明,得到"干净透明"的插图color: '#fff':线条统一填充为白色,与 PNG 源图视觉一致optCurve: true+optTolerance: 0.2:用贝塞尔曲线拟合轮廓并做平滑优化,这是线条"干净流畅"的关键turdSize: 0:不过滤任何噪点碎块,保证细节完整
traceMask 函数(第 18–26 行)把 potrace 的回调 API 封装成 Promise,让整条流水线可以干净地 await。
🗜️ 第三步:svgo 多遍优化
potrace 输出的 SVG 往往带有冗余精度。最后一步用 svgo 收尾:
const optimized = optimize(svg, {
multipass: true,
path: outputPath,
});
multipass: true 让 svgo 反复遍历直到产物不再变化,把坐标小数位、冗余属性等全部压缩,最终写入磁盘(vectorize-png.mjs#L41-L45)。打开任意产出的 frame-1.svg,你会看到一个 512×512 的 <svg> 和唯一一个 <path> 元素——结构极简,方便样式化与二次处理。
🛡️ 细节设计:确定性、容错与可复现
这套流水线有几个值得学习的工程细节:
| 设计点 | 做法 | 出处 |
|---|---|---|
| 输入校验 | 无 Alpha 通道直接抛错 | vectorize-png.mjs#L30-L32 |
| 确定性遍历 | findPngs 递归收集后 sort(),顺序稳定 |
vectorize-png.mjs#L48-L57 |
| 进度反馈 | 每 100 张打印一次进度(共 906 张) | vectorize-assets.mjs#L11 |
| 安全护栏 | 拒绝在包外目录替换资产 | import-catalog.mjs#L72-L74 |
同一套 vectorizePng 还被目录导入脚本 scripts/import-catalog.mjs 复用:维护者可以从兼容的源导出重新生成整个目录,位图与矢量图一次全部重建,保证产物可复现。
🚀 如何本地运行
环境要求 Node ≥ 24(见 package.json),依赖在仓库根 package.json 中声明:potrace、sharp、svgo。
npm install
npm run assets:vectorize
运行结束后,packages/workout-guide/assets/ 下每个 frame-N.png 旁边都会出现同名的 frame-N.svg,906 张图一次转换完成。
✅ 小结
workout-guide 的图像处理流水线是"位图转矢量"的一个教科书式范例:
- sharp 负责提取 Alpha 蒙版,把彩色透明图归一化为 potrace 可理解的黑白输入
- potrace 负责轮廓拟合,透明背景 + 白色填充 + 曲线优化,产出干净的线条 SVG
- svgo 多遍优化,压掉所有冗余,最终产物是单
<path>的极简文件
一条 npm run assets:vectorize,906 张 PNG 全部变成可缩放、可换色、可程序化复用的矢量资产——这正是这个开源插画库能在网页和移动端稳定呈现的关键基础设施。



