skill-pdf-to-pptx-tool

convert - 将 PDF 转换为 PowerPoint

将 PDF 文档转换为 PowerPoint 格式，并为每个 PDF 页面创建一张幻灯片；画质设置可自定义。

用法：

pdf-to-pptx-tool convert INPUT_PDF OUTPUT_PPTX [OPTIONS]

参数：

• INPUT_PDF：输入 PDF 文件的路径（必需）
  • 文件必须存在且为有效的 PDF 文件
  • 支持任意 PDF 版本
  • 大小不限（取决于可用内存）
• OUTPUT_PPTX：输出 PowerPoint 文件的路径（必需）
  • 如果文件已存在，则会覆盖；否则会新建
  • 扩展名应为 .pptx
  • 父目录必须存在
• --dpi INTEGER：页面转换分辨率（可选）
  • 默认值：200 DPI（画质良好，文件大小适中）
  • 范围：72–600 DPI
  • DPI 越高，画质越好，但文件越大
  • 建议值：用于演示文稿时为 200–300
• -v, --verbose：多级详细程度
  • 不添加标志：仅显示警告和错误
  • -v：INFO 级别（操作和进度）
  • -vv：DEBUG 级别（详细步骤）
  • -vvv：TRACE 级别（库内部信息）

示例：

# Example 1: Basic conversion (default 200 DPI)
pdf-to-pptx-tool convert quarterly-report.pdf q4-presentation.pptx

# Example 2: High quality for detailed diagrams
pdf-to-pptx-tool convert technical-diagram.pdf slides.pptx --dpi 300

# Example 3: Lower quality for quick preview
pdf-to-pptx-tool convert draft.pdf preview.pptx --dpi 150

# Example 4: With INFO logging to see progress
pdf-to-pptx-tool -v convert large-doc.pdf output.pptx

# Example 5: With DEBUG logging for troubleshooting
pdf-to-pptx-tool -vv convert problematic.pdf fixed.pptx

# Example 6: Batch conversion with shell loop
for pdf in *.pdf; do
  pdf-to-pptx-tool convert "$pdf" "${pdf%.pdf}.pptx"
done

输出：

• 在指定路径创建 PowerPoint 文件
• 幻灯片属性：
  • 宽高比：16:9（宽屏）
  • 尺寸：10" × 5.625"
  • 布局：每个 PDF 页面对应一张铺满幻灯片的图像
  • 背景：透明
• 控制台输出：
  • 成功："✓ Successfully converted input.pdf to output.pptx"
  • 错误："✗ Error: [detailed error message]"
• 退出代码：
  • 0：成功
  • 1：错误（文件不存在、输入无效或转换失败）

completion - 生成 Shell 补全脚本

为 bash、zsh 或 fish Shell 生成 Shell 补全脚本。

用法：

pdf-to-pptx-tool completion SHELL

参数：

• SHELL：Shell 类型（必需）
  • 选项：bash、zsh、fish
  • 不区分大小写

示例：

# Generate bash completion
eval "$(pdf-to-pptx-tool completion bash)"

# Generate zsh completion
eval "$(pdf-to-pptx-tool completion zsh)"

# Generate fish completion
pdf-to-pptx-tool completion fish | source

# Save to file for permanent installation
pdf-to-pptx-tool completion bash > ~/.pdf-to-pptx-tool-completion.bash
echo 'source ~/.pdf-to-pptx-tool-completion.bash' >> ~/.bashrc

输出： 将对应 Shell 的补全脚本打印到 stdout。

该工具支持逐级提高日志详细程度，用于调试和监控转换过程。

日志级别：

示例：

# Quiet mode - only see errors
pdf-to-pptx-tool convert input.pdf output.pptx

# INFO - see conversion progress
pdf-to-pptx-tool -v convert input.pdf output.pptx
# Output:
# [INFO] Starting PDF to PPTX conversion
# [INFO] Converting input.pdf to output.pptx (DPI: 200)
# [INFO] Converting PDF pages to images...
# [INFO] Converted 5 pages
# [INFO] Creating PowerPoint presentation...
# [INFO] Saving presentation to output.pptx

# DEBUG - see detailed processing
pdf-to-pptx-tool -vv convert input.pdf output.pptx
# Additional output:
# [DEBUG] Input: input.pdf, Output: output.pptx, DPI: 200
# [DEBUG] Validating input file: input.pdf
# [DEBUG] Input file size: 2.45 MB
# [DEBUG] Using DPI setting: 200
# [DEBUG] Processing slide 1/5
# [DEBUG] Output file size: 8.23 MB

