Skip to content

About

照片 → 纯 SVG 矢量插画 + 逐笔绘制回放页。在线直接用(浏览器内跑,图片不上传):拖张图进去就能下载 SVG 和回放网页。真线稿层、视觉重量时间轴、Canvas 渲染,18 万笔也能在手机上流畅播放。

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

photo-to-svg

photo-to-svg logo

把一张照片变成逐笔绘制的 SVG 矢量插画,并生成一个能回放整个作画过程的网页。

拖一张图进去就出 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 反馈、键盘快捷键(空格 ← → Home End F)、双击缩放(全屏用 F 键或「全屏」按钮)
  • 全屏预览——CSS 伪全屏(藏起页头页脚让画面占满);嵌在网页版预览框里时,全屏请求会转交外层打开真正的全屏层,Android WebView 也能用
  • 缩放——滚轮 / 双指捏合 / + − 按钮缩放(最高 24×),放大后拖动平移, 双击画面在 1× ⇄ 2.5× 间切换,0 适应窗口、1 实际大小。 放大是相册手感:图片在整个视口里缩放,放大后铺满屏幕、拖看细节; 实现上只给画面容器套 CSS transform,不重绘,所以放到 2400% 也不掉帧

装成 Agent Skill(可选)

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-width 0.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),分发时请保留该文件。

About

照片 → 纯 SVG 矢量插画 + 逐笔绘制回放页。在线直接用(浏览器内跑,图片不上传):拖张图进去就能下载 SVG 和回放网页。真线稿层、视觉重量时间轴、Canvas 渲染,18 万笔也能在手机上流畅播放。

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

⌂ 换网址