隆重推出 LiteRT：Google 為裝置端 AI (舊稱 TensorFlow Lite) 打造的高效能執行階段。

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

iOS 版圖片嵌入指南

MediaPipe 圖片嵌入器工作可將圖片資料轉換為數值表示法，以便完成機器學習相關的圖片處理工作，例如比較兩張圖片的相似度。

您可以在 GitHub 上找到這些操作說明中所述的程式碼範例。您可以查看此網路示範，瞭解這項工作的實際運作情形。如要進一步瞭解這項工作的功能、模型和設定選項，請參閱總覽。

程式碼範例

MediaPipe Tasks 程式碼範例是 iOS 圖片嵌入應用程式的基本實作方式。這個範例會使用實體 iOS 裝置的相機持續嵌入圖片，也可以在裝置相片庫中執行嵌入器。

您可以使用這個應用程式做為自有 iOS 應用程式的起點，或是在修改現有應用程式時參考這個應用程式。圖片嵌入器範例程式碼託管於 GitHub 上。

下載程式碼

以下操作說明說明如何使用 git 指令列工具，建立範例程式碼的本機副本。

下載程式碼範例：

使用下列指令複製 Git 存放區：

git clone https://github.com/google-ai-edge/mediapipe-samples

您可以選擇將 Git 例項設定為使用稀疏檢查，這樣就只會取得 Image Embedder 範例應用程式的檔案：
```
cd mediapipe
git sparse-checkout init --cone
git sparse-checkout set examples/image_embedder/ios
```

建立範例程式碼的本機版本後，您可以安裝 MediaPipe 工作程式庫、使用 Xcode 開啟專案，然後執行應用程式。如需操作說明，請參閱 iOS 設定指南。

重要元件

以下檔案包含 Image Embedder 範例應用程式的關鍵程式碼：

ImageEmbedderService.swift：初始化 Image Embedder、處理模型選取作業，並針對輸入資料執行推論。
CameraViewController.swift：為即時攝影機動態饋給輸入模式實作 UI，並將結果以視覺化方式呈現。
MediaLibraryViewController.swift：實作靜態影像輸入模式的 UI，並將結果以視覺化方式呈現。

設定

本節將說明設定開發環境和程式碼專案，以便使用 Image Embedder 的關鍵步驟。如要進一步瞭解如何設定開發環境以使用 MediaPipe 工作，包括平台版本需求，請參閱 iOS 設定指南。

依附元件

圖片嵌入工具會使用 MediaPipeTasksVision 程式庫，必須使用 CocoaPods 安裝。這個程式庫與 Swift 和 Objective-C 應用程式相容，且不需要任何額外的語言專屬設定。

如需在 macOS 上安裝 CocoaPods 的操作說明，請參閱 CocoaPods 安裝指南。如需有關如何為應用程式建立包含必要 Pod 的 Podfile 的操作說明，請參閱「使用 CocoaPods」一文。

使用下列程式碼，在 Podfile 中新增 MediaPipeTasksVision Pod：

target 'MyImageEmbedderApp' do
  use_frameworks!
  pod 'MediaPipeTasksVision'
end

如果您的應用程式包含單元測試目標，請參閱「iOS 設定指南」，進一步瞭解如何設定 Podfile。

型號

MediaPipe 圖片嵌入器工作需要訓練的模型與此工作相容。如要進一步瞭解可供圖像嵌入器使用的訓練模型，請參閱「模型」一節。

選取並下載模型，然後使用 Xcode 將模型新增至專案目錄。如需在 Xcode 專案中新增檔案的操作說明，請參閱「管理 Xcode 專案中的檔案和資料夾」。

使用 BaseOptions.modelAssetPath 屬性指定應用程式套件中的模型路徑。

建立工作

您可以呼叫其中一個初始化器來建立 Image Embedder 工作。ImageEmbedder(options:) 初始化器會接受設定選項的值。

如果您不需要使用自訂設定選項來初始化圖片嵌入器，可以使用 ImageEmbedder(modelPath:) 初始化工具，以預設選項建立圖片嵌入器。如要進一步瞭解設定選項，請參閱設定總覽。

圖片嵌入器工作支援 3 種輸入資料類型：靜態圖片、影片檔案和直播影片串流。根據預設，ImageEmbedder(modelPath:) 會初始化靜態圖片的工作。如要初始化工作以處理影片檔案或直播影片串流，請使用 ImageEmbedder(options:) 指定影片或即時串流執行模式。直播模式也需要額外的 imageEmbedderLiveStreamDelegate 設定選項，讓 Image Embedder 能非同步將圖片嵌入結果傳送給委派。

請選擇對應於執行模式的分頁，瞭解如何建立工作並執行推論。

