在 iOS 上使用 ML Kit 識別圖像中的文本

This page describes an old version of the Text Recognition API, which was part of ML Kit for Firebase. The functionality of this API has been split into two new APIs (learn more):

• On-device text recognition is part of the new standalone ML Kit SDK, which you can use with or without Firebase.
• Cloud text recognition is part of Firebase ML, which includes all of Firebase's cloud-based ML features.

您可以使用 ML Kit 識別圖像中的文本。 ML Kit 既有一個適用於識別圖像中文本（例如街道標誌的文本）的通用 API，也有一個針對識別文檔文本進行了優化的 API。通用 API 既有設備上的模型，也有基於雲的模型。文檔文本識別僅作為基於雲的模型提供。有關雲和設備上模型的比較，請參閱概述。

在你開始之前

1. 如果您尚未將 Firebase 添加到您的應用，請按照入門指南中的步驟進行操作。
2. 在您的 Podfile 中包含 ML Kit 庫：

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

   安裝或更新項目的 Pod 後，請務必使用其.xcworkspace打開您的 Xcode 項目。
3. 在您的應用中，導入 Firebase：

   迅速

   import Firebase

   Objective-C

   @import Firebase;

4. 如果您想使用基於雲的模型，並且尚未為您的項目啟用基於雲的 API，請立即執行此操作：

   1. 打開 Firebase 控制台的ML Kit API 頁面。

   2. 如果您尚未將項目升級到 Blaze 定價計劃，請單擊升級以執行此操作。 （僅當您的項目不在 Blaze 計劃中時，系統才會提示您升級。）

      只有 Blaze 級項目可以使用基於雲的 API。

   3. 如果尚未啟用基於雲的 API，請單擊啟用基於雲的 API 。
   在將使用 Cloud API 的應用程序部署到生產環境之前，您應該採取一些額外的步驟來防止和減輕未經授權的 API 訪問的影響。

   如果您只想使用設備端模型，則可以跳過此步驟。

現在您已準備好開始識別圖像中的文本。

輸入圖像指南

• 為使 ML Kit 準確識別文本，輸入圖像必須包含由足夠像素數據表示的文本。理想情況下，對於拉丁文本，每個字符至少應為 16x16 像素。對於中文、日文和韓文文本（僅雲 API 支持），每個字符應為 24x24 像素。對於所有語言，大於 24x24 像素的字符通常沒有準確性優勢。

  因此，例如，一張 640x480 的圖像可能適用於掃描佔據整個圖像寬度的名片。要掃描在信紙大小的紙張上打印的文檔，可能需要 720x1280 像素的圖像。

• 圖像聚焦不佳會損害文本識別的準確性。如果您沒有得到可接受的結果，請嘗試要求用戶重新捕獲圖像。

• 如果您在實時應用程序中識別文本，您可能還需要考慮輸入圖像的整體尺寸。較小的圖像可以更快地處理，因此為了減少延遲，以較低的分辨率捕獲圖像（牢記上述精度要求）並確保文本盡可能多地佔據圖像。另請參閱提高實時性能的技巧。

---

識別圖像中的文本

要使用設備上或基於雲的模型識別圖像中的文本，請按如下所述運行文本識別器。

1.運行文本識別器

將圖像作為 `UIImage` 或 `CMSampleBufferRef` 傳遞給 `VisionTextRecognizer` 的 `process(_:completion:)` 方法：

1. 通過調用onDeviceTextRecognizer或cloudTextRecognizer獲取VisionTextRecognizer的實例：

   迅速

   要使用設備上模型：

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

   要使用雲模型：

   使用 ML Kit 訪問 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];
   

   要使用雲模型：

   使用 ML Kit 訪問 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 。

      迅速

      let image = VisionImage(image: uiImage)

      Objective-C

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

   要使用CMSampleBufferRef ：

   1. 創建一個VisionImageMetadata對象，該對象指定CMSampleBufferRef緩衝區中包含的圖像數據的方向。

      要獲取圖像方向：

      迅速

      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;
        }
      }

      然後，創建元數據對象：

      迅速

      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對象：

      迅速

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

      Objective-C

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

3. 然後，將圖像傳遞給process(_:completion:)方法：

   迅速

   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` 代表一個矩形文本塊，其中包含零個或多個 [`VisionTextLine`][VisionTextLine] 對象。每個 `VisionTextLine` 對象包含零個或多個 [`VisionTextElement`][VisionTextElement] 對象，它們表示單詞和類似單詞的實體（日期、數字等）。對於每個 `VisionTextBlock`、`VisionTextLine` 和 `VisionTextElement` 對象，您可以獲得區域內識別的文本和區域的邊界坐標。例如：

迅速

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;
    }
  }
}

注意：僅在使用雲模型時提供可識別的語言。要使用設備上模型識別語言，請使用 ML Kit 的語言識別 API 。

提高實時性能的技巧

如果您想使用設備端模型來識別實時應用程序中的文本，請遵循以下指南以獲得最佳幀速率：

• 限制對文本識別器的調用。如果在文本識別器運行時有新的視頻幀可用，請丟棄該幀。
• 如果您使用文本識別器的輸出在輸入圖像上疊加圖形，首先從 ML Kit 獲取結果，然後在一個步驟中渲染圖像並疊加。通過這樣做，您只為每個輸入幀渲染到顯示表面一次。有關示例，請參閱展示示例應用程序中的previewOverlayView和FIRDetectionOverlayView類。
• 考慮以較低的分辨率捕獲圖像。但是，還要記住此 API 的圖像尺寸要求。

下一步

• 在將使用 Cloud API 的應用程序部署到生產環境之前，您應該採取一些額外的步驟來防止和減輕未經授權的 API 訪問的影響。

---

識別文檔圖像中的文本

要識別文檔的文本，請配置並運行基於雲的文檔文本識別器，如下所述。

使用 ML Kit 訪問 Cloud ML 功能需遵守Google Cloud Platform 許可協議和服務特定條款，並相應收費。有關結算信息，請參閱 Firebase定價頁面。

下面描述的文檔文本識別 API 提供了一個接口，旨在更方便地處理文檔圖像。但是，如果您更喜歡稀疏文本 API 提供的接口，則可以通過將雲文本識別器配置為使用密集文本模型來代替它來掃描文檔。

要使用文檔文本識別 API：

1.運行文本識別器

將圖像作為UIImage或CMSampleBufferRef傳遞給VisionDocumentTextRecognizer的process(_:completion:)方法：

1. 通過調用cloudDocumentTextRecognizer獲取VisionDocumentTextRecognizer的實例：

   迅速

   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 。

      迅速

      let image = VisionImage(image: uiImage)

      Objective-C

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

   要使用CMSampleBufferRef ：

   1. 創建一個VisionImageMetadata對象，該對象指定CMSampleBufferRef緩衝區中包含的圖像數據的方向。

      要獲取圖像方向：

      迅速

      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;
        }
      }

      然後，創建元數據對象：

      迅速

      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對象：

      迅速

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

      Objective-C

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

3. 然後，將圖像傳遞給process(_:completion:)方法：

   迅速

   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對象，您可以獲得區域中識別的文本和區域的邊界坐標。

例如：

迅速

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 訪問的影響。