image-to-svg

图像转 SVG

通过拆解、研究并独立重建每个视觉元素，将栅格图像重新创作成高质量 SVG。

核心原则

切勿尝试一次性重现整张图像。 质量源于隔离每个特征，对照裁剪后的参考图仔细研究，并在合成之前将其构建为独立的 SVG。

正确性优先于速度。 这个工作流中的每一处捷径，都会叠加成最终输出中明显的质量损失。批量验证裁剪图、跳过程序化检查、凭目测估算坐标而非测量、满足于“看起来差不多”而不运行差异比较——每种做法都只省下一分钟，却会在返工上花掉十分钟，或导致结果明显更差。这项技能的价值在于输出质量。请花时间在每个步骤中进行验证。

适用场景

• 将图像（照片、插画、AI 艺术）转换为 SVG
• 创建徽标、吉祥物、图标或艺术作品的矢量版本
• 从图像中提取特定元素，制作可缩放图形
• 用户提供参考图像并希望将其重新创作为 SVG

说明

你正在将栅格图像转换为 SVG 复刻。请按顺序完成以下阶段。

此技能采用渐进式探索——参考文件位于此技能相邻的子目录中（analysis/、features/、styles/、workflow/）。只有在特定阶段或条件需要时才读取它们。不要预先读取所有参考文件。

阶段 0：环境设置

阅读 workflow/workflow-dependencies.md 并运行依赖检查脚本。确保所需工具（magick、rsvg-convert、xmllint）可用。对于可选工具（vtracer、svgo），检查是否可用，并记录能够进行哪些增强。

如果尚未安装 vtracer 且 Python 可用，请询问用户希望将虚拟环境放在哪里，然后再创建。有关三个选项（项目本地、共享技能 venv、用户指定），请参阅依赖文件。

阶段 1：分析图像

初步分析——以下工作彼此独立。请委派给并行子 Agent，让每个子 Agent 都能专注于自己的任务：

1. 识别艺术风格。 启动一个子 Agent，让它读取 styles/styles-identification.md、研究图像，并返回风格分类及其依据（线条表现、形状语言、色彩处理、细节层次）。确定的风格将决定后续使用的技术。
2. 建立观察框架。 启动一个子 Agent，让它读取 analysis/analysis-asking-questions.md、研究图像，并返回关键观察问题的答案——对于复杂对象，尤其要关注构造和结构相关的问题。这份报告将为拆解步骤提供参考。
3. 处理透明度。 通过程序检查：magick identify -format "%[channels]" original.png——如果结果显示 srgba 或类似的 alpha 通道，请记录最终 SVG 是否应保留透明背景（表情符号／贴纸常见此需求），还是填充为纯色。

拆解——此步骤依赖上述观察框架：

4. 拆解为特征。 阅读 analysis/analysis-identifying-concepts.md。将图像拆解为彼此独立的视觉元素，并确定 Z 轴顺序（图层堆叠顺序）。

并行准备——以下任务都依赖步骤 4 得出的特征列表，但彼此独立。请并行执行：

5. 创建并验证参考裁剪图。 阅读 analysis/analysis-reference-crops.md。编写 feature-locations.yml，为每个特征指定边界框，然后一次性裁剪所有特征。对每张裁剪图运行程序化边缘留白检查——这是最常见的失败点。通过调整 YAML 并重新裁剪来修复未通过检查的裁剪图（不要重新根据图像估算）。然后逐张目视验证每张裁剪图（每次 Read 调用一张，不要批量处理）。在所有裁剪图都没有被截断之前，不要进入构建阶段。

6. 以编程方式测量并映射坐标。 阅读 workflow/workflow-verification.md，了解测量流程。切勿凭目测估算特征坐标——微小的估算误差会在多个特征间累积，破坏比例。

   • 确定画布尺寸（表情符号/图标通常采用 512x512；其他主体使用原始宽高比）
   • 使用 ImageMagick 测量原图尺寸，并计算缩放到画布的比例
   • 确定比例锚点：测量 3-5 个关键点（例如：“头部中心位于角色高度的 35%，下巴位于 52%，双脚位于 95%”）。用比例而非绝对像素表示——将画布重新映射后，比例仍然适用。
   • 通过测量原图并缩放到画布坐标，计算每个特征的边界框
   • 记录特征间关系——不仅要记录各个边界框，还要说明特征之间的关系：“嘴宽 = 脸宽的 55%”“靴子间距 = 身体宽度的 15%”“耳朵超出帽檐边缘 20%”。这些相对测量能确保分别构建特征时比例依然正确。
   • 使用测量坐标、比例、特征间关系和层级顺序记录特征图。每个群组 Agent 都会携带这份特征图。

