Guía de detección de puntos de referencia manuales para Android

La tarea MediaPipe Hand Landmarker te permite detectar los puntos de referencia de las manos en una imagen. Estas instrucciones te muestran cómo usar el marcador de la mano con las aplicaciones para Android. La muestra de código que se describe en estas instrucciones está disponible en GitHub.

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 marcador de posición manual para Android. En el ejemplo, se usa la cámara de un dispositivo Android físico para detectar de forma continua los puntos de referencia de las manos y también se pueden usar imágenes y videos de la galería del dispositivo para detectar de forma estática los puntos de referencia de las manos.

Puedes usar la app como punto de partida para tu propia app para Android o consultarla cuando modifiques una app existente. El código de ejemplo de Hand Landmarker está alojado 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 tu instancia de Git para que use un proceso de confirmación de compra disperso, de modo que solo tengas los archivos para la app de ejemplo de Hand Landmarker: 
    cd mediapipe
git sparse-checkout init --cone
git sparse-checkout set examples/hand_landmarker/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 detección de puntos de referencia manuales:

  • HandLandmarkerHelper.kt: Inicializa el detector de puntos de referencia de la mano y controla la selección del modelo y del delegado.
  • MainActivity.kt: Implementa la aplicación, incluida la llamada a HandLandmarkerHelper.

Configuración

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

Dependencias

La tarea Hand Landmarker usa la biblioteca com.google.mediapipe:tasks-vision. Agrega esta dependencia al archivo build.gradle de tu app para Android:

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

Modelo

La tarea de marcador manual de MediaPipe requiere un paquete de modelos entrenados que sea compatible con esta tarea. Si deseas obtener más información sobre los modelos entrenados disponibles para el marcador manual, consulta la sección Modelos de la descripción general de la tarea.

Selecciona y descarga el modelo, y 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 el archivo HandLandmarkerHelper.kt:

baseOptionBuilder.setModelAssetPath(MP_HAND_LANDMARKER_TASK)

Crea la tarea

La tarea MediaPipe Hand Landmarker usa la función createFromOptions() para configurar la tarea. La función createFromOptions() acepta valores para las opciones de configuración. Si deseas obtener más información sobre las opciones de configuración, consulta Opciones de configuración.

El marcador manual es compatible con 3 tipos de datos de entrada: imágenes estáticas, archivos de video y transmisión 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 que corresponda a tu tipo de datos de entrada para ver cómo crear la tarea y ejecutar la inferencia.

De imagen

val baseOptionsBuilder = BaseOptions.builder().setModelAssetPath(MP_HAND_LANDMARKER_TASK)
val baseOptions = baseOptionBuilder.build()

val optionsBuilder =
    HandLandmarker.HandLandmarkerOptions.builder()
        .setBaseOptions(baseOptions)
        .setMinHandDetectionConfidence(minHandDetectionConfidence)
        .setMinTrackingConfidence(minHandTrackingConfidence)
        .setMinHandPresenceConfidence(minHandPresenceConfidence)
        .setNumHands(maxNumHands)
        .setRunningMode(RunningMode.IMAGE)

val options = optionsBuilder.build()

handLandmarker =
    HandLandmarker.createFromOptions(context, options)

Video

val baseOptionsBuilder = BaseOptions.builder().setModelAssetPath(MP_HAND_LANDMARKER_TASK)
val baseOptions = baseOptionBuilder.build()

val optionsBuilder =
    HandLandmarker.HandLandmarkerOptions.builder()
        .setBaseOptions(baseOptions)
        .setMinHandDetectionConfidence(minHandDetectionConfidence)
        .setMinTrackingConfidence(minHandTrackingConfidence)
        .setMinHandPresenceConfidence(minHandPresenceConfidence)
        .setNumHands(maxNumHands)
        .setRunningMode(RunningMode.VIDEO)

val options = optionsBuilder.build()

