Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

2 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Python OCR Project

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.

Features

  • 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

Requirements

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 pdf2image to 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.txt

Quick start

Run the self-contained demo (it generates its own test image):

python examples/demo.py

As a command-line tool

# 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 60

As a library

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

Project structure

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

How it works

  1. Load the input. PDFs are rendered to images at 300 DPI; image files are read directly with OpenCV.
  2. 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.
  3. Recognize with Tesseract via pytesseract, collecting both the full text and per-word bounding boxes + confidence.
  4. Return an OCRResult with the text, mean confidence, and word data.

Tuning tips

  • Bad results on a photo? Try --threshold otsu for high-contrast scans, or --threshold none if your image is already clean.
  • Text on one line getting merged/split oddly? Experiment with --psm (e.g. 7 for a single line, 3 for fully automatic, 11 for sparse text).
  • Other languages: install the Tesseract language pack (apt-get install tesseract-ocr-fra) and pass --lang fra (or eng+fra).

License

MIT — do whatever you like with it.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages