Guide d'intégration d'images pour Android

La tâche MediaPipe Image Embedder vous permet de convertir les données d'image en représentation numérique pour effectuer des tâches de traitement d'image liées au ML, telles que la comparaison de la similarité de deux images. Ces instructions vous expliquent comment utiliser l'outil d'intégration d'images avec les applications Android.

Pour en savoir plus sur les fonctionnalités, les modèles et les options de configuration de cette tâche, consultez la section Présentation.

Exemple de code

L'exemple de code MediaPipe Tasks est une implémentation simple d'une application d'intégration d'images pour Android. L'exemple utilise l'appareil photo d'un appareil Android physique pour intégrer des images en continu et peut également exécuter l'outil d'intégration sur les fichiers image stockés sur l'appareil.

Vous pouvez utiliser l'application comme point de départ pour votre propre application Android ou vous y référer lorsque vous modifiez une application existante. L'exemple de code de l'outil d'intégration d'images est hébergé sur GitHub.

Télécharger le code

Les instructions suivantes vous expliquent comment créer une copie locale de l'exemple de code à l'aide de l'outil de ligne de commande git.

Pour télécharger l'exemple de code:

1. Clonez le dépôt Git à l'aide de la commande suivante:

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

2. Vous pouvez également configurer votre instance git pour utiliser un "checkout sparse" afin de n'avoir que les fichiers de l'exemple d'application Image Embedder:

   cd mediapipe
   git sparse-checkout init --cone
   git sparse-checkout set examples/image_embedder/android
   

Après avoir créé une version locale de l'exemple de code, vous pouvez importer le projet dans Android Studio et exécuter l'application. Pour obtenir des instructions, consultez le guide de configuration pour Android.

Composants clés

Les fichiers suivants contiennent le code essentiel de cet exemple d'application d'intégration d'images:

• ImageEmbedderHelper.kt: initialise l'outil d'intégration d'images et gère le modèle et la sélection du délégué.
• MainActivity.kt: implémente l'application et assemble les composants de l'interface utilisateur.

Configuration

Cette section décrit les étapes clés à suivre pour configurer votre environnement de développement et vos projets de code afin d'utiliser Image Embedder. Pour obtenir des informations générales sur la configuration de votre environnement de développement pour utiliser les tâches MediaPipe, y compris les exigences concernant la version de la plate-forme, consultez le guide de configuration pour Android.

Dépendances

Image Embedder utilise la bibliothèque com.google.mediapipe:tasks-vision. Ajoutez cette dépendance au fichier build.gradle de votre projet de développement d'application Android. Importez les dépendances requises avec le code suivant:

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

Modèle

La tâche d'encapsulation d'image MediaPipe nécessite un modèle entraîné compatible avec cette tâche. Pour en savoir plus sur les modèles entraînés disponibles pour Image Embedder, consultez la section Modèles de la présentation de la tâche.

Sélectionnez et téléchargez le modèle, puis stockez-le dans le répertoire de votre projet:

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

Spécifiez le chemin d'accès au modèle dans le paramètre ModelAssetPath. Dans l'exemple de code, le modèle est défini dans la fonction setupImageEmbedder() du fichier ImageEmbedderHelper.kt:

Utilisez la méthode BaseOptions.Builder.setModelAssetPath() pour spécifier le chemin d'accès utilisé par le modèle. Cette méthode est référencée dans l'exemple de code de la section suivante.

Créer la tâche

Vous pouvez utiliser la fonction createFromOptions pour créer la tâche. La fonction createFromOptions accepte des options de configuration pour définir les options d'intégration. Pour en savoir plus sur les options de configuration, consultez la section Présentation de la configuration.

La tâche d'insertion d'images accepte trois types de données d'entrée: les images fixes, les fichiers vidéo et les flux vidéo en direct. Vous devez spécifier le mode d'exécution correspondant à votre type de données d'entrée lorsque vous créez la tâche. Sélectionnez l'onglet correspondant à votre type de données d'entrée pour découvrir comment créer la tâche et exécuter l'inférence.

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);
    

L'implémentation de l'exemple de code permet à l'utilisateur de basculer entre les modes de traitement. Cette approche rend le code de création de tâches plus complexe et n'est peut-être pas adaptée à votre cas d'utilisation. Vous pouvez voir ce code dans la fonction setupImageEmbedder() du fichier ImageEmbedderHelper.kt.

Options de configuration

Cette tâche propose les options de configuration suivantes pour les applications Android:

Préparer les données

L'outil d'intégration d'images fonctionne avec les images, les fichiers vidéo et les vidéos en direct. La tâche gère le prétraitement de l'entrée des données, y compris le redimensionnement, la rotation et la normalisation des valeurs.

Vous devez convertir l'image ou le frame d'entrée en objet com.google.mediapipe.framework.image.MPImage avant de le transmettre à la tâche d'intégration d'images.

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();
    

Dans l'exemple de code, la préparation des données est gérée dans le fichier ImageEmbedderHelper.kt.

Exécuter la tâche

Vous pouvez appeler la fonction embed correspondant à votre mode d'exécution pour déclencher des inférences. L'API Image Embedder renvoie les vecteurs d'embedding pour l'image ou le frame d'entrée.

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);
    

Veuillez noter les points suivants :

• Lorsque vous exécutez le mode vidéo ou le mode diffusion en direct, vous devez également fournir le code temporel du frame d'entrée à la tâche d'intégration d'images.
• Lorsqu'elle s'exécute en mode image ou vidéo, la tâche d'intégration d'images bloque le thread actuel jusqu'à ce qu'elle ait terminé de traiter l'image ou le frame d'entrée. Pour éviter de bloquer le thread actuel, exécutez le traitement dans un thread en arrière-plan.
• Lorsqu'elle s'exécute en mode diffusion en direct, la tâche d'intégration d'images ne bloque pas le thread en cours, mais renvoie immédiatement. Il appelle son écouteur de résultats avec le résultat de la détection chaque fois qu'il a terminé le traitement d'un frame d'entrée. Si la fonction embedAsync est appelée lorsque la tâche d'intégration d'images est occupée à traiter un autre frame, la tâche ignore le nouveau frame d'entrée.

Dans l'exemple de code, la fonction embed est définie dans le fichier ImageEmbedderHelper.kt.

Gérer et afficher les résultats

Lors de l'exécution de l'inférence, la tâche Image Embedder renvoie un objet ImageEmbedderResult contenant une liste d'embeddings (à virgule flottante ou à quantification scalaire) pour l'image d'entrée.

Voici un exemple des données de sortie de cette tâche:

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

Ce résultat a été obtenu en encapsulant l'image suivante:

Vous pouvez comparer la similarité de deux représentations vectorielles continues à l'aide de la fonction ImageEmbedder.cosineSimilarity. Pour en savoir plus, consultez le code suivant.

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