# TRACE - see library internals
pdf-to-pptx-tool -vvv convert input.pdf output.pptx
# Shows pdf2image, PIL, and pptx library debug messages

DPI 质量指南

根据使用场景选择 DPI：

权衡：

• 较高 DPI：质量更好、文件更大、转换更慢
• 较低 DPI：转换更快、文件更小、质量更低
• 最佳平衡点：大多数演示文稿使用 200-300 DPI

批量处理

高效处理多个 PDF：

# Convert all PDFs in directory
for pdf in *.pdf; do
  echo "Converting $pdf..."
  pdf-to-pptx-tool convert "$pdf" "${pdf%.pdf}.pptx"
done

# With custom DPI
for pdf in *.pdf; do
  pdf-to-pptx-tool convert "$pdf" "${pdf%.pdf}.pptx" --dpi 300
done

# With error handling
for pdf in *.pdf; do
  if pdf-to-pptx-tool -v convert "$pdf" "${pdf%.pdf}.pptx"; then
    echo "✓ Converted $pdf"
  else
    echo "✗ Failed to convert $pdf"
  fi
done

Shell 补全

启用 Tab 补全，加快操作：

# Bash - add to ~/.bashrc
eval "$(pdf-to-pptx-tool completion bash)"

# Zsh - add to ~/.zshrc
eval "$(pdf-to-pptx-tool completion zsh)"

# Fish - save to completions directory
mkdir -p ~/.config/fish/completions
pdf-to-pptx-tool completion fish > ~/.config/fish/completions/pdf-to-pptx-tool.fish

优点：

• 补全命令：pdf-to-pptx-tool <TAB>
• 补全选项：pdf-to-pptx-tool convert --<TAB>
• 自动补全文件路径

常见问题

问题：“poppler not found”或 PDF 转换失败

# Symptom
RuntimeError: Failed to convert PDF pages: poppler not found

解决方案： 安装 poppler 系统库：

# macOS
brew install poppler

# Ubuntu/Debian
sudo apt-get install poppler-utils

# Fedora
sudo dnf install poppler-utils

# Verify installation
pdftoppm -v

问题：“File not found”错误

# Symptom
✗ Error: Input PDF file not found: document.pdf

解决方案：

• 确认文件路径正确
• 必要时使用绝对路径
• 检查文件权限

# Check file exists
ls -l document.pdf

# Use absolute path
pdf-to-pptx-tool convert /full/path/to/document.pdf output.pptx

问题：输出文件过大

# Symptom
Generated 50MB PPTX from 2MB PDF

解决方案： 降低 DPI 设置：

# Try lower DPI
pdf-to-pptx-tool convert input.pdf output.pptx --dpi 150

# Or use default 200 DPI
pdf-to-pptx-tool convert input.pdf output.pptx

问题：PowerPoint 中的图像看起来模糊

# Symptom
Text and diagrams appear pixelated

解决方案： 提高 DPI 设置：

# Use higher quality
pdf-to-pptx-tool convert input.pdf output.pptx --dpi 300

# For print quality
pdf-to-pptx-tool convert input.pdf output.pptx --dpi 600

问题：转换速度非常慢

# Symptom
Large PDF takes minutes to convert

解决方案：

1. 使用 DEBUG 日志查看进度：

pdf-to-pptx-tool -vv convert large.pdf output.pptx

2. 考虑降低 DPI 以加快转换：

pdf-to-pptx-tool convert large.pdf output.pptx --dpi 150

3. 将大型 PDF 拆分成多个部分，分别转换

问题：写入输出文件时权限被拒绝

# Symptom
PermissionError: [Errno 13] Permission denied: 'output.pptx'

解决方案：

• 检查目录写入权限
• 使用其他输出位置

# Write to home directory
pdf-to-pptx-tool convert input.pdf ~/output.pptx

# Or create directory first
mkdir -p output-dir
pdf-to-pptx-tool convert input.pdf output-dir/output.pptx

获取帮助

# Tool help
pdf-to-pptx-tool --help

# Command help
pdf-to-pptx-tool convert --help

# Completion help
pdf-to-pptx-tool completion --help

# Version info
pdf-to-pptx-tool --version

调试工作流

转换失败时，请使用以下调试工作流：

# 1. Check file exists and is readable
ls -lh document.pdf
file document.pdf

# 2. Verify poppler is installed
pdftoppm -v

# 3. Try with DEBUG logging
pdf-to-pptx-tool -vv convert document.pdf test.pptx

# 4. Try with lower DPI if memory issues
pdf-to-pptx-tool -vv convert document.pdf test.pptx --dpi 150

# 5. Check Python and dependencies
python --version
pdf-to-pptx-tool --version