图片转可编辑 PPT

技能文档

---
name: image-to-editable-pptx
title: 图片转可编辑 PPT
category: 办公效率
description: 把上传的图片（PPT 截图、设计稿、海报、信息图、图表页、扫描件版式）逐像素重建为完全可编辑的 PowerPoint 文件——文字是文本框、卡片按钮是自选图形、图标是自由多边形、表格是原生表格，颜色取自像素采样、版式按像素测量，并用渲染对比验证一致性。适合图片转 PPT、截图还原、设计稿转可编辑文件场景。触发词：图片转PPT、截图转PPT、还原设计稿、可编辑幻灯片、海报文字可编辑。不做内容创作（帮我做一页讲 XX 的 PPT）和格式转换（PDF/Word 转 PPT）。
---

# 图片转可编辑 PPTX

把**已经设计好的静态图片**还原成**可编辑的** PPTX。
核心是「还原」——版式、颜色、图标都尽量不走样，同时让每一个元素都能在
PowerPoint / WPS 里直接改。

## 什么时候用 / 什么时候别用

**✅ 用**：手上有一张确定的图，希望它变成能改的 PPT，样子尽量不变。
典型说法：「图片转 PPT」「这张截图能编辑吗」「还原这张设计稿」
「这页 PPT 只有图，我要能改文字」「按这张海报做一份可编辑的」。

**❌ 别用**（直接说明原因，别硬做）：

| 用户其实想要 | 该走什么 |
|---|---|
| 「帮我做一页讲季度业绩的 PPT」 | 内容创作，直接按需求做 |
| 「把 PDF / Word 转成 PPT」 | 格式转换工具 |
| 「这张图帮我美化一下」 | 设计类工具（本技能的原则恰是**不改**原设计） |
| 「把图里的字识别出来」 | OCR（只要文字，不要版式） |

完整判定树与预期管理见 [references/boundaries.md](references/boundaries.md)。

## 快速开始

```bash
python scripts/doctor.py                       # 0. 自检环境（没 Office 也能用）
python scripts/measure.py info IMG             # 1. 图片尺寸 → layout.json 的 slide 段
python scripts/measure.py grid IMG -o g.png    # 2. 出网格图，目视定位
python scripts/measure.py ink IMG --x .. --y .. --x2 .. --y2 ..   # 3. 量精确外框
python scripts/pick_color.py IMG --mode dominant --x .. --y .. --w .. --h ..  # 4. 实测颜色
# 5. 写 layout.json
python scripts/build_ppt.py layout.json --check            # 6. 先体检
python scripts/build_ppt.py layout.json -o output/deck.pptx # 7. 生成
python scripts/preview_offscreen.py layout.json \
    -o output/preview.png --reference IMG                  # 8. 校验 + 迭代
```

逐个命令的说明、输出样例、迭代技巧：
[references/quickstart.md](references/quickstart.md)（3 分钟跑通第一张图）

## 五条硬规则（不可协商）

1. **禁止整图嵌入。** 不能做背景，不能铺满整页，**单张图片必须 < 15% 版面**。
   `build_ppt.py` 会拦截；这条规则的例外 = 无。真正的转换不是"把图贴进去"。
2. **1:1 保真。** 文字用词、颜色、位置、图标形状、线宽都要与原图一致。
   **不重新设计、不重新排版、不"顺手优化"。** 颜色必须像素采样，坐标必须像素测量。
3. **原生对象优先。** 文字→`text`；卡片/按钮/色块→`shape`；
   图标/箭头/徽标→`freeform`（顶点多边形，可拖点改形）；线→`line`；表格→`table`。
   **只有照片级 / 有机曲线的复杂插画**才允许贴小图，且单张 < 15%。
4. **交付前必须跑校验。** 至少一轮。没有 Office 就用 `preview_offscreen.py`
   （纯 Pillow，不需要 Office），不能跳过。
