chrome-ocr-extract 0.1.0

A generic command-line tool to extract text from scanned/image-based PDFs using Google Chrome's built-in ScreenAI OCR engine.

chrome-ocr-extract

A generic command-line interface to extract high-quality text from scanned or image-based PDFs using Google Chrome's built-in ScreenAI OCR engine.

Traditional PDF text extraction tools (like PyMuPDF or PyPDF2) struggle or produce garbled results when processing scanned documents. This tool automates a real Google Chrome instance running with accessibility and ScreenAI features enabled to capture high-accuracy OCR results at zero cost, making it highly suitable for complex scripts (such as Urdu, Arabic, etc.) as well as standard Latin scripts.

---

Installation

Method 1: Install from Source (Python Environment)

1. Clone this repository and navigate to the project directory:

   git clone <repository-url>
   cd PunjabTM/chrome-ocr-extract
   

2. Install the package in editable mode:

   pip install -e .
   

3. Run the setup command to verify environment dependencies and download the required Playwright Chromium binary:

   chrome-ocr-extract setup
   

Method 2: Standalone Binary (No Python Required)

If you downloaded the standalone compiled binary (chrome-ocr-extract or chrome-ocr-extract.exe):

1. Place the executable in a directory on your system's PATH.
2. Run the executable directly. The browser binaries are fully bundled inside the executable, so no secondary installation steps are needed.

---

Usage

1. Basic Text Extraction

Extract text from a single PDF:

chrome-ocr-extract extract /path/to/document.pdf -o ./output_dir

Extract text from all PDFs in a directory:

chrome-ocr-extract extract /path/to/pdf_directory -o ./output_dir

2. Custom Chapter Splitting via Table of Contents (TOC)

You can automatically split a PDF into separate chapter files by providing a Table-of-Contents JSON file with the --toc flag.

chrome-ocr-extract extract /path/to/urdu_textbook.pdf -o ./output_dir --toc ./urdu_toc.json --verbose

TOC JSON Schema

The --toc option expects a JSON file structured as follows. Specify the start page and end page (1-indexed, inclusive) for each chapter number:

{
  "chapters": {
    "1": {
      "title": "Introduction",
      "start_page": 5,
      "end_page": 12
    },
    "2": {
      "title": "Literature Review",
      "start_page": 13,
      "end_page": 28
    },
    "3": {
      "title": "Methodology",
      "start_page": 29,
      "end_page": 45
    }
  }
}

If a chapter's end page is not specified or same as the start page, only that page is extracted for the chapter.

3. Configuring OCR Stability Parameters

OCR processing runs in a real browser instance and can take some time. The tool monitors OCR progress by copying text periodically and evaluating when the content length stabilizes. You can customize these thresholds:

• --check-interval <seconds>: How frequently to perform the Ctrl+A/Ctrl+C text polling (default: 4.0 seconds).
• --stable-checks <count>: How many consecutive stable checks are required to finalize OCR (default: 2).
• --stable-interval <seconds>: The time interval between stability checks (default: 60.0 seconds).
• --min-wait <seconds>: The minimum time to wait after text is first detected before starting stability checks (default: 60.0 seconds).
• --max-wait <seconds>: The maximum time to wait before forcing a completion (default: 600.0 seconds).

Example with aggressive timings for short PDFs:

chrome-ocr-extract extract document.pdf -o ./out --min-wait 15 --stable-interval 15 --verbose

---

Development & Building Standalone Binary

To build a standalone executable for distribution:

1. Install PyInstaller:

   pip install pyinstaller
   

2. Run the build script:

   python build_binary.py
   

This will download the Playwright Chromium binary into a local folder (build_browsers/) and compile the Python CLI along with the browser folder into a single executable file inside the dist/ directory. Note: The generated binary will be large (~150MB - 250MB) due to the bundled web browser.