Android 圖片嵌入指南

MediaPipe 圖片嵌入工具工作可讓您將圖片資料轉換為數字表示法,以完成與機器學習相關的圖片處理工作,例如比較兩張圖片的相似度。以下操作說明將說明如何在 Android 應用程式中使用圖片嵌入工具。

如要進一步瞭解這項工作的功能、模型和設定選項,請參閱總覽

程式碼範例

MediaPipe 工作範例程式碼是 Android 圖片嵌入程式應用程式的簡易實作方式。這個範例使用實體 Android 裝置的相機持續嵌入圖片,也可以在裝置上儲存的圖片檔上執行嵌入程式。

您可以將該應用程式做為開發 Android 應用程式的起點,或在修改現有應用程式時參照該應用程式。Image Embedder 範例程式碼則代管在 GitHub

下載程式碼

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

如要下載範例程式碼,請按照下列步驟操作:

  1. 使用下列指令複製 Git 存放區:
    git clone https://github.com/google-ai-edge/mediapipe-samples
    
  2. 您可以選擇將 Git 執行個體設為使用稀疏檢查,因此只有 Image Embedder 範例應用程式的檔案:
    cd mediapipe
    git sparse-checkout init --cone
    git sparse-checkout set examples/image_embedder/android
    

建立範例程式碼的本機版本後,您可以將專案匯入 Android Studio 並執行應用程式。如需操作說明,請參閱 Android 設定指南

重要元件

下列檔案包含此圖片嵌入程式範例應用程式的重要程式碼:

設定

本節說明設定開發環境及程式碼專案以使用 Image Embedder 的重要步驟。如需瞭解如何設定開發環境以使用 MediaPipe 工作 (包括平台版本需求),請參閱 Android 設定指南

依附元件

圖片嵌入程式會使用 com.google.mediapipe:tasks-vision 程式庫。將此依附元件新增至 Android 應用程式開發專案的 build.gradle 檔案。使用下列程式碼匯入必要的依附元件:

dependencies {
    ...
    implementation 'com.google.mediapipe:tasks-vision:latest.release'
}

型號

MediaPipe 圖片嵌入程式工作需要與這項工作相容的已訓練模型。如要進一步瞭解圖片嵌入工具的可用已訓練模型,請參閱工作總覽「模型」一節

選取並下載模型,然後將其儲存在專案目錄中:

<dev-project-root>/src/main/assets

ModelAssetPath 參數中指定模型的路徑。範例程式碼中的 ImageEmbedderHelper.kt 檔案的 setupImageEmbedder() 函式定義了模型:

請使用 BaseOptions.Builder.setModelAssetPath() 方法指定模型使用的路徑。在下一節的程式碼範例中稱為此方法。

建立工作

您可以使用 createFromOptions 函式建立工作。createFromOptions 函式可接受設定選項,設定嵌入工具選項。如要進一步瞭解設定選項,請參閱「設定總覽」一文。

圖片嵌入工具工作支援 3 種輸入資料類型:靜態圖片、影片檔案和直播影片串流。您在建立工作時,需要指定與輸入資料類型相對應的執行模式。請選擇與輸入資料類型對應的分頁標籤,瞭解如何建立工作並執行推論。

圖片

ImageEmbedderOptions options =
  ImageEmbedderOptions.builder()
    .setBaseOptions(
      BaseOptions.builder().setModelAssetPath("model.tflite").build())
    .setQuantize(true)
    .setRunningMode(RunningMode.IMAGE)
    .build();
imageEmbedder = ImageEmbedder.createFromOptions(context, options);
    

影片

ImageEmbedderOptions options =
  ImageEmbedderOptions.builder()
    .setBaseOptions(
      BaseOptions.builder().setModelAssetPath("model.tflite").build())
    .setQuantize(true)
    .setRunningMode(RunningMode.VIDEO)
    .build();
imageEmbedder = ImageEmbedder.createFromOptions(context, options);
    

直播

ImageEmbedderOptions options =
  ImageEmbedderOptions.builder()
    .setBaseOptions(
      BaseOptions.builder().setModelAssetPath("model.tflite").build())
    .setQuantize(true)
    .setRunningMode(RunningMode.LIVE_STREAM)
    .setResultListener((result, inputImage) -> {
         // Process the embedding result here.
    })
    .build();
imageEmbedder = ImageEmbedder.createFromOptions(context, options);
    

程式碼範例實作可讓使用者切換處理模式。這種做法會讓工作建立程式碼變得更加複雜,且可能不適合您的用途。您可以在 ImageEmbedderHelper.kt 檔案的 setupImageEmbedder() 函式中看到此程式碼。

設定選項

這項工作的 Android 應用程式設定選項如下:

選項名稱 說明 值範圍 預設值
runningMode 設定工作的執行模式。共有三種模式:

IMAGE:單一圖片輸入的模式。

影片:影片已解碼影格的模式。

