使用机器学习套件识别图片中的文本 (iOS)

本页面介绍了旧版 Text Recognition API，它是 Firebase 机器学习套件的一部分。此 API 的功能已拆分为两个新的 API（了解详情）：

• 设备端 text recognition 是新的独立机器学习套件 SDK 的一部分，可以搭配 Firebase 使用，也可以不搭配 Firebase 使用。
• 云 text recognition 是 Firebase ML 的一部分，后者包含 Firebase 的所有云端机器学习功能。

您可以使用机器学习套件识别图片中的文本。机器学习套件中既包含可用于识别图片中的文本（例如街道标志的文本）的通用 API，也包含针对识别文档文本而优化的 API。通用 API 同时具有设备端模型和云端模型。 文档文本识别只能以云端模型的形式提供。如需查看云端模型和设备端模型的对比结果，请参阅概览。

准备工作

1. 如果您尚未将 Firebase 添加到自己的应用中，请按照入门指南中的步骤执行此操作。
2. 在 Podfile 中添加机器学习套件库：

   pod 'Firebase/MLVision', '6.25.0'
   # If using an on-device API:
   pod 'Firebase/MLVisionTextModel', '6.25.0'
   

   在安装或更新项目的 Pod 之后，请务必使用 Xcode 项目的 .xcworkspace 打开该项目。
3. 在您的应用中导入 Firebase：

   Swift

   import Firebase

   Objective-C

   @import Firebase;

4. 如果您想使用云端模型，但尚未为项目启用基于 Cloud 的 API，此时请执行以下操作来启用该 API：

   1. 打开 Firebase 控制台的机器学习套件 API 页面。

   2. 如果您尚未将项目升级到 Blaze 定价方案，请点击升级以执行此操作。（只有在您的项目未采用 Blaze 方案时，系统才会提示您进行升级。）

      只有 Blaze 级项目才能使用基于 Cloud 的 API。

   3. 如果尚未启用基于 Cloud 的 API，请点击启用基于 Cloud 的 API。
   在向生产环境中部署使用 Cloud API 的应用之前，您应该执行一些额外的步骤来防止未经授权的 API 访问并减轻这些访问造成的影响。

   如果您只想使用设备端模型，可以跳过此步骤。

现在，您可以开始识别图片中的文本了。

输入图片指南

• 要使机器学习套件准确识别文本，输入图片中包含的文本必须由足够大的像素表示。理想情况下，对于拉丁文本，每个字符应至少为 16x16 像素。对于中文、日语和韩语文本（只有在基于 Cloud 的 API 的支持下），每个字符应为 24x24 像素。对于所有语言，字符像素大于 24x24 通常不会增加准确性。

  例如，640x480 像素的图片可能非常适合用于扫描占据图片整个宽度的名片。如需扫描打印在信纸大小纸张上的文档，可能需要 720x1280 像素的图片。

• 图片聚焦不佳会影响文本识别的准确性。如果您无法获得满意的结果，请尝试让用户重新捕获图片。

• 如果您是在实时应用中识别文本，则可能还需要考虑输入图片的整体尺寸。较小图片的处理速度相对较快，因此，为了减少延迟时间，请以较低的分辨率捕获图片（但请牢记上述准确性要求），并确保文本在图片中占据尽可能大的画面。另请参阅提高实时性能的相关提示。

---

识别图片中的文本

如需使用设备端模型或云端模型来识别图片中的文本，请按照以下说明运行文本识别器。

1. 运行文本识别器

将图片作为“UIImage”或“CMSampleBufferRef”传递给“VisionTextRecognizer”的“process(_:completion:)”方法：

