ocr-documents

---
name: ocr-documents
description: Use when the user has an image, screenshot, or scanned document and wants the text extracted — via Tesseract or EasyOCR — including preprocessing low-quality scans, pulling text with bounding boxes, OCR'ing a PDF page, or handling multi-language/handwritten input.
version: 1.0.0
author: Hermes Agent
license: MIT
metadata:
  hermes:
    tags: [ocr, tesseract, easyocr, image-processing, text-extraction, pdf]
    related_skills: [pdf-extract, markdown-to-pdf]
---

# ocr-documents

## Overview

Extract text from images, screenshots, and scanned documents using Tesseract OCR and EasyOCR. The agent handles image preprocessing, OCR execution, and text cleanup.

## When to Use

- The user has a screenshot or image containing text they want to extract.
- The user has a scanned document that needs to be converted to editable text.
- The user says "read the text in this image", "OCR this scan", or "extract text from screenshot".

## Prerequisites

```bash
# Tesseract (recommended for most use cases)
pip install pytesseract pillow
# System package:
# Linux: apt install tesseract-ocr
# macOS: brew install tesseract
# Windows: https://github.com/UB-Mannheim/tesseract/wiki

# EasyOCR (alternative, better for handwriting/complex layouts)
pip install easyocr
```

## Basic OCR

### Tesseract (fast, reliable for printed text)

```python
import pytesseract
from PIL import Image

def ocr_image(image_path: str, lang: str = "eng") -> str:
    img = Image.open(image_path)
    return pytesseract.image_to_string(img, lang=lang)
```

### EasyOCR (better for complex layouts, handwriting)

```python
import easyocr

reader = easyocr.Reader(['en'])

def ocr_image_easyocr(image_path: str) -> str:
    results = reader.readtext(image_path)
    return "\n".join([r[1] for r in results])
```

## Image Preprocessing

OCR accuracy depends heavily on image quality. Preprocess for better results:

```python
from PIL import Image, ImageEnhance, ImageFilter
import pytesseract

def ocr_with_preprocessing(image_path: str) -> str:
    img = Image.open(image_path)

    # Convert to grayscale
    img = img.convert('L')

    # Increase contrast
    enhancer = ImageEnhance.Contrast(img)
    img = enhancer.enhance(2.0)

    # Sharpen
    img = img.filter(ImageFilter.SHARPEN)

    # Upscale small images
    if img.width < 1000:
        ratio = 1000 / img.width
        img = img.resize((int(img.width * ratio), int(img.height * ratio)))

    return pytesseract.image_to_string(img)
```

## OCR with Bounding Boxes

```python
import pytesseract
from PIL import Image, ImageDraw

def ocr_with_boxes(image_path: str, output_path: str = "annotated.png"):
    img = Image.open(image_path)
    data = pytesseract.image_to_data(img, output_type=pytesseract.Output.DICT)

    draw = ImageDraw.Draw(img)
    for i in range(len(data["text"])):
        if int(data["conf"][i]) > 60:  # confidence threshold
            x, y, w, h = data["left"][i], data["top"][i], data["width"][i], data["height"][i]
            draw.rectangle([x, y, x + w, y + h], outline="red", width=2)

    img.save(output_path)
    return [data["text"][i] for i in range(len(data["text"])) if int(data["conf"][i]) > 60]
```

## PDF Page OCR

```python
import fitz  # pymupdf
import pytesseract
from PIL import Image
import io

def ocr_pdf_page(pdf_path: str, page_num: int = 0, dpi: int = 300) -> str:
    doc = fitz.open(pdf_path)
    page = doc[page_num]
    pix = page.get_pixmap(dpi=dpi)
    img = Image.open(io.BytesIO(pix.tobytes("png")))
    return pytesseract.image_to_string(img)
```

## Multi-language OCR