5. **文本框绝不自动缩放。** `build_ppt.py` 对所有文本框写入 `noAutofit`。
   多行文本要给足 `h`：`h ≥ 行数 × size_pt × 1.2 ÷ 72 × 每英寸像素数`。
   这是「在 LibreOffice 里正常、到 PowerPoint 就错位」的头号原因。

## 技能工作流

### 步骤0：自检
```bash
python scripts/doctor.py
```
确认 Python ≥ 3.8、`python-pptx`、`pillow` 就位。
没有 PowerPoint / WPS / LibreOffice **不影响使用**，校验会走离屏渲染。

### 步骤1：像素级清点
用 `measure.py` 量，不要凭肉眼估：

- `info` → 图片尺寸，写进 `slide.width_px / height_px`
- `grid` → 带坐标网格图，快速目视定位
- `ink` → 任意区域的精确墨迹外框（文字块、卡片、图标都能用）
- `rows` / `cols` → 一次看清整块区域的行列结构，**重复单元只精测一个，其余平移**
- `bands` → 纵向色带变化点，用来找分层背景
- `pick_color.py --mode dominant/avg/point` → 实测颜色

背景一律用原生矩形 + 填充/渐变重建，**绝不使用原图**。

### 步骤2：复杂插画才裁剪
能用 `shape` / `freeform` 重画的，一律原生。只有照片级 / 立体插画 / 有机曲线才裁图：

```bash
python scripts/crop_assets.py IMG --x .. --y .. --w .. --h .. --out a.png --bbox   # 先预览
python scripts/crop_assets.py IMG --x .. --y .. --w .. --h .. --out a.png \
    --transparent --bg auto --tolerance 30
python scripts/extract_icons.py IMG OUT_DIR icons.json     # 批量（中心 + 半径）
```

裁剪要贴边不留白；单张 < 15%；平坦背景优先出透明 PNG。
`--bbox` 会提示是否切到图标边缘，`extract_icons.py` 会自动列出可疑图标。

### 步骤3：写 layout.json
从 `assets/layout_template.json` 起手。完整字段说明：
[references/layout-guide.md](references/layout-guide.md)。

要点：坐标用**原图像素**（左上角原点）；元素按数组顺序叠放
（背景 → 卡片 → 图标 → 文字）；自定义图标用 `freeform` 顶点列表。

### 步骤4：先体检，再构建
```bash
python scripts/build_ppt.py layout.json --check            # 一次性列出全部问题
python scripts/build_ppt.py layout.json -o output/deck.pptx
```
体检会把所有问题**一次列全**（不是报一个改一个），并给出可操作的修改建议。
`--report r.json` 可把结果写成 JSON。

### 步骤5：校验与迭代
```bash
# 有 Office 时（最精确）
python scripts/render_compare.py output/deck.pptx --reference IMG --out-dir output/verify

# 没有 Office 时（纯 Pillow，不需要 Office）
python scripts/preview_offscreen.py layout.json -o output/preview.png --reference IMG
```

| `rms_diff` | 判定 |
|---|---|
| `< 0.06` | 很好 |
| `< 0.12` | 可接受（多因中文字形差异） |
| `> 0.12` | 需要修 |

**`rms_diff` 是整体指标，必须同时看上下拼图。** 重点核对：位置漂移、尺寸不符、
颜色偏差、图标缺失或变形、文字溢出、层级关系。

想精确定位字号问题，用 `--blocks` 做文字块级量化比对：

```bash
python scripts/preview_offscreen.py layout.json -o p.png --reference IMG --blocks blocks.json
# 文字块          原图宽  预览宽    Δ宽    Δ高  建议
# 主标题            937    944     +7     -5  OK
# 数值              164    131    -33     -6  size_pt × 1.252
```

Δ宽为负 = 字号偏小，按「建议」系数乘当前 `size_pt`，重建再校验。
**通常 1~2 轮收敛到 ±5px。** 实测复杂信息图案例一轮收敛。

文本块**允许**越界重叠（宽文本框的 advance 会伸到下一个框），只看**墨迹**是否打架。

### 步骤6：交付
交付 `.pptx` + 原图/重建对照图 + `layout.json`，并说明：

