HarmonyOS鸿蒙基于Java开发: 通用文字识别

目录

约束与限制

场景介绍

接口说明

开发步骤

通用文字识别的核心技术是OCR（Optical Character Recognition，光学字符识别）。OCR是一种通过拍照、扫描等光学输入方式，把各种票据、卡证、表格、报刊、书籍等印刷品文字转化为图像信息，再利用文字识别技术将图像信息转化为计算机等设备可以使用的字符信息的技术。

约束与限制

  • 支持处理的图片格式包括JPEG、JPG、PNG。
  • 通用文字识别目前支持的语言有：中文、英文、日语、韩语、俄语、意大利语、西班牙语、葡萄牙语、德语，以及法语（将来会增加更多语种）。
  • 目前支持文档印刷体识别，不支持手写字体识别。
  • 为保证较理想的识别结果，调用通用文字识别功能时，应尽可能保证输入图像具有合适的成像质量（建议720p以上）和高宽比例（建议2:1以下，接近手机屏幕高宽比例为宜）。当输入图像为非建议图片尺寸时，文字识别的准确度可能会受到影响。
  • 为保证较理想的识别结果，建议文本与拍摄角度夹角在正负30度范围内。

场景介绍

通用文字识别适用于如下场景：

  • 可以对文档翻拍、街景翻拍等图片进行文字检测和识别，也可以集成于其他应用中，提供文字检测、识别的功能，并根据识别结果提供翻译、搜索等相关服务；
  • 可以处理来自相机、图库等多种来源的图像数据，提供一个自动检测文本、识别图像中文本位置以及文本内容功能的开放接口；
  • 能在一定程度上支持文本倾斜、拍摄角度倾斜、复杂光照条件以及复杂文本背景等场景的文字识别。

接口说明

通用文字识别提供了setVisionConfiguration()和detect()两个函数接口。

  • 调用ITextDetector的setVisionConfiguration()方法，通过传入的TextConfiguration，选择需要调用的OCR类型。 
    

      

    1. void setVisionConfiguration(TextConfiguration textConfiguration);
      2. 

    

    下表列出了TextConfiguration的常用设置：
    

    


    


     
    

    接口名称
    
    		


    参数名
    
    		


    类型
    
    		


    参数说明
    
    		

    

    


    setDetectType()
    
    		


    detectType
    
    		


    int
    
    		


    OCR引擎类型定义：
    

    TextDetectType.TYPE_TEXT_DETECT_FOCUS_SHOOT（自然场景OCR）
    
    		

    

    


    setLanguage()
    
    		


    language
    
    		


    int
    
    		


    识别语种定义：
    

      

    • TextConfiguration.AUTO（不指定语种，会进行语种检测操作）
      • 

    • TextConfiguration.CHINESE（中文）
      • 

    • TextConfiguration.ENGLISH（英语）
      • 

    • TextConfiguration.SPANISH（西班牙语）
      • 

    • TextConfiguration.PORTUGUESE（葡萄牙语）
      • 

    • TextConfiguration.ITALIAN（意大利语）
      • 

    • TextConfiguration.GERMAN（德语）
      • 

    • TextConfiguration.FRENCH（法语）
      • 

    • TextConfiguration.RUSSIAN（俄语）
      • 

    • TextConfiguration.JAPANESE（日语）
      • 

    • TextConfiguration.KOREAN（韩语）
      • 

    

    默认值为TextConfiguration.AUTO。
    
    		

    

    


    setProcessMode()
    
    		


    mode
    
    		


    int
    
    		


    进程模式定义：
    

      

    • VisionConfiguration.MODE_IN（同进程调用）
      • 

    • VisionConfiguration.MODE_OUT（跨进程调用）
      • 

    

    默认值为VisionConfiguration.MODE_OUT。
    
    		

    
    

    

    • 

  • 调用ITextDetector的detect()方法，获取识别结果。

    

      

    1. int detect(VisionImage image, Text result, VisionCallback<Text> visionCallBack);
      2. 

    

    其中：
    

      

    • image为待OCR检测识别的输入图片。
      • 

    • 如果visionCallback为null，执行同步调用，结果码由方法返回，检测及识别结果由result返回。
      • 

    • 如果visionCallback为有效的回调函数，则该函数为异步调用，函数返回时result中的值无效，实际识别结果由回调函数返回。回调函数的使用方法请参见开发步骤中的具体说明。
      • 

    • 同步模式调用成功时，该函数返回结果码0。异步模式调用请求发送成功时，该函数返回结果码700。
      • 

    

    • 



