1. 1.简介

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

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

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

1.1 名词解释

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

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

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

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

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

1.2 能力定义

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

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 调用流程

OCR包含了多种识别方式，基本流程为根据识别业务，准备会话参数与识别参数后，启动会话，加载图像，进行识别。

2. 准备工作

2.1 创建应用

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

2.2 下载SDK

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

2.3 使用C++版SDK

• 必选模块
  • hci_sys.dll
  • hci_sys.lib
  • hci_ocr.dll
  • hci_ocr.lib
  • iReadFunction.dll
  • jtz.dll
  • libhci_curl.dll

• 云端能力

  • iReadText.dll
  • hci_ocr_cloud_recog.dll

• 本地能力

• opencv

  • opencv_core342.dll
  • opencv_dnn342.dll
  • opencv_features2d342.dll
  • opencv_flann342.dll
  • opencv_imgcodecs342.dll
  • opencv_imgproc342.dll
  • opencv_xfeatures2d342.dll

• mkl

  • mkl_avx.dll
  • mkl_avx2.dll
  • mkl_core.dll
  • mkl_intel_thread.dll
  • mkl_p4.dll
  • mkl_p4m.dll
  • mkl_p4m3.dll
  • mkl_p4p.dll
  • mkl_rt.dll
  • mkl_sequential.dll
  • mkl_vml_avx.dll
  • mkl_vml_avx2.dll
  • mkl_vml_cmpt.dll
  • mkl_vml_ia.dll
  • mkl_vml_p4.dll
  • mkl_vml_p4m.dll
  • mkl_vml_p4m2.dll
  • mkl_vml_p4m3.dll
  • mkl_vml_p4p.dll

• 本地文本

  • iReadText.dll
  • hci_ocr_local_recog.dll

• 本地模板

  • iReadForm.dll
  • hci_ocr_local_recog_template.dll

• 本地名片

  • iRead_BizCard.dll
  • iReadText.dll
  • hci_ocr_local_recog_bizcard.dll

• 本地银行卡

  • iReadBankCard.dll
  • hci_ocr_local_recog_bankcard.dll

2.5 资源文件

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

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

2.5.1 模板文件介绍

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

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

3. OCR能力集成

3.1 系统模块初始化

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

• C++示例代码

HCI_ERR_CODE err_code = HCI_ERR_NONE;
//配置串是由"字段=值"的形式给出的一个字符串，多个字段之间以','隔开。字段名不分大小写。
string init_config = "";
//灵云应用序号
init_config += "appKey=1234abcd";
//灵云开发者密钥
init_config += ",developerKey=1234567890";
//灵云云服务的接口地址
init_config += ",cloudUrl=http://api.hcicloud.com:8888";
//授权文件所在路径，保证可写
init_config += ",authpath=../../bin";
//日志的路径
init_config += ",logfilepath=../../bin";
//日志的等级
init_config += ",loglevel=5";
//日志文件的大小
init_config += ",logfilesize=512";
//其他配置使用默认值，不再添加，如果想设置可以参考开发手册
err_code = hci_init( init_config.c_str() );

提示 因灵云SDK8.1使用Visual Studio 2015开发的原因，在windows下的开发运行环境需要确认安装运行组件vc_redist.x64.exe,vc_redist.x86.exe, 具体请参考https://www.microsoft.com/zh-cn/download/details.aspx?id=48145

3.2 授权检测

在初始化灵云SDK的通用模块后，还需要调用授权检测函数获取云端授权。

C++示例代码

//获取过期时间
int64 expire_time;
int64 current_time = (int64)time( NULL );
HCI_ERR_CODE err_code = hci_get_auth_expire_time( &expire_time );
if( err_code == HCI_ERR_NONE )
{
    //获取成功则判断是否过期
    if( expire_time > current_time )
    {
        //没有过期
        printf( "auth can use continue\n" );
        return true;
    }
}
//获取过期时间失败或已经过期
//手动调用更新授权
err_code = hci_check_auth();
if( err_code == HCI_ERR_NONE )
{
    //更新成功
    printf( "check auth success \n" );
    return true;
}
else
{
    //更新失败
    printf( "check auth return (%d)\n", err_code);
    return false;
}

