ocr-locator

A tiny Python package that wraps a full PaddleOCR workflow — engine setup, text/number/symbol extraction, bounding-box drawing, and word search — behind a single class or one CLI command, so you don't have to re-copy notebook cells every time.

Install

pip install ocr-locator

(Or, from a local checkout: pip install .)

First run downloads PaddleOCR's model weights automatically — no manual setup needed.

Usage

Python API

from ocr_locator import OCRLocator

ocr = OCRLocator()  # loads the PaddleOCR engine once (put outside any loop)

# 1. Extract all text/numbers/symbols with boxes
extracted = ocr.extract("screenshot.png")
# -> [{"text": "Login", "score": 0.98, "box": [120, 40, 210, 70]}, ...]

# 2. Draw a box + label around every detection
annotated_path = ocr.annotate("screenshot.png", extracted, output_path="out.png")

# 3. Search for a word/phrase; matches are highlighted in a separate image
result = ocr.search("screenshot.png", extracted, "Login")
result["found"]           # True/False
result["matches"]         # matching detection dicts
result["annotated_path"]  # path to the highlighted image, if found

Command line

Runs the whole workflow — extract, annotate, search — in one shot:

ocr-locate screenshot.png --search "Login" --output detected.png --json-output detections.json

Omit --search and you'll be prompted interactively; pass --no-prompt to skip search entirely and just get the all-boxes annotated image.

What it handles for you

• Dependency management — paddlepaddle, paddleocr, paddlex, and Pillow declared in pyproject.toml.
• Engine initialization — PaddleOCR(...) created once per OCRLocator instance, with enable_mkldnn=False set by default to avoid a known oneDNN runtime crash.
• Box normalization — handles rectangles, 4-point polygons, and flattened 8-number quads, whatever shape PaddleOCR returns.
• Drawing — labeled bounding boxes for every detection, with separate colors for "all detections" vs. "search matches".
• Search — case-insensitive substring or exact match, with match details printed and a highlighted image saved automatically.

Package layout

ocr_locator/
├── __init__.py     # public API: OCRLocator
├── config.py        # default confidence, colors, font, PaddleOCR init kwargs
├── core.py            # OCRLocator class: extract(), annotate(), search()
├── utils.py            # to_rect() box-shape normalizer
└── cli.py                # `ocr-locate` command line entry point

Notes

• Unlike the original notebook, this package does not force an interactive Colab file upload/download — you pass a file path in and get a file path out, so it works the same in a script, a notebook, or a server.
• ocr.extract() is a pure function-ish call you can run once and reuse for both annotate() and multiple search() calls without re-running OCR.