Pdf Ocr Tool

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

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

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

ModeDescriptionUse CaseautoAuto-detect content typeGeneral use (default)textPure text recognitionAcademic papers, articles, reportstableTable recognitionData tables, financial reportsfigureChart/figure recognitionStatistical charts, flowcharts, diagramsmixedMixed modePages with multiple content types

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

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]  ---

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 ])

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