Swift

圖片

import MediaPipeTasksVision

let modelPath = Bundle.main.path(
  forResource: "model",
  ofType: "tflite")

let options = ImageEmbedderOptions()
options.baseOptions.modelAssetPath = modelPath
options.quantize = true
options.l2Normalize = true

let imageEmbedder = try ImageEmbedder(options: options)

影片

import MediaPipeTasksVision

let modelPath = Bundle.main.path(
  forResource: "model",
  ofType: "tflite")

let options = ImageEmbedderOptions()
options.baseOptions.modelAssetPath = modelPath
options.runningMode = .video
options.quantize = true
options.l2Normalize = true

let imageEmbedder = try ImageEmbedder(options: options)

直播

import MediaPipeTasksVision

// Class that conforms to the `ImageEmbedderLiveStreamDelegate` protocol and
// implements the method that the image embedder calls once it finishes
// embedding each input frame.
class ImageEmbedderResultProcessor: NSObject, ImageEmbedderLiveStreamDelegate {

  func imageEmbedder(
    _ imageEmbedder: ImageEmbedder,
    didFinishEmbedding result: ImageEmbedderResult?,
    timestampInMilliseconds: Int,
    error: Error?) {

    // Process the image embedder result or errors here.

  }
}

let modelPath = Bundle.main.path(
  forResource: "model",
  ofType: "tflite")

let options = ImageEmbedderOptions()
options.baseOptions.modelAssetPath = modelPath
options.runningMode = .liveStream
options.quantize = true
options.l2Normalize = true

// Assign an object of the class to the `imageEmbedderLiveStreamDelegate`
// property.
let processor = ImageEmbedderResultProcessor()
options.imageEmbedderLiveStreamDelegate = processor

let imageEmbedder = try ImageEmbedder(options: options)

Objective-C

圖片

@import MediaPipeTasksVision;

NSString *modelPath = [[NSBundle mainBundle] pathForResource:@"model"
                                                      ofType:@"tflite"];

MPPImageEmbedderOptions *options = [[MPPImageEmbedderOptions alloc] init];
options.baseOptions.modelAssetPath = modelPath;
options.runningMode = MPPRunningModeImage;
options.quantize = YES;
options.l2Normalize = YES;

MPPImageEmbedder *imageEmbedder =
  [[MPPImageEmbedder alloc] initWithOptions:options error:nil];

影片

@import MediaPipeTasksVision;

NSString *modelPath = [[NSBundle mainBundle] pathForResource:@"model"
                                                      ofType:@"tflite"];

MPPImageEmbedderOptions *options = [[MPPImageEmbedderOptions alloc] init];
options.baseOptions.modelAssetPath = modelPath;
options.runningMode = MPPRunningModeVideo;
options.quantize = YES;
options.l2Normalize = YES;

MPPImageEmbedder *imageEmbedder =
  [[MPPImageEmbedder alloc] initWithOptions:options error:nil];

直播

@import MediaPipeTasksVision;

// Class that conforms to the `MPPImageEmbedderLiveStreamDelegate` protocol
// and implements the method that the image embedder calls once it finishes
// embedding each input frame.
@interface APPImageEmbedderResultProcessor : NSObject 

@end

@implementation APPImageEmbedderResultProcessor

-   (void)imageEmbedder:(MPPImageEmbedder *)imageEmbedder
    didFinishEmbeddingWithResult:(MPPImageEmbedderResult *)imageEmbedderResult
         timestampInMilliseconds:(NSInteger)timestampInMilliseconds
                           error:(NSError *)error {

    // Process the image embedder result or errors here.

}

@end

NSString *modelPath = [[NSBundle mainBundle] pathForResource:@"model"
                                                      ofType:@"tflite"];

MPPImageEmbedderOptions *options = [[MPPImageEmbedderOptions alloc] init];
options.baseOptions.modelAssetPath = modelPath;
options.runningMode = MPPRunningModeLiveStream;
options.quantize = YES;
options.l2Normalize = YES;

// Assign an object of the class to the `imageEmbedderLiveStreamDelegate`
// property.
APPImageEmbedderResultProcessor *processor =
  [APPImageEmbedderResultProcessor new];
options.imageEmbedderLiveStreamDelegate = processor;

MPPImageEmbedder *imageEmbedder =
  [[MPPImageEmbedder alloc] initWithOptions:options error:nil];

設定選項

此工作包含下列 iOS 應用程式的設定選項：

