Skip to content
BranchesTags

Repository files navigation

simple-ppocr5

English | 中文

中文

简介

基于百度 PaddleOCR PP-OCRv5 模型的简易 Python OCR 库，使用 ONNXRuntime 推理，支持中英文文本检测与识别，几行代码即可完成图片文字提取。

特性

  • 轻量封装：一个类即可完成加载模型、检测、方向分类与识别
  • ONNXRuntime 推理：支持 CPU / GPU（CUDAExecutionProvider）
  • 检测+识别一体化：自动完成文本框检测、角度分类与文本识别
  • 简易可视化：内置 displaybox 方法，可直接画出检测框查看效果
  • 易于集成：既可作为脚本运行，也可在其他 Python 项目中 import simple_ppocr5 作为库使用
  • HTTP 服务：提供生产级 HTTP API 服务（可选）

环境与依赖

  • Python: 3.7+
  • 依赖:
    • onnxruntime 或 onnxruntime-gpu
    • opencv-python

说明：opencv-python 依赖 numpy，通常会自动一并安装，无需单独声明。

安装依赖：

pip install -r requirements.txt

模型文件

本项目使用 PaddleOCR PP-OCRv5 的 ONNX 导出模型：

  • models/ppocr5_m_det.onnx — 文本检测模型
  • models/ppocr5_m_cls.onnx — 方向分类模型
  • models/ppocr5_m_rec.onnx — 文本识别模型
  • models/ppocr5_dict.txt — 字典文件

说明：模型文件来源于 PaddleOCR 项目，请参考 PaddleOCR 官方文档下载原始模型并转换为 ONNX，或使用本仓库提供的下载方式。使用模型时请遵守其原始许可证和使用条款。

将上述文件放到仓库根目录下的 models/ 目录，保持默认路径，即可正常使用。

安装与使用

克隆仓库并安装依赖：

git clone https://github.com/wanghanmin/simple-ppocr5.git
cd simple-ppocr5
pip install -r requirements.txt

快速上手

下面是一个最小示例，演示如何对单张图片进行 OCR：

from simple_ppocr5 import simple_ppocr5

# 初始化 OCR 引擎
ocr = simple_ppocr5()

# 对图片进行识别
ocr.run("path/to/your/image.jpg")

# 打印所有识别结果
for item in ocr.results:
    text = item['text']
    box = item['rec_pos']
    print(text, box)

# 可视化检测框
ocr.displaybox("OCR Result")

更多示例可以参考仓库根目录中的 ocr_image.py 和 winclip_ocr.py。

示例

1. 命令行 OCR

  • ocr_image.py
    从本地图片进行 OCR，打印全部文本与框位置、性能统计，并可视化检测框；支持命令行参数传入图片路径（无参数时默认使用 example.jpg）

  • winclip_ocr.py
    Windows 截图/剪贴板 OCR 示例

运行示例：

python ocr_image.py                         # 使用默认 example.jpg
python ocr_image.py path/to/your_image.jpg  # 指定图片路径
python winclip_ocr.py                       # Windows 剪贴板 OCR

2. HTTP API 服务

  • ocr-http-service.py
    提供生产级 HTTP API 服务，支持接收 base64 编码的图片，返回 JSON 格式的 OCR 结果

安装额外依赖：

pip install flask waitress

启动服务：

# 使用默认配置（0.0.0.0:11005，CPU 模式）
python ocr-http-service.py

# 指定端口
python ocr-http-service.py --port 8080

# 指定 IP 和端口
python ocr-http-service.py --host 127.0.0.1 --port 8080

# 启用 GPU 模式
python ocr-http-service.py --gpu

# 完整配置
python ocr-http-service.py --host 0.0.0.0 --port 8080 --threads 8 --gpu

# 查看帮助
python ocr-http-service.py --help

启动参数：

  • --host: 绑定的 IP 地址（默认：0.0.0.0）
  • --port: 绑定的端口号（默认：11005）
  • --threads: 工作线程数（默认：4）
  • --gpu: 启用 GPU 加速（默认：CPU 模式）

API 调用示例：

import requests
import base64

# 读取图片并转换为 base64
with open("image.jpg", "rb") as f:
    image_base64 = base64.b64encode(f.read()).decode('utf-8')

# 发送 POST 请求
response = requests.post(
    "http://localhost:11005/ocr",
    json={"image": image_base64}
)

# 查看结果
result = response.json()
print(f"OCR 处理时间: {result['processing_time']:.3f}s")
for item in result['results']:
    print(f"文本: {item['text']}")
    print(f"位置: {item['bounding_box']}")

返回格式：

{
  "processing_time": 0.523,
  "decode_time": 0.012,
  "total_time": 0.535,
  "results": [
    {
      "text": "识别的文本",
      "bounding_box": [[x1, y1], [x2, y2], [x3, y3], [x4, y4]]
    }
  ]
}

注意事项

  • 模型文件体积较大，首次下载可能需要一定时间
  • 使用 GPU 推理需要正确安装 CUDA 和 onnxruntime-gpu
  • 当前实现主要面向中英文场景，如需其他语种，可更换识别模型与字典文件

协议与致谢

本项目推荐使用 Apache-2.0 License 开源（与 PaddleOCR 一致）。

本项目基于 PaddleOCR 的 PP-OCRv5 模型与相关技术实现，特此致谢 PaddleOCR 及其开发团队。

