1. 1.简介

光学字符识别技术（Optical Character Recognition）简称OCR，是指用扫描仪或数码相机等光学设备， 获取文本资料的图像，然后对图像文件进行分析处理，获取上面的文字及版面信息的过程。相关的功能有文本识别，名片识别，银行卡识别，模板（行驶证、驾驶证、旅行证件、身份证、票据等）识别功能。

灵云 OCR SDK 支持本地和云端两种识别方式，支持多达12种语言的识别。除了单纯的文本识别，灵云 OCR SDK 还为证照（身份证、驾驶证、银行卡）和票据（如增值税发票）的识别提供简洁的开发接口。

本文档旨在讲解灵云SDK的相关知识和使用过程，帮助开发者快速地集成灵云 OCR 功能到开发者应用中。关于各服务接口更详细的说明，请参考灵云SDK开发手册。在集成过程中如有疑问，可登录灵云开发者论坛，查找答案或与其他开发者交流。

1.1 1.1名词解释

在 OCR 进行识别的过程中，需要对图片做一些特定处理，涉及到如下概念：

• 模板 捷通华声通过定义模板，将识别图像区域化，指导识别工作，从而实现一种核心引擎对若干种不同票据、证件及其他特殊纸质信息进行高速高准确率的OCR识别。

• 二值化 将灰度图像或彩色图像转换为二值图像的过程。二值图像，即常见的黑白图像。二值化用来减少网络数据传输量，现在只在文本识别中使用。

• 倾斜校正 通过图像处理技术，校正文本图像中倾斜现象的技术。能校正倾斜度在+/- 15度以内的图像。该技术只在文本识别中使用。

• 版面分析 划分文本图像的各栏（横排文本、竖排文本），并将每一栏切割为若干区域（文字区域、图像区域、表格区域等）的过程。该技术只在文本识别中使用。

1.2 1.2能力定义

灵云 OCR SDK 目前提供以下能力：

1.3 1.3支持的图像类型

• 图像数据格式 OCR内部支持三种图像格式：

  • 二值图像：每个像素点由1bit表示（0和1分别表示背景和文字）
  • 256级灰度图像：每个像素点由1byte表示, 表示256级灰度
  • 24位真彩色图像：每个像素点为RGB三种分量，每个分量由1byte表示。

  同样幅面的图像，灰度图像的大小是二值图像的8倍，真彩色图像的大小是二值图像的24倍。 尽管通过压缩可使这一倍数缩小，但灰度和彩色图像仍然要比二值图像大很多。 当使用云端识别功能时，图像需要传输到云端，因此图像的大小显得比较关键。 我们建议在可以使用二值图像的时候，尽量直接使用二值图像。例如在使用扫描仪的时候， 可以将扫描图像的类型设为二值，而非灰度或彩色，这样可以减少上传的流量。 当一定要使用灰度图像时，我们也提供了配置项，可以让在本地端进行二值化工作，之后再传送到云端。

• 图像文件格式 灵云 OCR SDK 支持多种格式的文件，如 TIFF, BMP, JPG, PNG, GIF 等，并能够根据文件头自动判断文件格式。对于多页 TIFF 文件的情况，只处理第一页的内容。目前 Android 版 SDK 不支持 GIF 和 TIFF 格式的文件。

1.4 调用流程

2. 准备工作

2.1 创建应用

在集成OCR之前，开发者需要在灵云开发者社区创建相关应用，并保存appkey，developerkey等信息。

2.2 下载SDK

下载文字识别SDK并解压缩。

2.3 使用Android版SDK

Android版的SDK提供如下文件：

使用时将这些文件复制到安卓工程的 app\src\main\jniLibs\ 目录下，并把 jar包放在app\libs\目录下，并添加到工程中。

2.3.1 库文件介绍

• 必选模块

  • libcurl.so
  • libhci_sys.so
  • libhci_sys_jni.so
  • libhci_ocr.so
  • libhci_ocr_jni.so
  • libiReadFunction.so
  • libjtz.so
  • libopencv_core.so
  • libopencv_imgproc.so

• 云端识别

  • libiReadText.so
  • libhci_ocr_cloud_recog.so