LIVE_STREAM:輸入資料串流 (例如攝影機) 的直播模式。在這個模式下,必須呼叫 resultListener 才能設定事件監聽器,以非同步方式接收結果。
{IMAGE, VIDEO, LIVE_STREAM} IMAGE
l2_normalize 是否使用 L2 正規化傳回的特徵向量。只有在模型不含原生 L2_NORMALIZATION TFLite Op 的情況下,才能使用這個選項。在大多數情況下,已經是此情況,L2 正規化是透過 TFLite 推論達成,不需要使用這個選項。 Boolean False
quantize 是否應透過純量量化,將傳回的嵌入量化為位元組。以隱含方式假設嵌入為單位標準,因此任何維度保證在 [-1.0, 1.0] 中都有一個值。如果並非如此,請使用 l2_正規化選項。 Boolean False
resultListener 在 Image Embedder 處於直播模式時,設定結果事件監聽器以非同步方式接收嵌入結果。只能在執行模式設為 LIVE_STREAM 時使用 不適用 未設定
errorListener 設定選用的錯誤事件監聽器。 不適用 未設定

準備資料

「圖片嵌入程式」支援圖片、影片檔案和直播影片。工作會處理資料輸入的預先處理作業,包括調整大小、旋轉和值正規化。

您必須先將輸入圖片或影格轉換為 com.google.mediapipe.framework.image.MPImage 物件,才能將其傳送至圖片嵌入工具工作。

圖片

import com.google.mediapipe.framework.image.BitmapImageBuilder;
import com.google.mediapipe.framework.image.MPImage;

// Load an image on the user’s device as a Bitmap object using BitmapFactory.

// Convert an Android’s Bitmap object to a MediaPipe’s Image object.
Image mpImage = new BitmapImageBuilder(bitmap).build();
    

影片

import com.google.mediapipe.framework.image.BitmapImageBuilder;
import com.google.mediapipe.framework.image.MPImage;

// Load a video file on the user's device using MediaMetadataRetriever

// From the video’s metadata, load the METADATA_KEY_DURATION and
// METADATA_KEY_VIDEO_FRAME_COUNT value. You’ll need them
// to calculate the timestamp of each frame later.

// Loop through the video and load each frame as a Bitmap object.

// Convert the Android’s Bitmap object to a MediaPipe’s Image object.
Image mpImage = new BitmapImageBuilder(frame).build();
    

直播

import com.google.mediapipe.framework.image.MediaImageBuilder;
import com.google.mediapipe.framework.image.MPImage;

// Create a CameraX’s ImageAnalysis to continuously receive frames
// from the device’s camera. Configure it to output frames in RGBA_8888
// format to match with what is required by the model.

// For each Android’s ImageProxy object received from the ImageAnalysis,
// extract the encapsulated Android’s Image object and convert it to
// a MediaPipe’s Image object.
android.media.Image mediaImage = imageProxy.getImage()
Image mpImage = new MediaImageBuilder(mediaImage).build();
    

範例程式碼中的 ImageEmbedderHelper.kt 檔案會處理資料準備。

執行工作

您可以呼叫執行模式對應的 embed 函式來觸發推論。Image Embedder API 會傳回輸入圖片或影格的嵌入向量。

圖片

ImageEmbedderResult embedderResult = imageEmbedder.embed(image);
    

影片

// Calculate the timestamp in milliseconds of the current frame.
long frame_timestamp_ms = 1000 * video_duration * frame_index / frame_count;

// Run inference on the frame.
ImageEmbedderResult embedderResult =
    imageEmbedder.embedForVideo(image, frameTimestampMs);
    

直播


// Run inference on the frame. The embedding results will be available
// via the `resultListener` provided in the `ImageEmbedderOptions` when
// the image embedder was created.
imageEmbedder.embedAsync(image, frameTimestampMs);
    

注意事項:

  • 以影片模式或直播模式執行時,您也必須為圖片嵌入工具工作提供輸入影格的時間戳記。
  • 在圖片或影片模式中執行時,圖片嵌入程式工作會封鎖目前的執行緒,直到完成輸入圖片或影格的處理為止。為避免封鎖目前的執行緒,請在背景執行緒中執行處理作業。
  • 以直播模式執行時,圖片嵌入工具工作不會封鎖目前的執行緒,但會立即傳回。每當它處理完輸入影格時,就會透過偵測結果叫用結果監聽器。如果在圖片嵌入工具工作忙於處理其他影格時呼叫 embedAsync 函式,則工作會忽略新的輸入影格。

範例程式碼中的 ImageEmbedderHelper.kt 檔案中定義了 embed 函式。

處理並顯示結果

執行推論時,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 函式來比較兩個嵌入的相似性。相關範例請看以下程式碼。

// Compute cosine similarity.
double similarity = ImageEmbedder.cosineSimilarity(
  result.embeddingResult().embeddings().get(0),
  otherResult.embeddingResult().embeddings().get(0));