handLandmarker =
    HandLandmarker.createFromOptions(context, options)

Transmisión en vivo

val baseOptionsBuilder = BaseOptions.builder().setModelAssetPath(MP_HAND_LANDMARKER_TASK)
val baseOptions = baseOptionBuilder.build()

val optionsBuilder =
    HandLandmarker.HandLandmarkerOptions.builder()
        .setBaseOptions(baseOptions)
        .setMinHandDetectionConfidence(minHandDetectionConfidence)
        .setMinTrackingConfidence(minHandTrackingConfidence)
        .setMinHandPresenceConfidence(minHandPresenceConfidence)
        .setNumHands(maxNumHands)
        .setResultListener(this::returnLivestreamResult)
        .setErrorListener(this::returnLivestreamError)
        .setRunningMode(RunningMode.VIDEO)

val options = optionsBuilder.build()

handLandmarker =
    HandLandmarker.createFromOptions(context, options)

La implementación de código de ejemplo de Hand Landmarker 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 que no sea apropiado para tu caso de uso. Puedes ver este código en la función setupHandLandmarker() del archivo HandLandmarkerHelper.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
numHands La cantidad máxima de manos detectadas por el detector de puntos de referencia de la mano. Any integer > 0 1
minHandDetectionConfidence Puntuación de confianza mínima para que la detección de la mano se considere exitosa en el modelo de detección de palma. 0.0 - 1.0 0.5
minHandPresenceConfidence Puntuación de confianza mínima para la puntuación de presencia de la mano en el modelo de detección de puntos de referencia de la mano. En los modos de video y de transmisión en vivo, si la puntuación de confianza de la presencia de la mano del modelo del punto de referencia de la mano es inferior a este umbral, el marcador de la mano activa el modelo de detección de la palma. De lo contrario, un algoritmo básico de seguimiento de la mano determina la ubicación de las manos para las detecciones de puntos de referencia posteriores. 0.0 - 1.0 0.5
minTrackingConfidence La puntuación de confianza mínima para que el seguimiento de la mano se considere exitoso. Este es el umbral de IoU del cuadro de límite entre las manos en el marco actual y el último fotograma. Si el seguimiento falla, en los modos Video y Transmisión de Marcadores manuales, se activa la detección de la mano. De lo contrario, omitirá la detección de la mano. 0.0 - 1.0 0.5
resultListener Configura el objeto de escucha de resultados para recibir los resultados de la detección de forma asíncrona cuando el punto de referencia manual está en el modo de transmisión en vivo. Solo se aplica cuando el modo de ejecución está configurado en LIVE_STREAM N/A N/A
errorListener Establece un objeto de escucha de errores opcional. N/A N/A

Preparar los datos

El marcador manual funciona con imágenes, archivos de video y videos de transmisión 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.

En el siguiente código, se muestra cómo transferir datos para su procesamiento. En estos ejemplos, se incluyen detalles sobre cómo controlar los datos de las imágenes, los archivos de video y las transmisiones de video en vivo.

De imagen

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

// Convert the input Bitmap object to an MPImage object to run inference
val mpImage = BitmapImageBuilder(image).build()

Video

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

val argb8888Frame =
    if (frame.config == Bitmap.Config.ARGB_8888) frame
    else frame.copy(Bitmap.Config.ARGB_8888, false)

// Convert the input Bitmap object to an MPImage object to run inference
val mpImage = BitmapImageBuilder(argb8888Frame).build()

Transmisión en vivo

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

// Convert the input Bitmap object to an MPImage object to run inference
val mpImage = BitmapImageBuilder(rotatedBitmap).build()

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

Ejecuta la tarea

Según el tipo de datos con los que trabajes, usa el método HandLandmarker.detect...() específico para ese tipo de datos. Usa detect() para imágenes individuales, detectForVideo() para fotogramas en archivos de video y detectAsync() para transmisiones de video por Internet. Cuando realices detecciones en una transmisión de video por Internet, asegúrate de ejecutarlas en un subproceso independiente para evitar bloquear el subproceso de interfaz de usuario.

