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

Installation

1. Ensure you have Python 3.8+ 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

Trims excess white space and optionally runs PNG optimization (requires optipng).

Create Final PDF

./pdf_cleaner.py finalize output.pdf

Combines all processed pages into a final PDF and cleans up temporary files.

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 back into a PDF using img2pdf

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

[Insert chosen license here]