```python
# Install language packs:
# Linux: apt install tesseract-ocr-fra tesseract-ocr-deu tesseract-ocr-spa
# Then:
text = pytesseract.image_to_string(img, lang='eng+fra+deu')
```

## Workflow

1. Identify the image or document to OCR
2. Check image quality — if low resolution or poor contrast, preprocess
3. Run Tesseract for printed text, EasyOCR for handwriting/complex layouts
4. Clean up the output (remove stray characters, fix common OCR errors)
5. Return the extracted text

## Common OCR Errors and Fixes

| Error | Cause | Fix |
|---|---|---|
| Empty output | Image too small | Upscale to 1000px+ width |
| Garbled text | Low contrast | Convert to grayscale + enhance contrast |
| Missing text | Dark background | Invert colors: `ImageOps.invert(img)` |
| Wrong characters | Similar-looking chars (0/O, 1/l) | Post-process with regex replacements |
| Slow processing | High DPI | Use 300 DPI (sufficient for most text) |

## Common Pitfalls

1. **Tesseract path not found on Windows.** Unlike Linux/macOS, the `tesseract` binary isn't on PATH by default. Set it explicitly: `pytesseract.pytesseract.tesseract_cmd = r'C:\Program Files\Tesseract-OCR\tesseract.exe'`.
2. **Handwriting comes back garbled.** Tesseract is trained on printed text and performs poorly on handwriting. Switch to EasyOCR or TrOCR instead of trying to tune Tesseract further.
3. **Rotated pages produce nonsense text.** Tesseract assumes horizontal text; a sideways or upside-down scan silently returns garbage rather than an error. Detect orientation first with `pytesseract.image_to_osd(img)` and rotate before running OCR.
4. **Multi-column documents get jumbled.** Tesseract reads left-to-right, top-to-bottom across the whole page, so two-column layouts interleave lines from both columns. Use `image_to_data` with bounding boxes and sort by column (x-position) before reassembling text.
5. **Trusting low-confidence words.** `image_to_data` returns a per-word confidence score; anything below ~50 is unreliable and should be flagged or dropped rather than trusted verbatim.
6. **OCR-ing oversized images wastes time for no gain.** Images over 5000px take significant time with no accuracy benefit past ~2000-3000px width — resize down first.

## Verification Checklist

- [ ] Extracted text is non-empty and roughly matches the visible content when spot-checked against the source image
- [ ] Low-confidence words (below ~50 via `image_to_data`) are flagged or excluded, not silently included
- [ ] For rotated or scanned pages, orientation was checked/corrected before OCR, not assumed upright
- [ ] For multi-column layouts, column order in the output matches reading order, not raster scan order
- [ ] Language pack matches the actual document language (multi-language docs use `lang='eng+fra+...'` as needed)

# ocr-documents



Extract text from images, screenshots, and scanned documents using OCR.



## What it does



The agent runs OCR (Tesseract or EasyOCR) on an image or scanned document and returns the extracted text. For poor-quality images, it preprocesses first (grayscale, contrast enhancement, upscaling) to improve accuracy. For multi-language documents, it loads the appropriate language packs.



## Install



```bash

hermes skills install https://raw.githubusercontent.com/THEROCKSSS/hermes-skills-portfolio/main/skills/ocr-documents/SKILL.md

```



## How to use



```

"Extract the text from this screenshot"

```



The agent:

1. Opens the image

2. Preprocesses if needed (grayscale, contrast, upscale)

3. Runs Tesseract OCR

4. Returns the text



## Prerequisites



- Tesseract OCR installed (system package)

- Python: `pip install pytesseract pillow`



## Example



```

User: "Read the text in this receipt photo"



Agent:

  1. Opens receipt.jpg (800px wide, low contrast)

  2. Preprocesses: grayscale + contrast x2 + upscale to 1000px

  3. Runs: pytesseract.image_to_string(img)

  4. Returns: "Coffee Shop\nLatte      $4.50\nMuffin     $3.25\nTotal      $7.75"

```