开发步骤


    

  1. 在使用通用文字识别SDK时，将实现文字识别的相关的类添加至工程。

    

      

    1. import ohos.ai.cv.common.ConnectionCallback;
      2. 

    2. import ohos.ai.cv.common.VisionCallback;
      3. 

    3. import ohos.ai.cv.common.VisionConfiguration;
      4. 

    4. import ohos.ai.cv.common.VisionImage;
      5. 

    5. import ohos.ai.cv.common.VisionManager;
      6. 

    6. import ohos.ai.cv.text.ITextDetector;
      7. 

    7. import ohos.ai.cv.text.Text;
      8. 

    8. import ohos.ai.cv.text.TextConfiguration;
      9. 

    9. import ohos.ai.cv.text.TextDetectType;
      10. 

    10. import ohos.app.Context;
      11. 

    11. import ohos.media.image.PixelMap;
      12. 

    

    2. 

  2. 定义ConnectionCallback回调，实现连接能力引擎成功与否后的操作。

    

      

    1. ConnectionCallback connectionCallback = new ConnectionCallback() {
      2. 

    2. @Override
      3. 

    3. public void onServiceConnect() {
      4. 

    4. // 定义连接能力引擎成功后的操作。
      5. 

    5. }
      6. 

    6. 

    7. @Override
      8. 

    8. public void onServiceDisconnect() {
      9. 

    9. // 定义连接能力引擎失败后的操作。
      10. 

    10. }
      11. 

    11. };
      12. 

    

    3. 

  3. 调用VisionManager.init()方法，将此工程的context和已经定义的connectionCallback回调作为入参，建立与能力引擎的连接。context应为ohos.aafwk.ability.Ability或ohos.aafwk.ability.AbilitySlice的实例或子类实例。

    

      

    1. int result = VisionManager.init(context, connectionCallback);
      2. 

    

    4. 

  4. 在收到onServiceConnect回调连接服务成功后，实例化ITextDetector接口，将此工程的context作为入参。

    

      

    1. ITextDetector textDetector = VisionManager.getTextDetector(context);
      2. 

    

    5. 

  5. 实例化VisionImage对象image，并传入待检测图片pixelMap。

    

      

    1. VisionImage image = VisionImage.fromPixelMap(pixelMap);
      2. 

    

    6. 

  6. 实例化Text对象text，该对象在同步模式下用于存放调用textDetector.detect()方法的结果返回码及文字识别结果。

    

      

    1. Text text = new Text();
      2. 

    

    7. 

  7. (可选) 定义VisionCallback<Text>回调。

    

      

    1. VisionCallback<Text> callback= new VisionCallback<Text>() {
      2. 

    2. @Override
      3. 

    3. public void onResult(Text text) {
      4. 

    4. // 对正确获得文字识别结果进行处理。
      5. 

    5. }
      6. 

    6. 

    7. @Override
      8. 

    8. public void onError(int i) {
      9. 

    9. // 处理错误返回码。
      10. 

    10. }
      11. 

    11. 

    12. @Override
      13. 

    13. public void onProcessing(float v) {
      14. 

    14. // 返回处理进度。
      15. 

    15. }
      16. 

    16. };
      17. 

    

     
    

    说明
    

      

    • 在异步模式下，该类的onResult()方法用于获得文字识别结果Text；onError()方法用于处理错误返回码；onProcessing()方法用于返回处理进度，目前没有实现此接口的功能。
      • 

    • 同步与异步模式区别在于detect()的最后一个参数VisionCallback<Text>是否为空。若非空则为异步模式。此时会忽略自定义的Text输入（效果与传入null相同），接口调用结果一律从VisionCallback<Text>获得，自定义的Text输入不做更新。
      • 

    

    8. 

  8. 通过TextConfiguration配置textDetector()方法的运行参数，可选择识别场景、语言类型、调用模式等。跨进程模式（MODE_OUT）下调用方与能力引擎处于不同进程；同进程模式（MODE_IN)下，能力引擎在调用方进程中实例化，调用方通过反射的方式调用引擎里的通用文字识别能力。以聚焦通用文字识别，同进程英文语种检测为例：

    

      

    1. TextConfiguration.Builder builder = new TextConfiguration.Builder();
      2. 

    2. builder.setProcessMode(VisionConfiguration.MODE_IN);
      3. 

    3. builder.setDetectType(TextDetectType.TYPE_TEXT_DETECT_FOCUS_SHOOT);
      4. 

    4. builder.setLanguage(TextConfiguration.ENGLISH);
      5. 

    5. TextConfiguration config = builder.build();
      6. 

    6. textDetector.setVisionConfiguration(config);
      7. 

    

    9. 

  9. （可选）调用ITextDetector的prepare()方法。

    

      

    1. result = textDetector.prepare();
      2. 

    

    说明
    

    如果返回的result不为0，说明当前OCR能力准备失败，需要处理错误，不再执行之后的动作。在detect()方法中会首先调用prepare()启动引擎，如果引擎已经启动则不会再次启动。
    

    10. 

  10. 调用ITextDetector的detect()方法。

    

      

    1. result = textDetector.detect(image, text, null); // 同步
      2. 

    

    或者
    

    

      

    1. result = textDetector.detect(image, null, visionCallback); // 异步
      2. 

    

    说明
    

      

    • 同步模式调用完成时，该函数立即返回结果码；
      • 

    • 异步模式调用请求发送成功时，该函数返回结果码700。如果返回其他的结果码，说明异步调用请求不成功，需要先处理错误，此时回调函数不会被调用。
      • 

    • 如果异步模式调用请求发送成功，则OCR完成后，相应的回调函数会被自动调用。

        

      • 如果onResult()回调被调用，说明OCR检测识别成功，相当于同步模式结果码为0的情况。
        • 

      • 如果onError()方法被调用，则说明OCR发生了错误，具体的调用结果码将由onError()的参数接收。
        • 

      

      • 

    

    结果码定义如下表：
    

    


    


    结果码
    
    		


    说明
    
    		

    

    


    0
    
    		


    成功
    
    		

    

    


    -1
    
    		


    未知错误
    
    		

    

    


    -2
    
    		


    不支持的功能或接口
    
    		

    

    


    -3
    
    		


    内存分配失败或创建对象失败
    
    		

    

    


    -4
    
    		


    所需库加载失败
    
    		

    

    


    -10
    
    		


    引擎开关已经关闭
    
    		

    

    


    101
    
    		


    失败
    
    		

    

    


    102
    
    		


    超时
    
    		

    

    


    200
    
    		


    输入参数不合法（图片尺寸错误）
    
    		

    

    


    201
    
    		


    输入参数不合法（为空）
    
    		

    

    


    210
    
    		


    输入参数合法
    
    		

    

    


    500
    
    		


    服务绑定异常
    
    		

    

    


    521
    
    		


    服务绑定异常断开
    
    		

    

    


    522
    
    		


    服务已连接
    
    		

    

    


    600
    
    		


    模型文件异常
    
    		

    

    


    601
    
    		


    模型文件不存在
    
    		

    

    


    602
    
    		


    模型加载失败
    
    		

    

    


    700
    
    		


    异步调用请求发送成功
    
    		

    

    


    1001
    
    		


    神经网络处理单元错误
    
    		

    
    

    

    11. 

  11. 调用ITextDetector的release()方法，释放资源。调用pixelMap的release()方法，释放图片内存。

    

      

    1. textDetector.release();
      2. 

    2. if (pixelMap != null) {
      3. 

    3. pixelMap.release();
      4. 

    4. pixelMap = null;
      5. 

    5. }
      6. 

    

    说明
    

    不再使用通用文字识别能力时，调用release()方法释放资源。
    

    12. 

  12. 调用VisionManager.destroy()方法，断开与能力引擎的连接。

    

      

    1. VisionManager.destroy();
      2. 

    

    13.