在 iOS 上使用 ML Kit 偵測及追蹤物件

你可以使用 ML Kit 偵測及追蹤影片畫面中的物件。

傳遞 ML Kit 圖片後,ML Kit 就會針對每個圖片傳回一份清單 偵測到的物體 (最多五個),以及物件在圖片中的位置。偵測時 每個物件都會有專屬的 ID,可用來追蹤 物件您也可以視需要啟用粗略物件 也就是將物件加上廣泛類別說明的標籤

事前準備

  1. 如果尚未將 Firebase 加入應用程式,請按照下列步驟操作: 入門指南中的步驟。
  2. 在 Podfile 中加入 ML Kit 程式庫:
    pod 'Firebase/MLVision', '6.25.0'
    pod 'Firebase/MLVisionObjectDetection', '6.25.0'
    
    安裝或更新專案的 Pod 後,請務必開啟 Xcode 專案 .xcworkspace
  3. 在應用程式中匯入 Firebase:

    Swift

    import Firebase

    Objective-C

    @import Firebase;

1. 設定物件偵測工具

如要開始偵測和追蹤物件,請先建立 VisionObjectDetector,您可以視需要指定任何偵測工具設定 變更。

  1. 使用 VisionObjectDetectorOptions 物件。您可以變更下列設定 設定:

    物件偵測器設定
    偵測模式 .stream (預設) |.singleImage

    在串流模式 (預設) 中,物件偵測工具會在極低的情況下執行 但可能會產生不完整的結果 (例如未指定 定界框或類別) 偵測工具。此外,在串流模式下,偵測工具會指派追蹤項目 對應至物件,這樣就能用多個影格追蹤物件。 當你想要追蹤物件或低延遲時,請使用這個模式 例如即時處理影片串流 讓應用程式從可以最快做出回應的位置 回應使用者要求

    在單張圖片模式中,物件偵測器會等到偵測到 物件的定界框,以及 (如果您已啟用分類) 類別 可在傳回結果之前使用因此 可能更長的時間偵測。另外,在單張圖片中 模式,系統不會指派追蹤 ID。如果發生延遲,請使用這個模式 而不是關鍵時刻 也就是預測結果

    偵測並追蹤多個物件 false (預設) |true

    偵測及追蹤最多五個物件 明顯的物件 (預設)。

    將物件分類 false (預設) |true

    是否將偵測到的物件歸類為粗略的類別。 啟用時,物件偵測工具會將物件 以下類別:時尚商品、食品、居家用品 例如景點、植物和不明地點

    物件偵測及追蹤 API 已針對這兩種核心用途進行最佳化 案件:

    • 即時偵測和追蹤相機中最顯眼的物體 觀景窗
    • 偵測靜態圖片中的多個物件

    如何針對這些用途設定 API:

    Swift

    // Live detection and tracking
    let options = VisionObjectDetectorOptions()
    options.detectorMode = .stream
    options.shouldEnableMultipleObjects = false
    options.shouldEnableClassification = true  // Optional
    
    // Multiple object detection in static images
    let options = VisionObjectDetectorOptions()
    options.detectorMode = .singleImage
    options.shouldEnableMultipleObjects = true
    options.shouldEnableClassification = true  // Optional
    

    Objective-C

    // Live detection and tracking
    FIRVisionObjectDetectorOptions *options = [[FIRVisionObjectDetectorOptions alloc] init];
    options.detectorMode = FIRVisionObjectDetectorModeStream;
    options.shouldEnableMultipleObjects = NO;
    options.shouldEnableClassification = YES;  // Optional
    
    // Multiple object detection in static images
    FIRVisionObjectDetectorOptions *options = [[FIRVisionObjectDetectorOptions alloc] init];
    options.detectorMode = FIRVisionObjectDetectorModeSingleImage;
    options.shouldEnableMultipleObjects = YES;
    options.shouldEnableClassification = YES;  // Optional
    
  2. 取得 FirebaseVisionObjectDetector 的例項:

    Swift

    let objectDetector = Vision.vision().objectDetector()
    
    // Or, to change the default settings:
    let objectDetector = Vision.vision().objectDetector(options: options)
    

    Objective-C

    FIRVisionObjectDetector *objectDetector = [[FIRVision vision] objectDetector];
    
    // Or, to change the default settings:
    FIRVisionObjectDetector *objectDetector = [[FIRVision vision] objectDetectorWithOptions:options];
    

