PaddleOcr

中文文档 (Chinese Documentation)

A lightweight, type-safe, dependency-free JavaScript/TypeScript library for PaddleOCR, supporting both Node.js and browser environments.

Features

• Cross-platform: Works in Node.js, Bun, and browser environments.
• Type-safe: Written in TypeScript with full type definitions.
• No dependencies: Minimal footprint, no heavy image processing libraries included.
• Flexible model loading: Accepts model files as ArrayBuffer, allowing custom loading strategies (e.g., fetch, fs.readFileSync).
• ONNX Runtime support: Compatible with both onnxruntime-web and onnxruntime-node.
• Customizable dictionary: Pass your own character dictionary for recognition.
• Modern API: Simple, promise-based API for easy integration.

Installation

npm install paddleocr
# or
yarn add paddleocr
# or
pnpm add paddleocr

Usage

1. Prepare ONNX Runtime and Model Files

• In browser:

  import * as ort from "onnxruntime-web";

• In Node.js or Bun:

  import * as ort from "onnxruntime-node";

2. Load Model Files and Dictionary

You can use fetch, fs.readFileSync, or any other method to load your ONNX model files and dictionary as ArrayBuffer and string array, respectively.

3. Initialize the Service

import { PaddleOcrService } from "paddleocr";

const paddleOcrService = await PaddleOcrService.createInstance({
    ort,
    detection: {
        modelBuffer: detectOnnx,
        minimumAreaThreshold: 24,
        textPixelThreshold: 0.55,
        paddingBoxVertical: 0.3,
        paddingBoxHorizontal: 0.5,
    },
    recognition: {
        modelBuffer: recOnnx,
        charactersDictionary: dict,
        imageHeight: 48,
    },
});

The detection and recognition objects above act as instance defaults. They are applied to every recognize() call unless you override them per request.

4. Prepare Image Data

The recognize method expects an object with width, height, and data (Uint8Array of RGB(A) values). Use your preferred image decoding library (e.g., fast-png, image-js).

import { decode } from "fast-png";
const imageFile = await readFile("tests/image.png");
const buffer = imageFile.buffer.slice(imageFile.byteOffset, imageFile.byteOffset + imageFile.byteLength);
const image = decode(buffer);
const input = {
    data: image.data,
    width: image.width,
    height: image.height,
};

5. Run OCR

const result = await paddleOcrService.recognize(input);
console.log(result);

6. Track Progress

You can pass onProgress to recognize to receive detection and recognition updates in real time.

const result = await paddleOcrService.recognize(input, {
    onProgress(event) {
        console.log(event.type, event.stage, event.progress);

        if (event.type === "rec" && event.stage === "item") {
            console.log("Partial result:", event.result?.text, event.box);
        }
    },
});

Event contract:

• det emits preprocess, infer, and postprocess with fixed progress 1/3, 2/3, 3/3
• rec emits start, one item per detected text box, then complete
• rec/item includes the current result and box
• det/postprocess includes detectedCount

7. Tune Detection, Recognition, and Ordering

You can set defaults when creating the instance, then override them for a single image.

const strictResult = await paddleOcrService.recognize(invoiceInput, {
    detection: {
        minimumAreaThreshold: 40,
        textPixelThreshold: 0.65,
        paddingBoxVertical: 0,
        paddingBoxHorizontal: 0,
        dilationKernelSize: 3,
    },
    recognition: {
        imageHeight: 64,
        charactersDictionary: digitsOnlyDict,
    },
    ordering: {
        sortByReadingOrder: true,
        sameLineThresholdRatio: 0.15,
    },
});

const looseResult = await paddleOcrService.recognize(noteInput, {
    detection: {
        minimumAreaThreshold: 8,
        textPixelThreshold: 0.45,
    },
});

Supported per-call override groups:

• detection: padding, mean, stdDeviation, maxSideLength, paddingBoxVertical, paddingBoxHorizontal, minimumAreaThreshold, textPixelThreshold, dilationKernelSize
• recognition: imageHeight, mean, stdDeviation, charactersDictionary
• ordering: sortByReadingOrder, sameLineThresholdRatio

charactersDictionary can be provided either when creating the instance or per call. If neither is provided, recognize() throws.

8. Control Line Merging in processRecognition

const rawRecognition = await paddleOcrService.recognize(input);
const processed = paddleOcrService.processRecognition(rawRecognition, {
    lineMergeThresholdRatio: 0.8,
});

console.log(processed.text);
console.log(processed.lines);

Model Files

You can find sample models in the assets/ directory:

• PP-OCRv5_mobile_det_infer.onnx
• PP-OCRv5_mobile_rec_infer.onnx
• ppocrv5_dict.txt

Examples

See the examples/ directory for usage samples. About browser usage with Vite, check out paddleocr-vite-example

Contributing

Contributions are welcome! Feel free to submit a PR or open an issue.

License

MIT