Ocr tiered

Tiered OCR

Pick the right OCR engine based on what's available and what the user prioritizes.

The three tiers

Tier	Engine	When to use	Trade-offs
1 — Accuracy	PaddleOCR	Maximum accuracy, especially for Chinese/mixed CJK	Requires Python venv with paddlepaddle + paddleocr (~1 GB)
2 — Balanced	Tesseract + tessdata_best	Good accuracy without heavy Python deps	Downloads best .traineddata on first use; needs tesseract on PATH
3 — Fast	Default Tesseract	Lightweight, no extra downloads, fast	Lower accuracy; uses whatever model ships with the system

Decision guide

• User wants best quality → Tier 1 (if PaddleOCR venv exists or user is okay installing it)
• User wants good quality but no Python deps → Tier 2
• User wants it fast / already has tesseract → Tier 3
• User is unsure → compare mode on one representative page, then pick the winner for the rest

Use this when

• User wants OCR on a scanned image or PDF
• User wants Chinese or mixed Chinese-English OCR
• User has strong accuracy/speed preferences
• User doesn't know what OCR tools are available (cascade finds the best one that works)

Boundaries

• Outputs text files + JSON summaries, not searchable PDFs
• Does not overwrite source files
• Tiers 2/3 require tesseract on PATH; PDF input also needs pdftoppm
• Tier 1 requires a dedicated Python venv (setup below)

Setup (Tier 1 only)

bash scripts/setup_paddleocr_env.sh

Creates .venv-paddleocr/ in this skill directory with paddlepaddle + paddleocr.

Commands

Single tier — when you know which one to use

# Tier 1: best accuracy
.venv-paddleocr/bin/python scripts/ocr_tiered.py tier1 /path/to/page.png

# Tier 2: balanced (no Python venv needed, uses system tesseract)
python3 scripts/ocr_tiered.py tier2 /path/to/page.png

# Tier 3: fast and lightweight
python3 scripts/ocr_tiered.py tier3 /path/to/page.png

Compare — test all tiers on one page, pick the best

.venv-paddleocr/bin/python scripts/ocr_tiered.py compare /path/to/page.png

Cascade — try tier 1 → 2 → 3, stop on first good result

.venv-paddleocr/bin/python scripts/ocr_tiered.py cascade /path/to/file.pdf --pages 100

PDF support

All modes accept PDFs. Use --pages to target specific pages:

.venv-paddleocr/bin/python scripts/ocr_tiered.py tier1 /path/to/file.pdf --pages 1,3-5

Outputs

Written to a sibling directory (<stem>.ocr-tiered/) by default:

• tier1_paddleocr.txt
• tier2_tesseract_best.txt
• tier3_tesseract_default.txt
• summary.json

Tier 1 config details

PaddleOCR runs with quality-oriented defaults:

• lang="ch", use_doc_orientation_classify=True, use_doc_unwarping=True
• use_textline_orientation=True, text_det_limit_type="max", text_det_limit_side_len=1216
• text_det_thresh=0.3, text_det_box_thresh=0.5, text_det_unclip_ratio=1.5

Tier 2 caches downloaded .traineddata in ~/.cache/ocr-tiered/tessdata_best/.

Tier 3 uses whatever tesseract ships with on the system — no extra downloads.