文字识别离线SDK

商米文字识别离线SDK获取方式:发送邮件至AI部门(meijuan@sunmi.com)获取,可附带试用授权申请,邮件可参考如下示例:

需要商米文字识别离线SDK 
使用场景描述:XXX
设备SN:XXX
授权申请:通用OCR能力试用授权 

1. 概述

商米文字识别离线SDK是一种面向安卓设备的技术开发包,主要功能为印刷文字识别,可以识别票据、卡证、关键字符串、各类文件等文本信息。本文档介绍了SDK的使用说明以及数据结构和接口的定义,便于开发者在调用SDK接口时参考。

1.1 功能介绍

商米文字识别离线SDK主要提供文本识别模块,能够精准识别文本内容进行文字检测和识别提取,将其转化成计算机可编码文本。SDK提供简单易用,功能完善的接口,满足各类场景不同需求。

1.2 开发SDK的说明

文件/文件夹名说明
config/模型的配置文件
libocr-release.aarSDK lib库相关代码的aar

2. 环境信息

系统环境平台编译环境
Android7及以上arm64, arm32Android studio

3. Java SDK使用说明

3.1 获取授权文件

商米文字识别离线SDK的授权需要绑定Android系统信息。在第一次使用前,开发者需要获取OCR识别SDK的license授权文件,请参考文档试用&购买授权

3.2 导入SDK包

在Android Studio项目中导入SDK aar包即可。

3.3 存放模型文件

模型文件可以存放在SD卡某个路径下,也可以存放在APP文件路径下。请务必保证模型所在路径可以被访问。

3.4 配置config.json文件

使用模型包中config.json文件作为模板,或者自行创建一个config.json文件,拷贝如下代码,并根据模型存放的实际路径进行修改。SDK需通过读取此config.json配置文件进行初始化。

注:需要修改为绝对路径。

{
  "det_model_path": "mobile_v1.1_det_opt.nb",    //文字检测模型路径
  "rec_model_path": "mobile_v1.1_rec_opt.nb",    //文字识别模型路径
  "cls_model_path": "mobile_v1.1_cls_opt.nb",    //文字方向模型路径
  "char_list_file": "keys_v1.txt",               //识别字典
  "thread_num": 4                                //执行识别的线程数
  "application": 1                               //应用代号
}

3.5 创建SDK Handle

在配置和使用SDK前,需要创建Handle。以下为代码示例。

SunmiOCRSDK.createHandle();

3.6 初始化SDK

以下为SDK调用init接口执行初始化的示例。init接口参数为3.4中的config.json文件的路径。

int ret = SunmiOCRSDK.init(confPath); // configPath为String类型的config文件路径

3.7 验证授权文件

使用类似如下代码读取授权文件内容到Java String中,再通过verifyLicense接口验证。若验证通过,可正常调用SDK其他接口。若验证失败,调用SDK其他接口将返回授权错误代码。错误代码为“6”,则表示授权文件无效;错误代码为“7”,则表示授权文件过期。如有授权问题,请联系商米解决。

注:通过无线网连接获取的license,需保证wifi开关为打开状态。

String licence = readToString(licencePath); // 从文件中读取license
int ret = SunmiOCRSDK.verifyLicense(context, licence); // context为Android Context

3.8 配置SDK

商米文字识别离线SDK参数都可动态配置,建议先通过getConfig得到当前参数,根据需要将参数修改完成后,再用setConfig接口进行设置。示例代码如下:

SunmiOCRConfigParam param = new SunmiOCRConfigParam();
SunmiOCRSDK.getConfig(param);
param.setDetMaxSideLen(960);
int ret = SunmiOCRSDK.setConfig(param);

3.9 释放内存

在SDK调用过程中,通过调用SunmiOCRTextArrayGetItem方法得到的对象,都需要调用delete方法释放内存,否则会造成内存泄漏 。示例代码如下:

SunmiOCRText text = SunmiOCRLib.SunmiOCRTextArrayGetItem(text_ary, 0);
text.delete();

3.10 执行OCR

OCR步骤:

  1. 获取的Bitmap图片:用户根据需求,从摄像头获取bitmap转换为BGR像素buffer传给SDK。(灰度图需要扩展为BGR后再输入到SDK)
  2. 获取text文本数据:根据图片,使用getImageTexts获取文本信息。
  3. 获取text文本内容和对应的置信度:根据text.getText()获取文本,再根据text.getScore()获取对应的置信度。

