OCR Recognition — On-Device Execution

Overview

The OCR module performs image recognition
The OCR module uses the ocrAgent prefix, e.g. ocrAgent.initOcr()
Currently includes appleVision

ocrAgent.releaseAll Release All Instances

Release all instances
Requires EC 9.0.0+

1
// See code examples below

ocrAgent.initOcr Initialize

Initialize the OCR module
@param map Parameter map with the following keys:
type: OCR type; appleVision = iOS built-in Vision module
For appleVision, use: {"type":"appleVision","level":"fast","languages":"zh-Hans,en-US"}
level: fast = fast mode, accurate = accurate mode
languages: Recognition languages; default zh-Hans,en-US (Simplified Chinese and English)
Supported: ["en-US", "fr-FR", "it-IT", "de-DE", "es-ES", "pt-BR", "zh-Hans", "zh-Hant"]
@return {bool} true on success, false on failure

appleVision OCR example

1
function main() {
2

3
 let appleVision = {
4
 "type": "appleVision"
5
 }
6
 ocrAgent.releaseAll()
7
 let inited = ocrAgent.initOcr(appleVision)
8
 logd("init result -" + inited);
9
 if (!inited) {
10
 loge("error : " + ocrAgent.getErrorMsg());
11
 return;
12
 }
13

14
 for (var ix = 0; ix < 20; ix++) {
15

16
 // Read bitmap
17
 let img = imageAgent.captureFullScreen();
18
 if (!img) {
19
 loge("failed to read image");
20
 continue;
21
 }
22
 console.time("1")
23
 logd("start---ocr");
24
 // Recognize image
25
 let result = ocrAgent.ocrImage(img, 20 * 1000, {});
26
 logd(result)
27
 if (result) {
28
 logd("ocr result -> " + JSON.stringify(result));
29
 for (var i = 0; i < result.length; i++) {
30
 var value = result[i];
31
 logd("text : " + value.label + " x: " + value.x + " y: " + value.y + " width: " + value.width + " height: " + value.height);
32
 }
33
 } else {
34
 logw("no result");
35
 }
36

37
 logd("elapsed: " + console.timeEnd(1) + " ms")
38
 imageAgent.recycle(img)
39
 sleep(1000);
40
 logd("ix = " + ix)
41
 }
42
 // Release all resources
43
 ocrAgent.releaseAll();
44
}
45

46
main();

ocrAgent.ocrImage Recognize Text

Perform OCR on an AutoImage; returns JSON data like:

1
 [
2
 {
3
 "label": "奇趣装扮三阶盘化",
4
 "confidence": 0.48334712,
5
 "x": 11,
6
 "y": 25,
7
 "width": 100,
8
 "height": 100
9
 }
10
]

label: recognized text
confidence: recognition confidence
x: X start coordinate
Y: Y start coordinate
width: width
height: height
@param bitmap Image
@param timeout Timeout in milliseconds
@param extra Extra parameters as a map, e.g. {"token":"xxx"}
@return {json} JSON object

1
See OCR initialization examples

ocr.getErrorMsg Get Error Message

Get OCR error message
@return {string} null means no error

1
See OCR initialization examples

ocrAgent.releaseAllEx Release OCR Resources

Release OCR resources
@return {bool} true on success, false on failure

1
See OCR initialization examples

Multi-Instance OCR Mode

ocrAgent.newOcr Create Instance

Create an OCR instance
@return {OcrInstAgent|null}

1
See OCR initialization examples

initOcr Initialize OCR