• 本地文本识别

  • libiReadText.so
  • libhci_ocr_local_recog.so

• 本地银行卡识别

  • libiReadText.so
  • libiReadBankCard.so
  • libhci_ocr_local_recog_bankcard.so

• 本地名片识别

  • libiReadText.so
  • libiReadBizCard.so
  • libhci_ocr_local_recog_bizcard.so

• 本地模板识别

  • libiReadForm.so
  • libhci_ocr_local_recog_template.so

特别注意

Module的build.gradle中，必须配置packagingOptions.doNotStrip参数，以保留灵云SDK中的签名信息，该信息在SDK内部使用，用来保护灵云SDK的知识版权。 若此参数未配置，或配置不正确，在进行本地能力调用时，将会返回本地引擎初始化失败的信息。

• build.gradle示例

    apply plugin: 'com.android.application'
  
    android {
        compileSdkVersion 17
        buildToolsVersion "27.0.3"
  
        defaultConfig {
            applicationId "com.sinovoice.example"
            minSdkVersion 7
            targetSdkVersion 17
            packagingOptions {
                doNotStrip "*/armeabi/*.so"
                doNotStrip "*/armeabi-v7a/*.so"
                doNotStrip "*/arm64-v8a/*.so"
                // add other if needed
            }
        }
  
        buildTypes {
            release {
                minifyEnabled false
                proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.txt'
            }
        }
    }
  
    dependencies {
        compile files('libs/hcicloud-8.1.jar')
        compile files('libs/hcicloud_recorder-8.1.jar')
    }
  

2.3.2 添加用户权限

参考灵云sdk模块通用开发指南

2.4 资源文件

如果需要使用本地能力时，请下载相应资源包并解压缩，资源文件版本请根据 2.2 节下载的SDK版本确定。

下载完成后，将资源文件放入指定的资源路径下，资源路径指定方式详见3.1节。

2.4.1 模板文件介绍

使用本地模板能力时下载的模板资源文件有以下几个文件夹，其使用场景如下：

• BL：营业执照
• DLC：驾驶证
• IDCard：身份证
• PCN：中国护照
• PID：旅行证件
• VAT：增值税票
• VLC：行驶证

3. OCR能力集成

3.1 系统模块初始化

在调用OCR能力之前，需要初始化灵云SDK的通用模块。详见灵云SDK开发手册

• Android示例代码

    // 创建初始化参数辅助类
    InitParam initparam = new InitParam();
    // 授权文件所在路径，此项必填
    String authDirPath = context.getFilesDir()  .getAbsolutePath();;
    initparam.addParam  (InitParam.AuthParam.PARAM_KEY_AUTH_PATH, authDirPath)    ;
    // 灵云云服务的接口地址，此项必填
    initparam.addParam  (InitParam.AuthParam.PARAM_KEY_CLOUD_URL,     "http://api.hcicloud.com:8888");
    // 开发者密钥，此项必填，由捷通华声提供
    initparam.addParam  (InitParam.AuthParam.PARAM_KEY_DEVELOPER_KEY,     "01234567890");
    // 应用程序序号，此项必填，由捷通华声提供
    initparam.addParam  (InitParam.AuthParam.PARAM_KEY_APP_KEY, "1234abcd");
    // 日志的路径，可选，如果不传或者为空则不生成日志
    String logDirPath =     "/storage/emulated/0/sinovoice/com.sinovoice.   example/log";
    initparam.addParam  (InitParam.LogParam.PARAM_KEY_LOG_FILE_PATH,  logDirPath);
    //日志等级，0=无，1=错误，2=警告，3=信息，4=细节，5=调试
    //SDK将输出小于等于logLevel的日志信息
    initparam.addParam  (InitParam.LogParam.PARAM_KEY_LOG_LEVEL, "5");
    // 灵云系统初始化
    // 第二个参数在Android平台下，必须为当前的Context
    int errCode = HciCloudSys.hciInit   (initparam.getStringConfig(), this);
    if(errCode != HciErrorCode.HCI_ERR_NONE) {
        // "系统初始化失败"
        return;
    }
  