1. 通过调用 onDeviceTextRecognizer 或 cloudTextRecognizer 获取 VisionTextRecognizer 的实例：

   Swift

   如需使用设备端模型，请运行以下命令：

   let vision = Vision.vision()
   let textRecognizer = vision.onDeviceTextRecognizer()
   

   如需使用云端模型，请运行以下命令：

   通过机器学习套件使用 Cloud ML 功能需遵守 Google Cloud Platform 许可协议和服务专用条款，并支付相应的费用。如需了解结算信息，请参阅 Firebase 价格页面。

   let vision = Vision.vision()
   let textRecognizer = vision.cloudTextRecognizer()
   
   // Or, to provide language hints to assist with language detection:
   // See https://cloud.google.com/vision/docs/languages for supported languages
   let options = VisionCloudTextRecognizerOptions()
   options.languageHints = ["en", "hi"]
   let textRecognizer = vision.cloudTextRecognizer(options: options)
   

   Objective-C

   如需使用设备端模型，请运行以下命令：

   FIRVision *vision = [FIRVision vision];
   FIRVisionTextRecognizer *textRecognizer = [vision onDeviceTextRecognizer];
   

   如需使用云端模型，请运行以下命令：

   通过机器学习套件使用 Cloud ML 功能需遵守 Google Cloud Platform 许可协议和服务专用条款，并支付相应的费用。如需了解结算信息，请参阅 Firebase 价格页面。

   FIRVision *vision = [FIRVision vision];
   FIRVisionTextRecognizer *textRecognizer = [vision cloudTextRecognizer];
   
   // Or, to provide language hints to assist with language detection:
   // See https://cloud.google.com/vision/docs/languages for supported languages
   FIRVisionCloudTextRecognizerOptions *options =
           [[FIRVisionCloudTextRecognizerOptions alloc] init];
   options.languageHints = @[@"en", @"hi"];
   FIRVisionTextRecognizer *textRecognizer = [vision cloudTextRecognizerWithOptions:options];
   

2. 使用 UIImage 或 CMSampleBufferRef 创建一个 VisionImage 对象。

   如需使用 UIImage，请按以下步骤操作：

   1. 在必要时旋转图片，以使其 imageOrientation 属性为 .up。
   2. 使用方向正确的 UIImage 创建一个 VisionImage 对象。不要指定任何旋转方式元数据，必须使用默认值 .topLeft。

      Swift

      let image = VisionImage(image: uiImage)

      Objective-C

      FIRVisionImage *image = [[FIRVisionImage alloc] initWithImage:uiImage];

   如需使用 CMSampleBufferRef，请按以下步骤操作：

   1. 创建一个 VisionImageMetadata 对象，用其指定 CMSampleBufferRef 缓冲区中所含图片数据的方向。

      如需获取图片方向，请运行以下代码：

      Swift

      func imageOrientation(
          deviceOrientation: UIDeviceOrientation,
          cameraPosition: AVCaptureDevice.Position
          ) -> VisionDetectorImageOrientation {
          switch deviceOrientation {
          case .portrait:
              return cameraPosition == .front ? .leftTop : .rightTop
          case .landscapeLeft:
              return cameraPosition == .front ? .bottomLeft : .topLeft
          case .portraitUpsideDown:
              return cameraPosition == .front ? .rightBottom : .leftBottom
          case .landscapeRight:
              return cameraPosition == .front ? .topRight : .bottomRight
          case .faceDown, .faceUp, .unknown:
              return .leftTop
          }
      }

      Objective-C

      - (FIRVisionDetectorImageOrientation)
          imageOrientationFromDeviceOrientation:(UIDeviceOrientation)deviceOrientation
                                 cameraPosition:(AVCaptureDevicePosition)cameraPosition {
        switch (deviceOrientation) {
          case UIDeviceOrientationPortrait:
            if (cameraPosition == AVCaptureDevicePositionFront) {
              return FIRVisionDetectorImageOrientationLeftTop;
            } else {
              return FIRVisionDetectorImageOrientationRightTop;
            }
          case UIDeviceOrientationLandscapeLeft:
            if (cameraPosition == AVCaptureDevicePositionFront) {
              return FIRVisionDetectorImageOrientationBottomLeft;
            } else {
              return FIRVisionDetectorImageOrientationTopLeft;
            }
          case UIDeviceOrientationPortraitUpsideDown:
            if (cameraPosition == AVCaptureDevicePositionFront) {
              return FIRVisionDetectorImageOrientationRightBottom;
            } else {
              return FIRVisionDetectorImageOrientationLeftBottom;
            }
          case UIDeviceOrientationLandscapeRight:
            if (cameraPosition == AVCaptureDevicePositionFront) {
              return FIRVisionDetectorImageOrientationTopRight;
            } else {
              return FIRVisionDetectorImageOrientationBottomRight;
            }
          default:
            return FIRVisionDetectorImageOrientationTopLeft;
        }
      }

      然后，创建元数据对象：

      Swift

      let cameraPosition = AVCaptureDevice.Position.back  // Set to the capture device you used.
      let metadata = VisionImageMetadata()
      metadata.orientation = imageOrientation(
          deviceOrientation: UIDevice.current.orientation,
          cameraPosition: cameraPosition
      )

      Objective-C

      FIRVisionImageMetadata *metadata = [[FIRVisionImageMetadata alloc] init];
      AVCaptureDevicePosition cameraPosition =
          AVCaptureDevicePositionBack;  // Set to the capture device you used.
      metadata.orientation =
          [self imageOrientationFromDeviceOrientation:UIDevice.currentDevice.orientation
                                       cameraPosition:cameraPosition];

   2. 使用 CMSampleBufferRef 对象和旋转方式元数据创建一个 VisionImage 对象：

      Swift

      let image = VisionImage(buffer: sampleBuffer)
      image.metadata = metadata

      Objective-C

      FIRVisionImage *image = [[FIRVisionImage alloc] initWithBuffer:sampleBuffer];
      image.metadata = metadata;

