domains / documents / image-ocr / image-ocr

image-ocr

Skill card

combined

Both copies describe Tesseract OCR via pytesseract, but they are materially different procedures. The benchflow copy is a Python-centric skill that defines a strict JSON output schema, confidence thresholds, and batch-processing code. The aipoch copy is a config-driven runner that uses a JSON config file, supports natural-language path extraction, and emphasizes system-level Tesseract installation and language model selection. Neither is a reproduction of the other; crowning one would hide the config-driven workflow and the strict JSON schema respectively.

Repositories

Other copies

Combined skill

---
name: image-ocr
description: Extract text from images using Tesseract OCR via Python, supporting both direct Python calls and config-driven execution.
---

# Image OCR Skill

## Purpose
Extract text from image files (JPG, PNG, TIFF, BMP, WEBP) using Tesseract OCR via the `pytesseract` Python library. Suitable for scanned documents, screenshots, receipts, forms, and other visual content containing text.

## When to Use
- Extracting text from scanned documents or photos
- Reading text from screenshots or image captures
- Processing batch image files that contain textual information
- Running OCR with a specific Tesseract language model
- Running OCR via a config-driven script or natural-language request

## Required Libraries and System Dependencies

Python packages:
```bash
pip install pytesseract Pillow
```

System dependency:
- Tesseract OCR must be installed. If not on `PATH`, set `tesseract_cmd` to the full executable path in your config or environment.

## Input Requirements
- **File formats**: JPG, JPEG, PNG, TIFF, BMP, WEBP
- **Image quality**: Minimum 300 DPI recommended for printed text; clear and legible text
- **File size**: Under 5MB per image (resize if necessary)
- **Text language**: Specify if non-English to improve accuracy

## Execution Modes

### Mode 1: Direct Python Call
Use the Python functions below to extract text and produce a structured JSON result.

### Mode 2: Config-Driven Script
Create or edit `scripts/ocr_config.json` with the following fields:
- `image_path`: Explicit path to the image file (optional if `request` is provided).
- `request`: Natural-language instruction that includes an image path; when provided, the script extracts the path from this text.
- `lang`: Tesseract language model code (e.g., `eng`, `chi_sim`).
- `tesseract_cmd`: The Tesseract executable name or full path.

Example config:
```json
{
  "image_path": "path/to/image.png",
  "request": "",
  "lang": "eng",
  "tesseract_cmd": "tesseract"
}
```

Run:
```bash
python scripts/image_ocr.py
```

## Output Schema (Direct Python Call)
All extracted content must be returned as valid JSON conforming to this schema:

```json
{
  "success": true,
  "filename": "example.jpg",
  "extracted_text": "Full raw text extracted from the image...",
  "confidence": "high|medium|low",
  "metadata": {
    "language_detected": "en",
    "text_regions": 3,
    "has_tables": false,
    "has_handwriting": false
  },
  "warnings": [
    "Text partially obscured in bottom-right corner"
  ]
}
```

### Field Descriptions
- `success`: Boolean indicating whether text extraction completed
- `filename`: Original image filename
- `extracted_text`: Complete text content in reading order
- `confidence`: Overall OCR confidence level (high >= 80, medium >= 50, low < 50)
- `metadata.language_detected`: ISO 639-1 language code
- `metadata.text_regions`: Number of distinct text blocks identified
- `metadata.has_tables`: Whether tabular data structures were detected
- `metadata.has_handwriting`: Whether handwritten text was detected
- `warnings`: Array of quality issues or potential errors

## Code Examples

### Basic OCR Extraction

```python
import pytesseract
from PIL import Image

def extract_text_from_image(image_path):
    """Extract text from a single image using Tesseract OCR."""
    img = Image.open(image_path)
    text = pytesseract.image_to_string(img)
    return text.strip()
```

### Full OCR with JSON Output

```python
import pytesseract
from PIL import Image
import json
import os

def ocr_to_json(image_path, lang="eng"):
    """Perform OCR and return results as JSON."""
    filename = os.path.basename(image_path)
    warnings = []

    try:
        img = Image.open(image_path)

        # Get detailed OCR data
        data = pytesseract.image_to_data(img, lang=lang, output_type=pytesseract.Output.DICT)

        # Extract text preserving structure
        text = pytesseract.image_to_string(img, lang=lang)

        # Calculate confidence
        confidences = [c for c in data['conf'] if c > 0]
        avg_conf = sum(confidences) / len(confidences) if confidences else 0

        # Determine confidence level
        if avg_conf >= 80:
            confidence = "high"
        elif avg_conf >= 50:
            confidence = "medium"
        else:
            confidence = "low"
            warnings.append(f"Low OCR confidence: {avg_conf:.1f}%")

        # Count text regions (blocks)
        block_nums = set(data['block_num'])
        text_regions = len([b for b in block_nums if b > 0])

        result = {
            "success": True,
            "filename": filename,
            "extracted_text": text.strip(),
            "confidence": confidence,
            "metadata": {
                "language_detected": lang,
                "text_regions": text_regions,
                "has_tables": False,
                "has_handwriting": False
            },
            "warnings": warnings
        }

    except Exception as e:
        result = {
            "success": False,
            "filename": filename,
            "extracted_text": "",
            "confidence": "low",
            "metadata": {
                "language_detected": "unknown",
                "text_regions": 0,
                "has_tables": False,
                "has_handwriting": False
            },
            "warnings": [f"OCR failed: {str(e)}"]
        }

    return result

# Usage
result = ocr_to_json("document.jpg", lang="eng")
print(json.dumps(result, indent=2))
```

### Batch Processing Multiple Images

```python
import pytesseract
from PIL import Image
import json
import os
from pathlib import Path

def process_image_directory(directory_path, output_file, lang="eng"):
    """Process all images in a directory and save results."""
    image_extensions = {'.jpg', '.jpeg', '.png', '.webp', '.tiff', '.bmp'}
    results = []

    for file_path in sorted(Path(directory_path).iterdir()):
        if file_path.suffix.lower() in image_extensions:
            result = ocr_to_json(str(file_path), lang=lang)
            results.append(result)

    with open(output_file, 'w') as f:
        json.dump(results, f, indent=2)

    return results
```

## Conflicts
- **benchflow-ai/skillsbench** defines a strict JSON output schema and Python functions for direct calls, while **aipoch/medical-research-skills** uses a config-driven script with natural-language path parsing and does not define the same JSON output schema. Use the appropriate mode based on your workflow.

## Validation and Safety Rules
- Validate required inputs before execution and stop early when mandatory fields or files are missing.
- Do not fabricate measurements, references, findings, or conclusions that are not supported by the provided source material.
- Emit a clear warning when credentials, privacy constraints, safety boundaries, or unsupported requests affect the result.
- Keep the output safe, reproducible, and within the documented scope at all times.

## Failure Handling
- If validation fails, explain the exact missing field, file, or parameter and show the minimum fix required.
- If an external dependency or script fails, surface the command path, likely cause, and the next recovery step.
- If partial output is returned, label it clearly and identify which checks could not be completed.

## Completion Checklist
- Confirm all required inputs were present and valid.
- Confirm the supported execution path completed without unresolved errors.
- Confirm the output conforms to the expected schema or format.