3.3 OCR 初始化

在系统模块初始化成功后，进行OCR模块初始化。

• C++代码

    //OCR初始化
    HCI_ERR_CODE err_code = HCI_ERR_NONE;
    string init_config;
    //本地资源所在路径 
    init_config += ("dataPath=" + data_path); 
    //初始化所需的本地能力
    init_config += (",initCapkeys=" + cap_key); 
    err_code = hci_ocr_init(init_config.c_str());
    if (err_code != HCI_ERR_NONE) 
    {
        printf("hci_ocr_init return (%d:%s) \n", err_code, hci_get_error_info(err_code));
        return;
    }
    printf("hci_ocr_init success \n");
  

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

• C++代码

    //OCR 初始化
    string ocr_init_config = "dataPath=";
    ocr_init_config += data_path;
    ocr_init_config += ",initCapkeys=";
    ocr_init_config += "ocr.local.template.v6;ocr.local.bankcard.v7";
  

3.4 加载模板

本地模板能力需要加载相应的模板文件，使用其他能力时请跳过此步骤。使用模板识别时需要在config中传入加载成功后的template id。

• C++代码

    //如果是本地模板识别则加载模板
    int tempalte_id = -1;
    if (cap_key.find("local.template") != string::npos)
    {
        //此处默认加载身份证的模板，如果调用了边缘检测和清晰度检测，需使用iRead_IDCard_embeded_encode.xml，否则使用iRead_IDCard_encode.xml
        string template_file = data_path + "/templates/IDCard/iRead_IDCard_encode.xml";
        string template_config;
        template_config += "resPrefix=templates/";
        err_code = hci_ocr_load_template(template_config.c_str(), template_file.c_str(), &tempalte_id);
        if (err_code != HCI_ERR_NONE)
        {
            printf("hci_ocr_load_template failed(%d:%s) \n",err_code, hci_get_error_info(err_code));  
            hci_ocr_release();
            return;
        }
        printf("hci_ocr_load_template success! \n");
    }
  
    //设置识别参数，其他配置参数请参考《灵云SDK开发手册》
    string recog_config = ""; 
    //是否输出置信度，默认设为no不输出置信度,如果设为yes则输出置信度， 仅支持云端名片识别。
     //recog_config += "need_score=yes";  
    //返回识别结果时，是否同时返回图片数据,默认为no,仅针对模板识别和名片识别。
     //recog_config += "exportimage=no";  
    //是否返回详细结果,如果设为no,只返回识别结果的文本串，如果设为yes，则会返回详细的节点信息 。
    recog_config += "detailResult=no"; 
    if (cap_key.find("template") != string::npos)
    {
        //模板识别的配置
        if (cap_key.find("local.template") != string::npos)
        {
            //本地为加载的模板ID
            char chTmp[32] =  {0};
            sprintf(chTmp,"%d",tempalte_id);
            recog_config += (",templateId="+string(chTmp));
        }
        else
        {
            //云端需设置property参数
            recog_config += ",property=idcard";
        }
        //此处默认模板索引和模板页索引为0
        recog_config += ",templateIndex=0,templatePageIndex=0";
    }        
    //进行识别……
  

3.5 开启会话

OCR能力引擎通过会话来管理识别过程，可同时开启的最大会话数量由线程授权控制。

• C++代码

    HCI_ERR_CODE err_code = HCI_ERR_NONE;
    // 启动 OCR Session
    int session_id = -1;
    err_code = hci_ocr_session_start(session_config.c_str(), &session_id);
    if (err_code != HCI_ERR_NONE)
    {
        printf("hci_ocr_session_start return(%d:%s)\n", err_code,hci_get_error_info(err_code));
        return false;
    }
    printf( "hci_ocr_session_start success\n" );
  