Initialize the OCR module
@param map Parameter map with the following keys:
type: OCR type — paddleOcrNcnnV5 = NCNN PPOCR-v5, ocrLite = ocrLite, paddleLiteOcr = paddleLite, appleVision = iOS Vision module
For appleVision:
Use: {"ocrType":"appleVision","level":"fast","languages":"zh-Hans,en-US"}
level: fast = fast mode, accurate = accurate mode
languages: Recognition languages; default zh-Hans,en-US (Simplified Chinese and English)
Supported: [“en-US”, “fr-FR”, “it-IT”, “de-DE”, “es-ES”, “pt-BR”, “zh-Hans”, “zh-Hant”]
For paddleNcnnOcrV5:
numThread: Thread count; -1 = all, -2 = half of device CPUs, 0 = unset. Adjust for recognition speed
modelsDir: Model directory path; omit to use built-in models
padding: White border around image to improve recognition when text boxes are incomplete; default 32
maxSideLen If the longest image side exceeds max_side_len, scale it down proportionally; default 640
keysName: Label file name, e.g. keys.txt; omit for built-in models
detName: Detection model file name (param suffix) under modelsDir; e.g. det.param → write det
recName: Recognition model file name (onnx suffix) under modelsDir; e.g. rec.param → write rec
For paddleLiteOcr (paddleLiteOcr = paddleLite; paddleOnnxOcr = onnxruntime PPOCR-v5; onnxruntime and paddlelite conflict, so onnx reimplements paddlelite):
Use: {"ocrType":"paddleLiteOcr","cpuThreadNum":2}
cpuThreadNum: CPU threads; omit if unknown. -1 = all CPUs, -2 = half
modelPath: Model path; external e.g. /sdcard/models/; omit for built-in models
labelPath: Label file path, e.g. /sdcard/labels/ppocr_keys_v1.txt; omit for built-in models
detModelFilename: Detection model filename (.onnx) under modelPath; omit for built-in models
recModelFilename: Recognition model filename (.onnx) under modelPath; omit for built-in models
clsModelFilename: Classification model filename (.onnx) under modelPath; omit for built-in models
padding: White border around image; default 10
boxThresh Text/background segmentation threshold [0,1]; default 0.3
boxScoreThresh Detection box retention threshold [0,1]; default 0.5
unClipRatio Text box size multiplier [1.6, 2.0]; default 1.6
doAngle: 1 enable / 0 disable text orientation detection; default 1
mostAngle: 1 enable / 0 disable angle voting; default 1
maxSideLen: Scale longest side; default 960
For ocrLite:
Use: {"ocrType":"ocrLite","numThread":2,"padding":10,"maxSideLen":0}
numThread: Thread count
padding: Add white border around image to improve recognition
maxSideLen: Scale by longest side; 0 = no scaling. E.g. 1024 scales down if longer than 1024; scales up to 32 if shorter than 32
@return {boolean} true on success, false on failure

1
function usbagentocr() {
2
 ocrAgent.releaseAll()
3
 let ocrInstance = ocrAgent.newOcr();
4
 logd(ocrInstance.ocrId)
5
 // numThread should not be too large or recognition may fail
6
 let ocrLiteConfig = {"ocrType": "ocrLite", "numThread": 2, "padding": 10, "maxSideLen": 960}
7
 // apple vision config
8
 let appleVisionConfig = {"ocrType": "appleVision", "level": "accurate", "languages": "zh-Hans,en-US"}
9
 // paddleOnnxOcr config
10
 let paddleOnnxOcrConfig = {"ocrType": "paddleOnnxOcr", "cpuThreadNum": 2, "padding": 10, "maxSideLen": 960}
11

12
 // For custom paddleonnx models, upload files to agent and pass returned paths
13
 // let keysFilePath = utils.uploadAgentFile("/Volumes/dev/ppocrv5_mobile_labels.txt", "ppocrv5_mobile_labels.txt")
14
 // let clsFilePath = utils.uploadAgentFile("/Volumes/dev/ch_ppocr_mobile_v2.0_cls_infer.onnx", "cls.txt")
15
 // let detFilePath = utils.uploadAgentFile("/Volumes/dev/ch_PP-OCRv5_mobile_det.onnx", "det.txt")
16
 // let recFilePath = utils.uploadAgentFile("/Volumes/dev/ch_PP-OCRv5_rec_mobile_infer.onnx", "rec.txt")
17
 // logd("custom keysFilePath " + keysFilePath)
18
 // logd("custom clsFilePath " + clsFilePath)
19
 // logd("custom detFilePath " + detFilePath)
20
 // logd("custom recFilePath " + recFilePath)
21
 // modelPath can be the labels path
22
 // paddleOnnxOcrConfig["modelPath"] = keysFilePath
23
 // paddleOnnxOcrConfig["labelPath"] = keysFilePath
24
 // paddleOnnxOcrConfig["clsModelFilename"] = clsFilePath
25
 // paddleOnnxOcrConfig["detModelFilename"] = detFilePath
26
 // paddleOnnxOcrConfig["recModelFilename"] = recFilePath
27

28

29
 let initResult = ocrInstance.initOcr(ocrLiteConfig)
30

31

32
 logd("initResult " + initResult)
33
 if (!initResult) {
34
 logd("errorMsg:" + ocrInstance.getErrorMsg())
35
 } else {
36
 for (let i = 0; i < 10; i++) {
37
 let img = imageAgent.captureFullScreen();
38
 logd("img " + img)
39
 if (img) {
40
 console.time(1)
41
 let result = ocrInstance.ocrImage(img, 20000, {});
42
 let goTime = console.timeEnd(1)
43
 logd("elapsed " + goTime + " result " + JSON.stringify(result))
44
 if (result) {
45
 for (let j = 0; j < result.length; j++) {
46
 let rs = result[j];
47
 console.log("label: {} confidence:{} range: {},{},{},{}", rs.label, rs.confidence, rs.x, rs.y, (rs.x + rs.width), (rs.y + rs.height))
48
 }
49
 }
50
 }
51

52
 imageAgent.recycle(img)
53
 }
54
 }
55
 ocrInstance.releaseAll();
56
}
57
usbagentocr()

