pdf-ocr-cli 1.0.0__tar.gz

pdf_ocr_cli-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sameer Bajaj
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pdf_ocr_cli-1.0.0/PKG-INFO

@@ -0,0 +1,207 @@
+Metadata-Version: 2.4
+Name: pdf-ocr-cli
+Version: 1.0.0
+Summary: High-quality OCR tool for scanned PDFs using Tesseract
+Author-email: Sameer Bajaj <sameer@sameerbajaj.com>
+License-Expression: MIT
+Project-URL: Homepage, https://sameerbajaj.com/tools/pdf-ocr/
+Project-URL: Website, https://sameerbajaj.com
+Project-URL: Repository, https://github.com/sameerbajaj/pdf-ocr
+Keywords: ocr,pdf,tesseract,document-processing
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pytesseract>=0.3.13
+Requires-Dist: pdf2image>=1.17.0
+Requires-Dist: pillow>=10.0.0
+Requires-Dist: click>=8.1.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: PyPDF2>=3.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Dynamic: license-file
+
+# PDF OCR Tool
+
+Convert scanned or poorly OCR'd PDFs into searchable PDFs with selectable text using Tesseract OCR.
+
+## Features
+
+- 🎯 High-quality OCR using Tesseract 5.x
+- 📄 Creates searchable PDFs with invisible text layer
+- 🎨 Interactive, user-friendly command-line interface
+- ⚡ Fast processing with configurable DPI (default: 300)
+- 🎭 Process entire PDFs or specific page ranges
+
+## Prerequisites
+
+Install system dependencies first:
+
+**macOS:**
+```bash
+brew install tesseract poppler
+```
+
+**Linux (Ubuntu/Debian):**
+```bash
+sudo apt-get install tesseract-ocr poppler-utils
+```
+
+## Quick Start
+
+### Option 1: Run Directly from GitHub (Easiest - No Installation!)
+
+```bash
+uvx --from git+https://github.com/sameerbajaj/pdf-ocr pdf-ocr
+```
+
+That's it! The tool will run directly without any installation.
+
+### Option 2: Clone and Run Locally
+
+```bash
+# Clone the repository
+git clone https://github.com/sameerbajaj/pdf-ocr.git
+cd pdf-ocr
+
+# Run directly
+uvx --from . pdf-ocr
+```
+
+### Option 3: Install Permanently
+
+```bash
+# Clone and install
+git clone https://github.com/sameerbajaj/pdf-ocr.git
+cd pdf-ocr
+uv pip install -e .
+source .venv/bin/activate
+
+# Run from anywhere
+pdf-ocr
+```
+
+## Usage
+
+### Interactive Mode (Recommended)
+
+Simply run the command and follow the friendly prompts:
+
+```bash
+pdf-ocr
+```
+
+The tool will ask you:
+1. **Which PDF file?** - You can type the path or drag & drop the file
+2. **Which pages?** - Enter a range like `4-5`, a single page like `7`, or press Enter for all pages
+
+### Command-Line Mode
+
+```bash
+# Process entire PDF
+pdf-ocr document.pdf
+
+# Process specific pages
+pdf-ocr document.pdf --pages 4-5
+pdf-ocr document.pdf -p 1-10
+
+# Custom output
+pdf-ocr document.pdf --output result.pdf
+
+# Save text files too
+pdf-ocr document.pdf --save-text
+
+# Higher quality (slower)
+pdf-ocr document.pdf --dpi 400
+```
+
+## Examples
+
+```bash
+# Process pages 4-5 of a book
+pdf-ocr book.pdf --pages 4-5
+
+# Process chapter (pages 20-40) with text export
+pdf-ocr textbook.pdf -p 20-40 --save-text
+
+# High-quality scan of a single page
+pdf-ocr scan.pdf --pages 7 --dpi 600
+```
+
+## Output
+
+The tool generates:
+- **`filename_ocr.pdf`** or **`filename_pages4-5_ocr.pdf`** - Searchable PDF with text layer
+- **`filename_pageX.txt`** (optional) - Plain text files if `--save-text` is used
+
+All files are saved in the same directory as the input PDF.
+
+## Troubleshooting
+
+**Command not found:**
+```bash
+source .venv/bin/activate
+```
+
+**Tesseract not installed:**
+```bash
+brew install tesseract  # macOS
+sudo apt-get install tesseract-ocr  # Linux
+```
+
+**Poppler not installed:**
+```bash
+brew install poppler  # macOS
+sudo apt-get install poppler-utils  # Linux
+```
+
+## Development
+
+```bash
+# Setup for development
+git clone https://github.com/yourusername/pdf-ocr-tool.git
+cd pdf-ocr-tool
+uv venv
+source .venv/bin/activate
+uv pip install -e ".[dev]"
+
+# Run from source
+python -m pdf_ocr_tool.cli
+```
+
+## Project Structure
+
+```
+pdf-ocr-tool/
+├── pdf_ocr_tool/          # Main package
+│   ├── cli.py            # Command-line interface
+│   ├── ocr.py            # OCR processing
+│   └── pdf_utils.py      # PDF generation
+├── pyproject.toml        # Package configuration
+├── setup.sh              # Auto-installer script
+└── README.md             # This file
+```
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Acknowledgments
+
+- [Tesseract OCR](https://github.com/tesseract-ocr/tesseract)
+- [pdf2image](https://github.com/Belval/pdf2image)
+- [Rich](https://github.com/Textualize/rich)
+
+---
+
+Part of the open-source tools collection by [Sameer Bajaj](https://sameerbajaj.com). Learn more on the [project page](https://sameerbajaj.com/tools/pdf-ocr/).

pdf_ocr_cli-1.0.0/README.md

@@ -0,0 +1,174 @@
+# PDF OCR Tool
+
+Convert scanned or poorly OCR'd PDFs into searchable PDFs with selectable text using Tesseract OCR.
+
+## Features
+
+- 🎯 High-quality OCR using Tesseract 5.x
+- 📄 Creates searchable PDFs with invisible text layer
+- 🎨 Interactive, user-friendly command-line interface
+- ⚡ Fast processing with configurable DPI (default: 300)
+- 🎭 Process entire PDFs or specific page ranges
+
+## Prerequisites
+
+Install system dependencies first:
+
+**macOS:**
+```bash
+brew install tesseract poppler
+```
+
+**Linux (Ubuntu/Debian):**
+```bash
+sudo apt-get install tesseract-ocr poppler-utils
+```
+
+## Quick Start
+
+### Option 1: Run Directly from GitHub (Easiest - No Installation!)
+
+```bash
+uvx --from git+https://github.com/sameerbajaj/pdf-ocr pdf-ocr
+```
+
+That's it! The tool will run directly without any installation.
+
+### Option 2: Clone and Run Locally
+
+```bash
+# Clone the repository
+git clone https://github.com/sameerbajaj/pdf-ocr.git
+cd pdf-ocr
+
+# Run directly
+uvx --from . pdf-ocr
+```
+
+### Option 3: Install Permanently
+
+```bash
+# Clone and install
+git clone https://github.com/sameerbajaj/pdf-ocr.git
+cd pdf-ocr
+uv pip install -e .
+source .venv/bin/activate
+
+# Run from anywhere
+pdf-ocr
+```
+
+## Usage
+
+### Interactive Mode (Recommended)
+
+Simply run the command and follow the friendly prompts:
+
+```bash
+pdf-ocr
+```
+
+The tool will ask you:
+1. **Which PDF file?** - You can type the path or drag & drop the file
+2. **Which pages?** - Enter a range like `4-5`, a single page like `7`, or press Enter for all pages
+
+### Command-Line Mode
+
+```bash
+# Process entire PDF
+pdf-ocr document.pdf
+
+# Process specific pages
+pdf-ocr document.pdf --pages 4-5
+pdf-ocr document.pdf -p 1-10
+
+# Custom output
+pdf-ocr document.pdf --output result.pdf
+
+# Save text files too
+pdf-ocr document.pdf --save-text
+
+# Higher quality (slower)
+pdf-ocr document.pdf --dpi 400
+```
+
+## Examples
+
+```bash
+# Process pages 4-5 of a book
+pdf-ocr book.pdf --pages 4-5
+
+# Process chapter (pages 20-40) with text export
+pdf-ocr textbook.pdf -p 20-40 --save-text
+
+# High-quality scan of a single page
+pdf-ocr scan.pdf --pages 7 --dpi 600
+```
+
+## Output
+
+The tool generates:
+- **`filename_ocr.pdf`** or **`filename_pages4-5_ocr.pdf`** - Searchable PDF with text layer
+- **`filename_pageX.txt`** (optional) - Plain text files if `--save-text` is used
+
+All files are saved in the same directory as the input PDF.
+
+## Troubleshooting
+
+**Command not found:**
+```bash
+source .venv/bin/activate
+```
+
+**Tesseract not installed:**
+```bash
+brew install tesseract  # macOS
+sudo apt-get install tesseract-ocr  # Linux
+```
+
+**Poppler not installed:**
+```bash
+brew install poppler  # macOS
+sudo apt-get install poppler-utils  # Linux
+```
+
+## Development
+
+```bash
+# Setup for development
+git clone https://github.com/yourusername/pdf-ocr-tool.git
+cd pdf-ocr-tool
+uv venv
+source .venv/bin/activate
+uv pip install -e ".[dev]"
+
+# Run from source
+python -m pdf_ocr_tool.cli
+```
+
+## Project Structure
+
+```
+pdf-ocr-tool/
+├── pdf_ocr_tool/          # Main package
+│   ├── cli.py            # Command-line interface
+│   ├── ocr.py            # OCR processing
+│   └── pdf_utils.py      # PDF generation
+├── pyproject.toml        # Package configuration
+├── setup.sh              # Auto-installer script
+└── README.md             # This file
+```
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Acknowledgments
+
+- [Tesseract OCR](https://github.com/tesseract-ocr/tesseract)
+- [pdf2image](https://github.com/Belval/pdf2image)
+- [Rich](https://github.com/Textualize/rich)
+
+---
+
+Part of the open-source tools collection by [Sameer Bajaj](https://sameerbajaj.com). Learn more on the [project page](https://sameerbajaj.com/tools/pdf-ocr/).

pdf_ocr_cli-1.0.0/pdf_ocr_cli.egg-info/PKG-INFO

@@ -0,0 +1,207 @@
+Metadata-Version: 2.4
+Name: pdf-ocr-cli
+Version: 1.0.0
+Summary: High-quality OCR tool for scanned PDFs using Tesseract
+Author-email: Sameer Bajaj <sameer@sameerbajaj.com>
+License-Expression: MIT
+Project-URL: Homepage, https://sameerbajaj.com/tools/pdf-ocr/
+Project-URL: Website, https://sameerbajaj.com
+Project-URL: Repository, https://github.com/sameerbajaj/pdf-ocr
+Keywords: ocr,pdf,tesseract,document-processing
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pytesseract>=0.3.13
+Requires-Dist: pdf2image>=1.17.0
+Requires-Dist: pillow>=10.0.0
+Requires-Dist: click>=8.1.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: PyPDF2>=3.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Dynamic: license-file
+
+# PDF OCR Tool
+
+Convert scanned or poorly OCR'd PDFs into searchable PDFs with selectable text using Tesseract OCR.
+
+## Features
+
+- 🎯 High-quality OCR using Tesseract 5.x
+- 📄 Creates searchable PDFs with invisible text layer
+- 🎨 Interactive, user-friendly command-line interface
+- ⚡ Fast processing with configurable DPI (default: 300)
+- 🎭 Process entire PDFs or specific page ranges
+
+## Prerequisites
+
+Install system dependencies first:
+
+**macOS:**
+```bash
+brew install tesseract poppler
+```
+
+**Linux (Ubuntu/Debian):**
+```bash
+sudo apt-get install tesseract-ocr poppler-utils
+```
+
+## Quick Start
+
+### Option 1: Run Directly from GitHub (Easiest - No Installation!)
+
+```bash
+uvx --from git+https://github.com/sameerbajaj/pdf-ocr pdf-ocr
+```
+
+That's it! The tool will run directly without any installation.
+
+### Option 2: Clone and Run Locally
+
+```bash
+# Clone the repository
+git clone https://github.com/sameerbajaj/pdf-ocr.git
+cd pdf-ocr
+
+# Run directly
+uvx --from . pdf-ocr
+```
+
+### Option 3: Install Permanently
+
+```bash
+# Clone and install
+git clone https://github.com/sameerbajaj/pdf-ocr.git
+cd pdf-ocr
+uv pip install -e .
+source .venv/bin/activate
+
+# Run from anywhere
+pdf-ocr
+```
+
+## Usage
+
+### Interactive Mode (Recommended)
+
+Simply run the command and follow the friendly prompts:
+
+```bash
+pdf-ocr
+```
+
+The tool will ask you:
+1. **Which PDF file?** - You can type the path or drag & drop the file
+2. **Which pages?** - Enter a range like `4-5`, a single page like `7`, or press Enter for all pages
+
+### Command-Line Mode
+
+```bash
+# Process entire PDF
+pdf-ocr document.pdf
+
+# Process specific pages
+pdf-ocr document.pdf --pages 4-5
+pdf-ocr document.pdf -p 1-10
+
+# Custom output
+pdf-ocr document.pdf --output result.pdf
+
+# Save text files too
+pdf-ocr document.pdf --save-text
+
+# Higher quality (slower)
+pdf-ocr document.pdf --dpi 400
+```
+
+## Examples
+
+```bash
+# Process pages 4-5 of a book
+pdf-ocr book.pdf --pages 4-5
+
+# Process chapter (pages 20-40) with text export
+pdf-ocr textbook.pdf -p 20-40 --save-text
+
+# High-quality scan of a single page
+pdf-ocr scan.pdf --pages 7 --dpi 600
+```
+
+## Output
+
+The tool generates:
+- **`filename_ocr.pdf`** or **`filename_pages4-5_ocr.pdf`** - Searchable PDF with text layer
+- **`filename_pageX.txt`** (optional) - Plain text files if `--save-text` is used
+
+All files are saved in the same directory as the input PDF.
+
+## Troubleshooting
+
+**Command not found:**
+```bash
+source .venv/bin/activate
+```
+
+**Tesseract not installed:**
+```bash
+brew install tesseract  # macOS
+sudo apt-get install tesseract-ocr  # Linux
+```
+
+**Poppler not installed:**
+```bash
+brew install poppler  # macOS
+sudo apt-get install poppler-utils  # Linux
+```
+
+## Development
+
+```bash
+# Setup for development
+git clone https://github.com/yourusername/pdf-ocr-tool.git
+cd pdf-ocr-tool
+uv venv
+source .venv/bin/activate
+uv pip install -e ".[dev]"
+
+# Run from source
+python -m pdf_ocr_tool.cli
+```
+
+## Project Structure
+
+```
+pdf-ocr-tool/
+├── pdf_ocr_tool/          # Main package
+│   ├── cli.py            # Command-line interface
+│   ├── ocr.py            # OCR processing
+│   └── pdf_utils.py      # PDF generation
+├── pyproject.toml        # Package configuration
+├── setup.sh              # Auto-installer script
+└── README.md             # This file
+```
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Acknowledgments
+
+- [Tesseract OCR](https://github.com/tesseract-ocr/tesseract)
+- [pdf2image](https://github.com/Belval/pdf2image)
+- [Rich](https://github.com/Textualize/rich)
+
+---
+
+Part of the open-source tools collection by [Sameer Bajaj](https://sameerbajaj.com). Learn more on the [project page](https://sameerbajaj.com/tools/pdf-ocr/).

pdf_ocr_cli-1.0.0/pdf_ocr_cli.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pdf_ocr_cli.py
+pyproject.toml
+pdf_ocr_cli.egg-info/PKG-INFO
+pdf_ocr_cli.egg-info/SOURCES.txt
+pdf_ocr_cli.egg-info/dependency_links.txt
+pdf_ocr_cli.egg-info/entry_points.txt
+pdf_ocr_cli.egg-info/requires.txt
+pdf_ocr_cli.egg-info/top_level.txt
+pdf_ocr_tool/__init__.py
+pdf_ocr_tool/cli.py
+pdf_ocr_tool/ocr.py
+pdf_ocr_tool/pdf_utils.py

pdf_ocr_cli-1.0.0/pdf_ocr_cli.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pdf_ocr_cli-1.0.0/pdf_ocr_cli.egg-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+pdf-ocr = pdf_ocr_tool.cli:main
+pdf-ocr-cli = pdf_ocr_tool.cli:main

pdf_ocr_cli-1.0.0/pdf_ocr_cli.egg-info/requires.txt

@@ -0,0 +1,11 @@
+pytesseract>=0.3.13
+pdf2image>=1.17.0
+pillow>=10.0.0
+click>=8.1.0
+rich>=13.0.0
+PyPDF2>=3.0.0
+
+[dev]
+pytest>=7.0.0
+black>=23.0.0
+ruff>=0.1.0

pdf_ocr_cli-1.0.0/pdf_ocr_cli.egg-info/top_level.txt

@@ -0,0 +1,2 @@
+pdf_ocr_cli
+pdf_ocr_tool

pdf_ocr_cli-1.0.0/pdf_ocr_cli.py

@@ -0,0 +1,5 @@
+"""Command-line interface for PDF OCR Tool."""
+from pdf_ocr_tool.cli import main
+
+if __name__ == "__main__":
+    main()

pdf_ocr_cli-1.0.0/pdf_ocr_tool/__init__.py

@@ -0,0 +1,3 @@
+"""PDF OCR Tool - High-quality OCR for scanned PDFs."""
+
+__version__ = "1.0.0"

pdf_ocr_cli-1.0.0/pdf_ocr_tool/cli.py

@@ -0,0 +1,352 @@
+"""Command-line interface for PDF OCR tool."""
+
+import os
+import sys
+import re
+from pathlib import Path
+from typing import Optional, Tuple
+
+import click
+from rich.console import Console
+from rich.progress import Progress, SpinnerColumn, TextColumn, BarColumn, TaskProgressColumn
+from rich.panel import Panel
+from rich.text import Text
+from rich import print as rprint
+
+from .ocr import OCRProcessor
+from .pdf_utils import create_searchable_pdf, save_text_files
+
+
+console = Console()
+
+
+def parse_page_range(page_range_str: str) -> Tuple[int, int]:
+    """
+    Parse page range string like '4-5', '1-10', '5' into tuple.
+    
+    Args:
+        page_range_str: String like "4-5" or "4" or "1-10"
+    
+    Returns:
+        Tuple of (start_page, end_page)
+    
+    Raises:
+        ValueError: If format is invalid
+    """
+    page_range_str = page_range_str.strip()
+    
+    if '-' in page_range_str:
+        parts = page_range_str.split('-')
+        if len(parts) != 2:
+            raise ValueError("Invalid page range format. Use 'start-end' like '4-5' or '1-10'")
+        
+        try:
+            start = int(parts[0].strip())
+            end = int(parts[1].strip())
+        except ValueError:
+            raise ValueError("Page numbers must be integers")
+        
+        if start < 1 or end < 1:
+            raise ValueError("Page numbers must be positive (starting from 1)")
+        
+        if start > end:
+            raise ValueError(f"Start page ({start}) must be less than or equal to end page ({end})")
+        
+        return (start, end)
+    else:
+        try:
+            page = int(page_range_str)
+        except ValueError:
+            raise ValueError("Invalid page number. Must be an integer")
+        
+        if page < 1:
+            raise ValueError("Page numbers must be positive (starting from 1)")
+        
+        return (page, page)
+
+
+def normalize_path(path_str: str) -> Path:
+    """
+    Normalize file path, handling backslashes and spaces.
+    
+    Args:
+        path_str: Input path string (may contain backslashes from copy-paste)
+    
+    Returns:
+        Normalized Path object
+    """
+    # Remove backslashes used as escape characters (common when copy-pasting macOS paths)
+    path_str = path_str.replace('\\ ', ' ')
+    
+    # Expand user home directory
+    path_str = os.path.expanduser(path_str)
+    
+    # Convert to Path and resolve
+    return Path(path_str).resolve()
+
+
+def validate_pdf_path(pdf_path: Path) -> None:
+    """
+    Validate that PDF file exists and is readable.
+    
+    Args:
+        pdf_path: Path to PDF file
+    
+    Raises:
+        click.ClickException: If file is invalid
+    """
+    if not pdf_path.exists():
+        raise click.ClickException(f"File not found: {pdf_path}")
+    
+    if not pdf_path.is_file():
+        raise click.ClickException(f"Not a file: {pdf_path}")
+    
+    if pdf_path.suffix.lower() != '.pdf':
+        console.print("[yellow]Warning: File doesn't have .pdf extension[/yellow]")
+    
+    if not os.access(pdf_path, os.R_OK):
+        raise click.ClickException(f"File not readable: {pdf_path}")
+
+
+@click.command()
+@click.argument('pdf_path', type=str, required=False)
+@click.option(
+    '--pages', '-p',
+    type=str,
+    help='Page range to process (e.g., "4-5", "1-10", "7"). Leave empty for all pages.'
+)
+@click.option(
+    '--output', '-o',
+    type=str,
+    help='Output PDF path (default: adds "_ocr" suffix to input filename)'
+)
+@click.option(
+    '--dpi',
+    type=int,
+    default=300,
+    help='DPI for image conversion (default: 300, higher = better quality but slower)'
+)
+@click.option(
+    '--save-text/--no-save-text',
+    default=False,
+    help='Also save extracted text to .txt files'
+)
+@click.option(
+    '--output-dir',
+    type=str,
+    help='Directory for output files (default: same as input PDF)'
+)
+@click.version_option(version="1.0.0", prog_name="pdf-ocr")
+def main(
+    pdf_path: Optional[str],
+    pages: Optional[str],
+    output: Optional[str],
+    dpi: int,
+    save_text: bool,
+    output_dir: Optional[str]
+):
+    """
+    High-quality OCR tool for scanned PDFs using Tesseract.
+    
+    Convert scanned PDFs into searchable PDFs with selectable text.
+    
+    Examples:
+    
+        # Interactive mode
+        pdf-ocr
+        
+        # Process entire PDF
+        pdf-ocr document.pdf
+        
+        # Process specific pages
+        pdf-ocr document.pdf --pages 4-5
+        pdf-ocr document.pdf -p 1-10
+        
+        # Process with custom output
+        pdf-ocr document.pdf --output result.pdf
+        
+        # Process with text files
+        pdf-ocr document.pdf --save-text
+    """
+    console.print(Panel.fit(
+        "[bold cyan]PDF OCR Tool[/bold cyan]\n"
+        "High-quality OCR for scanned PDFs",
+        border_style="cyan"
+    ))
+    
+    # Interactive mode if no PDF path provided
+    if not pdf_path:
+        console.print("\n[bold cyan]Step 1: Select your PDF file[/bold cyan]")
+        console.print("  • You can type the full path to your PDF")
+        console.print("  • Or drag and drop the PDF file into this terminal")
+        console.print("  • Press Enter when done\n")
+        pdf_path = input("📄 PDF file path: ").strip()
+        
+        if not pdf_path:
+            console.print("[red]✗ No PDF path provided. Exiting.[/red]")
+            sys.exit(1)
+    
+    # Normalize and validate PDF path
+    try:
+        pdf_path_obj = normalize_path(pdf_path)
+        validate_pdf_path(pdf_path_obj)
+    except click.ClickException as e:
+        console.print(f"[red]Error: {e.message}[/red]")
+        sys.exit(1)
+    
+    console.print(f"\n[green]✓[/green] Found PDF: [bold]{pdf_path_obj.name}[/bold]")
+    
+    # Interactive page range if not provided
+    page_range = None
+    if pages:
+        try:
+            page_range = parse_page_range(pages)
+            console.print(f"[green]✓[/green] Processing pages: [bold]{page_range[0]}-{page_range[1]}[/bold]")
+        except ValueError as e:
+            console.print(f"[red]Error: {e}[/red]")
+            sys.exit(1)
+    else:
+        console.print("\n[bold cyan]Step 2: Choose which pages to process[/bold cyan]")
+        console.print("  • Enter a page range like: [bold]4-5[/bold] (pages 4 through 5)")
+        console.print("  • Or a single page like: [bold]7[/bold] (just page 7)")
+        console.print("  • Or press [bold]Enter[/bold] to process the entire PDF\n")
+        console.print("[dim]Examples: 4-5, 1-10, 20-25, or just 7[/dim]\n")
+        pages_input = input("📖 Which pages? (press Enter for all): ").strip()
+        
+        if pages_input:
+            try:
+                page_range = parse_page_range(pages_input)
+                console.print(f"\n[green]✓[/green] Will process pages: [bold]{page_range[0]} to {page_range[1]}[/bold]")
+            except ValueError as e:
+                console.print(f"[red]✗ Error: {e}[/red]")
+                sys.exit(1)
+        else:
+            console.print("\n[green]✓[/green] Will process [bold]all pages[/bold] in the PDF")
+    
+    # Determine output directory
+    if output_dir:
+        out_dir = Path(output_dir).resolve()
+        out_dir.mkdir(parents=True, exist_ok=True)
+    else:
+        out_dir = pdf_path_obj.parent
+    
+    # Determine output PDF path
+    if output:
+        output_pdf = normalize_path(output)
+    else:
+        # Generate output filename
+        base_name = pdf_path_obj.stem
+        if page_range:
+            suffix = f"_pages{page_range[0]}-{page_range[1]}_ocr"
+        else:
+            suffix = "_ocr"
+        output_pdf = out_dir / f"{base_name}{suffix}.pdf"
+    
+    console.print(f"[green]✓[/green] Output PDF: [bold]{output_pdf.name}[/bold]")
+    
+    # Initialize OCR processor
+    processor = OCRProcessor(dpi=dpi)
+    
+    # Check dependencies
+    console.print("\n[bold]Checking dependencies...[/bold]")
+    success, message = processor.check_dependencies()
+    if not success:
+        console.print(f"[red]✗ {message}[/red]")
+        sys.exit(1)
+    console.print("[green]✓ All dependencies installed[/green]")
+    
+    # Process PDF
+    console.print("\n[bold cyan]Starting OCR processing...[/bold cyan]")
+    
+    try:
+        with Progress(
+            SpinnerColumn(),
+            TextColumn("[progress.description]{task.description}"),
+            BarColumn(),
+            TaskProgressColumn(),
+            console=console
+        ) as progress:
+            
+            # Convert PDF to images
+            task1 = progress.add_task(
+                f"[cyan]Converting PDF to images (DPI: {dpi})...",
+                total=None
+            )
+            images = processor.convert_pdf_to_images(str(pdf_path_obj), page_range)
+            progress.update(task1, completed=True)
+            console.print(f"[green]✓[/green] Converted [bold]{len(images)}[/bold] page(s) to images")
+            
+            # Perform OCR
+            task2 = progress.add_task(
+                "[cyan]Performing OCR on pages...",
+                total=len(images)
+            )
+            
+            ocr_results = []
+            for idx, image in enumerate(images):
+                progress.update(task2, advance=1, description=f"[cyan]OCR on page {idx + 1}/{len(images)}...")
+                ocr_text = processor.ocr_image(image)
+                ocr_results.append((image, ocr_text))
+            
+            console.print(f"[green]✓[/green] OCR completed for [bold]{len(images)}[/bold] page(s)")
+            
+            # Create searchable PDF
+            task3 = progress.add_task(
+                "[cyan]Creating searchable PDF...",
+                total=len(images)
+            )
+            
+            def pdf_progress(current, total):
+                progress.update(task3, completed=current)
+            
+            create_searchable_pdf(images, str(output_pdf), pdf_progress)
+            console.print(f"[green]✓[/green] Created searchable PDF: [bold]{output_pdf}[/bold]")
+            
+            # Save text files if requested
+            if save_text:
+                task4 = progress.add_task("[cyan]Saving text files...", total=None)
+                start_page = page_range[0] if page_range else 1
+                text_files = save_text_files(
+                    ocr_results,
+                    str(out_dir),
+                    pdf_path_obj.stem,
+                    start_page
+                )
+                progress.update(task4, completed=True)
+                console.print(f"[green]✓[/green] Saved [bold]{len(text_files)}[/bold] text file(s)")
+        
+        # Summary
+        file_size = output_pdf.stat().st_size / (1024 * 1024)  # MB
+        
+        console.print("\n" + "="*60)
+        console.print(Panel.fit(
+            f"[bold green]✓ OCR Complete![/bold green]\n\n"
+            f"[bold]Output PDF:[/bold] {output_pdf}\n"
+            f"[bold]File size:[/bold] {file_size:.2f} MB\n"
+            f"[bold]Pages processed:[/bold] {len(images)}\n"
+            f"[bold]Status:[/bold] Searchable & selectable text ✓",
+            border_style="green",
+            title="Success"
+        ))
+        
+        # Show sample text
+        if ocr_results:
+            sample_text = ocr_results[0][1][:200].strip()
+            if sample_text:
+                console.print(f"\n[dim]Sample text from first page:[/dim]")
+                console.print(f"[dim]{sample_text}...[/dim]")
+        
+    except Exception as e:
+        console.print(f"\n[red]✗ Error during processing:[/red]")
+        console.print(f"[red]{str(e)}[/red]")
+        
+        if "poppler" in str(e).lower():
+            console.print("\n[yellow]Install poppler with:[/yellow]")
+            console.print("  macOS: [bold]brew install poppler[/bold]")
+            console.print("  Linux: [bold]apt-get install poppler-utils[/bold]")
+        
+        sys.exit(1)
+
+
+if __name__ == '__main__':
+    main()

pdf_ocr_cli-1.0.0/pdf_ocr_tool/ocr.py

@@ -0,0 +1,135 @@
+"""Core OCR processing functionality."""
+
+import os
+from pathlib import Path
+from typing import List, Tuple
+from PIL import Image
+import pytesseract
+from pdf2image import convert_from_path
+
+
+class OCRProcessor:
+    """Handle OCR processing for PDF pages."""
+    
+    def __init__(self, dpi: int = 300, tesseract_config: str = '--oem 3 --psm 3'):
+        """
+        Initialize OCR processor.
+        
+        Args:
+            dpi: Resolution for PDF to image conversion (default: 300)
+            tesseract_config: Tesseract configuration string
+        """
+        self.dpi = dpi
+        self.tesseract_config = tesseract_config
+    
+    def check_dependencies(self) -> Tuple[bool, str]:
+        """
+        Check if required system dependencies are installed.
+        
+        Returns:
+            Tuple of (success: bool, message: str)
+        """
+        # Check Tesseract
+        try:
+            pytesseract.get_tesseract_version()
+        except Exception as e:
+            return False, (
+                "Tesseract OCR is not installed or not in PATH.\n"
+                "Install it with: brew install tesseract (macOS) or apt-get install tesseract-ocr (Linux)"
+            )
+        
+        # Check poppler (required by pdf2image)
+        try:
+            # This will fail if poppler is not installed
+            from pdf2image.exceptions import PDFInfoNotInstalledError
+            # Try a simple conversion to check if poppler works
+            # We'll catch the error if it's not installed
+        except ImportError:
+            pass
+        
+        return True, "All dependencies are installed."
+    
+    def convert_pdf_to_images(
+        self, 
+        pdf_path: str, 
+        page_range: Tuple[int, int] = None
+    ) -> List[Image.Image]:
+        """
+        Convert PDF pages to images.
+        
+        Args:
+            pdf_path: Path to PDF file
+            page_range: Tuple of (start_page, end_page) or None for all pages
+        
+        Returns:
+            List of PIL Image objects
+        """
+        kwargs = {'dpi': self.dpi}
+        
+        if page_range:
+            kwargs['first_page'] = page_range[0]
+            kwargs['last_page'] = page_range[1]
+        
+        try:
+            images = convert_from_path(pdf_path, **kwargs)
+            return images
+        except Exception as e:
+            if "poppler" in str(e).lower() or "pdftoppm" in str(e).lower():
+                raise RuntimeError(
+                    "Poppler is not installed or not in PATH.\n"
+                    "Install it with: brew install poppler (macOS) or apt-get install poppler-utils (Linux)"
+                )
+            raise
+    
+    def ocr_image(self, image: Image.Image) -> str:
+        """
+        Perform OCR on a single image.
+        
+        Args:
+            image: PIL Image object
+        
+        Returns:
+            Extracted text as string
+        """
+        return pytesseract.image_to_string(image, config=self.tesseract_config)
+    
+    def ocr_image_to_pdf(self, image: Image.Image) -> bytes:
+        """
+        Perform OCR on image and return PDF bytes with text layer.
+        
+        Args:
+            image: PIL Image object
+        
+        Returns:
+            PDF bytes with searchable text layer
+        """
+        return pytesseract.image_to_pdf_or_hocr(image, extension='pdf')
+    
+    def process_pdf(
+        self,
+        pdf_path: str,
+        page_range: Tuple[int, int] = None,
+        progress_callback=None
+    ) -> List[Tuple[Image.Image, str]]:
+        """
+        Process PDF and return images with OCR text.
+        
+        Args:
+            pdf_path: Path to PDF file
+            page_range: Tuple of (start_page, end_page) or None for all pages
+            progress_callback: Optional callback function for progress updates
+        
+        Returns:
+            List of tuples (image, ocr_text)
+        """
+        images = self.convert_pdf_to_images(pdf_path, page_range)
+        results = []
+        
+        for idx, image in enumerate(images):
+            if progress_callback:
+                progress_callback(idx + 1, len(images))
+            
+            ocr_text = self.ocr_image(image)
+            results.append((image, ocr_text))
+        
+        return results

pdf_ocr_cli-1.0.0/pdf_ocr_tool/pdf_utils.py

@@ -0,0 +1,154 @@
+"""PDF generation utilities."""
+
+import os
+from pathlib import Path
+from typing import List
+from PIL import Image
+import pytesseract
+
+
+def create_searchable_pdf(
+    images: List[Image.Image],
+    output_path: str,
+    progress_callback=None
+) -> str:
+    """
+    Create a searchable PDF from images with OCR text layer.
+    
+    Args:
+        images: List of PIL Image objects
+        output_path: Path for output PDF file
+        progress_callback: Optional callback for progress updates
+    
+    Returns:
+        Path to created PDF file
+    """
+    try:
+        # Use PyPDF2 to merge multiple pages
+        from PyPDF2 import PdfMerger
+    except ImportError:
+        # Fallback: create single-page or multi-page PDF directly
+        return _create_pdf_direct(images, output_path, progress_callback)
+    
+    merger = PdfMerger()
+    temp_files = []
+    
+    try:
+        for idx, image in enumerate(images):
+            if progress_callback:
+                progress_callback(idx + 1, len(images))
+            
+            # Create temporary PDF for each page
+            temp_pdf = f".temp_page_{idx}_{os.getpid()}.pdf"
+            temp_files.append(temp_pdf)
+            
+            # Generate searchable PDF using pytesseract
+            pdf_data = pytesseract.image_to_pdf_or_hocr(image, extension='pdf')
+            
+            with open(temp_pdf, 'wb') as f:
+                f.write(pdf_data)
+            
+            merger.append(temp_pdf)
+        
+        # Write the merged PDF
+        merger.write(output_path)
+        merger.close()
+        
+    finally:
+        # Clean up temporary files
+        for temp_file in temp_files:
+            try:
+                if os.path.exists(temp_file):
+                    os.remove(temp_file)
+            except Exception:
+                pass
+    
+    return output_path
+
+
+def _create_pdf_direct(
+    images: List[Image.Image],
+    output_path: str,
+    progress_callback=None
+) -> str:
+    """
+    Create PDF directly when PyPDF2 is not available.
+    
+    For single page PDFs or fallback method.
+    """
+    if len(images) == 1:
+        # Single page - direct conversion
+        if progress_callback:
+            progress_callback(1, 1)
+        
+        pdf_data = pytesseract.image_to_pdf_or_hocr(images[0], extension='pdf')
+        with open(output_path, 'wb') as f:
+            f.write(pdf_data)
+    else:
+        # Multiple pages - need to combine somehow
+        # This is a fallback - try using img2pdf if available
+        try:
+            import img2pdf
+            
+            # Convert images to bytes
+            image_bytes_list = []
+            for idx, img in enumerate(images):
+                if progress_callback:
+                    progress_callback(idx + 1, len(images))
+                
+                # Create OCR PDF for this page
+                pdf_bytes = pytesseract.image_to_pdf_or_hocr(img, extension='pdf')
+                image_bytes_list.append(pdf_bytes)
+            
+            # For now, just save the first one with a warning
+            with open(output_path, 'wb') as f:
+                f.write(image_bytes_list[0])
+            
+            print("Warning: PyPDF2 not available. Only first page saved.")
+            print("Install PyPDF2 for multi-page PDF support: uv pip install PyPDF2")
+            
+        except ImportError:
+            # No merge capability - save first page only
+            pdf_data = pytesseract.image_to_pdf_or_hocr(images[0], extension='pdf')
+            with open(output_path, 'wb') as f:
+                f.write(pdf_data)
+            
+            print("Warning: Limited PDF support. Only first page saved.")
+            print("Install PyPDF2 for multi-page PDF support: uv pip install PyPDF2")
+    
+    return output_path
+
+
+def save_text_files(
+    ocr_results: List[tuple],
+    output_dir: str,
+    base_name: str,
+    start_page: int = 1
+) -> List[str]:
+    """
+    Save OCR text to individual text files.
+    
+    Args:
+        ocr_results: List of (image, text) tuples
+        output_dir: Directory to save text files
+        base_name: Base name for output files
+        start_page: Starting page number for naming
+    
+    Returns:
+        List of created file paths
+    """
+    output_dir = Path(output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+    
+    created_files = []
+    
+    for idx, (image, text) in enumerate(ocr_results):
+        page_num = start_page + idx
+        text_file = output_dir / f"{base_name}_page{page_num}.txt"
+        
+        with open(text_file, 'w', encoding='utf-8') as f:
+            f.write(text)
+        
+        created_files.append(str(text_file))
+    
+    return created_files

pdf_ocr_cli-1.0.0/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pdf-ocr-cli"
+version = "1.0.0"
+description = "High-quality OCR tool for scanned PDFs using Tesseract"
+authors = [
+    {name = "Sameer Bajaj", email = "sameer@sameerbajaj.com"}
+]
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+keywords = ["ocr", "pdf", "tesseract", "document-processing"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: End Users/Desktop",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+
+dependencies = [
+    "pytesseract>=0.3.13",
+    "pdf2image>=1.17.0",
+    "pillow>=10.0.0",
+    "click>=8.1.0",
+    "rich>=13.0.0",
+    "PyPDF2>=3.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "black>=23.0.0",
+    "ruff>=0.1.0",
+]
+
+[project.scripts]
+pdf-ocr = "pdf_ocr_tool.cli:main"
+pdf-ocr-cli = "pdf_ocr_tool.cli:main"
+
+[tool.setuptools]
+packages = ["pdf_ocr_tool"]
+py-modules = ["pdf_ocr_cli"]
+
+[project.urls]
+Homepage = "https://sameerbajaj.com/tools/pdf-ocr/"
+Website = "https://sameerbajaj.com"
+Repository = "https://github.com/sameerbajaj/pdf-ocr"

pdf_ocr_cli-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+