# pdf2pptx

**Repository Path**: zdsiyan/pdf2pptx

## Basic Information

- **Project Name**: pdf2pptx
- **Description**: pdf文件还原回PPT的skill，感觉wps的不太好用，就vc了一个。测试过能解决大部分问题。对于很复杂的页面还是无法还原，需要一定手动操作辅助。
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-22
- **Last Updated**: 2026-09-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# pdf2pptx — PDF 矢量级还原为可编辑 PPTX

把一个「由 PowerPoint 导出的 PDF」尽可能无损地还原成**可编辑**的 `.pptx` 文件。
与 WPS / MinerU 等 OCR 方案不同，本工具直接读取 PDF 内部对象（文字 span、嵌入图片、矢量路径），
按原始几何坐标重建 PPT 元素，因此文字、图片、形状的位置与字体字号都和原文一致，且全部可编辑。

> 适用对象：**含文字层与矢量对象的 PDF**（如 PPT 导出的 PDF）。
> 不适用：**扫描件 / 纯图片型 PDF**（无文字层，无法还原出可编辑文字，应使用 OCR 工具）。

## 目录结构

```
README.md             # 使用文档（本文件）
├── SKILL.md              # 给 AI（CodeBuddy）看的能力说明与调用指引
└── scripts/
    └── pdf2pptx.py       # 转换脚本（核心实现，可独立运行）
```

## 环境依赖

```bash
pip install pymupdf python-pptx Pillow
```

| 包 | 用途 |
|----|------|
| `pymupdf` | 读取 PDF 内部对象与页面几何坐标 |
| `python-pptx` | 生成可编辑的 PPTX |
| `Pillow` | 解码 / 裁剪 / 合成图片 alpha（按需懒加载，仅在遇到图片时使用） |

## 快速开始

```bash
# 基本用法：PDF -> PPTX
python scripts/pdf2pptx.py input.pdf output.pptx

# 只还原指定页（逗号分隔，支持区间）
python scripts/pdf2pptx.py input.pdf output.pptx --pages 1,2,3-5

# 静默模式（不打印逐页进度）
python scripts/pdf2pptx.py input.pdf output.pptx --quiet
```

转换完成后会打印每页的「文本框 / 图片 / 矢量图形 / 跳过」数量，便于核查还原质量。

## 参数说明

| 参数 | 说明 |
|------|------|
| `input.pdf` | 源 PDF 路径（必填） |
| `output.pptx` | 输出 PPTX 路径（必填） |
| `--metrics <path>` | 字体度量标定 json，覆盖内置默认度量。不指定时自动查找「脚本同目录」或「当前工作目录」下的 `font_metrics.json` |
| `--pages <list>` | 仅转换指定页，如 `1,3,5-8` |
| `--quiet` | 关闭逐页进度输出 |

## 工作原理（简述）

1. 用 `pymupdf.open` 打开 PDF，以第 0 页尺寸作为幻灯片画布尺寸；
2. 逐页构建元素：
   - **文字**：`get_text('dict')` 取出文字 span，按视觉行聚类成文本框，保持 PDF 中的断行，不重排；
   - **图片**：解码并合成 SMask alpha，按变换矩阵与可见区域裁切，导出 PNG 后内嵌为 `add_picture`；
   - **矢量图形**：贝塞尔曲线折线化后重建为可编辑自由形状，还原填充 / 描边 / 透明度 / 虚线；
   - **渐变**：PDF 的 shading pattern 可还原为 PPT 原生 `gradFill`（见下方限制）；
3. 用内容流 `bboxlog` 顺序决定图片 / 图形的层级（z-order），文字最后绘制置于最上层；
4. `prs.save(output.pptx)` 写出。

## 已知限制与调优

- **仅处理水平文本**：旋转 / 竖排文本会被跳过。
- **径向渐变默认跳过**：`ENABLE_SHADING = False`。径向渐变（如玻璃高光）在 PPT 中难以等比还原，
  画错比跳过更糟。需要时可把 `scripts/pdf2pptx.py` 顶部的 `ENABLE_SHADING` 改为 `True`，
  此时仅轴向渐变会被还原。
- **字体度量**：常用中英文体的首行基线与行距经验值内置在 `DEFAULT_METRICS` 中。
  若某字体还原后行位明显偏移，可用标定脚本产出 `font_metrics.json` 经 `--metrics` 覆盖。
- **超大纯白背景块**：面积接近整页的白色填充会被跳过（PDF 页面本身已有白底），避免无意义元素。
- **图片资产**：还原过程图片以临时 PNG 写出，脚本结束随临时目录自动清理；最终 PPTX 已内嵌图片，
  无需保留临时文件。

## 常见问题

**Q：转换后文字能直接改吗？**
能。所有文本框都是原生 PPT 文本对象，点击即可编辑。

**Q：为什么有些形状位置有点偏？**
多为字体度量（基线/行距）偏差导致。提供对应字体的 `font_metrics.json` 即可修正。

**Q：扫描件转出来全是图片？**
本工具针对矢量 PDF 设计。扫描件请用 OCR 工具（如 MinerU / WPS）先识别文字层。

**Q：如何只验证某一页效果？**
用 `--pages` 只转换单页，例如 `python scripts/pdf2pptx.py in.pdf out.pptx --pages 3`。