在 iOS 上使用 ML Kit 為圖片加上標籤

本頁面說明舊版 Image Labeling API，這是 Firebase 專用機器學習套件的一部分。這項 API 的功能已分割為 兩個新的 API (瞭解詳情)：

• 使用裝置 image labeling 屬於新的獨立 ML Kit SDK 的一部分，可與 (或) 搭配使用 沒有 Firebase。
• Cloud image labeling 是 Firebase ML 的一部分，其中包含 Firebase 的所有雲端 ML 功能。

您可以使用 ML Kit 為圖片中辨識出的物件加上標籤， 例如裝置端模型或雲端模式詳情請參閱 總覽，以瞭解 。

使用 ML Kit 存取 Cloud ML 功能時必須遵循 Google Cloud Platform 授權 協議和服務 專屬條款並據此收費。如需帳單資訊，請參閱 Firebase 的「定價」頁面。

事前準備

1. 如果尚未將 Firebase 加入應用程式，請按照下列步驟操作： 入門指南中的步驟。
2. 在 Podfile 中加入 ML Kit 程式庫：

   pod 'Firebase/MLVision', '6.25.0'
   
   
   # If using the on-device API:
   pod 'Firebase/MLVisionLabelModel', '6.25.0'
   

   敬上 安裝或更新專案的 Pod 後，請務必開啟 Xcode 專案 .xcworkspace。
3. 在應用程式中匯入 Firebase：

   Swift

   import Firebase

   Objective-C

   @import Firebase;

4. 如要使用雲端模型，且尚未啟用 為專案設定雲端式 API，請立即採用以下做法：

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

   2. 如果您尚未將專案升級至 Blaze 定價方案，請按一下 如要這麼做，請升級。(只有在您的 專案並未採用 Blaze 方案)。

      只有 Blaze 層級的專案可以使用以雲端為基礎的 API。

   3. 如果尚未啟用雲端式 API，請按一下「Enable Cloud-based API」(啟用雲端式 API) API
   ，瞭解如何調查及移除這項存取權。
   部署至使用 Cloud API 的正式版應用程式之前，您應先完成 防範及降低 未經授權 API 存取的影響

   如果只想使用裝置端模型，可以略過這個步驟。

您現在可以使用裝置上的模型或 雲端式模型

1. 準備輸入圖片

使用 UIImage 或VisionImage CMSampleBufferRef。

如何使用 UIImage：

1. 視需要旋轉圖片，使其 imageOrientation 屬性為 .up。
2. 使用正確旋轉的做法建立 VisionImage 物件 UIImage。請勿指定任何輪替中繼資料 (預設值) 值 (.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. 請使用VisionImage CMSampleBufferRef 物件和輪替中繼資料：

   Swift

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

   Objective-C

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

2. 設定並執行映像檔標籤工具

如要為圖片中的物件加上標籤，請將 VisionImage 物件傳遞至 VisionImageLabeler 的 processImage() 方法。

1. 首先，請取得 VisionImageLabeler 的例項。

   如要使用裝置端圖片標籤工具：

   Swift

   let labeler = Vision.vision().onDeviceImageLabeler()
   
   // Or, to set the minimum confidence required:
   // let options = VisionOnDeviceImageLabelerOptions()
   // options.confidenceThreshold = 0.7
   // let labeler = Vision.vision().onDeviceImageLabeler(options: options)
   

   Objective-C

   FIRVisionImageLabeler *labeler = [[FIRVision vision] onDeviceImageLabeler];
   
   // Or, to set the minimum confidence required:
   // FIRVisionOnDeviceImageLabelerOptions *options =
   //         [[FIRVisionOnDeviceImageLabelerOptions alloc] init];
   // options.confidenceThreshold = 0.7;
   // FIRVisionImageLabeler *labeler =
   //         [[FIRVision vision] onDeviceImageLabelerWithOptions:options];
   

   如何使用雲端映像檔標籤工具：

   Swift

   let labeler = Vision.vision().cloudImageLabeler()
   
   // Or, to set the minimum confidence required:
   // let options = VisionCloudImageLabelerOptions()
   // options.confidenceThreshold = 0.7
   // let labeler = Vision.vision().cloudImageLabeler(options: options)
   

   Objective-C

   FIRVisionImageLabeler *labeler = [[FIRVision vision] cloudImageLabeler];
   
   // Or, to set the minimum confidence required:
   // FIRVisionCloudImageLabelerOptions *options =
   //         [[FIRVisionCloudImageLabelerOptions alloc] init];
   // options.confidenceThreshold = 0.7;
   // FIRVisionImageLabeler *labeler =
   //         [[FIRVision vision] cloudImageLabelerWithOptions:options];
   

2. 接著，將圖片傳遞至 processImage() 方法：

   Swift

   labeler.process(image) { labels, error in
       guard error == nil, let labels = labels else { return }
   
       // Task succeeded.
       // ...
   }
   

   Objective-C

   [labeler processImage:image
              completion:^(NSArray<FIRVisionImageLabel *> *_Nullable labels,
                           NSError *_Nullable error) {
                  if (error != nil) { return; }
   
                  // Task succeeded.
                  // ...
              }];
   

3. 取得加上標籤的物件相關資訊

如果圖片標籤成功，系統會傳回 VisionImageLabel 的陣列 傳遞到完成處理常式在每個物件中，您可以 圖片中辨識功能的相關資訊。

例如：

Swift

for label in labels {
    let labelText = label.text
    let entityId = label.entityID
    let confidence = label.confidence
}

Objective-C

for (FIRVisionImageLabel *label in labels) {
   NSString *labelText = label.text;
   NSString *entityId = label.entityID;
   NSNumber *confidence = label.confidence;
}

即時效能改善訣竅

如要在即時應用程式中為圖片加上標籤，請按照下列步驟操作： 實現最佳影格速率：

• 限制對圖片標籤人員的呼叫。如果新的影片影格 請在圖片標籤工具執行期間捨棄頁框。
• 如果您使用圖片標籤人員的輸出內容，將圖像重疊 先從 ML Kit 取得結果，然後算繪圖片 並疊加單一步驟這麼一來，您的應用程式就會算繪到顯示途徑 每個輸入影格只能建立一次請參閱 previewOverlayView 和 FIRDetectionOverlayView 例如，在展示範例應用程式中使用類別。

後續步驟

• 部署至使用 Cloud API 的正式版應用程式之前，您應先完成 防範及減少 未經授權 API 存取的影響