English

Introduction

A simple Python OCR library based on Baidu PaddleOCR PP-OCRv5 models, running on ONNXRuntime. It supports Chinese and English text detection and recognition with a lightweight and easy-to-use API.

Features

  • Lightweight Wrapper: One class handles model loading, detection, orientation classification, and recognition
  • ONNXRuntime Inference: Supports both CPU and GPU (CUDAExecutionProvider)
  • All-in-One Detection & Recognition: Automatically performs text box detection, angle classification, and text recognition
  • Easy Visualization: Built-in displaybox method to draw detection boxes
  • Easy Integration: Can be used as a script or imported as a library in other Python projects
  • HTTP Service: Production-ready HTTP API service (optional)

Environment & Dependencies

  • Python: 3.7+
  • Dependencies:
    • onnxruntime or onnxruntime-gpu
    • opencv-python

Note: opencv-python depends on numpy, which is usually installed automatically.

Install dependencies:

pip install -r requirements.txt

Model Files

This project uses PaddleOCR PP-OCRv5 ONNX exported models:

  • models/ppocr5_m_det.onnx — Text detection model
  • models/ppocr5_m_cls.onnx — Orientation classification model
  • models/ppocr5_m_rec.onnx — Text recognition model
  • models/ppocr5_dict.txt — Dictionary file

Note: Model files are from the PaddleOCR project. Please refer to PaddleOCR official documentation to download and convert original models to ONNX format, or use the download method provided by this repository. Please comply with the original license and terms of use when using the models.

Place these files in the models/ directory under the repository root to use the default paths.

Installation & Usage

Clone the repository and install dependencies:

git clone https://github.com/wanghanmin/simple-ppocr5.git
cd simple-ppocr5
pip install -r requirements.txt

If published to PyPI in the future, you can use:

pip install simple-ppocr5

Quick Start

Here is a minimal example to run OCR on a single image:

from simple_ppocr5 import simple_ppocr5

# Initialize OCR engine
ocr = simple_ppocr5()

# Run OCR on an image
ocr.run("path/to/your/image.jpg")

# Print all recognition results
for item in ocr.results:
    text = item['text']
    box = item['rec_pos']
    print(text, box)

# Visualize detected boxes
ocr.displaybox("OCR Result")

For more examples, please refer to ocr_image.py and winclip_ocr.py in the repository root.

Examples

1. Command Line OCR

  • ocr_image.py
    Perform OCR on local images, print all text and box positions with performance statistics, and visualize detection boxes. Supports command line arguments to specify image path (defaults to example.jpg if not specified)

  • winclip_ocr.py
    Windows screenshot/clipboard OCR example

Run examples:

python ocr_image.py                         # Use default example.jpg
python ocr_image.py path/to/your_image.jpg  # Specify image path
python winclip_ocr.py                       # Windows clipboard OCR

2. HTTP API Service

  • ocr-http-service.py
    Production-ready HTTP API service that accepts base64-encoded images and returns OCR results in JSON format

Install additional dependencies:

pip install flask waitress

Start the service:

# Use default settings (0.0.0.0:11005, CPU mode)
python ocr-http-service.py

# Specify port
python ocr-http-service.py --port 8080

# Specify host and port
python ocr-http-service.py --host 127.0.0.1 --port 8080

# Enable GPU mode
python ocr-http-service.py --gpu

# Full configuration
python ocr-http-service.py --host 0.0.0.0 --port 8080 --threads 8 --gpu

# Show help
python ocr-http-service.py --help

Command line options:

  • --host: Host address to bind (default: 0.0.0.0)
  • --port: Port number to bind (default: 11005)
  • --threads: Number of worker threads (default: 4)
  • --gpu: Enable GPU acceleration (default: CPU mode)

API usage example:

import requests
import base64

# Read image and convert to base64
with open("image.jpg", "rb") as f:
    image_base64 = base64.b64encode(f.read()).decode('utf-8')

# Send POST request
response = requests.post(
    "http://localhost:11005/ocr",
    json={"image": image_base64}
)

# View results
result = response.json()
print(f"OCR processing time: {result['processing_time']:.3f}s")
for item in result['results']:
    print(f"Text: {item['text']}")
    print(f"Position: {item['bounding_box']}")

Response format:

{
  "processing_time": 0.523,
  "decode_time": 0.012,
  "total_time": 0.535,
  "results": [
    {
      "text": "Recognized text",
      "bounding_box": [[x1, y1], [x2, y2], [x3, y3], [x4, y4]]
    }
  ]
}

Notes

  • Model files are large and may take time to download initially
  • GPU inference requires proper installation of CUDA and onnxruntime-gpu
  • Current implementation is mainly for Chinese and English. For other languages, replace the recognition model and dictionary file

License & Acknowledgements

This project is recommended to use Apache-2.0 License (consistent with PaddleOCR).

This project is based on the PP-OCRv5 models and related technologies from PaddleOCR. Special thanks to PaddleOCR and its development team.

About

Fast PP-OCRv5 ONNXRuntime-based OCR with only OpenCV as dependency (lightweight, CPU & GPU friendly)

Resources

Readme
Apache-2.0 license
Activity

Stars

5 stars

Watchers

1 watching

Forks

1 fork
Report repository

Releases

Packages

Contributors

Languages