示例代码:

// 将bitmap转为 BGR byte数组
byte[] srcData = OCRUtils.getPixelsBGR(bitmap);
// 构造OCR输入
SunmiOCRImage image = new SunmiOCRImage(srcData, bitmap.getHeight(), bitmap.getWidth(), 0);
// 设置OCR功能
image.setPredictMode(SunmiOCRMode.PredictMode_Det+SunmiOCRMode.PredictMode_Rec);
// 设置ROI [可选]
SunmiOCRDetRoi detRoi = image.getDetRoiBox();
detRoi.setX1(120);
detRoi.setY1(240);
detRoi.setX2(640);
detRoi.setY2(960);
image.setDetRoiBox(detRoi);
// 构造OCR输出
SunmiOCRImageTexts texts = new SunmiOCRImageTexts();
// 执行OCR
int ret = SunmiOCRSDK.getImageTexts(image, texts);
// 判断OCR是否正常运行
if (ret ! = SunmiOCRStatusCode.OCR_CODE_OK) {
    Log.d(TAG, "SunmiOCRSDK.getImageTexts error code " + ret);
    return;
}
// 获取识别出的文本
SunmiOCRText text_ary = texts.getTexts();
for (int i = 0; i ‹ texts.getTextsCount(); i++) {
    SunmiOCRText text = SunmiOCRLib.SunmiOCRTextArrayGetItem(text_ary, i);
    Log.d(TAG, text.getText() + " " + text.getScore());
    text.delete();
}

4. Java接口定义

4.1 类接口定义

4.1.1 SunmiOCRStatusCode 商米OCR识别状态码

成员变量说明
OCR_CODE_OK0正确
OCR_CODE_UNINIT1SDK没有初始化
OCR_CODE_EMPTY_IMAGE2图片为空
OCR_CODE_NO_MODEL3无加载模型
OCR_CODE_CONFIG_ERROR4配置错误
OCR_CODE_LOW_IMAGE_QUALITY5OCR图像模糊
OCR_CODE_LICENSE_ERROR6授权文件无效
OCR_CODE_LICENSE_EXPIRED7授权文件过期
OCR_CODE_IMAGE_BUFFER_ERROR8输入图像尺寸或通道数错误
OCR_CODE_CONFIG_APPLICATION_NOT_SUPPORT9config.json文件中,application设置错误
OCR_CODE_LICENSE_APPLICATION_NOT_AUTHORIZED10config.json文件中,application无权限使用
OCR_CODE_IMAGE_ROI_ERROR11ROI设置错误
OCR_CODE_IMAGE_PREDICT_MODE_ERROR12Predict Mode设置错误
OCR_CODE_OTHER_ERROR1000其他错误

4.1.2 SunmiOCRMode 执行功能选择

成员变量说明
PredictMode_None0不执行任何功能
PredictMode_Det1 << 0对传入图片进行ocr文字检测
PredictMode_Rec(1 << 1) 对传入图片进行ocr文字识别
PredictMode_DetRecPredictMode_Det + PredictMode_Rec对传入图片先进行ocr文字检测,再对检测出的文本框执行ocr文字识别

4.1.3 SunmiOCRRecRoi OCR Rec指定区域

成员类型说明
x1_, y1_floatOCR框左上角坐标点的横纵坐标
x2_, y2_floatOCR框右上角坐标点的横纵坐标
x3_, y3_floatOCR框右下角坐标点的横纵坐标
x4_, y4_floatOCR框左下角坐标点的横纵坐标

4.1.4 SunmiOCRDetRoi OCR Det指定区域

成员类型说明
x1_, y1_floatOCR框左上角坐标点的横纵坐标
x2_, y2_floatOCR框右下角坐标点的横纵坐标

4.1.5 SunmiOCRDirection OCR文本方向

成员类型说明
label_int0: 0度; 1: 180 度
score_float置信度

4.1.6 SunmiOCRImage OCR输入图像

