把一张照片变成逐笔绘制的 SVG 矢量插画,并生成一个能回放整个作画过程的网页。
不是简单的"图片转矢量"——它模拟人的作画顺序:先勾线稿 → 再铺大色块 → 最后抠细节, 每一步都按"视觉重量"分配时间,大笔慢慢铺、小笔快带过,像看一段绘画录像。
建立在 AvroraCL/image-to-css-art(MIT)之上。 上游提供算法管线与本 skill 本体,本项目在此之上加了 SVG 输出与完整回放页。 详见
ATTRIBUTION.md。
真实照片 SVG 描摹(172,471 个色块 + 1,527 笔线稿)
┌──────────────────┐ ┌──────────────────┐
│ │ │ │
│ 走廊人像 │ ──────────► │ 纯矢量,无位图 │
│ 1440 × 2012 │ │ DOM 里只有 1 个 │
│ │ │ <canvas> │
└──────────────────┘ └──────────────────┘
线稿阶段(起稿时只勾结构,天空云彩一笔不落):
在线使用:https://vanemkrau.github.io/photo-to-svg/
打开网页 → 拖一张图片进去 → 等一会儿 → 下载 SVG 和回放页。
-
图片不上传:整个流水线跑在你自己的浏览器里(Pyodide 把 CPython + OpenCV 编译成 WebAssembly)
-
无需安装:第一次打开要下载约 21 MB 运行时(含 numpy / OpenCV / Pillow),之后走浏览器缓存
-
生成历史:最近生成的作品存在浏览器本地(IndexedDB),可随时重新预览 / 下载;打开或下载旧作品时会自动升级到新的时间轴与相册式缩放
-
耗时参考(实测,取决于设备):
档位 长边 耗时 产物大小 快速 800 约 1 分钟 SVG 几 MB 标准 1200 约 1.5 分钟 SVG 16 MB / HTML 7 MB 高清 1600 约 2.5 分钟 — 最高 不缩放 3~4 分钟 SVG 31 MB / HTML 13 MB(1440×2012 实拍) 手机建议选「标准」及以下;超大图可能因浏览器内存不足失败。
一致,而且默认更好。 网页版跑的是仓库里同一份 Python 脚本(tools/ + skill/scripts/),
没有另写 JS 实现。实测同一张图(统一缩到原尺寸比较):
| 配置 | SSIM | MAE |
|---|---|---|
| 命令行 · 无预处理 | 0.9035 | 4.203 |
| 网页版 · 无预处理 | 0.8990 | 4.331 |
| 网页版 · 默认(自动预处理) | 0.9485 | 2.945 |
- 平台差异只有 0.0045(OpenCV 4.11 vs 5.0.0 的实现细节),肉眼不可辨
- 网页版默认开了「小图自动放大 2 倍」,所以默认质量比命令行默认高 0.045
详见 docs/参数速查.md。
git clone https://github.com/VanemKrAu/photo-to-svg.git
cd photo-to-svg
bash install.sh # 约 1 分钟,装依赖 + 自动自检装完想再确认一遍能不能用(会真跑一张小图,约 30 秒):
.venv/bin/python tools/smoke_test.py --render然后一条命令出全套:
.venv/bin/python tools/make_art.py 照片.jpg 作品名 "标题" 90 0 0.25 2.6后 4 位依次是:时长(秒)、线稿时间占比、epsilon、线稿线宽。
线稿时间占比默认 0,表示不单独给线稿分配时间(线稿按「√面积 ≈ 线长」计重,实测自然占 34% 时间);
只有想固定起稿时长时才填 01 的小数(如 0.15)。
还可以加 --desc="一句话描述":描述会写进回放页顶栏右上角的「描述」,收起显示一行、点击展开可编辑。
70 秒后,output/作品名/ 下会得到这四个文件:
| 文件 | 大小 | 用途 |
|---|---|---|
作品名.svg |
十几~几十 MB | 矢量原图,无限放大不糊,电脑上看 |
作品名.html |
十几 MB | 逐笔回放页,手机/电脑直接打开 |
作品名.json |
1 KB | 本次参数报告 |
原图.<ext> |
原图大小 | 原图副本(随产物留档,方便重出 / 对照) |
注意:SVG 和 HTML 都很大,别用 GitHub 网页界面直接打开(会卡)。 下载到本地再打开。
- 离散回放——每帧直接跳变,没有任何补间动画,贴合绘画录像的观感
- 图片描述——
--desc写入一段画面描述,收在顶栏右上角:不点击只显示一行,点击展开可读全文、可自由编辑(改动存在本机浏览器,不写回文件) - 播放 / 暂停 / 重播 / 0.5–4× 倍速 / 进度条拖动
- 真线稿层——从原图 Canny 边缘提取并追踪成有序折线,用描边画出来(不是填充色块)
- 宽屏并排——窗口 ≥800px 且视口为横向(宽高比 ≥1)时自动分左右两栏(需先打开「对照」):左边绘制中、右边同步原图(左栏是纯 SVG,不会再叠一层原图)
- 两栏各自缩放 / 拖动——双栏下滚轮与拖动只作用于鼠标所在的那一栏,两栏互不影响,可以单独把原图放大看细节。底部
+−作用于最后操作过的那一栏,⤢与1:1是全局动作、两栏一起归位 - 对照原图——窄屏单栏时拖动分界线控制原图露出多少:手指按下即定位,鼠标要按住拖动才移动(悬停不会再带着它跑)
- PC 适配——hover 反馈、键盘快捷键(
空格←→HomeEndF)、双击缩放(全屏用F键或「全屏」按钮) - 全屏预览——CSS 伪全屏(藏起页头页脚让画面占满);嵌在网页版预览框里时,全屏请求会转交外层打开真正的全屏层,Android WebView 也能用
- 缩放——滚轮 / 双指捏合 /
+−按钮缩放(最高 24×),放大后拖动平移, 双击画面在 1× ⇄ 2.5× 间切换,0适应窗口、1实际大小。 放大是相册手感:图片在整个视口里缩放,放大后铺满屏幕、拖看细节; 实现上只给画面容器套 CSStransform,不重绘,所以放到 2400% 也不掉帧
skill/ 是上游 skill 的副本(SKILL.md 末尾追加了一节本地扩展说明)+ 本项目的 SVG 扩展,可以直接丢给 AI 助手用:
# Claude Code
cp -r skill ~/.claude/skills/image-to-css-art
# 通用 skills 目录
cp -r skill ~/.agents/skills/image-to-css-art装好后,你说「把这张图转成 SVG」,助手就会读到 skill/SKILL.md 和
AGENTS.md 里的规则,按既定流程执行。
两个产物形态怎么选
需求 用什么 纯 HTML + CSS、有资源限制(禁 img/svg/script/base64/外链) 上游原版 skill/scripts/image_to_css.py要矢量 .svg文件、或想看绘制过程回放本项目 tools/make_art.py
| 作品 | 尺寸 | 形状数 | 线稿笔 | SVG | HTML | SSIM |
|---|---|---|---|---|---|---|
| 海边人像 | 1440×2162 | 182,640 | 2,310 | 46.9 MB | 12.9 MB | 0.9434 |
| 走廊人像 | 1440×2012 | 172,071 | 1,527 | 31.1 MB | 12.7 MB | 0.9154 |
| 夜景人像 | 1440×1912 | 13,255 | — | 4.1 MB | 4.8 MB | 前景 MAE 0.386 |
| 动漫三人组 | 1667×943 | 25,729 | — | 7.0 MB | 8.5 MB | — |
体积按 MiB 计(1 MiB = 1,048,576 字节)。
保真度天花板:照片纹理矢量化之后必然变成色块,SSIM 大约卡在 0.92~0.94, 结构越"硬"、线条越多的图越低。想更接近照片只能堆笔数/分辨率,换不来「照片感」。
- 纯矢量输出:
<path fill=… fill-rule="evenodd">+ 局部拟合的linearGradient, 没有位图、没有 base64 图片、没有外部依赖 - 色块同色描边:每个色块补同色
stroke(stroke-width0.6),糊住轮廓简化留下的发丝缝、 消掉白点;SVG 与 Canvas 两侧保持一致 - Canvas 回放:DOM 里只有 1 个
<canvas>,笔数据打包成二进制(TypedArray 零拷贝), 逐帧增量绘制。18 万笔也能在手机上流畅播放 - 时间轴按视觉重量分配:色块按 bbox 面积计重,线稿按 √面积(≈线长)计重—— 起稿快、铺色慢,各按各的节奏;累计权重表 + 二分查找做「时间 ↔ 笔序号」双向映射
- 大色块扫描线切分:画面 75% 的面积在前 1.94% 的笔里铺完, 所以大色块会被切成横条,像大笔刷一横条一横条刷上去
- 底板固定纸白,且一笔不省:整幅画都在
#f0f0f0的白纸上逐笔画成——起笔是一张纸, 画满才成图。没有「和底色相近就整簇跳过」的省笔,每一块都实打实画出来; 底板同时是 SVG 底板 rect 与回放页背景的来源,两边永远同源 - 零外部依赖的网页:不加载任何框架、字体、CDN
| 文件 | 内容 |
|---|---|
ATTRIBUTION.md |
出处、上游项目、许可 |
docs/原理与流程.md |
整条流水线怎么走的、数据格式、关键设计 |
docs/参数速查.md |
每个参数怎么选、不同图类型的经验值 |
docs/踩坑记录.md |
23 个真实踩过的坑及修法 + 防线索引(改代码前必读) |
docs/历史升级机制.md |
网页版历史作品怎么升级(版本戳 + 迁移链 + 黄金样本测试) |
AGENTS.md |
给 AI 助手的操作规则(让它直接照做) |
SETUP.md |
换设备 / 换系统的详细安装步骤 |
photo-to-svg/
├── install.sh 一键安装
├── requirements.txt
├── skill/ ★ 上游 skill 副本(MIT,仅 SKILL.md 末尾追加一节本地扩展)+ 本项目 extras
│ ├── SKILL.md
│ ├── LICENSE 上游 MIT 许可(分发时请保留)
│ ├── scripts/ 上游原版:CSS clip-path 输出
│ ├── references/ 上游参数调优文档
│ └── extras/ ★ 本项目新增:SVG 输出 + Canvas 回放页 + 保真度校验
├── tools/ ★ 本项目新增:完整流水线
│ ├── make_art.py 入口(串联全流程 + 尺寸自检)
│ ├── build_svg_art.py 描摹核心(与 skill/extras/ 同一份)
│ ├── svg2canvas.py SVG → Canvas 回放页(与 skill/extras/ 同一份)
│ ├── verify_svg.py 保真度校验(与 skill/extras/ 同一份)
│ ├── smoke_test.py 一条命令自检(依赖/语法/同步/常量/升级测试/实跑+底板)
│ ├── secret_scan.py 推送前密钥自检
│ ├── test_upgrade.js 历史升级的黄金样本测试(node)
│ ├── make_upgrade_fixtures.py 从 git 历史重造黄金样本(五个代表世代)
│ └── shot_web.py 更新 README 界面截图(需 playwright)
├── web/ ★ 网页版(GitHub Pages)
│ ├── index.html 界面
│ ├── worker.js Web Worker:加载 Pyodide、跑流水线
│ ├── upgrade.js 历史回放页升级库(版本戳 + 迁移链,纯函数、可单测)
│ └── web_run.py 浏览器端驱动(不走 subprocess,直接调模块)
├── tests/fixtures/ 五个代表世代的回放页样本(给升级测试用)
├── docs/ 文档
├── examples/ 示例图
├── .github/workflows/ 发布网页版到 Pages
└── output/ 产物(已 gitignore)
- AvroraCL/image-to-css-art —— 算法管线与 skill 本体,MIT 许可
- 本项目的 SVG 输出、Canvas 回放页、时间轴设计、以及那 23 条踩坑记录,都是在它之上做的
MIT。skill/ 下的上游代码版权归 AvroraCL(见 skill/LICENSE),分发时请保留该文件。


