A practical optical character recognition (OCR) toolkit in Python. It extracts text from images and PDFs using Google's Tesseract engine, with an OpenCV preprocessing pipeline that does the heavy lifting for accuracy (denoising, binarization, deskewing). Usable as both a library and a command-line tool.
This is real Python, not a browser demo — Tesseract runs locally, no network or cloud API required.
- Image OCR (
.png,.jpg,.tiff,.bmp,.webp) - Multi-page PDF OCR (each page rendered at 300 DPI and read separately)
- OpenCV preprocessing: grayscale, upscaling, denoise, adaptive/Otsu threshold, deskew
- Per-word confidence scores and structured results (not just a raw string)
- Configurable Tesseract page-segmentation (
--psm) and engine (--oem) modes - Clean CLI with text-file output
Python packages (see requirements.txt):
pytesseract opencv-python pillow numpy pdf2image
System dependencies (these are NOT pip packages):
- Tesseract OCR — the actual recognition engine
- Poppler — used by
pdf2imageto render PDF pages
Install them per platform:
# Debian / Ubuntu
sudo apt-get install tesseract-ocr poppler-utils
# macOS (Homebrew)
brew install tesseract poppler
# Windows: install the Tesseract and Poppler binaries, then add them to PATH.Then the Python side:
pip install -r requirements.txtRun the self-contained demo (it generates its own test image):
python examples/demo.py# Basic image
python cli.py scan.png
# PDF, write result to a file
python cli.py document.pdf -o result.txt
# Tune the pipeline
python cli.py photo.jpg --threshold otsu --no-deskew --min-conf 60from ocr_engine import OCREngine, PreprocessConfig
engine = OCREngine(
lang="eng",
psm=6,
config=PreprocessConfig(threshold="adaptive", deskew=True),
)
# Returns a list of OCRResult (one per page; images are a single page).
for page in engine.read("document.pdf"):
print(f"Page {page.page} — {page.mean_confidence}% confidence")
print(page.text)ocr_project/
├── ocr_engine/
│ ├── __init__.py # public API
│ ├── preprocess.py # OpenCV cleanup pipeline (accuracy lives here)
│ ├── engine.py # core OCR + confidence scoring
│ └── pdf_handler.py # PDF -> images
├── examples/
│ └── demo.py # generates a test image and runs OCR
├── cli.py # command-line interface
├── requirements.txt
└── README.md
- Load the input. PDFs are rendered to images at 300 DPI; image files are read directly with OpenCV.
- Preprocess each image: convert to grayscale, upscale small inputs, denoise, binarize (adaptive thresholding handles uneven lighting well), and deskew slightly-rotated scans by estimating the dominant text angle.
- Recognize with Tesseract via
pytesseract, collecting both the full text and per-word bounding boxes + confidence. - Return an
OCRResultwith the text, mean confidence, and word data.
- Bad results on a photo? Try
--threshold otsufor high-contrast scans, or--threshold noneif your image is already clean. - Text on one line getting merged/split oddly? Experiment with
--psm(e.g.7for a single line,3for fully automatic,11for sparse text). - Other languages: install the Tesseract language pack
(
apt-get install tesseract-ocr-fra) and pass--lang fra(oreng+fra).
MIT — do whatever you like with it.