skill-pdf-to-pptx-tool（技能 PDF TO PPTX tool）

When to use

• Converting PDF documents to editable PowerPoint presentations
• Creating slide decks from PDF reports or documents
• Need high-quality PDF to PPTX conversion with custom DPI
• Want multi-level verbosity logging for debugging conversions

PDF to PowerPoint Converter Skill

Purpose

This skill provides comprehensive guidance for using pdf-to-pptx-tool, a professional CLI tool that converts PDF documents into PowerPoint presentations. Each PDF page becomes a high-quality slide with customizable resolution.

When to Use This Skill

Use this skill when:

• You need to convert PDF documents to PowerPoint format
• You want to customize conversion quality (DPI settings)
• You need to debug conversion issues with verbose logging
• You're working with multi-page PDF documents
• You need programmatic PDF to PPTX conversion in workflows

Do NOT use this skill for:

• Editing existing PowerPoint files (use PowerPoint directly)
• Converting other formats (images, Word docs) to PPTX
• Extracting text from PDFs (use PDF text extraction tools)
• Creating PowerPoint from scratch (use PowerPoint or python-pptx)

CLI Tool: pdf-to-pptx-tool

A modern Python CLI tool built with Click, featuring multi-level verbosity logging, shell completion, and type-safe code.

Installation

# Clone the repository
git clone https://github.com/dnvriend/pdf-to-pptx-tool.git
cd pdf-to-pptx-tool

# Install globally with uv
uv tool install .

Prerequisites

• Python 3.14+
• poppler system library (for PDF rendering)

- macOS: brew install poppler - Ubuntu/Debian: apt-get install poppler-utils - Windows: Download from poppler releases

Quick Start

# Basic conversion
pdf-to-pptx-tool convert document.pdf slides.pptx

# High quality (300 DPI)
pdf-to-pptx-tool convert report.pdf presentation.pptx --dpi 300

# With verbose logging
pdf-to-pptx-tool -v convert input.pdf output.pptx

Progressive Disclosure

convert - Convert PDF to PowerPoint

Converts a PDF document to PowerPoint format, creating one slide per PDF page with customizable quality settings.

Usage:

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

Arguments:

• INPUT_PDF: Path to input PDF file (required)

- Must exist and be a valid PDF file - Supports any PDF version - No size limit (memory permitting)

• OUTPUT_PPTX: Path to output PowerPoint file (required)

- Will be created or overwritten - Extension should be .pptx - Parent directory must exist

• --dpi INTEGER: Resolution for page conversion (optional)

- Default: 200 DPI (good quality, reasonable size) - Range: 72-600 DPI - Higher DPI = better quality but larger files - Recommended: 200-300 for presentations

• -v, --verbose: Multi-level verbosity

- No flag: Warnings/errors only - -v: INFO level (operations and progress) - -vv: DEBUG level (detailed steps) - -vvv: TRACE level (library internals)

Examples:

# 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

Output:

• Creates PowerPoint file at specified path
• Slide properties:

- Aspect ratio: 16:9 (widescreen) - Dimensions: 10" × 5.625" - Layout: One full-slide image per PDF page - Background: Transparent

• Console output:

- Success: "✓ Successfully converted input.pdf to output.pptx" - Error: "✗ Error: [detailed error message]"

• Exit codes:

- 0: Success - 1: Error (file not found, invalid input, conversion failed)

completion - Generate shell completion scripts

Generates shell completion scripts for bash, zsh, or fish shells.

Usage:

pdf-to-pptx-tool completion SHELL

Arguments:

• SHELL: Shell type (required)

- Options: bash, zsh, fish - Case-insensitive

Examples:

# 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

Output: Shell-specific completion script printed to stdout.

Multi-Level Verbosity Logging

The tool supports progressive verbosity levels for debugging and monitoring conversions.

Logging Levels:

Examples:

# 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 Quality Guidelines

Choose DPI based on your use case:

Trade-offs:

• Higher DPI: Better quality, larger file size, slower conversion
• Lower DPI: Faster conversion, smaller files, lower quality
• Sweet spot: 200-300 DPI for most presentations

Batch Processing

Process multiple PDFs efficiently:

# 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 Completion

Enable tab completion for faster usage:

# 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

Benefits:

• Tab-complete commands: pdf-to-pptx-tool <TAB>
• Tab-complete options: pdf-to-pptx-tool convert --<TAB>
• Tab-complete file paths automatically

Common Issues

Issue: "poppler not found" or PDF conversion fails

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

Solution: Install poppler system library:

# macOS
brew install poppler

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

# Fedora
sudo dnf install poppler-utils

# Verify installation
pdftoppm -v

Issue: "File not found" error

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

Solution:

• Verify file path is correct
• Use absolute paths if needed
• Check file permissions

# Check file exists
ls -l document.pdf

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

Issue: Output file is too large

# Symptom
Generated 50MB PPTX from 2MB PDF

Solution: Reduce DPI setting:

# 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

Issue: Images look blurry in PowerPoint

# Symptom
Text and diagrams appear pixelated

Solution: Increase DPI setting:

# 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

Issue: Conversion is very slow

# Symptom
Large PDF takes minutes to convert

Solution:

1. Use DEBUG logging to see progress:

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

1. Consider lower DPI for faster conversion:

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

1. Split large PDF into chunks and convert separately

Issue: Permission denied writing output file

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

Solution:

• Check directory write permissions
• Use different output location

# 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

Getting Help

# 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

Debug Workflow

When conversion fails, use this debugging workflow:

# 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

Exit Codes

• 0: Success - conversion completed successfully
• 1: Error - file not found, invalid input, conversion failed, or permission denied

Output Formats

Default PowerPoint Output:

• Format: Office Open XML (.pptx)
• Aspect Ratio: 16:9 widescreen
• Slide Size: 10 inches × 5.625 inches
• Layout: One full-slide image per PDF page
• Image Format: PNG embedded in slides
• Compatibility: PowerPoint 2007+ (Windows/Mac/Online)

Console Output:

# Success
✓ Successfully converted document.pdf to slides.pptx

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

Logging Output (with -v/-vv/-vvv):

[INFO] Starting PDF to PPTX conversion
[INFO] Converting document.pdf to slides.pptx (DPI: 200)
[DEBUG] Input file size: 2.45 MB
[INFO] Converted 10 pages
[DEBUG] Output file size: 12.78 MB
[INFO] Conversion completed successfully

Best Practices

1. Start with default DPI (200): Good balance of quality and file size
2. Use verbose logging for debugging: -vv shows detailed conversion steps
3. Test with sample PDFs first: Verify quality before batch processing
4. Monitor output file sizes: Adjust DPI if files are too large
5. Batch process efficiently: Use shell loops for multiple files
6. Enable shell completion: Speeds up command-line usage
7. Keep poppler updated: Ensures compatibility with latest PDF features
8. Use absolute paths: Avoids confusion with relative paths
9. Verify prerequisites: Check poppler installation before bulk conversions
10. Handle errors gracefully: Check exit codes in scripts

Resources

• GitHub Repository: https://github.com/dnvriend/pdf-to-pptx-tool
• Python Dependencies:

- pdf2image (PDF to image conversion) - python-pptx (PowerPoint file creation) - Pillow (Image processing) - Click (CLI framework)

• System Dependencies: poppler (PDF rendering engine)
• Related Tools:

- PyPDF2 (PDF text extraction) - ReportLab (PDF generation) - pandoc (Universal document converter)