3.2 OCR 初始化

在系统模块初始化成功后，进行OCR模块初始化。对于本地识别，需要将资源文件放置在datapath目录下。

• Android代码

    // 构造Ocr初始化的帮助类的实例
    OcrInitParam ocrInitParam = new OcrInitParam();
    ocrInitParam.addParam(OcrInitParam.PARAM_KEY_INIT_CAP_KEYS, capkey);
    String sdPath = Environment.getExternalStorageDirectory().getAbsolutePath();
    String packageName = context.getPackageName();
    String dataPath = sdPath + File.separator + "sinovoice"
            + File.separator + packageName + File.separator + "data" + File.separator;
    ocrInitParam.addParam(OcrInitParam.PARAM_KEY_DATA_PATH, dataPath); 
  
    ShowMessage("hciOcrInit config :" + ocrInitParam.getStringConfig());
  
    //拷贝assets/data目录下的文件到指定路径
    copyAssetsFiles(context, dataPath);        
  
    // 调用初始化方法
    int errCode = HciCloudOcr.hciOcrInit(ocrInitParam.getStringConfig());
    if (errCode != HciErrorCode.HCI_ERR_NONE) {
        ShowMessage("hciOcrInit error:" + HciCloudSys.hciGetErrorInfo(errCode));
        return;
    } else {
        ShowMessage("hciOcrInit Success");
    }
  

对于使用本地多能力时，可以使用initCapKeys传入需要使用的所有能力，以';'隔开。 initCapKeys的作用是告知SDK，需要预先准备哪些能力并提前加载对应的库资源，提高执行效率。

• Android示例代码

    initParam.addParam(OcrInitParam.PARAM_KEY_INIT_CAP_KEYS, 
                   "ocr.local.template.v6;  ocr.local.bankcard.v7");
  

3.3 准备会话与识别参数

灵云SDK提供的OCR识别方式众多，其使用区别主要在会话参数sessionConfig与识别参数recognizeConfig之间。

样例中按能力分为若干分支，开发者可根据场景进行配置