7. 撰写主体简介。 用 2-3 句话描述主体的个性、表情和整体感觉（“一个调皮、自信的地精，咧嘴欢笑，双臂交叉，神情自豪”）。每个 Agent 都会在测量数据之外携带这段定性描述——它能让 Agent 把握主体的感觉，而不只是几何形状。没有这段描述，Agent 生成的特征虽然在技术上正确，却缺少角色个性。

裁剪图验证完成后（必须先完成步骤 5）：

8. 从裁剪图中提取描摹元数据。 如果有 vtracer，请阅读 workflow/workflow-trace-metadata.md。以多边形模式自动描摹每个特征裁剪图，并提取结构化元数据：调色板、子元素位置/尺寸、面积百分比和拓扑提示。这会为 Agent 提供精确的数值数据（每个特征约 130 个词元），而无需它们凭目测从光栅图像中判断颜色和位置。将描摹元数据添加到特征图中每个特征的条目。

   如果没有 vtracer，则改用 ImageMagick 提取颜色：

   magick refs/{feature}.png -resize 200x200 -kmeans 10 -unique-colors txt: | tail -n +2 | tr -s ' ' | cut -d' ' -f3
   

   这样可以获得准确的十六进制值，但无法获取子元素的空间数据。

阶段 2：构建各个特征（Agent 群组）

确定风格、验证参考裁剪图并建立特征图后，让 Agent 群组协作构建各个特征。每个特征彼此独立——可以由不同的 Agent 并行构建，每个 Agent 都使用自己的参考裁剪图。

角色/面部图像

对于角色或面部图像，在构建每个元素之前，请先阅读 features/ 中相关的特征参考表：

特征	参考文件
眼睛	features/features-eyes.md
嘴部	features/features-mouth.md
鼻子	features/features-nose.md
耳朵	features/features-ears.md
脸型	features/features-face-shape.md
头发	features/features-hair.md
身体	features/features-body.md
配饰	features/features-accessories.md
复杂物体（手持物品、道具）	features/features-objects.md

只阅读图像中实际存在的特征对应的参考表。

非角色图像（风景、徽标、物体、抽象图像）

features/ 参考图表针对特定角色。对于其他主题，请改为按视觉图层进行分解：

• 徽标/图标： 背景形状、主要符号、文本（描摹为路径——不要使用 <text> 元素，因为字体不会匹配）、次要元素、边框/框架
• 风景/场景： 天空/背景、远景元素、中景、前景、焦点主体、氛围效果（雾、光束）
• 物体/产品： 阅读 features/features-objects.md，了解结构分解的详细指导。物体具有内部结构、多个可见表面，以及远超“轮廓 + 填充”的透视复杂性。请按结构部件（面板、肋条、关节、把手）进行分解，而不只是按颜色区域。
• 车辆/机器： 阅读 features/features-vehicles.md。车辆由多个面板组成——请按车身面板、玻璃、车轮、灯和装饰件进行分解。面板线条和金属渐变至关重要。
• 食物/饮品： 阅读 features/features-food.md。采用形状构建方法，添加光泽高光、分层结构以及蒸汽/香气效果。
• 植物/花卉： 阅读 features/features-plants.md。使用 <use> + rotate 构建径向花瓣对称结构，并通过裁剪构建带叶脉的叶片。
• 抽象图像/图案： 基础图层、重复图案（尽可能使用 <pattern> 或 <use>）、点缀元素、叠加效果
• 混合图像： 对于结合多个类别的图像（如角色在风景中手持物体），以焦点主体的分解方式为主，并对次要元素进行更简单的处理。

