商米文字识别离线SDK获取方式:发送邮件至AI部门(meijuan@sunmi.com)获取,可附带试用授权申请,邮件可参考如下示例:
需要商米文字识别离线SDK 使用场景描述:XXX 设备SN:XXX 授权申请:通用OCR能力试用授权
1. 概述
商米文字识别离线SDK是一种面向安卓设备的技术开发包,主要功能为印刷文字识别,可以识别票据、卡证、关键字符串、各类文件等文本信息。本文档介绍了SDK的使用说明以及数据结构和接口的定义,便于开发者在调用SDK接口时参考。
1.1 功能介绍
商米文字识别离线SDK主要提供文本识别模块,能够精准识别文本内容进行文字检测和识别提取,将其转化成计算机可编码文本。SDK提供简单易用,功能完善的接口,满足各类场景不同需求。
1.2 开发SDK的说明
文件/文件夹名 | 说明 |
config/ | 模型的配置文件 |
libocr-release.aar | SDK lib库相关代码的aar |
2. 环境信息
系统环境 | 平台 | 编译环境 |
Android7及以上 | arm64, arm32 | Android 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步骤:
- 获取的Bitmap图片:用户根据需求,从摄像头获取bitmap转换为BGR像素buffer传给SDK。(灰度图需要扩展为BGR后再输入到SDK)
- 获取text文本数据:根据图片,使用getImageTexts获取文本信息。
- 获取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_OK | 0 | 正确 |
OCR_CODE_UNINIT | 1 | SDK没有初始化 |
OCR_CODE_EMPTY_IMAGE | 2 | 图片为空 |
OCR_CODE_NO_MODEL | 3 | 无加载模型 |
OCR_CODE_CONFIG_ERROR | 4 | 配置错误 |
OCR_CODE_LOW_IMAGE_QUALITY | 5 | OCR图像模糊 |
OCR_CODE_LICENSE_ERROR | 6 | 授权文件无效 |
OCR_CODE_LICENSE_EXPIRED | 7 | 授权文件过期 |
OCR_CODE_IMAGE_BUFFER_ERROR | 8 | 输入图像尺寸或通道数错误 |
OCR_CODE_CONFIG_APPLICATION_NOT_SUPPORT | 9 | config.json文件中,application设置错误 |
OCR_CODE_LICENSE_APPLICATION_NOT_AUTHORIZED | 10 | config.json文件中,application无权限使用 |
OCR_CODE_IMAGE_ROI_ERROR | 11 | ROI设置错误 |
OCR_CODE_IMAGE_PREDICT_MODE_ERROR | 12 | Predict Mode设置错误 |
OCR_CODE_OTHER_ERROR | 1000 | 其他错误 |
4.1.2 SunmiOCRMode 执行功能选择
成员变量 | 值 | 说明 |
PredictMode_None | 0 | 不执行任何功能 |
PredictMode_Det | 1 << 0 | 对传入图片进行ocr文字检测 |
PredictMode_Rec | (1 << 1) | 对传入图片进行ocr文字识别 |
PredictMode_DetRec | PredictMode_Det + PredictMode_Rec | 对传入图片先进行ocr文字检测,再对检测出的文本框执行ocr文字识别 |
4.1.3 SunmiOCRRecRoi OCR Rec指定区域
成员 | 类型 | 说明 |
x1_, y1_ | float | OCR框左上角坐标点的横纵坐标 |
x2_, y2_ | float | OCR框右上角坐标点的横纵坐标 |
x3_, y3_ | float | OCR框右下角坐标点的横纵坐标 |
x4_, y4_ | float | OCR框左下角坐标点的横纵坐标 |
4.1.4 SunmiOCRDetRoi OCR Det指定区域
成员 | 类型 | 说明 |
x1_, y1_ | float | OCR框左上角坐标点的横纵坐标 |
x2_, y2_ | float | OCR框右下角坐标点的横纵坐标 |
4.1.5 SunmiOCRDirection OCR文本方向
成员 | 类型 | 说明 |
label_ | int | 0: 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_0 | 0 | 角度为0度 |
OCR_DIRECTION_180 | 1 | 角度为180度 |
4.1.8 SunmiOCRTextBox 文本框位置坐标
成员 | 类型 | 说明 |
x1_, y1_ | float | OCR框左上角坐标点的横纵坐标 |
x2_, y2_ | float | OCR框右上角坐标点的横纵坐标 |
x3_, y3_ | float | OCR框右下角坐标点的横纵坐标 |
x4_, y4_ | float | OCR框左下角坐标点的横纵坐标 |
score_ | float | 置信度 |
4.1.9 SunmiOCRText 单个文本框OCR结果
成员 | 类型 | 说明 |
box_ | SunmiOCRTextBox | OCR矩形框 |
text_[SunmiOCR_TEXT_MAX_LEN] | char | 文字识别结果 |
char_scores_[SunmiOCR_TEXT_MAX_LEN] | float | 单个字符的识别置信度数组 |
char_count_ | int | 字符个数 |
score_ | float | 置信度 |
direction_ | SunmiOCRDirection | OCR文字方向 |
4.1.10 SunmiOCRImageTexts 图片中所有OCR结果
成员 | 类型 | 说明 |
texts_ | SunmiOCRText * | OCR文字 |
texts_count_ | int | OCR文字个数 |
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设备指纹
函数输入:
变量 | 类型 | 说明 |
context | Context | 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
函数输入:
变量 | 类型 | 说明 |
configPath | String | 配置文件路径 |
返回值:status code
4.2.6 verifyLicense
函数定义:public static int verifyLicense(Context context, String license)
函数功能:验证许可证
函数输入:
变量 | 类型 | 说明 |
context | Context | Android context |
license | String | 许可证字符串 |
返回值:status
4.2.7 getErrorString
函数定义:public static String getErrorString(int code)
函数功能:获得错误字符串
函数输入:
变量 | 类型 | 说明 |
code | int | 错误代码 |
返回值:错误描述字符串
4.2.8 getConfig
函数定义:public static int getConfig(SunmiOCRConfigParam config)
函数功能:获取当前SDK配置
函数输入:
变量 | 类型 | 说明 |
config | SunmiOCRConfigParam | SDK配置参数 |
返回值:status code
4.2.9 setConfig
函数定义:public static int setConfig(SunmiOCRConfigParam config)
函数功能:Set configuration
函数输入:
变量 | 类型 | 说明 |
config | SunmiOCRConfigParam | SDK配置参数 |
返回值:status code
4.2.10 getImageTexts
函数定义:public static int getImageTexts(SunmiOCRImage image, SunmiOCRImageTexts texts)
函数功能:进行文本检测和识别
函数输入:
变量 | 类型 | 说明 |
image | SunmiOCRImage | 输入图像 |
texts | SunmiOCRImageTexts | OCR文本 |
返回值:status code
4.2.11 releaseImageTexts
函数定义:public static int releaseImageTexts(SunmiOCRImageTexts texts)
函数功能:释放SunmiOCRImageTexts
函数输入:
变量 | 类型 | 说明 |
texts | SunmiOCRImageTexts | OCR文本 |
返回值:status code