• Android代码

    // 不同的能力，需要不同的session配置与recognize配置
    String imageFile = "";
    OcrConfig sessionConfig = new OcrConfig();
    OcrConfig recognizeConfig = new OcrConfig();
    OcrTemplateId templateId = new OcrTemplateId();
    if(capkey.equalsIgnoreCase("ocr.cloud")){
        // 云端文本识别
        imageFile = "ocr.jpg";
        sessionConfig.addParam(OcrConfig.SessionConfig.PARAM_KEY_CAP_KEY, capkey);
        recognizeConfig.addParam("detailResult", "no");
    }else if(capkey.equalsIgnoreCase("ocr.local")){
        // 本地文本识别
        imageFile = "ocr.jpg";
        sessionConfig.addParam(OcrConfig.SessionConfig.PARAM_KEY_CAP_KEY, capkey);
        sessionConfig.addParam("resPrefix","text/");
        recognizeConfig.addParam("detailResult", "no");
    }else if(capkey.equalsIgnoreCase("ocr.cloud.bizcard")){
        // 云端名片识别
        imageFile = "BizCard.jpg";
        sessionConfig.addParam(OcrConfig.SessionConfig.PARAM_KEY_CAP_KEY, capkey);
    }else if(capkey.equalsIgnoreCase("ocr.local.bizcard.v6")){
        // 本地名片识别
        imageFile = "BizCard.jpg";
        sessionConfig.addParam(OcrConfig.SessionConfig.PARAM_KEY_CAP_KEY, capkey);
        sessionConfig.addParam("resPrefix","bizcard/");
    }else if(capkey.equalsIgnoreCase("ocr.cloud.bankcard")){
        // 云端银行卡识别
        imageFile = "BankCard.jpg";
        sessionConfig.addParam(OcrConfig.SessionConfig.PARAM_KEY_CAP_KEY, capkey);
    }else if(capkey.equalsIgnoreCase("ocr.local.bankcard.v7")){
        // 本地银行卡识别
        imageFile = "BankCard.jpg";
        sessionConfig.addParam(OcrConfig.SessionConfig.PARAM_KEY_CAP_KEY, capkey);
        sessionConfig.addParam("resPrefix","bankcard/");
    }else if(capkey.equalsIgnoreCase("ocr.cloud.template")){
        // 云端模板识别。此处以身份证为例
        imageFile = "IDCard.jpg";
        sessionConfig.addParam(OcrConfig.SessionConfig.PARAM_KEY_CAP_KEY, capkey);
        //云端需设置property参数
        recognizeConfig.addParam(OcrConfig.TemplateConfig.PARAM_KEY_PROPTERTY, "idcard");
        // 身份证正面模板索引、模板页索引。详见模板列表参见“开发指南>附录>能力列表>OCR能力描述>模板列表。
        recognizeConfig.addParam(OcrConfig.TemplateConfig.PARAM_KEY_TEMPLATE_INDEX, "0");
        recognizeConfig.addParam(OcrConfig.TemplateConfig.PARAM_KEY_TEMPLATE_PATE_INDEX, "0");
    }else if(capkey.equalsIgnoreCase("ocr.local.template.v6")){
        // 本地模板识别。此处以身份为例
        imageFile = "IDCard.jpg";
        sessionConfig.addParam(OcrConfig.SessionConfig.PARAM_KEY_CAP_KEY, capkey);
        sessionConfig.addParam("resPrefix","templates/");
  
        // 身份证正面模板索引、模板页索引。详见模板列表参见“开发指南>附录>能力列表>OCR能力描述>模板列表。
        recognizeConfig.addParam(OcrConfig.TemplateConfig.PARAM_KEY_TEMPLATE_INDEX, "0");
        recognizeConfig.addParam(OcrConfig.TemplateConfig.PARAM_KEY_TEMPLATE_PATE_INDEX, "0");
        OcrConfig loadConfig = new OcrConfig();
        loadConfig.addParam("resPrefix","templates/");
        // 请将模板文件复制到相应路径，如果调用边缘检测和清晰度检测，需使用iRead_IDCard_embeded_encode.xml，否则使用iRead_IDCard_encode.xml
        errCode = HciCloudOcr.hciOcrLoadTemplate(loadConfig.getStringConfig(),dataPath
                + "/templates/IDCard/iRead_IDCard_encode.xml", templateId);
        if (errCode != HciErrorCode.HCI_ERR_NONE) {
            ShowMessage("hciOcrLoadTemplate error:" + HciCloudSys.hciGetErrorInfo(errCode));
            HciCloudOcr.hciOcrRelease();
            return;
        } else {
            ShowMessage("hciOcrLoadTemplate Success");
        }
        //本地需设置templateId
        recognizeConfig.addParam(OcrConfig.TemplateConfig.PARAM_KEY_TEMPLATE_ID, templateId.toString());
    }
  

3.4 开启会话

使用准备好的sessionconfig，启动会话:

• Android代码

    // 启动 OCR Session
    ShowMessage("HciCloudOcr hciOcrSessionStart config: " + sessionConfig.getStringConfig());
    Session session = new Session();
    int errCode = HciCloudOcr.hciOcrSessionStart(sessionConfig.getStringConfig(), session);
    if (HciErrorCode.HCI_ERR_NONE != errCode) {
        ShowMessage("hciOcrSessionStart error:" + HciCloudSys.hciGetErrorInfo(errCode));
        return false;
    }
    ShowMessage("hciOcrSessionStart Success");
  

3.5 设置图片

此步骤用于设置需要进行识别的图片数据，可通过hciOcrSetImageBuffer或 hciOcrSetImageFile两种方式进行设置，此处以hci_ocr_set_image_buffer为例，可直接fread二进制方式读取图片文件，将读取到的buffer传入。

• Android代码

    byte[] data = getAssetFileData("BizCard.jpg");
    if(null == data) {
        ShowMessage("Open image file " + imageFile + "error!");
        return false;
    }
  
    errCode = HciCloudOcr.hciOcrSetImageBuffer(session, data);
    if (HciErrorCode.HCI_ERR_NONE != errCode) {
        ShowMessage("hciOcrSetImageBuffer error:" + HciCloudSys.hciGetErrorInfo(errCode));
        HciCloudOcr.hciOcrSessionStop(session);
        return false;
    }
  

