PDF 转 PPT 转换技能

该技能通过先将 PDF 文件的每一页渲染为高质量图像，再将这些图像逐页组装成 PowerPoint 演示文稿（每张图像填满一张幻灯片），实现 PDF 到 PPT 的转换。此方法适用于以视觉内容为主的 PDF（例如设计图纸、扫描成 PDF 的演示文稿等），并能忠实地保留原始视觉排版。

适用场景

当您需要满足以下任一需求时，可使用本技能：

• 将 PDF 文档转换为可编辑的 PowerPoint 演示文稿。
• 将 PDF 每一页的完整视觉布局（包括文字、图像、矢量图形）精确保留为幻灯片背景。
• 处理难以通过直接文本提取进行编辑的 PDF（例如复杂排版、设计师源文件等）。
• 批量将多个 PDF 文件转换为 PPT 格式。

核心规则

1. 输入 PDF 要求

• 为获得最佳效果，PDF 应为基于文本或基于矢量的格式；扫描型 PDF 将被整体转为图像（本技能仍完全支持该情形）。
• 请确保 PDF 未设置密码保护；若 PDF 受密码保护且工具支持，请通过环境变量提供密码。

2. 图像渲染质量

• 本技能使用可配置的缩放因子（默认值为 2.0，即在原始 72 DPI 基础上输出约 144 DPI）将 PDF 页面渲染为图像。
• 更高的缩放值可提升图像质量与文件体积，并增强生成 PPT 中文字的可读性。
• 若 PDF 文字密集，且您需要在 PPT 中保留可选中文本，请考虑改用直接 PDF→PPT 转换工具（如 LibreOffice）。

3. 输出 PPT 特性

• PDF 的每一页对应生成 PPT 的一张幻灯片。
• 幻灯片尺寸默认为 16:9（宽度 = 13.33 英寸，高度 = 7.5 英寸），但支持自定义。
• 图像将被拉伸以完全填充幻灯片区域；不锁定宽高比（以确保全覆盖）。若需严格保持原始宽高比，请修改脚本，改为居中并裁剪图像。
• 生成的 PPT 使用空白版式，每张幻灯片中将图像作为覆盖全屏的形状插入。

4. 依赖项

• Python 包：PyMuPDF（即 fitz）和 python-pptx。
• 首次使用本技能时，可通过提供的安装命令自动安装上述依赖；您也可手动安装。

安装

将技能文件复制到您的 skills 文件夹后，可使用以下命令从本地路径安装：

clawhub install /path/to/pdf-to-ppt

若您已克隆该技能仓库，则可运行：

clawhub install pdf-to-ppt

使用方法

基础转换

python3 scripts/pdf_to_ppt.py input.pdf

该命令将执行以下操作：

• 在输入 PDF 所在目录下创建 images/ 子目录（或使用指定目录）。
• 将 PDF 的每一页渲染为 PNG 图像并保存至该目录。
• 在输入 PDF 所在目录下生成同名 PPTX 文件（即在原文件名后追加 .pptx）。

高级选项

python3 scripts/pdf_to_ppt.py input.pdf 
    --img-dir /path/to/images 
    --output output.pptx 
    --zoom 3.0 
    --slide-width-in 16 
    --slide-height-in 9 
    --format png

参数说明：

• input.pdf：源 PDF 文件路径（必填）。
• --img-dir DIR：用于存放中间图像的目录；若未指定，默认为 /images/。
• --output PPTX：输出 PPTX 文件路径；若未指定，默认为与输入 PDF 同目录下的 .pptx。
• --zoom ZOOM：渲染缩放因子（默认 2.0），数值越大，DPI 越高。
• --slide-width-in INCHES：幻灯片宽度（单位：英寸；默认 13.33，对应 16:9 宽高比下高度为 7.5 英寸）。
• --slide-height-in INCHES：幻灯片高度（单位：英寸；默认 7.5）。
• --format {png,jpg}：中间图像格式（默认 png）。

示例：使用自定义设置进行转换

python3 scripts/pdf_to_ppt.py report.pdf 
    --img-dir ./tmp/imgs 
    --output ./presentation.pptx 
    --zoom 2.5 
    --format jpg

工作流提示

1. 检查图像质量：转换完成后，在 PowerPoint 中打开生成的 PPT 并抽查若干幻灯片。若文字模糊，可增大 --zoom 值。
2. 文件大小：更高的缩放倍率及 PNG 格式会同时增加中间图像与最终 PPT 的体积。如可接受轻微压缩伪影，建议选用 JPG 格式以减小文件体积。
3. 后期处理：生成的 PPT 在 PowerPoint 中完全可编辑，您可执行以下操作：
   • 在图像背景之上添加文本框、形状或批注。
   • 按需替换为更高清的图像版本。
   • 如需单独提取某张图像，可通过“另存为图片”功能导出。
4. 批量处理：可通过 shell 循环对多个 PDF 执行转换：

   for pdf in *.pdf; do
       python3 scripts/pdf_to_ppt.py "$pdf"
   done
   

故障排查

• 报错 ModuleNotFoundError：fitz 或 pptx 模块未找到：请确认依赖已正确安装。运行以下命令：

  pip install --break-system-packages PyMuPDF python-pptx
  

  （若在受限环境中使用系统 Python，请添加 --break-system-packages 参数。）
• 生成图像为空白：请确认 PDF 文件非空，且 PyMuPDF 可正常打开该文件。建议先用 PDF 阅读器打开验证其是否包含有效内容。
• 内存不足：对于页数极多或缩放倍率极高的 PDF，可能消耗大量内存。建议分批处理，或降低 --zoom 值。

相关技能

建议结合以下技能协同使用：

• pdf-tools —— 在转换前对 PDF 进行文本提取、合并或拆分。
• powerpoint-pptx —— 获取编辑与美化生成 PPT 的最佳实践指南。
• images —— 若需对中间图像进一步处理（如批量调整、增强等）。

反馈

如果您觉得本技能有用，欢迎在 ClawHub 上为其点亮 Star：clawhub star pdf-to-ppt

如遇问题或希望提出功能增强建议，请参考该技能的源代码仓库。

本技能旨在为富含视觉元素的文档自动化完成 PDF → 图像 → PPT 的转换流程。