3.6 设置图片

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

• C++代码

    // 设置图片
    err_code = hci_ocr_set_image_buffer(session_id, image_data.buff_, image_data.buff_len_);
    if (err_code != HCI_ERR_NONE)
    {
        printf("hci_ocr_set_image_by_decode_buffer failed(%d)\n", err_code);
        hci_ocr_session_stop(session_id);
        return false;
    }
    printf("hci_ocr_set_image_by_decode_buffer success\n");
  

3.7 倾斜校正

使用本地文本识别时，在识别前需要先进行倾斜校正，使用其他能力时请跳过此步骤。

• C++代码

    //倾斜校正
    OCR_DESKEW_RESULT deskew_result;
    err_code = hci_ocr_deskew( session_id,  NULL, &deskew_result );
    if( err_code != HCI_ERR_NONE )
    {
        printf("hci_ocr_deskew return(%d:%s)\n", err_code,hci_get_error_info(err_code));
        hci_ocr_session_stop( session_id );
        return false;
    }
    printf( "hci_ocr_deskew success\n" );
    // 释放倾斜检测结果
    hci_ocr_free_deskew_result(&deskew_result);
  

3.8 版面分析

使用本地文本识别时，在识别前需要先进行版面分析，使用其他能力时请跳过此步骤。

• C++代码

    // 进行版面分析
    OCR_LAYOUT_RESULT layout_result;
    err_code = hci_ocr_layout_analysis( session_id, "", &layout_result );
    if( err_code != HCI_ERR_NONE )
    {
        printf("hci_ocr_layout_analysis return(%d:%s)\n", err_code,hci_get_error_info(err_code));
        hci_ocr_session_stop( session_id );
        return false;
    }
    printf( "hci_ocr_layout_analysis success\n" );
    // 释放版面分析结果
    hci_ocr_free_layout_result(&layout_result);
  

3.9 识别

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

• C++代码

    // 进行识别
    OCR_RECOG_RESULT recog_result;
    err_code = hci_ocr_recog( session_id, "templateid=2", layoutRegionList, layoutRegionCount, &recog_result );
    if( err_code == HCI_ERR_NONE )
    {
        printf( "hci_ocr_recog success\n" );
        // 打印识别结果
        PrintOcrResult( recog_result );
        // 释放识别结果
        hci_ocr_free_recog_result(&recog_result);
    }
    else{
        printf("hci_ocr_recog return(%d:%s)\n", err_code,hci_get_error_info(err_code));
    }
  

  以识别名片为例，识别图片如下： 识别结果（(recogResult.getResultText()）如下：

    <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.10 关闭会话和反初始化

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

• C++代码

    // 终止 OCR Session
    err_code = hci_ocr_session_stop( session_id );
    if( err_code != HCI_ERR_NONE )
    {
        printf("hci_ocr_session_stop return(%d:%s)\n", err_code,hci_get_error_info(err_code));
    }
    printf( "hci_ocr_session_stop success\n" );
  
    //OCR反初始化
    hci_ocr_release();
    printf("hci_ocr_release\n");
  
    //SYS反初始化
    err_code = hci_release();
    printf("hci_release\n");
  

3.11 识别截屏图像

因为通过屏幕截取得到的图像的分辨率低于拍摄或扫描的图像，所以在进行截屏图像识别时要做特殊设置才能正确识别。可以在识别、版面分析、倾斜校正的时候通过“imageType=screen”进行指定，配置项使用方法详见灵云SDK开发手册：

4. 常用配置

以下为 OCR 识别中常用配置，更多配置项请参考灵云SDK开发手册。

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：

Q12: Win8 Win10操作系统下使用VS2015集成灵云SDK，发生类似"缺少mfc140d.dll"错误,如何解决？

请按微软官网要求，安装运行使用 Visual Studio 2015 生成的 C++ 应用程序所需的运行时组件。`