# img2ppt-lite

**把一张 PPT 效果图（PNG/JPG）还原成高保真、可编辑的 PPTX。**

Turn a slide mockup image (e.g. generated by GPT-image / Midjourney / any design tool) into an editable PowerPoint file: native text boxes + semantically-split draggable sprites + inpainted clean background. Built as an agent skill — the executing AI (Claude Code / Codex / any CLI agent with vision) acts as the VLM, deterministic Python scripts do everything else.


*左：合成样张源图 · 右：管线重建后由 PowerPoint 渲染回的图（文字全部为原生可编辑文本框，图表/图标为独立贴图）*

## 它解决什么问题

AI 出图工具能生成非常漂亮的 PPT 效果图，但那只是一张图片。想拿它当真正的工作底稿，你需要：

- **文字可编辑**——改标题、改数据是最高频操作； - **元素可拖拽**——每个图标、图表、色块都是独立对象，能单独移动缩放； - **视觉尽量 1:1**——还原完的页面和效果图肉眼几乎一致。

传统"图转 PPT"路线要么把整页塞成一张图（完全不可编辑），要么全原生重建（图标丑、收敛循环极慢）。img2ppt-lite 走中间路线，并把速度做到了**单页 3-5 分钟**（脚本部分约 40-60 秒）。

## 核心设计

``` 可编辑 PPTX = 干净底图 (inpaint 去前景) + 语义元素贴图 (每个图标/图表一张独立 picture，可拖拽) + 原生文本框 (PIL 墨水高度反解字号，可编辑) + 纯色矩形原生化 (KPI 条/按钮/色块 → 可改色的原生 shape) ```

三个反直觉的关键决策：

1. **视觉一致性的最大敌人恰恰是"原生重建"。** 从原图裁出来的贴图天然 100% 一致；会漂的只有文本层——而文本字号可以用 PIL 按墨水高度离线反解，**不需要"渲染→对比→调整"的收敛循环**。这是比前代管线快一个量级的根本原因。 2. **执行 agent 自身就是 VLM。** 不调外部视觉 API：agent 看图产出一份 `elements.json`（文本/色块/图形的语义标注），脚本吃 JSON 确定性完成其余一切。LLM 参与固定 2 次（标注 + 终检），零额外 token 成本。 3. **测量代替猜测。** 字号、文字颜色、卡片填充色、渐变、行首 marker 全部从像素实测，agent 只负责语义；每个测量器都经过阳性+阴性用例双验。

## 环境要求

- Windows（PowerPoint COM 用于渲染回读验证；**没有 PowerPoint 也能出 PPTX**，只是跳过渲染验证） - Python 3.10+

```bash pip install -r requirements.txt ```

装好后先跑自检（生成合成样张走全链路，含 marker 正/负回归用例）：

```bash python scripts/pipeline.py --selftest ```

## 使用方式

### 作为 agent skill（推荐）

把本仓库放进你的 agent skill 目录（如 Claude Code 的 `~/.claude/skills/img2ppt-lite/`），agent 会按 `SKILL.md` 的 5 步工作流执行：

``` 1. pipeline.py --run <run> --seed # OCR 冷启动，产出待审阅的文本骨架 2. [agent 看图] 校对 seed、补图形/色块标注 → elements.json 3. pipeline.py --run <run> # OCR校准 → 切图 → 装配 → COM 渲染验收 4. [agent 看图] 对比 compare.png，必要时改 JSON 秒级重跑 5. 交付 pptx + 验收报告（修补硬上限 2 轮，禁无限迭代） ```

### 手动使用

不用 agent 也可以：