同样的原则也适用：每个元素单独裁剪，每个图层使用独立的 SVG，共用相同的合成 viewBox。请阅读 analysis/analysis-asking-questions.md，了解每个元素的分析问题——形状、颜色和位置方面的问题具有普遍适用性。

对表情至关重要的特征

某些特征之所以格外重要，是因为它们决定了角色的个性或物体的特征。这些特征需要更加严格的比较——在合成前进行更多轮迭代、程序化差异验证以及并排检查：

• 嘴部/笑容——最能体现表情的单一因素。弧度、宽度和嘴角上扬的程度必须高度匹配。
• 视线方向——瞳孔位置和高光位置决定了角色在看哪里，以及它给人的“感觉”。
• 整体比例——头身比、站姿宽度、四肢长度。如果这些不准确，再多细节也无法弥补。
• 标志性特征——让这个特定主体易于辨认的任何特征（独特的帽子、特定的徽标、独一无二的轮廓）。

对于这些特征，请务必运行程序化差异检查（见下文“渲染-比较循环”），并持续迭代，直到差异分数趋于稳定，即使这意味着迭代超过 3 轮。

构建各个特征

对于每个特征：

1. 单独研究裁剪后的参考图像，并且查看完整原图，以了解比例关系
2. 思考 analysis/analysis-asking-questions.md 中的问题
3. 考虑被遮挡的部分——如果该特征被其他元素部分遮挡（如帽子下的头部、头发下的脸部），图层仍应延伸到遮挡元素下方。请参阅下文“处理被遮挡的内容”。
4. 在 parts/ 中构建独立的 SVG
5. 应用适当的艺术风格技法——插画／卡通风格请阅读 styles/styles-line-and-brush.md，扁平／几何风格请阅读 styles/styles-geometric.md，摄影／写实图像请阅读 styles/styles-applying-to-lifelike.md。只阅读与第 1 阶段确定的风格相匹配的样式文件。
6. 务必阅读 styles/styles-curves-and-shapes.md，了解曲线构造技法。此项适用于所有风格——该文件介绍了如何使用合适的 SVG 路径命令构建形状、何时使用填充形状而非描边，以及如何构造自然曲线。这是连接“应该呈现什么效果”与“如何在 SVG 中实现”的桥梁。
7. 渲染并比较——请参阅下文“渲染-比较循环”

优先采用复杂构造，而非简单几何（识别为几何／扁平风格的图像除外——此类图像应遵循 styles/styles-geometric.md）。使用三次贝塞尔曲线构建填充形状，并加入恰当的宽度变化、各面板的光照效果和结构细节，其效果总是优于带描边的圆形。只有当参考图像确实呈现完美的几何形状，或风格明确为扁平／几何风格时，才使用 SVG 基本图形（<circle>、<rect>、<ellipse>）。不确定时，选择构造更复杂的版本——两者在视觉质量上的差异相当显著。

Agent 集群协作

一个特征 = 一个 SVG = 一个 Agent。无一例外。 即使是极其简单的特征（只有两个点的鼻子、闪光、小徽章），也要有自己的文件和自己的 Agent。多派一个 Agent 的成本很低；合成和未来动画中各部分相互耦合的成本很高。

成对特征始终要分开。 左眼和右眼由不同的 Agent 分别编写不同的 SVG。左右耳、左右靴、左右手臂也一样。它们会在对齐阶段（Phase 3）检查一致性——一致性应在这里得到保证，而不是让一个 Agent 同时构建两者。

身体各部分相互独立。 手臂与躯干分开。每条腿单独处理。头部与颈部分开。设想每个部分将来都可能独立运动——身体静止时手臂可以移动，一只耳朵可以摆动而另一只保持不动。

如果有 5 个特征，就启动 5 个 Agent。如果有 50 个特征，就启动 50 个 Agent。并行处理正是关键。每个 Agent 会收到：

