Metadata-Version: 2.4
Name: chrome-ocr-extract
Version: 0.1.0
Summary: A generic command-line tool to extract text from scanned/image-based PDFs using Google Chrome's built-in ScreenAI OCR engine.
Author: NeuralNest Developers
License: MIT
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.8
Requires-Dist: click>=8.0.0
Requires-Dist: playwright>=1.30.0
Requires-Dist: pymupdf>=1.20.0
Requires-Dist: pyperclip>=1.8.0
Description-Content-Type: text/markdown

# 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:
   ```bash
   git clone <repository-url>
   cd PunjabTM/chrome-ocr-extract
   ```

2. Install the package in editable mode:
   ```bash
   pip install -e .
   ```

3. Run the setup command to verify environment dependencies and download the required Playwright Chromium binary:
   ```bash
   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:
```bash
chrome-ocr-extract extract /path/to/document.pdf -o ./output_dir
```

Extract text from all PDFs in a directory:
```bash
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.

```bash
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:

```json
{
  "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:
```bash
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:
   ```bash
   pip install pyinstaller
   ```

2. Run the build script:
   ```bash
   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.
