clipocr 0.1.0

Cross-platform screenshot & clipboard OCR with bbox, powered by RapidOCR.

clipocr

Cross-platform screenshot & clipboard OCR for Python. Powered by RapidOCR. Returns text plus bounding boxes. Works on macOS / Windows / Linux.

中文文档

Why

You took a screenshot. You want the text out of it — without uploading it anywhere.

clipocr reads the image directly from your clipboard or a file, runs a fast on-device OCR model, and gives you back:

• the recognized text (in reading order),
• a list of Blocks, each with text, bbox (xmin, ymin, xmax, ymax) and confidence,
• and overall metadata (engine, image size, average confidence).

Good for: error-screenshot to text, code screenshots, UI mock review, document snippets, anything where you don't want to send your image to a cloud API.

Install

pip install clipocr

The first run downloads ~15 MB of ONNX models into your site-packages (one-time, then cached).

Quick start

Python

from clipocr import ocr, ocr_clipboard

# From a file path
result = ocr("screenshot.png")
print(result.text)
for block in result.blocks:
    print(block.bbox, block.text, block.confidence)

# From the system clipboard
result = ocr_clipboard()
print(result.text)

OcrResult is a frozen dataclass:

result.text         # str  — full text in reading order, joined by "\n"
result.blocks       # list[Block] — text + bbox + confidence per region
result.confidence   # float — average confidence, 0..1
result.engine       # "rapidocr"
result.image_size   # (width, height)
result.is_empty     # True when no text was found
result.to_dict()    # JSON-serializable dict

CLI

clipocr screenshot.png              # plain text
clipocr screenshot.png --bbox       # text with bounding boxes
clipocr screenshot.png --json       # full result as JSON
clipocr --clip                      # read image from clipboard
clipocr --version

Set CLIPOCR_VERBOSE=1 to keep RapidOCR's INFO logs visible.

Platform notes

Platform	Clipboard backend
macOS	Pillow ImageGrab.grabclipboard()
Windows	Pillow ImageGrab.grabclipboard()
Linux (Wayland)	wl-paste --type image/png
Linux (X11)	xclip -selection clipboard -t image/png -o

On Linux, install wl-clipboard (Wayland) or xclip (X11) to enable --clip.

Languages

clipocr ships with the default RapidOCR PP-OCRv4 mobile models. They handle:

• Simplified & Traditional Chinese
• English (Latin alphabet)
• Numbers and common punctuation

Mixed Chinese + English content works out of the box.

Development

git clone https://github.com/lidongyangLeo/clipocr.git
cd clipocr

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

pytest                       # unit tests with coverage
pytest -m integration        # also exercise the real RapidOCR engine
ruff check src tests         # lint

The test suite enforces ≥ 90% coverage via pytest-cov.

How it works

┌──────────────────┐     ┌─────────────┐     ┌──────────┐
│ image / clipboard │ --> │ RapidOCR    │ --> │ OcrResult │
└──────────────────┘     │ (ONNX, on-device) │  └──────────┘
                         └─────────────┘

clipocr is a thin shim around RapidOCR. It contributes:

1. A clean Python API (ocr / ocr_clipboard / OcrResult).
2. A cross-platform clipboard adapter.
3. Reading-order block sorting (top-to-bottom rows, left-to-right within a row).
4. A version-tolerant engine output normalizer (works with both legacy rapidocr-onnxruntime and the new rapidocr >= 2.x).
5. A clipocr CLI with stdout-clean defaults.

Contributing

Issues and PRs welcome. Please run the tests and ruff check before submitting.

License

MIT — see LICENSE.