← Models

CV / PPOCR

PPOCR

End-to-end text detection and recognition using RKNN PPOCR-Det and PPOCR-Rec.

23 downloads
Precision
RKNN

Choose the device you're using, the set up guide and documentation will update accordingly.

Getting Started

Deploy
sudo docker run --rm --privileged --net=host \
  -e PYTHONUNBUFFERED=1 -e RKNN_LOG_LEVEL=0 \
  -v /proc/device-tree/compatible:/proc/device-tree/compatible:ro \
  ghcr.io/seeed-projects/recomputer-rk-cv/rk3576-ppocr:latest \
  python web_service.py --platform rk3576 --model_dir /app/model --host 0.0.0.0 --port 8000

REST API

Use the REST API to run inference. Copy the commands below.

Curl
curl http://localhost:8080/v1/chat/completions -d '{
  "model": "ppocr-rknn",
  "messages": [{"role": "user", "content": "Hello"}]
}'
Python
import requests

resp = requests.post(
    "http://localhost:8080/v1/chat/completions",
    json={"model": "ppocr-rknn", "messages": [{"role": "user", "content": "Hello"}]},
)
print(resp.json())

Model Details

Quick Start

1. Install Docker

Run the following commands on the development board to install Docker:

bash
# Download installation script
curl -fsSL https://get.docker.com -o get-docker.sh
# Install using Aliyun mirror source
sudo sh get-docker.sh --mirror Aliyun
# Start Docker and enable auto-start on boot
sudo systemctl enable docker
sudo systemctl start docker

2. Run the Project (One command, dual-mode preview)

This end-to-end OCR service comes from reComputer-RK-CV. It detects text polygons, sorts them into reading order, perspective-rectifies each crop, and recognizes every text line.

Model Information

ComponentFile
Text detectormodel/ppocr_det.rknn
Text recognizermodel/ppocr_rec.rknn
Character dictionarymodel/ppocr_keys_v1.txt
Annotation fontmodel/simfang.ttf
OutputText, confidence, quadrilateral coordinates, crops, and latency

PPOCR supports still images only. The upstream service intentionally does not include camera, local-video, or MP4-analysis controls.

Step A: Pull Images

bash
sudo docker pull ghcr.io/seeed-projects/recomputer-rk-cv/rk3588-ppocr:latest
sudo docker pull ghcr.io/seeed-projects/recomputer-rk-cv/rk3576-ppocr:latest

Step B: Run with One Click

For RK3576:

bash
sudo docker run --rm --privileged --net=host \
  -e PYTHONUNBUFFERED=1 -e RKNN_LOG_LEVEL=0 \
  -v /proc/device-tree/compatible:/proc/device-tree/compatible:ro \
  ghcr.io/seeed-projects/recomputer-rk-cv/rk3576-ppocr:latest \
  python web_service.py --platform rk3576 --model_dir /app/model \
  --host 0.0.0.0 --port 8000

For RK3588:

bash
sudo docker run --rm --privileged --net=host \
  -e PYTHONUNBUFFERED=1 -e RKNN_LOG_LEVEL=0 \
  -v /proc/device-tree/compatible:/proc/device-tree/compatible:ro \
  ghcr.io/seeed-projects/recomputer-rk-cv/rk3588-ppocr:latest \
  python web_service.py --platform rk3588 --model_dir /app/model \
  --host 0.0.0.0 --port 8000

Open http://<BOARD_IP>:8000 or /docs.

🔌 API Documentation

1. OCR Interface (Predict)

Endpoint: POST /api/models/ppocr/predict

Request Parameters (Multipart/Form-Data):

FieldRequiredDefaultDescription
fileYes—JPG, PNG, BMP, or WEBP image.
det_thresholdNo0.3Pixel-map detection threshold from 0 to 1.
box_thresholdNo0.6Minimum DB text-box score.
unclip_ratioNo1.5Polygon expansion ratio from 0.1 to 5.
drop_scoreNo0.5Minimum recognition confidence included in combined text.
max_resultsNo100Maximum regions sent to recognition.
include_cropsNofalseInclude base64 JPEG crops in result lines.

Usage Examples:

bash
curl -X POST "http://<BOARD_IP>:8000/api/models/ppocr/predict" \
  -F "file=@document.jpg" -F "drop_score=0.5" \
  -F "include_crops=false"

Response Format (JSON):

json
{
  "success": true,
  "model": "ppocr",
  "result": {
    "text": "Recognized first line\nRecognized second line",
    "lines": [
      {
        "index": 1,
        "text": "Recognized first line",
        "confidence": 0.9621,
        "accepted": true,
        "box": [[42, 31], [286, 29], [287, 72], [43, 74]]
      }
    ],
    "count": 2,
    "timing_ms": {"detection": 54.2, "recognition": 71.4, "total": 129.8}
  }
}

2. System Configuration Interface (Config)

  • GET /api/config: Returns the current detection and recognition defaults.
  • POST /api/config: Updates any supported threshold or result-limit field.

Other endpoints provide health state, the latest structured result, the latest annotated JPEG, and interactive OpenAPI documentation at /docs.

Detection quality directly affects recognition. Very small, blurred, curved, vertical, low-contrast, or heavily rotated text may be missed, and the simple reading-order heuristic may not suit complex multi-column documents. include_crops=true increases the response size and is intended mainly for the Web results panel. The detector and recognizer are pipeline stages and must remain compatible with the character dictionary and perspective-crop logic.

3. Command Line Arguments

ArgumentDefaultDescription
--platformRequiredrk3576 or rk3588.
--model_dirmodelModels, dictionary, font, and sample image.
--imageNoneStill image analyzed before server startup.
--outputNoneAnnotated JPG/PNG path for --image.
--no_serverOffExit after processing --image.
--host / --port0.0.0.0 / 8000Service address and port.

To analyze one mounted image, save the annotation, print JSON, and exit:

bash
python web_service.py --platform rk3576 --model_dir model \
  --image /data/document.jpg --output /data/document_result.jpg --no_server

🛠️ Developer Guide (Production Recommendations)

Build Local Images

bash
docker build -f docker/rk3576/ppocr.dockerfile \
  -t rk3576-ppocr:local src/rk3576_ppocr

docker build -f docker/rk3588/ppocr.dockerfile \
  -t rk3588-ppocr:local src/rk3588_ppocr

Inputs and Outputs

Input: still image. Output: ordered text lines, confidence scores, quadrilaterals, and annotated image.