PDF Musical Score Cleaner

A command-line tool for processing and cleaning scanned musical score PDFs. This tool helps you extract, deskew, optimize, and recompile PDF files while maintaining high quality and readability of musical notation.

Features

• Page Extraction: Extract individual pages from PDF files
• Deskewing: Automatically correct page rotation using staff line detection
• White Space Trimming: Remove excess white space around the musical content
• PNG Optimization: Optimize PNG files using optipng (if installed)
• Modular Processing: Process your files step by step or all at once
• High Quality Output: Preserve image quality throughout the process
• Professional PDF Output: Generate A4-sized PDFs with proper borders and centered content

Installation

1. Ensure you have Python 3.12+ installed

2. Install uv (recommended) or pip

3. Clone this repository:

   git clone <repository-url>
   cd notes_cleaner
   

4. Install dependencies:

   uv sync
   

5. (Optional) Install optipng for additional PNG optimization:

   # Ubuntu/Debian
   sudo apt-get install optipng
   
   # macOS
   brew install optipng
   
   # Arch Linux
   sudo pacman -Sy optipng
   

Usage

The tool provides several commands that can be run independently:

Extract Pages

./pdf_cleaner.py extract input.pdf

Extracts all pages from the input PDF to a temporary directory.

Deskew Pages

./pdf_cleaner.py deskew

Automatically detects and corrects page rotation by analyzing staff lines.

Optimize Pages

./pdf_cleaner.py optimize [--level {1,2,3}]

Processes pages with different optimization levels:

• Level 1: Only trims excess white space
• Level 2: Trims white space and converts to 1-bit monochrome
• Level 3: All optimizations + PNG optimization (requires optipng)

Default level is 1 if not specified.

Create Final PDF

./pdf_cleaner.py finalize output.pdf

Combines all processed pages into a final PDF with proper A4 sizing, borders, and centered content.

Typical Workflow

./pdf_cleaner.py extract input.pdf  # Extract pages
./pdf_cleaner.py deskew            # Correct rotation
./pdf_cleaner.py optimize          # Remove white space and optimize
./pdf_cleaner.py finalize output.pdf  # Create final PDF

How It Works

1. Extraction: Uses pdf2image to convert PDF pages to high-quality PNG images
2. Deskewing:
   • Applies morphological operations to enhance horizontal lines
   • Uses Hough transform to detect staff lines
   • Calculates and corrects rotation based on detected lines
3. Optimization:
   • Detects content boundaries and removes excess white space
   • Optionally runs optipng for additional file size reduction
4. Finalization:
   • Combines processed images into a professional A4-sized PDF
   • Adds configurable borders around content
   • Centers content on each page while maintaining aspect ratio

Dependencies

• click: Command line interface
• opencv-python: Image processing and deskewing
• numpy: Numerical operations
• pdf2image: PDF to image conversion
• img2pdf: Image to PDF conversion
• optipng (optional): PNG file optimization

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

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

Version History

• v0.9rc2: Second release candidate
  • Improved documentation
  • Added optimization level descriptions
  • Fixed aspect ratio in PDF output
• v0.9rc1: First release candidate with full functionality
  • Professional PDF output with A4 sizing and borders
  • Complete image processing pipeline
  • Configurable settings