3. 然后，将图片传递给 process(_:completion:) 方法：

   Swift

   textRecognizer.process(visionImage) { result, error in
     guard error == nil, let result = result else {
       // ...
       return
     }
   
     // Recognized text
   }
   

   Objective-C

   [textRecognizer processImage:image
                     completion:^(FIRVisionText *_Nullable result,
                                  NSError *_Nullable error) {
     if (error != nil || result == nil) {
       // ...
       return;
     }
   
     // Recognized text
   }];
   

2. 从识别出的文本块中提取文本

如果文本识别操作成功，它将返回一个 [`VisionText`][VisionText] 对象。“VisionText”对象包含图片中识别出的完整文本以及零个或零个以上的 [`VisionTextBlock`][VisionTextBlock] 对象。 每个“VisionTextBlock”表示一个矩形文本块，其中包含零个或零个以上的 [`TextTextLine`][VisionTextLine] 对象。每个“VisionTextLine”对象都包含零个或零个以上的 [`VisionTextElement`][VisionTextElement] 对象，这些对象表示字词和类似字词的实体（日期、数字等）。 对于每个“VisionTextBlock”“VisionTextLine”和“VisionTextElement”对象，您可以获取区域中识别出的文本以及该区域的边界坐标。 例如：

Swift

let resultText = result.text
for block in result.blocks {
    let blockText = block.text
    let blockConfidence = block.confidence
    let blockLanguages = block.recognizedLanguages
    let blockCornerPoints = block.cornerPoints
    let blockFrame = block.frame
    for line in block.lines {
        let lineText = line.text
        let lineConfidence = line.confidence
        let lineLanguages = line.recognizedLanguages
        let lineCornerPoints = line.cornerPoints
        let lineFrame = line.frame
        for element in line.elements {
            let elementText = element.text
            let elementConfidence = element.confidence
            let elementLanguages = element.recognizedLanguages
            let elementCornerPoints = element.cornerPoints
            let elementFrame = element.frame
        }
    }
}

Objective-C