• 对应特征的参考裁剪图
• 完整的原始图像——裁剪图用于查看细节，完整图像用于了解比例。构建嘴部的 Agent 若看不到完整的脸，就无法判断笑容是否足够宽。
• Phase 1 第 7 步的主体简介——目标个性／表情／氛围
• 已识别的艺术风格描述
• 相关的特征参考表（来自 features/）
• 相关的风格技巧文件（styles/styles-line-and-brush.md、styles/styles-geometric.md 或 styles/styles-applying-to-lifelike.md）
• 曲线构建参考（styles/styles-curves-and-shapes.md）——始终包含
• 验证流程（workflow/workflow-verification.md）——始终包含
• Phase 1 第 6 步中的特征图，包含测量坐标、比例锚点和特征间关系
• Phase 1 第 8 步中该特征的描摹元数据（调色板、子元素位置／大小、拓扑）——如果有
• 该特征是否对表情至关重要（见上文）——如果是，Agent 应运行完整的程序化差异比对循环
• 将独立 SVG 写入 parts/{feature-name}.svg 的指示

以定量而非定性的方式描述特征。 向 Agent 提供说明时，文字描述会丢失视觉细节——“宽阔的笑容”无法传达确切的曲率，“厚帽檐”也有歧义。应改用测量值：“嘴宽 = 脸宽的 55%”，“帽檐高度 = 帽高的 5%，沿穹顶曲线延伸”。形容词不可靠；比例不会。 所有 Agent 必须使用与合成画布相同的 viewBox（例如，viewBox="0 0 512 512"）。每个 Agent 都使用特征图中的边界框，在完整画布坐标内定位其特征。这样合成时各部分无需缩放即可对齐。

相互作用的特征（例如脸部 + 耳朵、头发 + 帽子）应予以说明，但仍需独立构建——交互关系在 Phase 4 中处理。对于紧密耦合的特征（耳朵 + 脸部轮廓、头发 + 帽檐），应提供相邻特征的边界框，让 Agent 知道边界所在位置。

渲染对比循环

阅读 workflow/workflow-verification.md，了解完整的验证流程。关键在于：不要只依赖视觉对比——LLM 擅长发现严重错误，却不擅长捕捉细微的比例和曲率差异。使用程序化差异比较精确定位错误，再用 LLM 解读并修复错误。

每次修改 SVG 后：

1. 验证 SVG XML，然后再进行渲染：

   xmllint --noout parts/{feature}.svg
   

   这能清楚地指出未闭合标签、格式错误的属性和缺失的命名空间，错误信息比 rsvg-convert 难以理解的报错有用得多。

2. 渲染 SVG 为 PNG：

   rsvg-convert -w 512 -h 512 parts/{feature}.svg -o parts/{feature}.png
   

   如果未安装 rsvg-convert，请安装它（macOS 上运行 brew install librsvg，Linux 上运行 apt install librsvg2-bin）。

3. 程序化差异比较——生成视觉差异图和数值评分，将渲染后的特征与参考裁剪图进行比较。ImageMagick 命令参见 workflow/workflow-verification.md。差异图会准确突出显示 SVG 在哪里存在偏差——红色区域表示差异最大的部分。

4. 查看差异图——根据突出显示的差异来指导修正。这比对比两张看起来相似的图有效得多：ImageMagick 能精确找到错误，你来解读错误并了解如何修复 SVG。

5. 视觉检查——同时查看渲染后的 PNG 和参考裁剪图，进行定性评估（颜色、整体观感、细节）。

6. 迭代——修复差异图突出显示的首要问题，重新渲染，再次比较差异。重复此过程。

何时停止迭代：对于普通特征，限制为 3-5 轮修正。对于表情关键特征（嘴巴、眼睛、整体比例），最多继续迭代 10 轮——这些特征决定角色形象，值得投入更多迭代。

收敛目标（RMSE，归一化至 0-1）：

• 表情关键特征：目标 RMSE < 0.15
• 标准特征：RMSE < 0.25 即可接受
• 背景/简单填充：RMSE < 0.30 即可接受
• 连续两轮迭代的改进幅度均小于 0.02 时停止——收益递减

这些只是参考标准，并非硬性门槛。RMSE 为 0.18 但看起来正确的特征就算完成；RMSE 为 0.12 但看起来不对的特征则需要换一种方法。相信差异图，而不是数字。

处理被遮挡的内容

当某个特征被另一图层部分遮挡时：

