PDF to PNG Plane

This script converts a PDF file to one or more PNG images, combining pages into grid layouts with customizable options.

Requirements

• Python 3.6+
• uv (Python package manager)
• poppler-utils (for pdf2image)

Installation

1. Install uv:

curl -LsSf https://astral.sh/uv/install.sh | sh

2. Install the required Python packages:

uv pip install -e .

3. Install poppler-utils:

• On macOS:

brew install poppler

• On Ubuntu/Debian:

sudo apt-get install poppler-utils

Usage

python pdf_to_png.py input.pdf output.png [options]

Options

• --max-width: Maximum width for each page (optional)
• --max-height: Maximum height for each page (optional)
• --h-spacing: Horizontal spacing between pages in pixels (default: 0)
• --v-spacing: Vertical spacing between pages in pixels (default: 0)
• --direction: Page arrangement direction ('vertical' or 'horizontal', default: 'vertical')
• --grid-y: Number of pages in a column (default: 5)
• --grid-x: Number of pages in a row (default: 8)

Examples

1. Basic conversion:

python pdf_to_png.py input.pdf output.png

2. With maximum dimensions and spacing:

python pdf_to_png.py input.pdf output.png --max-width 800 --max-height 1200 --h-spacing 20 --v-spacing 10

3. Horizontal arrangement with custom grid size:

python pdf_to_png.py input.pdf output.png --direction horizontal --grid-y 3 --grid-x 4

Features

• Multiple output files: If the number of pages exceeds the grid size (y * x), multiple PNG files will be created with numbered suffixes
• Transparent spacing: The spacing between pages is transparent, allowing for better integration with different backgrounds
• Customizable grid: Control both the number of rows and columns independently
• Flexible layout: Choose between vertical or horizontal page arrangement

Development

To set up the development environment:

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies
uv pip install -e ".[dev]"

# Create virtual environment
uv venv

Package Management

This project uses uv for package management. Common commands:

# Install dependencies
uv pip install -e .

# Update dependencies
uv pip compile pyproject.toml --upgrade

# Install development dependencies
uv pip install -e ".[dev]"