Local OCR Pipeline Skill

Robust Optical Character Recognition (OCR) pipeline driven by ocrmypdf and tesseract. Handles scanned PDFs, rotated image inputs, and raw text extraction securely and locally without external APIs.

Why not GPU via PyTorch/EasyOCR? The ocrmypdf tool is the industry standard for producing searchable PDFs. It leverages tesseract for pixel-accurate text placement. A pure-CPU pipeline is leaner (avoids a 1.5GB PyTorch payload) and reliably embeds text exactly where it appears in the scanned image.

Capabilities

Searchable PDF Generation: Converts rasterized/scanned PDFs or raw images (.jpg, .png, etc.) into PDFs with a selectable, searchable text layer.
Auto-Rotation & Deskew: Automatically detects incorrectly rotated text and straightens crooked scans.
Idempotent In-Place Processing: Safely processes files in-place using --skip-text, preventing double-processing of a PDF that already has embedded text.
Structured JSON Output: All commands output structured JSON, making failure states (like missing dependencies) parseable by agents.
Raw Text Extraction: Raw string extraction fallback for when agents need text directly in-memory instead of a PDF file.

Setup

# Installs system dependencies (tesseract, ocrmypdf, ghostscript) and sets up isolated venv
bash skills/ocr/scripts/setup.sh

Usage

uv run --project ~/.local-ocr scripts/ocr.py <command>

1. Generate a Searchable PDF (`pdf`)

Produces a standard, layered PDF. If you give it an image, it wraps it in a PDF. If you give it a scanned PDF, it adds the invisible text layer.

# Overwrites the file in-place, skipping it safely if it already contains text
uv run --project ~/.local-ocr scripts/ocr.py pdf ./scanned_invoice.pdf

# Output to a different file
uv run --project ~/.local-ocr scripts/ocr.py pdf ./scan_001.png -o ./contract.pdf

# Force reprocessing (ignore existing text layer)
uv run --project ~/.local-ocr scripts/ocr.py pdf ./scanned_invoice.pdf --force

Note: By default, auto-rotate and deskew are enabled. Disable with --no-rotate or --no-deskew.

2. Batch Process a Directory (`batch`)

Recursively scans a directory for images and PDFs, applying OCR.

# Process all files. Skips already-OCRed PDFs.
uv run --project ~/.local-ocr scripts/ocr.py batch ./archives/

3. Extract Raw Text (`text`)

Does not create a PDF. Just reads the words off the page and returns them as a JSON string. Good for agents reading documents on the fly.

uv run --project ~/.local-ocr scripts/ocr.py text ./han_solo_invoice.png

Franchise Examples (Star Wars)

Process the Death Star blueprints: uv run --project ~/.local-ocr scripts/ocr.py pdf ./ds-1_schematics.pdf
Extract raw orders: uv run --project ~/.local-ocr scripts/ocr.py text ./order_66_memo.jpg
Archive run: uv run --project ~/.local-ocr scripts/ocr.py batch /archives/jedi_temple

Troubleshooting

File already contains text: This is the most common "error", but it isn't an error. ocrmypdf returns exit code 6 when it skips a file that already has text. The wrapper script catches this and reports a JSON "status": "success" with a message noting the side-step.
Dependencies Missing: Run the setup.sh script again if the agent complains about missing tesseract or Python modules.

local-ocr