Metadata-Version: 2.4
Name: ocr-locator
Version: 0.1.0
Summary: One-call PaddleOCR workflow: extract text/numbers/symbols, draw bounding boxes, and search for a word/phrase in an image.
Author: Your Name
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: paddlepaddle
Requires-Dist: paddleocr
Requires-Dist: paddlex
Requires-Dist: Pillow
Dynamic: license-file

# 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

```bash
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

```python
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:

```bash
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.