PaddleNcnnOcrV5 Example

1
function usbagentocr() {
2
 ocrAgent.releaseAll()
3
 let ocrInstance = ocrAgent.newOcr();
4
 logd(ocrInstance.ocrId)
5
 // config
6
 let paddleNcnnOcrConfig = {"ocrType": "paddleNcnnOcrV5", "cpuThreadNum": 2, "padding": 32, "maxSideLen": 640}
7

8
 // For custom paddleNcnnOcrV5 models, upload files to agent and pass returned paths
9
 // let keysFilePath = utils.uploadAgentFile("/Volumes/dev/keys.txt", "keys.txt")
10
 // let detParamFilePath = utils.uploadAgentFile("/Volumes/dev/det.ncnn.param", "det.ncnn.param")
11
 // let detBinFilePath = utils.uploadAgentFile("/Volumes/dev/det.ncnn.bin", "det.ncnn.bin")
12
 // let recParamFilePath = utils.uploadAgentFile("/Volumes/dev/rec.ncnn.param", "rec.ncnn.param")
13
 // let recBinFilePath = utils.uploadAgentFile("/Volumes/dev/rec.ncnn.bin", "rec.ncnn.bin")
14
 // logd("custom keysFilePath " + keysFilePath)
15
 // logd("custom detParamFilePath " + detParamFilePath)
16
 // logd("custom detBinFilePath " + detBinFilePath)
17
 // logd("custom recParamFilePath " + recFilePath)
18
 // logd("custom recBinFilePath " + recBinFilePath)
19
 // modelDirs can be the labels path
20
 // paddleOnnxOcrConfig["modelDirs"] = keysFilePath
21
 // paddleOnnxOcrConfig["keysName"] = keys.txt
22
 // paddleOnnxOcrConfig["detName"] = "det.ncnn"
23
 // paddleOnnxOcrConfig["recName"] = "rec.ncnn"
24

25

26
 let initResult = ocrInstance.initOcr(paddleNcnnOcrConfig)
27

28
 logd("initResult " + initResult)
29
 if (!initResult) {
30
 logd("errorMsg:" + ocrInstance.getErrorMsg())
31
 } else {
32
 for (let i = 0; i < 10; i++) {
33
 let img = imageAgent.captureFullScreen();
34
 logd("img " + img)
35
 if (img) {
36
 console.time(1)
37
 let result = ocrInstance.ocrImage(img, 20000, {"paddinng":32,"numThread":1});
38
 let goTime = console.timeEnd(1)
39
 logd("elapsed " + goTime + " result " + JSON.stringify(result))
40
 if (result) {
41
 for (let j = 0; j < result.length; j++) {
42
 let rs = result[j];
43
 console.log("label: {} confidence:{} range: {},{},{},{}", rs.label, rs.confidence, rs.x, rs.y, (rs.x + rs.width), (rs.y + rs.height))
44
 }
45
 }
46
 }
47

48
 imageAgent.recycle(img)
49
 }
50
 }
51
 ocrInstance.releaseAll();
52
}
53
usbagentocr()

ocrImage Recognize Image

Perform OCR on an image
@param img AutoImage object
@param timeout Timeout in milliseconds
@param extra JSON parameters; default {}
@return {null|JSON} JSON object

1
See OCR initialization examples

getErrorMsg Get Error Message

Get error message
@return {string} null means no error

1
See OCR initialization examples

releaseAll Release OCR Resources

Release OCR resources
@return {boolean} true on success, false on failure

1
See OCR initialization examples