• **想象遮挡物下方的形状。**戴着帽子的头部仍然有完整的头顶——将头部轮廓向上延伸到帽子所在的位置，即使最终合成图中看不到这部分也一样。
• **简化但不要省略。**隐藏部分不需要完整细节，但形状应保持连贯。这样即使合成时图层发生偏移，也能避免出现硬边或空隙。
• **考虑完整形状。**面部路径应该是一条完整闭合的曲线，而不是在帽檐处中断。

阶段 3：类对齐（Agent 群组）

所有特征单独构建完成后，检查成对和重复特征的一致性。使用 Agent 群组处理此任务——为每一类相似特征安排一个 Agent。

“类”是指应采用相同构建风格的一组特征：

• 眼睛类——左眼 + 右眼
• 耳朵类——左耳 + 右耳
• 靴子／鞋子类——左靴 + 右靴
• 手臂类——左臂 + 右臂（如果姿势中两者都可见）
• 其他重复元素——例如自行车的两个车轮、建筑物上的多扇窗户

对于包含多个主体的图像，每个主体的特征分别归类：“角色 A 的眼睛”和“角色 B 的眼睛”属于不同的类。

每个对齐 Agent 都会收到两个 SVG、两个参考裁剪图和完整原图，并检查：

1. 轮廓粗细——成对特征是否使用相同的描边宽度或偏移技巧？（这是独立 Agent 之间最容易出现差异的地方）
2. 绝对尺寸——它们的尺寸是否相同，或者是否根据参考图有意采用不同尺寸？
3. 填充颜色——两者是否使用完全相同的十六进制值？
4. 构建技巧——一个使用椭圆，另一个却使用路径了吗？即使尺寸相同，这也会造成视觉不一致。
5. 高光数量和位置——高光是最具“创造性”的部分，也最容易在不同 Agent 之间出现差异。
6. 比例位置——例如“左右眼到脸部中心的距离应相等”这类检查。

对齐 Agent 会统一任何非预期的不一致之处，使成对特征保持一致，同时保留参考图中有意设计的不对称（例如，如果参考图确实显示双眼大小不同，就保留这种差异）。

阶段 4：合成与迭代

阅读 workflow/composition-bringing-layers-together.md。

此阶段不可省略。 首次合成永远不是最终输出。单独构建的特征总会存在比例和对齐问题，只有放在上下文中才能看出来。

1. 合成——将独立 SVG 合并为复合图
2. 应用效果——根据需要阅读 styles/styles-effects.md，了解 <clipPath>、<mask> 和 <filter>
3. 将复合图与原图进行差异比较——使用 workflow/workflow-verification.md 中的整图程序化差异比较。这会准确突出复合图与原图的差异位置。
4. 根据差异结果找出最明显的 3 处问题——通常是比例错误（头部太小、特征偏移）、表情不符（嘴部弧度、视线方向）或交互问题（帽子位置不对、肢体重叠不正确）。
5. 修正每处问题——将有针对性的修正反馈给负责该特征的 Agent，或直接在复合 SVG 中修正。每次修正后都要重新渲染并再次比较差异。
6. 重复此过程，直到复合图的差异趋于稳定——至少迭代 2 次；如果影响表情的关键特征有误，则需要迭代更多次。
7. 最终小尺寸检查：

   rsvg-convert -w 64 -h 64 final.svg -o /tmp/small-check-64.png
   rsvg-convert -w 128 -h 128 final.svg -o /tmp/small-check-128.png
   

   查看两种渲染结果——在图标尺寸下是否仍然清晰？在 512px 下看起来没问题的特征，可能会融合或消失。

阶段 5：交付

阅读 workflow/workflow-file-structure.md，了解预期的项目布局。

1. 优化最终 SVG。 如果可以使用 svgo，请运行它，并禁用 cleanupIds 以保留命名组：

   svgo final.svg -o final.svg \
     --config='{"plugins":[{"name":"preset-default","params":{"overrides":{"cleanupIds":false,"collapseGroups":false,"convertShapeToPath":false}}}]}'
   

   这通常可将文件大小缩减 25-40%（数值精度、默认属性、路径命令优化），且不会改变视觉效果。如果无法使用 svgo，则跳过此步骤——该 SVG 仍然有效。

2. 保留 parts/ 目录及其中的独立 SVG，以便日后编辑

3. 提供最终复合 SVG

4. 渲染目标分辨率的 PNG 以供比较