docs: Add comprehensive README

- Add project description and features - Include installation instructions with uv sync - Add usage examples for all commands - Document how each processing step works - Add package installation instructions for different distros
2024-12-03 21:07:39 +02:00
parent bad7612027
commit 7ef31b4876
1 changed files with 103 additions and 0 deletions
@@ -0,0 +1,103 @@
+# 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:
+   ```bash
+   git clone <repository-url>
+   cd notes_cleaner
+   ```
+4. Install dependencies:
+   ```bash
+   uv sync
+   ```
+
+5. (Optional) Install optipng for additional PNG optimization:
+   ```bash
+   # 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
+```bash
+./pdf_cleaner.py extract input.pdf
+```
+Extracts all pages from the input PDF to a temporary directory.
+
+### Deskew Pages
+```bash
+./pdf_cleaner.py deskew
+```
+Automatically detects and corrects page rotation by analyzing staff lines.
+
+### Optimize Pages
+```bash
+./pdf_cleaner.py optimize
+```
+Trims excess white space and optionally runs PNG optimization (requires optipng).
+
+### Create Final PDF
+```bash
+./pdf_cleaner.py finalize output.pdf
+```
+Combines all processed pages into a final PDF and cleans up temporary files.
+
+### Typical Workflow
+```bash
+./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]