選項名稱	說明	值範圍	預設值
`runningMode`	設定任務的執行模式。圖片嵌入器有三種模式：圖片：單一圖片輸入模式。 VIDEO：影片解碼影格模式。 LIVE_STREAM：輸入資料 (例如來自攝影機的資料) 的直播模式。在這個模式中，`imageEmbedderLiveStreamDelegate` 必須設為實作 `ImageEmbedderLiveStreamDelegate` 的類別例項，以非同步方式接收嵌入圖片影格結果。	{RunningMode.image, RunningMode.video, RunningMode.liveStream}	{RunningMode.image}
`l2Normalize`	是否使用 L2 正規化將傳回的特徵向量正規化。只有在模型未包含原生 L2_NORMALIZATION TFLite 運算時，才使用這個選項。在大多數情況下，模型都已包含原生 L2_NORMALIZATION TFLite 運算，因此不需要使用這個選項。	布林值	false
`quantize`	是否應透過標量量化，將傳回的嵌入值量化為位元組。默認會假設嵌入為單位非單位，因此所有維度保證都會有 [-1.0, 1.0] 的值。如果不是這種情況，請使用 l2Normalize 選項。	布林值	false

當執行模式設為直播時，圖片嵌入工具需要額外的 imageEmbedderLiveStreamDelegate 設定選項，才能讓圖片嵌入工具以非同步方式提供圖片嵌入結果。委派程式必須實作 imageEmbedder(_:didFinishEmbedding:timestampInMilliseconds:error:) 方法，圖片嵌入器會在處理每個輸入圖片影格嵌入結果後呼叫此方法。

選項名稱	說明	值範圍	預設值
`imageEmbedderLiveStreamDelegate`	啟用 Image Embedder，在直播模式中以非同步方式接收嵌入圖片的結果。將例項設為此屬性的類別必須實作 `imageEmbedder(_:didFinishEmbedding:timestampInMilliseconds:error:)` 方法。	不適用	未設定

準備資料

您必須先將輸入圖片或影格轉換為 MPImage 物件，再傳送至圖片嵌入工具。MPImage 支援不同類型的 iOS 圖片格式，並可在任何執行模式下用於推論。如要進一步瞭解 MPImage，請參閱 MPImage API。

請根據用途和應用程式所需的執行模式，選擇 iOS 圖片格式。MPImage 接受 UIImage、CVPixelBuffer 和 CMSampleBuffer iOS 圖片格式。

UIImage

UIImage 格式非常適合下列執行模式：

圖片：應用程式套件、使用者圖庫或檔案系統中的圖片 (格式為 UIImage 圖片) 可以轉換為 MPImage 物件。
影片：使用 AVAssetImageGenerator 將影片影格擷取為 CGImage 格式，然後轉換為 UIImage 圖片。

Swift

// Load an image on the user's device as an iOS `UIImage` object.

// Convert the `UIImage` object to a MediaPipe's Image object having the default
// orientation `UIImage.Orientation.up`.
let image = try MPImage(uiImage: image)

Objective-C

// Load an image on the user's device as an iOS `UIImage` object.

// Convert the `UIImage` object to a MediaPipe's Image object having the default
// orientation `UIImageOrientationUp`.
MPImage *image = [[MPPImage alloc] initWithUIImage:image error:nil];

這個範例會使用預設的 UIImage.Orientation.Up 方向初始化 MPImage。您可以使用任何支援的 UIImage.Orientation 值初始化 MPImage。圖片嵌入器不支援鏡像方向，例如 .upMirrored、.downMirrored、.leftMirrored、.rightMirrored。

如要進一步瞭解 UIImage，請參閱「UIImage Apple 開發人員說明文件」。

CVPixelBuffer

CVPixelBuffer 格式非常適合用於產生影格，並使用 iOS CoreImage 架構進行處理的應用程式。

CVPixelBuffer 格式非常適合下列執行模式：

圖片：如果應用程式在使用 iOS 的 CoreImage 架構進行部分處理後，產生 CVPixelBuffer 圖片，則可在圖片執行模式下傳送至圖片嵌入工具。
影片：可將影片影格轉換為 CVPixelBuffer 格式進行處理，然後以影片模式傳送至圖片嵌入工具。
直播：使用 iOS 相機產生影格時，應用程式可能會先將影格轉換為 CVPixelBuffer 格式進行處理，再以直播模式傳送至圖片嵌入工具。

Swift

// Obtain a CVPixelBuffer.

// Convert the `CVPixelBuffer` object to a MediaPipe's Image object having the default
// orientation `UIImage.Orientation.up`.
let image = try MPImage(pixelBuffer: pixelBuffer)

Objective-C

// Obtain a CVPixelBuffer.

// Convert the `CVPixelBuffer` object to a MediaPipe's Image object having the
// default orientation `UIImageOrientationUp`.
MPImage *image = [[MPPImage alloc] initWithUIImage:image error:nil];

