Guía de incorporación de imágenes para Android

La tarea de incorporación de imágenes de MediaPipe te permite convertir datos de imágenes en una representación numérica para realizar tareas de procesamiento de imágenes relacionadas con el AA, como comparar la similitud de dos imágenes. En estas instrucciones, se muestra cómo usar la incorporación de imágenes con apps para Android.

Para obtener más información sobre las capacidades, los modelos y las opciones de configuración de esta tarea, consulta la Descripción general.

Ejemplo de código

El código de ejemplo de MediaPipe Tasks es una implementación simple de una app de incorporación de imágenes para Android. En el ejemplo, se usa la cámara de un dispositivo Android físico para incorporar imágenes de manera continua y también se puede ejecutar la incorporación en archivos de imagen almacenados en el dispositivo.

Puedes usar la app como punto de partida de tu propia app para Android o consultarla cuando modifiques una app existente. El código de ejemplo de la incorporación de imágenes se aloja en GitHub.

Descarga el código

En las siguientes instrucciones, se muestra cómo crear una copia local del código de ejemplo con la herramienta de línea de comandos git.

Para descargar el código de ejemplo, haz lo siguiente:

  1. Usa el siguiente comando para clonar el repositorio de Git:
    git clone https://github.com/google-ai-edge/mediapipe-samples
    
  2. De manera opcional, configura la instancia de Git para que use la confirmación de la compra dispersa, de modo que solo tengas los archivos para la app de ejemplo de incorporación de imágenes:
    cd mediapipe
    git sparse-checkout init --cone
    git sparse-checkout set examples/image_embedder/android
    
    .

Después de crear una versión local del código de ejemplo, puedes importar el proyecto a Android Studio y ejecutar la app. Para obtener instrucciones, consulta la Guía de configuración de Android.

Componentes clave

Los siguientes archivos contienen el código fundamental para esta aplicación de ejemplo de incorporación de imágenes:

  • ImageEmbedderHelper.kt: Inicializa la incorporación de imágenes y controla la selección del modelo y del delegado.
  • MainActivity.kt: Implementa la aplicación y ensambla los componentes de la interfaz de usuario.

Configuración

En esta sección, se describen los pasos clave para configurar tu entorno de desarrollo y los proyectos de código a fin de usar la incorporación de imágenes. Si quieres obtener información general sobre cómo configurar tu entorno de desarrollo para usar tareas de MediaPipe, incluidos los requisitos de la versión de la plataforma, consulta la Guía de configuración para Android.

Dependencias

La incorporación de imágenes usa la biblioteca com.google.mediapipe:tasks-vision. Agrega esta dependencia al archivo build.gradle de tu proyecto de desarrollo de apps para Android. Importa las dependencias necesarias con el siguiente código:

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

Modelo

La tarea de incorporación de imágenes de MediaPipe requiere un modelo entrenado que sea compatible con esta tarea. Si deseas obtener más información sobre los modelos entrenados disponibles para la incorporación de imágenes, consulta la descripción general de la tarea en la sección Modelos.

Selecciona y descarga el modelo. Luego, almacénalo en el directorio de tu proyecto:

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

Especifica la ruta del modelo dentro del parámetro ModelAssetPath. En el código de ejemplo, el modelo se define en la función setupImageEmbedder() del archivo ImageEmbedderHelper.kt:

Usa el método BaseOptions.Builder.setModelAssetPath() para especificar la ruta que usa el modelo. Se hace referencia a este método en el ejemplo de código de la siguiente sección.

Crea la tarea

Puedes usar la función createFromOptions para crear la tarea. La función createFromOptions acepta opciones de configuración para establecer las opciones de incorporación. Para obtener más información sobre las opciones de configuración, consulta Descripción general de la configuración.

La tarea de incorporación de imágenes admite 3 tipos de datos de entrada: imágenes estáticas, archivos de video y transmisiones de video en vivo. Cuando creas la tarea, debes especificar el modo de ejecución correspondiente a tu tipo de datos de entrada. Elige la pestaña correspondiente a tu tipo de datos de entrada para ver cómo crear la tarea y ejecutar la inferencia.

De imagen

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

Video

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

Transmisión en vivo

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

La implementación de código de ejemplo permite al usuario cambiar entre los modos de procesamiento. Este enfoque hace que el código de creación de la tarea sea más complicado y puede no ser apropiado para tu caso de uso. Puedes ver este código en la función setupImageEmbedder() del archivo ImageEmbedderHelper.kt.

