ppllocr 2.2

Install the ppllocr library directly from PyPI. The library is lightweight, depending only on onnxruntime and numpy, and is optimized for CPU inference (typically <120 ms).

pip install ppllocr

Since ppllocr accepts bytes as input, you can pass the .content attribute from a requests response directly into the OCR methods.

import requests
from ppllocr import OCR

ocr = OCR()

# Fetch image from URL
url = "https://www.luogu.com.cn/lg4/captcha"
img_bytes = requests.get(url).content

# Pass bytes directly
text = ocr.classification(img_bytes)
print(f"Captcha is: {text}")

Use the classification_box method if you need character positions (coordinates) or confidence scores. This method returns a tuple containing the recognized text string and a list of detail dictionaries.

from ppllocr import OCR

ocr = OCR()

with open("captcha_sample.jpg", "rb") as f:
    img_bytes = f.read()

# Returns text and a list of details
text, details = ocr.classification_box(img_bytes)

# details structure:
# [
#   {'char': '2', 'conf': 0.98, 'box': [10.5, 5.0, 30.2, 45.1]},
#   {'char': 'a', 'conf': 0.95, 'box': [35.0, 8.0, 55.0, 48.0]}, ...
# ]
for char_info in details:
    print(f"Char: {char_info['char']}, Conf: {char_info['conf']:.2f}, Box: {char_info['box']}")

You can adjust inference thresholds during the call to classification to balance precision and recall:

• conf: Confidence threshold (default is 0.25). Increasing this improves precision but may lower recall.
• iou: Intersection over Union (NMS) threshold (default is 0.45).

# Example of tuning thresholds
text = ocr.classification(open("hard_sample.jpg", "rb").read(), conf=0.6, iou=0.45)

Use the classification method to get the recognized string from image binary data. The OCR class automatically loads the built-in ONNX models upon initialization. You can pass image bytes directly to the method, making it ideal for web scrapers.

from ppllocr import OCR

# Initialize (automatically loads built-in models)
ocr = OCR()

# Pass image binary data (bytes)
with open("captcha_sample.jpg", "rb") as f:
    img_bytes = f.read()

# Returns the recognized string, e.g., "2a3B"
text = ocr.classification(img_bytes)
print(f"Result: {text}")

The current version of ppllocr supports the following character set:

['#', '%', '*', '+', '-', '/', '0', '1', '2', '3', '4', '5', '6', '7', '8', '9', '=', '?', '@', 'A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K', 'L', 'M', 'N', 'O', 'P', 'Q', 'R', 'S', 'T', 'U', 'V', 'W', 'X', 'Y', 'Z', 'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j', 'k', 'l', 'm', 'n', 'o', 'p', 'q', 'r', 's', 't', 'u', 'v', 'w', 'x', 'y', 'z']

The ppllocr package exposes the OCR class via its entrypoint. This class is used to perform optical character recognition on image data. You can import it directly from ppllocr to initialize the engine and run inference.

from ppllocr import OCR

# Initialize the OCR engine
ocr = OCR()

# Perform recognition (example usage based on package structure)
# result = ocr.classify(image_bytes)

Use the classification_box method to retrieve both the recognized text and detailed metadata for each character. This is useful when you need to know the location and confidence of each character in the image.

from ppllocr.inference import OCR

ocr = OCR()
text, details = ocr.classification_box("path/to/image.png")

for item in details:
    print(f"Char: {item['char']}, Conf: {item['conf']}, Box: {item['box']}")

Use the classification method to get only the recognized text string from an image. This is useful for quick captcha solving where bounding box data is not required.

from ppllocr.inference import OCR

ocr = OCR()
# input_source can be a file path (str), image bytes (bytes), or a numpy array
text = ocr.classification("path/to/image.png", conf=0.25, iou=0.45)
print(f"Recognized text: {text}")

To use the OCR engine, instantiate the OCR class. You can optionally provide a custom path to an ONNX model file or specify whether to use GPU acceleration. If no model_path is provided, the engine automatically attempts to load the default model ppllocr_betav2.2.onnx from the package's assets directory. If use_gpu=True is requested but CUDA is unavailable, the engine will automatically fallback to CPUExecutionProvider.

from ppllocr.inference import OCR

# Initialize with default model and CPU
ocr = OCR()

# Initialize with a custom model and GPU support
ocr = OCR(model_path="path/to/your_model.onnx", use_gpu=True)

The classification_box method returns a tuple containing the recognized string and a list of detail dictionaries. Each dictionary in the list follows this structure:

[
    {
        "char": str,    # The recognized character
        "conf": float,  # Confidence score
        "box": list      # [x1, y1, x2, y2] coordinates
    },
    ...
]

The inference methods (classification, classification_box, predict) accept the following arguments:

input_source (str | bytes | np.ndarray): The image source (file path, raw bytes, or numpy array).
conf (float): Confidence threshold for filtering detections. Default: 0.25.
iou (float): Intersection over Union threshold for Non-Maximum Suppression (NMS). Default: 0.45.