NSString *resultText = result.text;
for (FIRVisionTextBlock *block in result.blocks) {
  NSString *blockText = block.text;
  NSNumber *blockConfidence = block.confidence;
  NSArray<FIRVisionTextRecognizedLanguage *> *blockLanguages = block.recognizedLanguages;
  NSArray<NSValue *> *blockCornerPoints = block.cornerPoints;
  CGRect blockFrame = block.frame;
  for (FIRVisionTextLine *line in block.lines) {
    NSString *lineText = line.text;
    NSNumber *lineConfidence = line.confidence;
    NSArray<FIRVisionTextRecognizedLanguage *> *lineLanguages = line.recognizedLanguages;
    NSArray<NSValue *> *lineCornerPoints = line.cornerPoints;
    CGRect lineFrame = line.frame;
    for (FIRVisionTextElement *element in line.elements) {
      NSString *elementText = element.text;
      NSNumber *elementConfidence = element.confidence;
      NSArray<FIRVisionTextRecognizedLanguage *> *elementLanguages = element.recognizedLanguages;
      NSArray<NSValue *> *elementCornerPoints = element.cornerPoints;
      CGRect elementFrame = element.frame;
    }
  }
}

注意：只有在使用云模型时，系统才提供识别出的语言。如需使用设备端模型识别语言，请使用机器学习套件的语言识别 API。

提高实时性能的相关提示

如果要在实时应用中使用设备端模型识别文本，请遵循以下准则以实现最佳帧速率：

• 限制文本识别器的调用次数。如果在文本识别器运行时有新视频帧可用，请丢弃该帧。
• 如果要使用文本识别器的输出在输入图片上叠加图形，请先从机器学习套件获取结果，然后在一个步骤中完成图片的呈现和叠加。采用这一方法，每个输入帧只需在显示表面呈现一次。如需查看示例，请参阅展示示例应用中的 previewOverlayView 和 FIRDetectionOverlayView 类。
• 建议以较低分辨率捕获图片，但是，请注意此 API 的图片尺寸要求。

后续步骤

• 在向生产环境中部署使用 Cloud API 的应用之前，您应该执行一些额外的步骤来防止未经授权的 API 访问并减轻这些访问造成的影响。

---

识别文档图片中的文本

如需识别文档的文本，请按照以下说明配置并运行云端文档文本识别器。

通过机器学习套件使用 Cloud ML 功能需遵守 Google Cloud Platform 许可协议和服务专用条款，并支付相应的费用。如需了解结算信息，请参阅 Firebase 价格页面。

下文所述的文档文本识别 API 提供了一个旨在更方便地处理文档图片的接口。但是，如果您更喜欢使用稀疏文本 API 提供的接口，则可以改用该接口来扫描文档（只需将云端文本识别器配置为使用密集文本模型即可）。

如需使用文档文本识别 API，请执行以下操作：

1. 运行文本识别器

将图片作为 UIImage 或 CMSampleBufferRef 传递给 VisionDocumentTextRecognizer 的 process(_:completion:) 方法：

1. 通过调用 cloudDocumentTextRecognizer 获取 VisionDocumentTextRecognizer 的实例：

   Swift

   let vision = Vision.vision()
   let textRecognizer = vision.cloudDocumentTextRecognizer()
   
   // Or, to provide language hints to assist with language detection:
   // See https://cloud.google.com/vision/docs/languages for supported languages
   let options = VisionCloudDocumentTextRecognizerOptions()
   options.languageHints = ["en", "hi"]
   let textRecognizer = vision.cloudDocumentTextRecognizer(options: options)
   

   Objective-C

   FIRVision *vision = [FIRVision vision];
   FIRVisionDocumentTextRecognizer *textRecognizer = [vision cloudDocumentTextRecognizer];
   
   // Or, to provide language hints to assist with language detection:
   // See https://cloud.google.com/vision/docs/languages for supported languages
   FIRVisionCloudDocumentTextRecognizerOptions *options =
           [[FIRVisionCloudDocumentTextRecognizerOptions alloc] init];
   options.languageHints = @[@"en", @"hi"];
   FIRVisionDocumentTextRecognizer *textRecognizer = [vision cloudDocumentTextRecognizerWithOptions:options];
   

