PDF OCR Tool - Intelligent PDF to Markdown Converter

Uses the Ollama GLM-OCR model to intelligently recognize text, tables, and figures in PDF pages, applying the most appropriate prompts for OCR processing and outputting structured Markdown documents.

Features

• ✅ Smart Content Detection: Automatically identifies page content type (text/table/figure)
• ✅ Mixed Mode: Splits pages into multiple regions for processing different content types
• ✅ Multiple Processing Modes: Supports text, table, figure, mixed, and auto modes
• ✅ PDF Page-by-Page Processing: Converts PDF to images and processes each page
• ✅ Image OCR: Supports OCR for single images
• ✅ Custom Prompts: Adjustable OCR prompts based on requirements
• ✅ Flexible Configuration: Customizable Ollama host, port, and model
• ✅ uv Package Management: Uses uv for Python dependency management

Installation

1. Prerequisites

# Install Ollama
curl -fsSL https://ollama.com/install.sh | sh
ollama pull glm-ocr:q8_0

# Install poppler-utils (for PDF to image conversion)
sudo apt install poppler-utils  # Debian/Ubuntu
brew install poppler            # macOS

# Install uv package manager
curl -LsSf https://astral.sh/uv/install.sh | sh

2. Install with uv (Recommended)

cd skills/pdf-ocr-tool
uv venv
source .venv/bin/activate
uv add requests Pillow

3. Install via ClawHub

npx clawhub install pdf-ocr-tool

4. Manual Installation

# Clone or download skill
git clone <repo> ~/.openclaw/workspace/skills/pdf-ocr-tool

# Create virtual environment and install dependencies
cd ~/.openclaw/workspace/skills/pdf-ocr-tool
uv venv
source .venv/bin/activate
uv add requests Pillow

# Run post-install script
bash hooks/post-install.sh

Usage

Basic Usage

# Auto-detect content type (recommended)
python ocr_tool.py --input document.pdf --output result.md

# Specify processing mode
python ocr_tool.py --input document.pdf --output result.md --mode text
python ocr_tool.py --input document.pdf --output result.md --mode table
python ocr_tool.py --input document.pdf --output result.md --mode figure

# Mixed mode: split page into regions
python ocr_tool.py --input document.pdf --output result.md --granularity region

# Process a single image
python ocr_tool.py --input image.png --output result.md --mode mixed

Advanced Configuration

# Specify Ollama host and port
python ocr_tool.py --input document.pdf --output result.md \
  --host localhost --port 11434

# Use different model
python ocr_tool.py --input document.pdf --output result.md \
  --model glm-ocr:q8_0

# Custom prompt
python ocr_tool.py --input image.png --output result.md \
  --prompt "Convert this table to Markdown format, keeping rows and columns aligned"

# Save figure region images
python ocr_tool.py --input document.pdf --output result.md --save-images

Environment Configuration

# Set default configuration
export OLLAMA_HOST="localhost"
export OLLAMA_PORT="11434"
export OCR_MODEL="glm-ocr:q8_0"

# Run
python ocr_tool.py --input document.pdf --output result.md

Processing Modes

Mixed Mode (Granularity)

When using --granularity region:

• Page is split vertically into multiple regions (default: 3)
• Each region is independently analyzed for content type
• Corresponding prompts are used for OCR
• Final results are combined into complete Markdown

Output Format

PDF Output Example

# PDF to Markdown Result
**Total Pages**: 15
**Model**: glm-ocr:q8_0
**Mode**: auto
**Generated**: 2026-02-27T01:00:00+08:00

---

## Page 1
*Type: mixed*

### Region 1 (text)
[OCR recognized text content]

### Region 2 (table)
<table>
<tr><th>Column 1</th><th>Column 2</th></tr>
<tr><td>Data 1</td><td>Data 2</td></tr>
</table>

### Region 3 (figure)
[Chart description]
![Chart](./images/page_1_region_3.png)

---

Image Output Example

# image.png OCR Result
Model: glm-ocr:q8_0
Mode: table

---

[OCR recognized result]

Prompt Templates

The tool includes four built-in prompt templates in the prompts/ directory:

Text Mode (prompts/text.md)

Convert the text in this region to Markdown format.
- Preserve paragraph structure and heading levels
- Handle lists correctly
- Preserve mathematical formulas
- Maintain citations and references

Table Mode (prompts/table.md)

Convert the table in this region to Markdown table format.
- Maintain row and column alignment
- Preserve all data and values
- Handle merged cells
- Preserve headers and units

Figure Mode (prompts/figure.md)

Analyze the chart or image in this region:
1. Chart type (bar, line, pie, flowchart, etc.)
2. Titles and axis labels
3. Data trends and key observations
4. Important values and anomalies
Describe in Markdown format.

Using in OpenClaw

import subprocess
from pathlib import Path

# Process PDF (auto mode)
subprocess.run([
    "python", "skills/pdf-ocr-tool/ocr_tool.py",
    "--input", "/path/to/document.pdf",
    "--output", "/tmp/result.md",
    "--mode", "auto"
])

# Read result
with open("/tmp/result.md", "r") as f:
    markdown_content = f.read()

# Process single image (table mode)
subprocess.run([
    "python", "skills/pdf-ocr-tool/ocr_tool.py",
    "--input", "/path/to/table.png",
    "--output", "/tmp/table.md",
    "--mode", "table"
])

# Mixed mode for complex PDF
subprocess.run([
    "python", "skills/pdf-ocr-tool/ocr_tool.py",
    "--input", "/path/to/mixed.pdf",
    "--output", "/tmp/mixed.md",
    "--granularity", "region",  # Split into regions
    "--save-images"  # Save figure images
])

Troubleshooting

Model Not Installed

ollama pull glm-ocr:q8_0

Service Not Running

ollama serve

Missing pdftoppm

sudo apt install poppler-utils  # Debian/Ubuntu
brew install poppler            # macOS

Poor OCR Results

• Try different modes: --mode text or --mode mixed
• Use custom prompts: --prompt "your prompt here"
• Check image quality (resolution, clarity)
• Try mixed mode: --granularity region

Dependency Issues

cd skills/pdf-ocr-tool
source .venv/bin/activate
uv sync  # Reinstall all dependencies

Related Resources

• Ollama API Documentation
• GLM-OCR Model Page
• poppler-utils
• uv Package Manager

Version History

• v1.2.0 - English prompts, install-deps.sh, fixed .gitignore
• v1.1.0 - Added mixed mode, region splitting, pyproject.toml
• v1.0.0 - Initial version with basic OCR functionality

Credits

This tool is developed and maintained by the OpenClaw community.

License

MIT License