Firebase 将于 5 月 20 日至 21 日重返 Google I/O 大会！立即报名。

本頁面由 Cloud Translation API 翻譯而成。

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

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

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

事前準備

如果尚未將 Firebase 加入應用程式，請按照下列步驟操作：入門指南中的步驟。
在 Podfile 中加入 ML Kit 程式庫：
```
pod 'Firebase/MLVision', '6.25.0'
pod 'Firebase/MLVisionObjectDetection', '6.25.0'
```
敬上安裝或更新專案的 Pod 後，請務必開啟 Xcode 專案 .xcworkspace。
在應用程式中匯入 Firebase：
Swift
```
import Firebase
```
Objective-C
```
@import Firebase;
```

1. 設定物件偵測工具

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

使用 VisionObjectDetectorOptions 物件。您可以變更下列設定設定：

物件偵測器設定

偵測模式

物件偵測器設定
偵測模式	`.stream` (預設) \|`.singleImage` 在串流模式 (預設) 中，物件偵測工具會在極低的情況下執行但可能會產生不完整的結果 (例如未指定定界框或類別) 偵測工具。此外，在串流模式下，偵測工具會指派追蹤項目對應至物件，這樣就能用多個影格追蹤物件。當你想要追蹤物件或低延遲時，請使用這個模式例如即時處理影片串流讓應用程式從可以最快做出回應的位置回應使用者要求在單張圖片模式中，物件偵測器會等到偵測到物件的定界框，以及 (如果您已啟用分類) 類別可在傳回結果之前使用因此可能更長的時間偵測。另外，在單張圖片中模式，系統不會指派追蹤 ID。如果發生延遲，請使用這個模式而不是關鍵時刻也就是預測結果
偵測並追蹤多個物件	`false` (預設) \|`true` 偵測及追蹤最多五個物件明顯的物件 (預設)。
將物件分類	`false` (預設) \|`true` 是否將偵測到的物件歸類為粗略的類別。啟用時，物件偵測工具會將物件以下類別：時尚商品、食品、居家用品例如景點、植物和不明地點

.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

取得 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 秒。

使用 UIImage 或VisionImage CMSampleBufferRef。

如何使用 UIImage：

視需要旋轉圖片，使其 imageOrientation 屬性為 .up。
使用正確旋轉的做法建立 VisionImage 物件 UIImage。請勿指定任何輪替中繼資料 (預設值) 值 (.topLeft)，則必須使用。
Swift
```
let image = VisionImage(image: uiImage)
```
Objective-C
```
FIRVisionImage *image = [[FIRVisionImage alloc] initWithImage:uiImage];
```

如何使用 CMSampleBufferRef：

建立 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];

請使用VisionImage CMSampleBufferRef 物件和輪替中繼資料：

Swift

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

Objective-C

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

將 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.
// ...

如果對圖片處理器的呼叫成功，則會傳遞 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 取得結果，然後算繪圖片並疊加單一步驟這麼一來，您的應用程式就會算繪到顯示途徑每個輸入影格只能建立一次請參閱 previewOverlayView 和 FIRDetectionOverlayView 例如，在展示範例應用程式中使用類別。