ONNX-based OCR (PP-OCRv5)

0.0.14 · active · verified Thu Apr 16

`onnxocr-ppocrv5` is a Python library providing an ONNX-based inference pipeline for Baidu's PP-OCRv5. It aims for efficient optical character recognition by leveraging ONNX Runtime for high-performance inference. The current version is 0.0.14, and releases appear to be infrequent, typically focusing on specific model updates or bug fixes.

Common errors

```
ModuleNotFoundError: No module named 'onnxocr_ppocrv5'
```
cause The `onnxocr-ppocrv5` package is not installed in your current Python environment.

fix Install the package using pip: `pip install onnxocr-ppocrv5`.
```
onnxruntime.capi.onnxruntime_pybind11_state.RuntimeException: [ONNXRuntimeError] : 2 : INVALID_ARGUMENT : Failed to load model from ...
```
cause This usually indicates an issue with the downloaded ONNX model files, such as corruption during download, insufficient disk space, or incorrect permissions.

fix Ensure you have an internet connection during the first run. Check disk space. If the issue persists, try deleting the cached model directory (often in `~/.cache/onnxocr_ppocrv5` or similar) to force a re-download. Check for proxy or firewall issues.
```
FileNotFoundError: [Errno 2] No such file or directory: 'path/to/your/image.jpg'
```
cause The image file specified in the `ocr()` call does not exist at the provided path, or the path is incorrect.

fix Double-check the image file path for typos and ensure the file actually exists at that location relative to where your script is running. Use absolute paths or `os.path.join` for robustness.

Warnings

gotcha Model files are automatically downloaded during the first initialization of the `OnnxOCR` object. This process requires an active internet connection and can download significant data (hundreds of MBs), potentially causing delays on the first run.
Fix: Ensure an active internet connection and sufficient disk space for model storage (~500 MB). The models are cached locally for subsequent runs.
gotcha By default, `onnxocr-ppocrv5` installs `onnxruntime` (the CPU version). For GPU acceleration, you must manually uninstall `onnxruntime` and install `onnxruntime-gpu`.
Fix: To enable GPU inference: `pip uninstall onnxruntime` then `pip install onnxruntime-gpu` (ensure you have compatible CUDA drivers and toolkit installed).
gotcha The library is in early development (0.0.x versions). While core functionality is generally stable, the API might undergo minor changes or refinements in future patch releases without explicit breaking change notifications.
Fix: Pin the exact version in your `requirements.txt` (`onnxocr-ppocrv5==0.0.14`) for production environments. Regularly check the GitHub repository for updates and release notes.
gotcha Incorrect image paths or unsupported image formats (e.g., corrupted files, uncommon extensions) passed to the `ocr()` method will result in errors, typically `FileNotFoundError` or internal `OpenCV` errors.
Fix: Always verify that the image path exists and points to a valid, supported image file (e.g., JPG, PNG, BMP). Use `os.path.exists()` for paths.

Install

pip install onnxocr-ppocrv5 Install latest version

Imports

OnnxOCR
```
from onnxocr_ppocrv5 import OnnxOCR
```

Quickstart

This quickstart demonstrates how to initialize the `OnnxOCR` model and perform OCR on a local image file. The model automatically downloads necessary ONNX files on the first run, which requires an internet connection and sufficient disk space.

import os
from onnxocr_ppocrv5 import OnnxOCR

# NOTE: Replace with a path to your actual image file
# For demonstration, we assume an image 'example.png' exists in the current directory
# In a real application, you might download or provide an actual image path.
image_path = os.environ.get('OCR_IMAGE_PATH', 'example.png')

# The first initialization will automatically download necessary models (~300-500 MB)
# This requires an internet connection and can take some time.
print("Initializing OnnxOCR model... (models will download on first run)")
ocr = OnnxOCR()
print("OCR model initialized.")

# Perform OCR on an image file path
# Ensure the image_path points to a valid image accessible by the script.
if os.path.exists(image_path):
    try:
        result = ocr(image_path)
        print("OCR Result:")
        for box_info in result:
            # Each box_info is a dictionary with 'box' and 'text'
            print(f"  Text: {box_info['text']}, Box: {box_info['box']}")
    except Exception as e:
        print(f"Error performing OCR: {e}")
        print("Please ensure the image_path is valid and the image is not corrupt.")
else:
    print(f"Error: Image file not found at '{image_path}'. Please provide a valid image path.")

view raw JSON →