En las siguientes muestras de código, se incluyen ejemplos simples sobre cómo ejecutar Hand Landmarker en estos modos de datos diferentes:

De imagen

val result = handLandmarker?.detect(mpImage)

Video

val timestampMs = i * inferenceIntervalMs

handLandmarker?.detectForVideo(mpImage, timestampMs)
    ?.let { detectionResult ->
        resultList.add(detectionResult)
    }

Transmisión en vivo

val mpImage = BitmapImageBuilder(rotatedBitmap).build()
val frameTime = SystemClock.uptimeMillis()

handLandmarker?.detectAsync(mpImage, frameTime)

Ten en cuenta lo siguiente:

  • Cuando se ejecuta en modo de video o de transmisión en vivo, también debes proporcionar la marca de tiempo del fotograma de entrada a la tarea de marcador manual.
  • Cuando se ejecuta en los modos de imagen o video, la tarea Hand Landmarker bloqueará el subproceso actual hasta que termine de procesar la imagen o el marco de entrada. Para evitar bloquear la interfaz de usuario, ejecuta el procesamiento en un subproceso en segundo plano.
  • Cuando se ejecuta en el modo de transmisión en vivo, la tarea Hand Landmarker 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 de detección cuando la tarea Hand Landmarker está ocupada procesando otro fotograma, la tarea ignorará el nuevo fotograma de entrada.

En el código de ejemplo de marcador de mano, las funciones detect, detectForVideo y detectAsync se definen en el archivo HandLandmarkerHelper.kt.

Cómo controlar y mostrar los resultados

Hand Landmarker genera un objeto de resultado del marcador de referencia de la mano para cada ejecución de detección. El objeto del resultado contiene puntos de referencia de la mano en coordenadas de imágenes, puntos de referencia de la mano en coordenadas mundiales y la mano(izquierda/derecha) de las manos detectadas.

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

El resultado de HandLandmarkerResult contiene tres componentes. Cada componente es un array, en el que cada elemento contiene los siguientes resultados para una sola mano detectada:

  • Mano dominante

    La mano representa si las manos detectadas son manos izquierdas o derechas.

  • Puntos de referencia

    Hay 21 puntos de referencia de la mano, cada uno compuesto por las coordenadas x, y y z. Las coordenadas x y y se normalizan a [0.0, 1.0] por el ancho y la altura de la imagen, respectivamente. La coordenada z representa la profundidad del punto de referencia, y la profundidad en la muñeca es el origen. Cuanto más bajo sea el valor, más cerca estará el punto de referencia de la cámara. La magnitud de z usa más o menos la misma escala que x.

  • Monumentos universales

    Los puntos de referencia de las 21 manos también se presentan en coordenadas mundiales. Cada punto de referencia está compuesto por x, y y z, que representan coordenadas 3D del mundo real en metros con el origen en el centro geométrico de la mano.

HandLandmarkerResult:
  Handedness:
    Categories #0:
      index        : 0
      score        : 0.98396
      categoryName : Left
  Landmarks:
    Landmark #0:
      x            : 0.638852
      y            : 0.671197
      z            : -3.41E-7
    Landmark #1:
      x            : 0.634599
      y            : 0.536441
      z            : -0.06984
    ... (21 landmarks for a hand)
  WorldLandmarks:
    Landmark #0:
      x            : 0.067485
      y            : 0.031084
      z            : 0.055223
    Landmark #1:
      x            : 0.063209
      y            : -0.00382
      z            : 0.020920
    ... (21 world landmarks for a hand)

En la siguiente imagen, se muestra una visualización del resultado de la tarea:

En el código de ejemplo de Hand Landmarker, se demuestra cómo mostrar los resultados que muestra la tarea. Consulta la clase OverlayView para obtener más detalles.