适用于 Android 的图片嵌入指南

借助 MediaPipe Image Embedder 任务,您可以将图片数据转换为数字表示,以完成与机器学习相关的图片处理任务,例如比较两张图片的相似度。以下说明介绍了如何在 Android 应用中使用图片嵌入器。

如需详细了解此任务的功能、模型和配置选项,请参阅概览

代码示例

MediaPipe Tasks 示例代码是 Android 版图片嵌入器应用的简单实现。该示例使用实体 Android 设备上的相机连续嵌入图片,还可以对存储在设备上的图片文件运行嵌入器。

您可以使用该应用作为基础来开发自己的 Android 应用,也可以在修改现有应用时参考该应用。图片嵌入器示例代码托管在 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 设置指南

依赖项

Image Embedder 使用 com.google.mediapipe:tasks-vision 库。将此依赖项添加到 Android 应用开发项目的 build.gradle 文件中。使用以下代码导入所需的依赖项:

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

模型

MediaPipe 图片嵌入器任务需要使用与此任务兼容的经过训练的模型。如需详细了解适用于 Image Embedder 的经过训练的模型,请参阅任务概览“模型”部分

选择并下载模型,然后将其存储在项目目录中:

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

ModelAssetPath 参数中指定模型的路径。在示例代码中,模型在 ImageEmbedderHelper.kt 文件中的 setupImageEmbedder() 函数中定义:

使用 BaseOptions.Builder.setModelAssetPath() 方法指定模型使用的路径。下一部分的代码示例将引用此方法。

创建任务

您可以使用 createFromOptions 函数创建任务。createFromOptions 函数接受配置选项来设置嵌入器选项。如需详细了解配置选项,请参阅配置概览

Image Embedder 任务支持 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:单张图片输入的模式。

VIDEO:视频的已解码帧的模式。

LIVE_STREAM:输入数据(例如来自摄像头)的直播的模式。在此模式下,必须调用 resultListener,以设置用于异步接收结果的监听器。
{IMAGE, VIDEO, LIVE_STREAM} IMAGE
l2_normalize 是否以 L2 范数归一化返回的特征向量。 仅当模型尚未包含原生 L2_NORMALIZATION TFLite 运算时,才可使用此选项。在大多数情况下,情况都是如此,L2 归一化是通过 TFLite 推断实现的,因此无需使用此选项。 Boolean False
quantize 是否应通过标量量化将返回的嵌入量化为字节。嵌入被隐式假定为单位范数,因此任何维度的值都必须在 [-1.0, 1.0] 之间。如果不属于这种情况,请使用 l2_normalize 选项。 Boolean False
resultListener 设置结果监听器,以在图片嵌入器处于直播模式时异步接收嵌入结果。只能在跑步模式设为“LIVE_STREAM”时使用 N/A 未设置
errorListener 设置可选的错误监听器。 N/A 未设置

准备数据

Image Embedder 可处理图片、视频文件和直播视频。该任务会处理数据输入预处理,包括大小调整、旋转和值归一化。

您需要先将输入图片或帧转换为 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);
    

请注意以下几点:

  • 在视频模式或直播模式下运行时,您还必须向图片嵌入器任务提供输入帧的时间戳。
  • 在图片模式或视频模式下运行时,图片嵌入器任务将阻塞当前线程,直到处理完输入图片或帧。为避免阻塞当前线程,请在后台线程中执行处理。
  • 在直播模式下运行时,Image Embedder 任务不会阻塞当前线程,但会立即返回结果。每当处理完输入帧时,它都会使用检测结果调用其结果监听器。如果在图片嵌入器任务正忙于处理另一帧时调用 embedAsync 函数,则该任务会忽略新的输入帧。

在示例代码中,embed 函数在 ImageEmbedderHelper.kt 文件中定义。

处理和显示结果

运行推断后,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));