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

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

將圖片傳送至 ML Kit 時,模型最多可偵測圖片中的五個物件 以及每個物件在圖片中的位置。偵測 中的物件時 影片串流,每個物件都有專屬 ID,可用來追蹤 每個影格都不成問題您也可以視需要啟用粗略物件 也就是將物件加上廣泛類別說明的標籤

立即試用

事前準備

  1. 在 Podfile 中加入下列 ML Kit Pod:
    pod 'GoogleMLKit/ObjectDetection', '3.2.0'
    
  2. 安裝或更新專案的 Pod 後,請使用 .xcworkspace。Xcode 12.4 以上版本支援 ML Kit。

1. 設定物件偵測工具

如要偵測和追蹤物件,請先建立 ObjectDetector,並視需要指定任何偵測工具設定 變更。

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

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

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

    在單一圖片模式中,物件偵測工具會傳回結果 其定界框決定。如果您也啟用了 解碼器會傳回定界框之後的結果 可以使用類別標籤因此 則延遲時間可能較長此外,如果在單一圖片模式中 系統不會指派 ID。如果延遲時間不重要且 你不想處理部分結果

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

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

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

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

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

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

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

Swift

// Live detection and tracking
let options = ObjectDetectorOptions()
options.shouldEnableClassification = true

// Multiple object detection in static images
let options = ObjectDetectorOptions()
options.detectorMode = .singleImage
options.shouldEnableMultipleObjects = true
options.shouldEnableClassification = true

Objective-C

// Live detection and tracking
MLKObjectDetectorOptions *options = [[MLKObjectDetectorOptions alloc] init];
options.shouldEnableClassification = YES;

// Multiple object detection in static images
MLKObjectDetectorOptions *options = [[MLKOptions alloc] init];
options.detectorMode = MLKObjectDetectorModeSingleImage;
options.shouldEnableMultipleObjects = YES;
options.shouldEnableClassification = YES;
  1. 取得 ObjectDetector 的例項:

Swift

let objectDetector = ObjectDetector.objectDetector()

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

Objective-C

MLKObjectDetector *objectDetector = [MLKObjectDetector objectDetector];

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

2. 準備輸入圖片

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

使用 UIImageVisionImage CMSampleBuffer

如果您使用 UIImage,請按照下列步驟操作:

  • 使用 UIImage 建立 VisionImage 物件。請務必指定正確的 .orientation

    Swift

    let image = VisionImage(image: UIImage)
    visionImage.orientation = image.imageOrientation

    Objective-C

    MLKVisionImage *visionImage = [[MLKVisionImage alloc] initWithImage:image];
    visionImage.orientation = image.imageOrientation;

如果您使用 CMSampleBuffer,請按照下列步驟操作:

  • 指定 CMSampleBuffer

    如何取得圖片方向:

    Swift

    func imageOrientation(
      deviceOrientation: UIDeviceOrientation,
      cameraPosition: AVCaptureDevice.Position
    ) -> UIImage.Orientation {
      switch deviceOrientation {
      case .portrait:
        return cameraPosition == .front ? .leftMirrored : .right
      case .landscapeLeft:
        return cameraPosition == .front ? .downMirrored : .up
      case .portraitUpsideDown:
        return cameraPosition == .front ? .rightMirrored : .left
      case .landscapeRight:
        return cameraPosition == .front ? .upMirrored : .down
      case .faceDown, .faceUp, .unknown:
        return .up
      }
    }
          

    Objective-C

    - (UIImageOrientation)
      imageOrientationFromDeviceOrientation:(UIDeviceOrientation)deviceOrientation
                             cameraPosition:(AVCaptureDevicePosition)cameraPosition {
      switch (deviceOrientation) {
        case UIDeviceOrientationPortrait:
          return cameraPosition == AVCaptureDevicePositionFront ? UIImageOrientationLeftMirrored
                                                                : UIImageOrientationRight;
    
        case UIDeviceOrientationLandscapeLeft:
          return cameraPosition == AVCaptureDevicePositionFront ? UIImageOrientationDownMirrored
                                                                : UIImageOrientationUp;
        case UIDeviceOrientationPortraitUpsideDown:
          return cameraPosition == AVCaptureDevicePositionFront ? UIImageOrientationRightMirrored
                                                                : UIImageOrientationLeft;
        case UIDeviceOrientationLandscapeRight:
          return cameraPosition == AVCaptureDevicePositionFront ? UIImageOrientationUpMirrored
                                                                : UIImageOrientationDown;
        case UIDeviceOrientationUnknown:
        case UIDeviceOrientationFaceUp:
        case UIDeviceOrientationFaceDown:
          return UIImageOrientationUp;
      }
    }
          
  • 使用VisionImage CMSampleBuffer 物件和方向:

    Swift

    let image = VisionImage(buffer: sampleBuffer)
    image.orientation = imageOrientation(
      deviceOrientation: UIDevice.current.orientation,
      cameraPosition: cameraPosition)

    Objective-C

     MLKVisionImage *image = [[MLKVisionImage alloc] initWithBuffer:sampleBuffer];
     image.orientation =
       [self imageOrientationFromDeviceOrientation:UIDevice.currentDevice.orientation
                                    cameraPosition:cameraPosition];