如要進一步瞭解 CVPixelBuffer，請參閱 CVPixelBuffer Apple 開發人員說明文件。

CMSampleBuffer

CMSampleBuffer 格式會儲存統一媒體類型的媒體樣本，非常適合直播執行模式。iOS AVCaptureVideoDataOutput 會以 CMSampleBuffer 格式，以非同步方式傳送 iOS 攝影機的即時影格。

Swift

// Obtain a CMSampleBuffer.

// Convert the `CMSampleBuffer` object to a MediaPipe's Image object having the default
// orientation `UIImage.Orientation.up`.
let image = try MPImage(sampleBuffer: sampleBuffer)

Objective-C

// Obtain a `CMSampleBuffer`.

// Convert the `CMSampleBuffer` object to a MediaPipe's Image object having the
// default orientation `UIImageOrientationUp`.
MPImage *image = [[MPPImage alloc] initWithSampleBuffer:sampleBuffer error:nil];

如要進一步瞭解 CMSampleBuffer，請參閱 CMSampleBuffer Apple 開發人員說明文件。

執行工作

如要執行 Image Embedder，請使用已指派的執行模式專用的 embed() 方法：

靜態圖片：embed(image:)
影片：embed(videoFrame:timestampInMilliseconds:)
直播：embedAsync(image:timestampInMilliseconds:)

以下程式碼範例提供如何在這些不同執行模式下執行 Image Embedder 的基本範例：

Swift

圖片

let result = try imageEmbedder.embed(image: image)

影片

let result = try imageEmbedder.embed(
  videoFrame: image,
  timestampInMilliseconds: timestamp)

直播

try imageEmbedder.embedAsync(
  image: image,
  timestampInMilliseconds: timestamp)

Objective-C

圖片

MPPImageEmbedderResult *result =
  [imageEmbedder embedImage:image error:nil];

影片

MPPImageEmbedderResult *result =
  [imageEmbedder embedVideoFrame:image
           timestampInMilliseconds:timestamp
                             error:nil];

直播

BOOL success =
  [imageEmbedder embedAsyncImage:image
           timestampInMilliseconds:timestamp
                             error:nil];

圖片嵌入器程式碼範例會更詳細說明這些模式的實作方式，包括 embed(image:)、embed(videoFrame:timestampInMilliseconds:) 和 embedAsync(image:timestampInMilliseconds:)。程式碼範例可讓使用者在處理模式之間切換，但這可能不是您使用情境所需的功能。

注意事項：

在影片模式或直播模式下執行時，您也必須向圖片嵌入器工作提供輸入影格時間戳記。
在圖片或影片模式中執行時，Image Embedder 工作會封鎖目前的執行緒，直到處理完成輸入圖片或影格為止。為避免阻斷目前執行緒，請使用 iOS Dispatch 或 NSOperation 架構，在背景執行緒中執行處理作業。如果您使用 Swift 建立應用程式，也可以使用 Swift 並行處理執行背景執行緒。
在直播模式下執行時，圖片嵌入器工作會立即傳回，且不會封鎖目前的執行緒。在嵌入每個輸入影格後，它會使用結果呼叫 imageEmbedder(_:didFinishEmbedding:timestampInMilliseconds:error:) 方法。Image Embedder 會在專屬的序列調度佇列中，以非同步方式叫用這個方法。如要在使用者介面上顯示結果，請在處理結果後將結果分派至主要佇列。如果在 Image Embedder 工作忙於處理另一個影格時呼叫 embedAsync 函式，圖片嵌入器會忽略新的輸入影格。

處理及顯示結果

執行推論時，Image Embedder 會傳回 ImageEmbedderResult 物件，其中包含輸入圖片的嵌入 (浮點或純量量化) 清單。

以下是這項工作的輸出資料範例：

ImageEmbedderResult:
  Embedding #0 (sole embedding head):
    float_embedding: {0.0, 0.0, ..., 0.0, 1.0, 0.0, 0.0, 2.0}
    head_index: 0

我們是透過嵌入下列圖片取得這項結果：

您可以使用 ImageEmbedder.cosineSimilarity 函式比較兩個嵌入項目的相似程度。

Swift

let similarity = try ImageEmbedder.cosineSimilarity(
  embedding1: result.embeddingResult.embeddings[0],
  embedding2: otherResult.embeddingResult.embeddings[0])

Objective-C

NSNumber *similarity = [MPPImageEmbedder
      cosineSimilarityBetweenEmbedding1:result.embeddingResult.embeddings[0]
                          andEmbedding2:otherResult.embeddingResult.embeddings[0]
                                  error:nil];