PDF Tools

A collection of Python tools for PDF layout fixing and content adjustment. This package provides utilities to fix PDF page orientation and adjust content positioning within PDF documents.

Features

• PDF Layout Fixing: Convert portrait pages to landscape orientation while preserving content direction
• Content Position Adjustment: Move PDF content to correct positions within pages
• Batch Processing: Handle multiple pages efficiently
• Debug Information: Optional verbose output for troubleshooting

Installation

Using uv (recommended)

# Install uv if you haven't already
pip install uv

# Clone the repository
git clone https://github.com/CrueChan/pdf-tools.git
cd pdf-tools

# Install the package and dependencies
uv pip install -e .

Using pip

pip install git+https://github.com/CrueChan/pdf-tools.git

Usage

Command Line Interface

After installation, you can use the command-line tools:

# Fix PDF layout (convert to landscape)
pdf-fix-layout input.pdf output.pdf

# Adjust content position
pdf-adjust-content input.pdf output.pdf

Python API

from pdf_tools.fix_pdf_layout import fix_pdf_rotation
from pdf_tools.adjust_pdf import adjust_content_position

# Fix PDF layout
success = fix_pdf_rotation("input.pdf", "output_rotated.pdf", debug=True)

# Adjust content position
adjust_content_position("input.pdf", "output_adjusted.pdf")

Example Usage

import os
from pdf_tools import fix_pdf_rotation, adjust_content_position

def process_pdf_workflow(input_file):
    """Complete PDF processing workflow"""
    
    # Step 1: Fix layout orientation
    temp_file = "temp_rotated.pdf"
    success = fix_pdf_rotation(input_file, temp_file, debug=True)
    
    if success:
        # Step 2: Adjust content position
        final_output = "processed_output.pdf"
        adjust_content_position(temp_file, final_output)
        
        # Clean up temporary file
        os.remove(temp_file)
        
        print(f"Processing complete! Output saved as: {final_output}")
    else:
        print("Failed to process PDF")

# Process a PDF file
if __name__ == "__main__":
    process_pdf_workflow("your_input.pdf")

How It Works

PDF Layout Fixing

The fix_pdf_rotation function:

1. Reads the input PDF file
2. Analyzes each page's dimensions
3. Swaps width and height for portrait pages to make them landscape
4. Adjusts MediaBox and CropBox accordingly
5. Preserves the original content orientation

Content Position Adjustment

The adjust_content_position function:

1. Applies transformation matrix to move content
2. Shifts content vertically by 40% of page height
3. Maintains original page dimensions
4. Processes all pages uniformly

Technical Details

• Dependencies: PyPDF2 3.0.0+
• Python Support: 3.8+
• Page Format: Optimized for A4 size (841.89 x 595.27 points)
• Coordinate System: Uses PDF coordinate system (bottom-left origin)

Development

Setting up Development Environment

# Clone repository
git clone https://github.com/CrueChan/pdf-tools.git
cd pdf-tools

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

# Run tests
pytest

# Format code
black src/ tests/

# Lint code
flake8 src/ tests/

# Type checking
mypy src/

Project Structure

pdf-tools/
├── src/pdf_tools/           # Main package source
│   ├── __init__.py         # Package initialization
│   ├── fix_pdf_layout.py   # Layout fixing functionality
│   ├── adjust_pdf.py       # Content adjustment functionality
│   └── cli.py              # Command-line interface
├── tests/                  # Test files
├── examples/               # Usage examples
├── README.md              # This file
├── pyproject.toml         # Project configuration
└── LICENSE                # MIT License

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests for new functionality
5. Run the test suite (pytest)
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Troubleshooting

Common Issues

1. "No module named 'PyPDF2'": Install dependencies with uv pip install PyPDF2
2. Permission errors: Ensure you have write permissions in the output directory
3. Memory issues with large PDFs: Process files in smaller batches

Debug Mode

Enable debug mode for detailed processing information:

fix_pdf_rotation("input.pdf", "output.pdf", debug=True)

This will show:

• Original page dimensions
• MediaBox and CropBox information
• Processing progress
• Error details if issues occur

Changelog

v0.1.0 (2025-02-07)

• Initial release
• PDF layout fixing functionality
• Content position adjustment
• Command-line interface
• Python API

Support

If you encounter issues or have questions:

1. Check the Issues page
2. Create a new issue with detailed information
3. Include sample PDF files if possible (remove sensitive content)

---

Made with ❤️ by CrueChan