3. 處理圖片

VisionImage 傳遞至其中一個物件偵測工具的圖片處理作業 方法。您可以使用非同步 process(image:) 方法,也可以採用 同步的 results() 方法

如要非同步偵測物件:

Swift

objectDetector.process(image) { objects, error in
  guard error == nil else {
    // Error.
    return
  }
  guard !objects.isEmpty else {
    // No objects detected.
    return
  }

  // Success. Get object info here.
  // ...
}

Objective-C

[objectDetector processImage:image
                  completion:^(NSArray * _Nullable objects,
                               NSError * _Nullable error) {
                    if (error == nil) {
                      return;
                    }
                    if (objects.count == 0) {
                      // No objects detected.
                      return;
                    }

                    // Success. Get object info here.
                  }];

若要同步偵測物件:

Swift

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

// Success. Get object info here.

Objective-C

NSError *error;
NSArray *objects = [objectDetector resultsInImage:image error:&error];
if (error == nil) {
  return;
}
if (objects.count == 0) {
  // No objects detected.
  return;
}

// Success. Get object info here.

4. 取得偵測到的物件相關資訊

如果對圖片處理器的呼叫成功,則會傳遞 Object 傳送至完成處理常式,或傳回清單,視實際情況而定 無論您呼叫的是非同步或同步方法

每個 Object 都包含下列屬性:

frame CGRect:指出物件在 圖片。
trackingID 一個整數,用來在圖片中識別物件,或是在圖片中識別「nil」 單張圖片模式
labels 說明偵測工具傳回的物件的標籤陣列。 如果偵測工具選項,則屬性為空白 shouldEnableClassification已設為 false

Swift

// objects contains one item if multiple object detection wasn't enabled.
for object in objects {
  let frame = object.frame
  let trackingID = object.trackingID

  // If classification was enabled:
  let description = object.labels.enumerated().map { (index, label) in
    "Label \(index): \(label.text), \(label.confidence)"
    }.joined(separator:"\n")

}

Objective-C

// The list of detected objects contains one item if multiple
// object detection wasn't enabled.
for (MLKObject *object in objects) {
  CGRect frame = object.frame;
  NSNumber *trackingID = object.trackingID;
  for (MLKObjectLabel *label in object.labels) {
    NSString *labelString = [NSString stringWithFormat: @"%@, %f, %lu",
      label.text, label.confidence, (unsigned long)label.index];
    ...
  }
}

提升可用性和效能

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

  • 是否成功偵測物件,取決於物件的視覺複雜度。於 不過,如果物體具有少量視覺特徵 將圖片放大出來您應該向使用者提供 以便擷取適用於目標物件種類的輸入資料。
  • 使用分類功能時,您可以偵測不會下降的物件 完整地新增至支援的類別,並針對不明狀況導入特殊處理 如需儲存大量結構化物件 建議使用 Cloud Bigtable

此外,您也可以查看 Material Design 機器學習輔助功能的模式集合。

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

  • 大多數裝置不會在串流模式下使用多項物件偵測功能, 產生足夠的影格速率
  • 如果不需要分類功能,請停用分類功能。
  • 如要處理影片影格,請使用偵測工具的 results(in:) 同步 API。致電 透過 AVCaptureVideoDataOutputSampleBufferDelegate captureOutput(_, didOutput:from:) 函式,以同步方式取得指定影片的結果 相框。保留 AVCaptureVideoDataOutput alwaysDiscardsLateVideoFrames 做為 true,以限制對偵測工具的呼叫。如果是 影格的畫面,就會遭到捨棄。
  • 如果使用偵測工具的輸出內容將圖像重疊 先從 ML Kit 取得結果,然後算繪圖片 並疊加單一步驟這麼一來,您的應用程式就會算繪到顯示途徑 每個處理的輸入影格只會產生一次請參閱 updatePreviewOverlayViewWithLastFrame 也可以查看一個範例