Opciones de configuración

Esta tarea incluye las siguientes opciones de configuración para apps para Android:

Nombre de la opción Descripción Rango de valores Valor predeterminado
runningMode Establece el modo de ejecución para la tarea. Existen tres modos:

IMAGE: El modo para entradas de una sola imagen.

VIDEO: Es el modo para los fotogramas decodificados de un video.

LIVE_STREAM: Es el modo para una transmisión en vivo de datos de entrada, como los que provienen de una cámara. En este modo, se debe llamar a resultListener para configurar un objeto de escucha a fin de recibir resultados de forma asíncrona.
{IMAGE, VIDEO, LIVE_STREAM} IMAGE
l2_normalize Indica si se debe normalizar el vector de atributos mostrados con la norma L2. Usa esta opción solo si el modelo todavía no contiene una operación nativa de TFLite L2_NORMALIZATION. En la mayoría de los casos, este ya es el caso y, por lo tanto, la normalización L2 se logra a través de inferencia de TFLite sin necesidad de esta opción. Boolean False
quantize Indica si la incorporación que se muestra debe cuantizarse en bytes a través de la cuantización escalar. Se supone implícitamente que las incorporaciones son la norma unitaria y, por lo tanto, se garantiza que cualquier dimensión tenga un valor en [-1.0, 1.0]. Si este no es el caso, usa la opción l2_normalize. Boolean False
resultListener Configura el objeto de escucha de resultados para recibir los resultados de incorporación de forma asíncrona cuando la incorporación de imágenes está en el modo de transmisión en vivo. Solo se puede usar cuando el modo de ejecución está configurado en LIVE_STREAM N/A No establecida
errorListener Establece un objeto de escucha de errores opcional. N/A No establecida

Preparar los datos

La incorporación de imágenes funciona con imágenes, archivos de video y transmisiones de video en vivo. La tarea controla el procesamiento previo de la entrada de datos, incluido el cambio de tamaño, la rotación y la normalización de valores.

Debes convertir la imagen o el marco de entrada en un objeto com.google.mediapipe.framework.image.MPImage antes de pasarlo a la tarea de incorporación de imágenes.

De imagen

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

Video

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

Transmisión en vivo

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

En el código de ejemplo, la preparación de los datos se controla en el archivo ImageEmbedderHelper.kt.

Ejecuta la tarea

Puedes llamar a la función embed correspondiente a tu modo de ejecución para activar las inferencias. La API de Image Embedder muestra los vectores de incorporación para la imagen o el marco de entrada.

De imagen

ImageEmbedderResult embedderResult = imageEmbedder.embed(image);
    

Video

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

Transmisión en vivo


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

Ten en cuenta lo siguiente:

  • Cuando la ejecutes en modo de video o de transmisión en vivo, también deberás proporcionar la marca de tiempo del fotograma de entrada a la tarea de incorporación de imágenes.
  • Cuando se ejecuta en el modo de imagen o video, la tarea de incorporación de imágenes bloqueará la conversación actual hasta que termine de procesar la imagen o el marco de entrada. Para evitar bloquear el subproceso actual, ejecuta el procesamiento en un subproceso en segundo plano.
  • Cuando se ejecuta en el modo de transmisión en vivo, la tarea de incorporación de imágenes no bloquea el subproceso actual, pero regresa de inmediato. Invocará su objeto de escucha de resultados con el resultado de la detección cada vez que termine de procesar un marco de entrada. Si se llama a la función embedAsync cuando la tarea de incorporación de imágenes está ocupada procesando otro marco, la tarea ignora el nuevo marco de entrada.

En el código de ejemplo, la función embed se define en el archivo ImageEmbedderHelper.kt.

Cómo controlar y mostrar los resultados

Cuando se ejecuta la inferencia, la tarea de incorporación de imágenes muestra un objeto ImageEmbedderResult que contiene una lista de incorporaciones (ya sea de punto flotante o cuantizadas de forma escalar) para la imagen de entrada.

A continuación, se muestra un ejemplo de los datos de salida de esta tarea:

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

Este resultado se obtuvo mediante la incorporación de la siguiente imagen:

Puedes comparar la similitud de dos incorporaciones con la función ImageEmbedder.cosineSimilarity. Consulta el siguiente código para ver un ejemplo.

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