成员类型说明
buf_unsigned char *图片像素字节地址
buf_len_int字节缓冲区长度
img_w_int图像宽度
img_h_int图像高度
max_text_count_int单图文本数最大返回值
predict_mode_int需要执行的功能选择
rec_roi_box_SunmiOCRRecRoi用于指定图像中需要识别的区域,仅在Mode为PredictMode_Rec或PredictMode_Rec+PredictMode_Cls时有效
det_roi_box_SunmiOCRDetRoi用于指定图像中需要检测的区域,仅在Mode=PrecideMode_Det+n有效,n为其他Mode。

4.1.7 SunmiOCRDirectionType 文本方向类型

成员变量说明
OCR_DIRECTION_00角度为0度
OCR_DIRECTION_1801角度为180度

4.1.8 SunmiOCRTextBox 文本框位置坐标

成员类型说明
x1_, y1_floatOCR框左上角坐标点的横纵坐标
x2_, y2_floatOCR框右上角坐标点的横纵坐标
x3_, y3_floatOCR框右下角坐标点的横纵坐标
x4_, y4_floatOCR框左下角坐标点的横纵坐标
score_float置信度

4.1.9 SunmiOCRText 单个文本框OCR结果

成员类型说明
box_SunmiOCRTextBoxOCR矩形框
text_[SunmiOCR_TEXT_MAX_LEN]char文字识别结果
char_scores_[SunmiOCR_TEXT_MAX_LEN]float单个字符的识别置信度数组
char_count_int字符个数
score_float置信度
direction_SunmiOCRDirectionOCR文字方向

4.1.10 SunmiOCRImageTexts 图片中所有OCR结果

成员类型说明
texts_SunmiOCRText *OCR文字
texts_count_intOCR文字个数

4.1.11 SunmiOCRConfigParam OCR配置参数

成员类型说明
det_max_side_len_int文本检测时图片长边的最大长度
rec_max_side_len_int文本识别时图片长边的最大长度
det_db_thresh_float文本检测阈值
det_db_box_thresh_float文本框筛选阈值
det_db_unclip_ratio_float文本检测框扩大比例
cls_thresh_float方向分类阈值
image_quality_threshold_float图像质量阈值

4.2 函数接口定义

4.2.1 getVersion

函数定义:public static String getVersion()

函数功能:获取Sunmi OCR SDK版本号

返回值:SDK版本字符串

4.2.2 getDeviceFingerprint

函数定义:public static String getDeviceFingerprint(Context context)

函数功能:获取Android设备指纹

函数输入:

变量类型说明
contextContext android context

返回值:设备指纹字符串

4.2.3 createHandle

函数定义:public static void createHandle()

函数功能:创建句柄

4.2.4 releaseHandle

函数定义:public static int release()

函数功能:释放句柄

返回值:status code

4.2.5 init

函数定义:public static int init(String configPath)

函数功能:初始化SDK

函数输入:

变量类型说明
configPathString 配置文件路径

返回值:status code

4.2.6 verifyLicense

函数定义:public static int verifyLicense(Context context, String license)

函数功能:验证许可证

函数输入:

变量类型说明
contextContext Android context
licenseString 许可证字符串

返回值:status

4.2.7 getErrorString

函数定义:public static String getErrorString(int code)

函数功能:获得错误字符串

函数输入:

变量类型说明
codeint 错误代码

返回值:错误描述字符串

4.2.8 getConfig

函数定义:public static int getConfig(SunmiOCRConfigParam config)

函数功能:获取当前SDK配置

函数输入:

变量类型说明
configSunmiOCRConfigParam SDK配置参数

返回值:status code

4.2.9 setConfig

函数定义:public static int setConfig(SunmiOCRConfigParam config)

函数功能:Set configuration

函数输入:

变量类型说明
configSunmiOCRConfigParam SDK配置参数

返回值:status code

4.2.10 getImageTexts

函数定义:public static int getImageTexts(SunmiOCRImage image, SunmiOCRImageTexts texts)

函数功能:进行文本检测和识别

函数输入:

变量类型说明
imageSunmiOCRImage 输入图像
textsSunmiOCRImageTexts OCR文本

返回值:status code

4.2.11 releaseImageTexts

函数定义:public static int releaseImageTexts(SunmiOCRImageTexts texts)

函数功能:释放SunmiOCRImageTexts

函数输入:

变量类型说明
textsSunmiOCRImageTexts OCR文本

返回值:status code