tanzhouhu / pdf-figure-vector

# pdf-figure-vector
2026.10.20下午16点更新。
把学术 PDF 里的 Figure 原样复刻成**自包含矢量 SVG**和**可编辑 PPTX**；
也可以把独立 PNG/JPG/WebP 图片自动描摹成矢量 SVG 和原生自由形状 PPTX。
这个仓库同时是一个 Claude Code/Codex/豆包 Skill。作为
Codex Skill 放到 `~/.codex/skills/pdf-figure-vector/`，或作为 Claude Code Skill 放到
`~/.claude/skills/pdf-figure-vector/` 后，直接说「把这篇 PDF 的图 2 转成矢量图」即可，skill在运行过程中会自动跳转到浏览器展示绘制过程。
对于WorkBuddy或其他 agent，目前没有测试和适配，能否使用取决于它是否支持 SKILL.md；不过脚本本身是可用的，所以建议作为可调用 Python 工具箱使用。
演示视频展示的是分别用Codex/Claude code 接入 deepseek v4.1 flash 的效果，token消耗非常少，速度也比较快，因此具有极高的性价比。
建议在转换前查看一下pdf的插图是否是矢量图（把pdf放大看如果清晰度没变化就是矢量图），由于模型的输出质量取决于识别时的清晰度，因此矢量图的转换质量高于其它类型的图片，且消耗的token非常少。
最后希望大家觉得好用的话顺便点点star。大家也可以在评论区提一些意见，后续我将持续维护更新。
## 演示
点击观看抖音演示视频
## 特点
- **逐元素重建**：按 PDF 原始绘制顺序输出路径、文字、位图，z-order 正确
- **独立图片转矢量**：PNG/JPG/WebP/BMP/TIFF 用 VTracer 输出 SVG 和可编辑 PPTX
- **实时预览**：`--live` 边画边写 SVG，自动起本地服务并在 VS Code 集成浏览器（或默认浏览器）中打开
- **字体内嵌**：从 PDF 抽取字体子集，补齐 cmap / OS/2 后在 Chrome 与 SVG 中正常显示
- **位图处理**：带蒙版（SMask）、色键图标、转置图自动走高倍渲染裁切
- **位图自动识别**：`probe.py --bbox` 判断图是原生矢量还是位图；位图会提示改走手工重绘，不会把一张图片冒充成矢量
- **逐像素验收**：Chrome 截图与 PDF 渲染对比，输出 MAE 与左右对照图
- **PPTX 可编辑**：文字/形状/图片分别生成，自动校验是否为整张位图贴图
- **自动清理**：生成结束后删掉 `assets/`、`fonts/`、诊断 PNG、调参脚本等中间产物，只留成品
- **跨 agent**：Claude Code、Codex CLI、普通终端、SSH/headless 都能跑；预览按环境自动降级
## 环境要求
- Python 3.9+
- 依赖见 `requirements.txt`
- 独立图片描摹依赖 `vtracer`
- 对比功能需要 Google Chrome（Windows / macOS / Linux）
- VS Code 自动预览（可选）：
 - Windows + PowerShell
 - VS Code 1.141+（`Open Integrated Browser`），或带 `Simple Browser` 的旧版
 - 无法自动操作 VS Code 时会退回默认浏览器，不影响使用
- 其它 agent / 环境：Codex CLI、普通终端、macOS/Linux 有 GUI → 默认浏览器；
 SSH / headless → 只打印 URL（可 `ssh -L 转发`）。也可用 `PDFVEC_PREVIEW=vscode|browser|none`
 强制指定，见下文「预览方式」
## 安装
 [code] 
作为 Skill 使用：
 [code] 
## 独立 PNG/JPG 转换
 [code] 
预设：
- `diagram`：框架图、流程图、论文示意图，保留彩色细节
- `logo`：黑白 logo、线稿、单色图标
- `photo`：照片近似描摹，路径较多
小字图片可使用 `--scale 2`；透明 PNG 使用 `--background transparent`。
默认会生成 `out/Figure1/_qa/_side.png` 和 `_diff.png` 做视觉对比。
输出文字会转成路径，不能在 SVG 中直接修改文字。
默认同时生成 `Figure1.pptx`。它由 PowerPoint 原生自由形状组成，不嵌入
整张位图。加 `--pptx-qa` 可渲染 PPTX 并生成 `_ppt_side.png` 与 `_ppt_diff.png`。
## 快速开始
所有命令假设当前目录是 skill 根目录（`scripts/` 的上一级）。
1. 探查页面，确认图在哪一页：
 [code] 
算出 bbox 后判断这张图是原生矢量还是位图：
 [code] 
提示「位图为主」时不要直接抽取（那只是把图片嵌进去），按 SKILL.md
「图本身是位图时：手工重绘成真矢量」处理。
2. 抽取并生成（`--live` 会边画边预览）：
 [code] 
3. 与 PDF 逐像素比对：
 [code] 
4. 检查 PPTX 是否真的是矢量（正常会在生成后自动执行）：
 [code] 
## 参数说明
`extract_figure.py`：
| 参数 | 说明 |
| --- | --- |
| `--pdf` | PDF 路径 |
| `--page` | 页索引，**0 起** |
| `--bbox` | 图像区域 `x0,y0,x1,y1`（PDF point） |
| `--out` | 输出目录 |
| `--name` | 输出文件名（不含扩展名） |
| `--width` | SVG 画布宽度，默认 1948 |
| `--live` | 边生成边写 SVG 并自动打开预览 |
| `--no-preview` | 配合 `--live`，只画不开预览窗口 |
| `--live-every` | 每 N 个元素写一次，默认 1 |
| `--no-pptx` | 只出 SVG |
| `--no-open` | 生成后不自动弹出 PowerPoint |
| `--no-clean` | 保留中间产物 |
`trace_image.py`：
| 参数 | 说明 |
| --- | --- |
| `--image` | PNG/JPG/JPEG/WebP/BMP/TIFF 输入 |
| `--out` | 输出目录 |
| `--name` | 输出 SVG 文件名（不含扩展名） |
| `--preset` | `diagram`、`logo` 或 `photo`，默认 `diagram` |
| `--scale` | 描摹前放大倍数；默认 `0