2. 使用 UIImage 或 CMSampleBufferRef 创建一个 VisionImage 对象。

   如需使用 UIImage，请按以下步骤操作：

   1. 在必要时旋转图片，以使其 imageOrientation 属性为 .up。
   2. 使用方向正确的 UIImage 创建一个 VisionImage 对象。不要指定任何旋转方式元数据，必须使用默认值 .topLeft。

      Swift

      let image = VisionImage(image: uiImage)

      Objective-C

      FIRVisionImage *image = [[FIRVisionImage alloc] initWithImage:uiImage];

   如需使用 CMSampleBufferRef，请按以下步骤操作：

   1. 创建一个 VisionImageMetadata 对象，用其指定 CMSampleBufferRef 缓冲区中所含图片数据的方向。

      如需获取图片方向，请运行以下代码：

      Swift

      func imageOrientation(
          deviceOrientation: UIDeviceOrientation,
          cameraPosition: AVCaptureDevice.Position
          ) -> VisionDetectorImageOrientation {
          switch deviceOrientation {
          case .portrait:
              return cameraPosition == .front ? .leftTop : .rightTop
          case .landscapeLeft:
              return cameraPosition == .front ? .bottomLeft : .topLeft
          case .portraitUpsideDown:
              return cameraPosition == .front ? .rightBottom : .leftBottom
          case .landscapeRight:
              return cameraPosition == .front ? .topRight : .bottomRight
          case .faceDown, .faceUp, .unknown:
              return .leftTop
          }
      }

      Objective-C

      - (FIRVisionDetectorImageOrientation)
          imageOrientationFromDeviceOrientation:(UIDeviceOrientation)deviceOrientation
                                 cameraPosition:(AVCaptureDevicePosition)cameraPosition {
        switch (deviceOrientation) {
          case UIDeviceOrientationPortrait:
            if (cameraPosition == AVCaptureDevicePositionFront) {
              return FIRVisionDetectorImageOrientationLeftTop;
            } else {
              return FIRVisionDetectorImageOrientationRightTop;
            }
          case UIDeviceOrientationLandscapeLeft:
            if (cameraPosition == AVCaptureDevicePositionFront) {
              return FIRVisionDetectorImageOrientationBottomLeft;
            } else {
              return FIRVisionDetectorImageOrientationTopLeft;
            }
          case UIDeviceOrientationPortraitUpsideDown:
            if (cameraPosition == AVCaptureDevicePositionFront) {
              return FIRVisionDetectorImageOrientationRightBottom;
            } else {
              return FIRVisionDetectorImageOrientationLeftBottom;
            }
          case UIDeviceOrientationLandscapeRight:
            if (cameraPosition == AVCaptureDevicePositionFront) {
              return FIRVisionDetectorImageOrientationTopRight;
            } else {
              return FIRVisionDetectorImageOrientationBottomRight;
            }
          default:
            return FIRVisionDetectorImageOrientationTopLeft;
        }
      }

      然后，创建元数据对象：

      Swift

      let cameraPosition = AVCaptureDevice.Position.back  // Set to the capture device you used.
      let metadata = VisionImageMetadata()
      metadata.orientation = imageOrientation(
          deviceOrientation: UIDevice.current.orientation,
          cameraPosition: cameraPosition
      )

      Objective-C

      FIRVisionImageMetadata *metadata = [[FIRVisionImageMetadata alloc] init];
      AVCaptureDevicePosition cameraPosition =
          AVCaptureDevicePositionBack;  // Set to the capture device you used.
      metadata.orientation =
          [self imageOrientationFromDeviceOrientation:UIDevice.currentDevice.orientation
                                       cameraPosition:cameraPosition];

   2. 使用 CMSampleBufferRef 对象和旋转方式元数据创建一个 VisionImage 对象：

      Swift

      let image = VisionImage(buffer: sampleBuffer)
      image.metadata = metadata

      Objective-C

      FIRVisionImage *image = [[FIRVisionImage alloc] initWithBuffer:sampleBuffer];
      image.metadata = metadata;

3. 然后，将图片传递给 process(_:completion:) 方法：

   Swift

   textRecognizer.process(visionImage) { result, error in
     guard error == nil, let result = result else {
       // ...
       return
     }
   
     // Recognized text
   }
   

   Objective-C

   [textRecognizer processImage:image
                     completion:^(FIRVisionDocumentText *_Nullable result,
                                  NSError *_Nullable error) {
     if (error != nil || result == nil) {
       // ...
       return;
     }
   
       // Recognized text
   }];
   