- 元素统计（text / shape / freeform / line / table / 小图）
- `rms_diff` 分数
- **明确告知未嵌入整幅原图**（脚本会自动汇报最大单张图片占比）
- 以图片形式保留的复杂插画清单，及为什么原生重建不可行

提醒用户：所有文本框、形状、自由多边形、表格、线条都能在 PowerPoint / WPS 里直接编辑；
想换数据只需改 `layout.json` 再重建，不用重画。

## 脚本一览

| 脚本 | 用途 |
|---|---|
| `doctor.py` | 环境自检：依赖、脚本完整性、渲染器、中文字体、最小构建演练 |
| `measure.py` | 像素测量：`info / grid / point / avg / dominant / ink / rows / cols / bands / compare` |
| `pick_color.py` | 取色：单点 / 区域均值 / 区域主色 |
| `crop_assets.py` | 单区域裁剪（左上角+宽高），可去背景透明化，`--bbox` 预览 |
| `extract_icons.py` | 批量裁剪图标（中心+半径），自动报告可疑切边 |
| `build_ppt.py` | 布局体检 + 构建 PPTX（`--check` / `--report` / `--quiet`） |
| `render_compare.py` | 有 Office 时渲染并比对（COM → WPS → LibreOffice，含 3 次重试） |
| `preview_offscreen.py` | **无 Office 时的校验方案**：纯 Pillow 离屏渲染 + `rms_diff` + 块级 Δ宽 |
| `selftest.py` | **22 个自动化用例**，端到端自检，可放 CI |

自检与回归：
```bash
python scripts/selftest.py          # 22 个用例：测量精确性、构建、校验、5 个反例、友好报错
```

## 遇到问题

先按现象查 [references/faq.md](references/faq.md)（26 条，按症状索引）。
高频的几条：

- **「`background.mode` 不能是 image」/「图片超过 15%」** → 这是**故意拦住**的，
  说明你想贴的是一块大区域的图。改用 `shape` / `freeform` / `text` 重建。
- **「layout.json 不是合法的 JSON」** → 多为中文引号「”」或多余逗号。
- **「没有可用的渲染器」** → 不是失败，改用 `preview_offscreen.py` 即可。
- **PowerPoint 里文本框自撑压住下方** → 文本框 `h` 给小了，按公式补足，别开自动缩放。
- **图标有彩色光晕** → `--tolerance` 从 30 调到 45~60；内部有白色高光则用 flood fill 抠图。

## 参考文档

| 文档 | 内容 |
|---|---|
| [quickstart.md](references/quickstart.md) | 3 分钟跑通第一张图，含一张全流程速查图 |
| [examples.md](references/examples.md) | 两个真实案例（195 元素信息图 / 带表格图表页），含实测数值与迭代记录 |
| [boundaries.md](references/boundaries.md) | 适用与不适用场景、判定决策树、能做/不做到什么程度 |
| [faq.md](references/faq.md) | 26 条按症状索引的常见问题 |
| [layout-guide.md](references/layout-guide.md) | layout.json 完整字段说明与示例 |

使用说明

# 图片转可编辑 PPT

把已设计好的静态图片逐像素还原为可编辑的 PPTX：文字是文本框、卡片是自选图形、图标是自由多边形、表格是原生表格，颜色像素采样、坐标像素测量，交付前用渲染对比验证一致性（无 Office 也能校验）。

## 使用

```bash
python scripts/doctor.py          # 环境自检
python scripts/measure.py info 图.png          # 量尺寸
python scripts/measure.py grid 图.png -o g.png # 网格定位
python scripts/build_ppt.py layout.json --check # 体检
python scripts/build_ppt.py layout.json -o output/deck.pptx
python scripts/preview_offscreen.py layout.json -o output/preview.png --reference 图.png
```

对话示例：

```text
把这张 PPT 截图还原成可编辑的幻灯片
按这张海报做一份文字能改的版本
```

3 分钟上手见 `references/quickstart.md`，常见问题见 `references/faq.md`。

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。