文字识别离线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