2. 執行物件偵測工具

如要偵測及追蹤物件,請對每個圖片或影格執行下列步驟。 如果啟用串流模式,就必須從以下位置建立 VisionImage 物件: CMSampleBufferRef 秒。

  1. 使用 UIImageVisionImage 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 傳遞至其中一個物件偵測工具的圖片處理作業 方法。您可以使用非同步 process(image:) 方法,也可以採用 同步的 results() 方法

    如要非同步偵測物件:

    Swift

    objectDetector.process(image) { detectedObjects, error in
      guard error == nil else {
        // Error.
        return
      }
      guard let detectedObjects = detectedObjects, !detectedObjects.isEmpty else {
        // No objects detected.
        return
      }
    
      // Success. Get object info here.
      // ...
    }
    

    Objective-C

    [objectDetector processImage:image
                      completion:^(NSArray<FIRVisionObject *> * _Nullable objects,
                                   NSError * _Nullable error) {
                        if (error == nil) {
                          return;
                        }
                        if (objects == nil | objects.count == 0) {
                          // No objects detected.
                          return;
                        }
    
                        // Success. Get object info here.
                        // ...
                      }];
    

    若要同步偵測物件:

    Swift

    var results: [VisionObject]? = nil
    do {
      results = try objectDetector.results(in: image)
    } catch let error {
      print("Failed to detect object with error: \(error.localizedDescription).")
      return
    }
    guard let detectedObjects = results, !detectedObjects.isEmpty else {
      print("Object detector returned no results.")
      return
    }
    
    // ...
    

    Objective-C

    NSError *error;
    NSArray<FIRVisionObject *> *objects = [objectDetector resultsInImage:image
                                                                   error:&error];
    if (error == nil) {
      return;
    }
    if (objects == nil | objects.count == 0) {
      // No objects detected.
      return;
    }
    
    // Success. Get object info here.
    // ...
    
  3. 如果對圖片處理器的呼叫成功,則會傳遞 VisionObject 傳送至完成處理常式,或傳回清單,視實際情況而定 無論您呼叫的是非同步或同步方法

    每個 VisionObject 都包含下列屬性:

    frame CGRect:指出物件在 圖片。
    trackingID 一個整數,可在圖片中識別物件。單肩 圖像模式
    classificationCategory 物件的概略類別。如果物件偵測工具並未 已啟用分類功能,這個屬性一律為 .unknown
    confidence 物件分類的可信度值。如果物件 偵測工具未啟用分類功能,或是 已歸類為不明,這是 nil

    Swift

    // detectedObjects contains one item if multiple object detection wasn't enabled.
    for obj in detectedObjects {
      let bounds = obj.frame
      let id = obj.trackingID
    
      // If classification was enabled:
      let category = obj.classificationCategory
      let confidence = obj.confidence
    }
    

    Objective-C

    // The list of detected objects contains one item if multiple
    // object detection wasn't enabled.
    for (FIRVisionObject *obj in objects) {
      CGRect bounds = obj.frame;
      if (obj.trackingID) {
        NSInteger id = obj.trackingID.integerValue;
      }
    
      // If classification was enabled:
      FIRVisionObjectCategory category = obj.classificationCategory;
      float confidence = obj.confidence.floatValue;
    }
    

提升可用性和效能

為獲得最佳使用者體驗,請在應用程式中遵循以下規範:

  • 是否成功偵測物件,取決於物件的視覺複雜度。物品 但如果有一小部分視覺特徵,您可能需要完成較大 指定要偵測到的映像檔您應為使用者提供應用程式擷取的相關指引 輸入適用您欲偵測物件的種類的輸入查詢
  • 使用分類功能時,可偵測未達預期狀態的物件 完整地新增至支援的類別,並針對不明狀況導入特殊處理 如需儲存大量結構化物件 建議使用 Cloud Bigtable

此外,也請參閱 [ML Kit Material Design 展示應用程式][showcase-link]{: .external } 和 質感設計 機器學習輔助功能的模式集合。

在即時應用程式中使用串流模式時,請遵循下列準則 最佳的影格速率:

  • 大多數裝置不會在串流模式下使用多項物件偵測功能, 產生足夠的影格速率

  • 如果不需要分類功能,請停用分類功能。

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