3.6 识别

以上准备工作完成后，可通过此步骤进行识别并获取识别结果。

• Android代码

    // 版面分析的结果要作为参数传递给识别方法  
    ArrayList<OcrRecogRegion> ocrlayoutResultList = ocrLayoutResult.getRecogRegionList(); // 上一步中得到的版面分析结果
    OcrRecogResult recogResult = new OcrRecogResult();
  
    errCode = HciCloudOcr.hciOcrRecog(session, recogConfig.getStringConfig(), ocrlayoutResultList, recogResult);
    if (errCode == HciErrorCode.HCI_ERR_NONE) {
        ShowMessage("hciOcrRecog success");
        ShowMessage("RecogResult: " );
        ShowMessage(recogResult.getResultText());
    }else{
        ShowMessage("hciOcrRecog error:" + HciCloudSys.hciGetErrorInfo(errCode));
    }
  

  以识别名片为例，识别图片如下：
  ![image](./image-3.png)
  识别结果（(recogResult.getResultText()）如下：
  ```xml 
    <bizcard>
        <cell id="0" item="postalcode" name="邮政编码">
            <result text="100085"/><bound left="527" top="421" right="639" bottom="449"/>
        </cell>
        <cell id="1" item="name" name="姓名">
            <result text="许丹"/><bound left="196" top="421" right="377" bottom="493"/>
        </cell>
        <cell id="2" item="org" name="单位名称"><result text="手机产品中心">
            <bound left="183" top="562" right="378" bottom="598"/>
        </cell>
        <cell id="3" item="title" name="称谓">
            <result text="软件产品经理"/><bound left="181" top="606" right="376" bottom="642"/>
        </cell>
        <cell id="4" item="tel_cell" name="移动电话">
            <result text="13601377553"/><bound left="516" top="542" right="701" bottom="570"/>
        </cell>
        <cell id="5" item="tel" name="电话">
            <result text="010-62966688-8120"/><bound left="518" top="461" right="788" bottom="489"/>
        </cell>
        <cell id="6" item="fax" name="传真">
                <result text="010-62966688-8100"/><bound left="841" top="692" right="1077" bottom="727"/>
        </cell>
        <cell id="9" item="unknown" name="其它">
                <result text="MSN:carolyn7758@hotmail.com"/><bound left="462" top="620" right="864" bottom="651"/>
        </cell>
        <cell id="10" item="unknown" name="其它">
                <result text="北海"/><bound left="737" top="225" right="918" bottom="247"/>
        </cell>
        <cell id="11" item="org" name="单位名称">
                <result text="北京纽曼伟业科技有限公司"/><bound left="469" top="317" right="1006" bottom="363"/>
        </cell>
    <cell id="12" item="adr" name="地址">
            <result text="北京市海淀区上地三街9号嘉华大厦D座505室"/><bound left="546" top="379" right="1094" bottom="409"/>
        </cell>
    </bizcard>
  

3.7 关闭会话和反初始化

识别完成后，需要关闭会话和反初始化来释放资源

• Android代码

    // 关闭会话
    HciCloudOcr.hciOcrSessionStop(session);
    //OCR反初始化
    HciCloudOcr.hciOcrRelease();
    //SYS反初始化
    HciCloudSys.hciRelease();
  

3.8 本地文本识别的高级用法

使用本地文本识别时，在识别前可进行版面分析，并在调用识别方法时传入此信息，从而提高识别效果：

• Android代码

    OcrRecogLayoutAnalysisResult ocrLayoutResult = new OcrRecogLayoutAnalysisResult();
    // 添加数据
    // 开始版面分析,分析配置参数传入空, 选择默认
    errCode = HciCloudOcr.hciOcrLayoutAnalysis(session, null, ocrLayoutResult);
    if (errCode != HciErrorCode.HCI_ERR_NONE) {
        ShowMessage("hciOcrLayoutAnalysis error:" + HciCloudSys.hciGetErrorInfo(errCode));
        HciCloudOcr.hciOcrSessionStop(session);
        return false;
    }
    ShowMessage("hciOcrLayoutAnalysis Success");
  
    // 识别
    ShowMessage("recog start...");
  
    // 版面分析的结果要作为参数传递给识别方法
    ArrayList<OcrRecogRegion> ocrlayoutResultList = ocrLayoutResult.getRecogRegionList();
    OcrRecogResult recogResult = new OcrRecogResult();
    ShowMessage("HciCloudOcr hciOcrRecog config: " + recogConfig.getStringConfig());
    errCode = HciCloudOcr.hciOcrRecog(session, recogConfig.getStringConfig(), ocrlayoutResultList, recogResult);
    if (errCode == HciErrorCode.HCI_ERR_NONE) {
        ShowMessage("hciOcrRecog success");
        ShowMessage("RecogResult: " );
        ShowMessage(recogResult.getResultText());
        // 输出详细信息
        outPutRecogResult(recogResult);
    }else{
        ShowMessage("hciOcrRecog error:" + HciCloudSys.hciGetErrorInfo(errCode));
    }
  

3.9 识别截屏图像

因为通过屏幕截取得到的图像的分辨率低于拍摄或扫描的图像，所以在进行截屏图像识别时要做特殊设置才能正确识别。可以在识别、版面分析、倾斜校正的时候通过“imageType=screen”进行指定。

4. 常用配置

以下为 OCR 识别中常用配置：

5. FAQ

Q1：我的需求是我会将我手写的数据保存为图片，你们的OCR能否帮我识别图片里的手写数据？

A：手写用的是HWR能力，而不是OCR。OCR目前的识别范围不包含手写体。

Q2：你们的OCR，是否支持对PDF的识别，我给你们一个PDF文件，能不能帮我们识别一下？

A：我们目前支持的图片格式，包括TIFF, BMP, JPG, PNG, GIF等，目前不支持PDF格式。多页TIFF类型的文件，只会处理第一页的内容。 Android平台，不支持GIF格式以及TIFF格式文件。

Q3：你们的OCR文本识别效果怎么这么差？我随便截取了一段文本，都无法识别。

A：截屏和拍照图片，对应的参数是不一样的。imageType需要对应调整，normal为普通图像 ，screen为截屏图像。binarize参数也需要调整，global为全局二值化算法，主要针对通过扫描、截屏等获取的图像。adaptive为局部自适应二值化算法，主要针对通过拍照、摄像头等获取的受光照影响较大图像。

Q4：你们的OCR识别，是否可以设置识别范围？

A：可以，通过recogRange参数设置，比如设置recogRange=gb, letter。缺失值是all。

Q5：OCR需要识别的图片，都支持以哪些方式进行加载？

A：两种接口。hci_ocr_set_image_buffer，通过内存缓冲设置本会话处理的图像。hci_ocr_set_image_file，通过文件设置本会话处理的图像。

Q6：OCR是否支持导出文件？都支持哪些导出文件格式？

A：云端多语种OCR支持，export参数可设置为none,xml,pdf,docx,rtf,xlsx,text,html,pptx。

Q：我用你们的SDK，识别身份证正面成功了，识别反面，返回403：HCI_ERR_OCR_ENGINE_FAILED，这个怎么解决？

A：模板识别，需要通过templatePageIndex参数设置模板页索引号，身份证识别正面此参数传0，反面传1，关于此配置具体细节，请参考Q11。

Q8：我不仅希望返回文字识别结果，还希望返回各个字的坐标等信息，是否支持？

A：支持，通过detailResult参数设置，缺省为yes，会返回详细的节点信息。如果设为no，则会只返回识别结果的文本串。

Q9：你们的模板是否支持自己编辑？我想编辑一下你们的增值税发票的模板。

A：我们目前没有对外开放模板编辑器，如果需要定制模板，请联系我们的相关技术和商务。

Q10：你们是否有拍照识别的示例程序？就是我在手机上，拍一张图，去识别相关信息。

A：有拍照器SDK，android和ios版本。默认支持识别银行卡和身份证。**

Q11：templateIndex和templatePageIndex取值设置及其含义。

A：