图解workout-guide图像处理流水线:906张PNG如何批量转为干净透明SVG(sharp + potrace + svgo)

原创2026-10-14 18:57:551,414 阅读

图解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 矢量版。

workout-guide 透明 PNG 源图:俯卧撑动作的白色线条插图

对开发者和最终用户来说,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 压缩优化。

workout-guide 锻炼动作 PNG 插图:卧推动作线条图转矢量前的位图素材

🔍 第一步: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 执行三步链式处理:

  1. extractChannel('alpha'):只取 Alpha 通道,黑白二值化"形状轮廓"
  2. negate():反转颜色,让线条变黑、背景变白——这是 potrace 的经典输入格式(深色为填充区)
  3. 输出为 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:不过滤任何噪点碎块,保证细节完整

workout-guide 硬拉动作 PNG 源图:白色透明线条插图经 potrace 描摹为 SVG 路径

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 复用:维护者可以从兼容的源导出重新生成整个目录,位图与矢量图一次全部重建,保证产物可复现。

workout-guide 高脚杯深蹲 PNG 插图:透明背景白色线条图批量矢量化的典型素材

🚀 如何本地运行

环境要求 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 的图像处理流水线是"位图转矢量"的一个教科书式范例:

  1. sharp 负责提取 Alpha 蒙版,把彩色透明图归一化为 potrace 可理解的黑白输入
  2. potrace 负责轮廓拟合,透明背景 + 白色填充 + 曲线优化,产出干净的线条 SVG
  3. svgo 多遍优化,压掉所有冗余,最终产物是单 <path> 的极简文件

一条 npm run assets:vectorize,906 张 PNG 全部变成可缩放、可换色、可程序化复用的矢量资产——这正是这个开源插画库能在网页和移动端稳定呈现的关键基础设施。

登录后查看全文
workout-guide