Guide d'intégration d'images pour Android

La tâche d'intégration d'images MediaPipe vous permet de convertir des données d'image en une représentation numérique pour effectuer des tâches de traitement d'images 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 des applications Android.

Pour en savoir plus sur les fonctionnalités, les modèles et les options de configuration de cette tâche, consultez la 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. Cet exemple utilise l'appareil photo d'un appareil Android physique pour intégrer en continu des images. Il 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, procédez comme suit:

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 éventuellement configurer votre instance Git pour utiliser le paiement creux afin de n'avoir que les fichiers de l'exemple d'application d'intégration d'images :

   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 crucial pour 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 des délégués.
• MainActivity.kt: met en œuvre l'application et assemble les composants de l'interface utilisateur.

Préparation

Cette section décrit les étapes clés de la configuration de votre environnement de développement et de vos projets de code afin d'utiliser l'outil d'intégration d'images. Pour obtenir des informations générales sur la configuration de votre environnement de développement pour l'utilisation des tâches MediaPipe, y compris les exigences concernant les versions de la plate-forme, consultez le guide de configuration pour Android.

Dépendances

L'outil d'intégration d'images 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 à l'aide du code suivant:

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

Modèle

La tâche d'intégration d'images 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 l'outil d'intégration d'images, consultez la section Modèles de la présentation des tâches.

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 du 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 de l'outil d'intégration. Pour en savoir plus sur les options de configuration, consultez la section Présentation de la configuration.

La tâche d'intégration d'images est compatible avec 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 lors de la création de la tâche. Choisissez l'onglet correspondant à votre type de données d'entrée pour voir 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'exemple d'implémentation de code permet à l'utilisateur de basculer entre les modes de traitement. Cette approche complique le code de création des tâches et peut ne pas être 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 dispose des options de configuration suivantes pour les applications Android:

Préparation des données

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

Vous devez convertir l'image ou l'image d'entrée en objet com.google.mediapipe.framework.image.MPImage avant de la transmettre à la tâche de l'outil 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 de représentation vectorielle continue de l'image ou du cadre 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 :

• Lors de l'exécution en mode vidéo ou en mode flux en direct, vous devez également fournir l'horodatage de l'image d'entrée à la tâche de l'outil d'intégration d'images.
• Lors de l'exécution en mode image ou vidéo, la tâche d'intégration d'images bloque le thread actuel jusqu'à ce qu'elle ait fini de traiter l'image ou le cadre d'entrée. Pour éviter de bloquer le thread actuel, exécutez le traitement dans un thread d'arrière-plan.
• Lorsqu'elle est exécutée en mode diffusion en direct, la tâche d'intégration d'images ne bloque pas le thread actuel, mais est renvoyée immédiatement. Il appelle son écouteur de résultat avec le résultat de la détection chaque fois qu'il a fini de traiter une trame d'entrée. Si la fonction embedAsync est appelée lorsque la tâche de l'outil 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 de l'outil d'intégration d'images renvoie un objet ImageEmbedderResult contenant une liste de représentations vectorielles continues (à 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 intégrant l'image suivante:

Vous pouvez comparer la similarité de deux représentations vectorielles continues à l'aide de la fonction ImageEmbedder.cosineSimilarity. Consultez le code suivant pour obtenir un exemple.

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