2. 从识别出的文本块中提取文本

如果文本识别操作成功，它将返回一个 VisionDocumentText 对象。VisionDocumentText 对象包含图片中识别到的完整文本以及反映所识别的文档结构的对象层次结构：

• VisionDocumentTextBlock
• VisionDocumentTextParagraph
• VisionDocumentTextWord
• VisionDocumentTextSymbol

对于每个 VisionDocumentTextBlock、VisionDocumentTextParagraph、VisionDocumentTextWord 和 VisionDocumentTextSymbol 对象，您可以获取区域中识别出的文本以及该区域的边界坐标。

例如：

Swift

let resultText = result.text
for block in result.blocks {
    let blockText = block.text
    let blockConfidence = block.confidence
    let blockRecognizedLanguages = block.recognizedLanguages
    let blockBreak = block.recognizedBreak
    let blockCornerPoints = block.cornerPoints
    let blockFrame = block.frame
    for paragraph in block.paragraphs {
        let paragraphText = paragraph.text
        let paragraphConfidence = paragraph.confidence
        let paragraphRecognizedLanguages = paragraph.recognizedLanguages
        let paragraphBreak = paragraph.recognizedBreak
        let paragraphCornerPoints = paragraph.cornerPoints
        let paragraphFrame = paragraph.frame
        for word in paragraph.words {
            let wordText = word.text
            let wordConfidence = word.confidence
            let wordRecognizedLanguages = word.recognizedLanguages
            let wordBreak = word.recognizedBreak
            let wordCornerPoints = word.cornerPoints
            let wordFrame = word.frame
            for symbol in word.symbols {
                let symbolText = symbol.text
                let symbolConfidence = symbol.confidence
                let symbolRecognizedLanguages = symbol.recognizedLanguages
                let symbolBreak = symbol.recognizedBreak
                let symbolCornerPoints = symbol.cornerPoints
                let symbolFrame = symbol.frame
            }
        }
    }
}

Objective-C

NSString *resultText = result.text;
for (FIRVisionDocumentTextBlock *block in result.blocks) {
  NSString *blockText = block.text;
  NSNumber *blockConfidence = block.confidence;
  NSArray<FIRVisionTextRecognizedLanguage *> *blockRecognizedLanguages = block.recognizedLanguages;
  FIRVisionTextRecognizedBreak *blockBreak = block.recognizedBreak;
  CGRect blockFrame = block.frame;
  for (FIRVisionDocumentTextParagraph *paragraph in block.paragraphs) {
    NSString *paragraphText = paragraph.text;
    NSNumber *paragraphConfidence = paragraph.confidence;
    NSArray<FIRVisionTextRecognizedLanguage *> *paragraphRecognizedLanguages = paragraph.recognizedLanguages;
    FIRVisionTextRecognizedBreak *paragraphBreak = paragraph.recognizedBreak;
    CGRect paragraphFrame = paragraph.frame;
    for (FIRVisionDocumentTextWord *word in paragraph.words) {
      NSString *wordText = word.text;
      NSNumber *wordConfidence = word.confidence;
      NSArray<FIRVisionTextRecognizedLanguage *> *wordRecognizedLanguages = word.recognizedLanguages;
      FIRVisionTextRecognizedBreak *wordBreak = word.recognizedBreak;
      CGRect wordFrame = word.frame;
      for (FIRVisionDocumentTextSymbol *symbol in word.symbols) {
        NSString *symbolText = symbol.text;
        NSNumber *symbolConfidence = symbol.confidence;
        NSArray<FIRVisionTextRecognizedLanguage *> *symbolRecognizedLanguages = symbol.recognizedLanguages;
        FIRVisionTextRecognizedBreak *symbolBreak = symbol.recognizedBreak;
        CGRect symbolFrame = symbol.frame;
      }
    }
  }
}

后续步骤

• 在向生产环境中部署使用 Cloud API 的应用之前，您应该执行一些额外的步骤来防止未经授权的 API 访问并减轻这些访问造成的影响。