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 utilizar el marcador de posición de la mano en las apps para Android. El de muestra de código descrita en estas instrucciones está disponible en GitHub:

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

Ejemplo de código

El código de ejemplo de tareas de MediaPipe es una implementación simple de un marcador de posición de mano para Android. En el ejemplo, se usa la cámara de un dispositivo Android físico para detecta continuamente puntos de referencia en las manos y puede usar imágenes y videos de la para detectar de forma estática puntos de referencia en la mano.

Puedes usar la app como punto de partida para tu propia app para Android o hacer referencia a ella. cuando se modifica una app existente. El código de ejemplo de Hand Landmarker se aloja en GitHub:

Descarga el código

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

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

  1. Clona el repositorio de Git con el siguiente comando: 
    git clone https://github.com/google-ai-edge/mediapipe-samples
  2. De forma opcional, configura tu instancia de Git para que use el resultado escaso. Solo tienes los archivos de 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 en Android Studio y ejecutar la app. Para obtener instrucciones, consulta la Guía de configuración para Android

Componentes clave

Los siguientes archivos contienen el código crucial para este punto de referencia de la mano. aplicación de ejemplo de detección:

  • HandLandmarkerHelper.kt: Inicializa el detector de puntos de referencia de la mano y controla el modelo y el delegado. selección.
  • 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 para proyectos de programación específicos para usar Hand Landmarker. Para obtener información general configurar tu entorno de desarrollo para usar tareas de MediaPipe, como de la versión de la plataforma, consulta la Guía de configuración para Android.

Dependencias

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

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

Modelo

La tarea MediaPipe Hand Landmarker requiere un paquete de modelos entrenados compatible con esta tarea. Para obtener más información sobre los modelos entrenados disponibles para Hand Landmarker, consulta la sección Modelos en 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 la código de ejemplo, el modelo se define en el archivo HandLandmarkerHelper.kt archivo:

baseOptionBuilder.setModelAssetPath(MP_HAND_LANDMARKER_TASK)

Crea la tarea

La tarea de marcador de posición de la mano de MediaPipe usa la función createFromOptions() para configurar la tarea. La función createFromOptions() acepta valores para la configuración opciones de estado. Para obtener más información sobre las opciones de configuración, consulta Opciones de configuración.

Hand Landmarker admite tres tipos de datos de entrada: imágenes fijas, archivos de video y transmisión en vivo. Debes especificar el modo de ejecución correspondiente a tu el tipo de datos de entrada cuando se crea la tarea. Elige la pestaña correspondiente a tu el tipo de datos de entrada para ver cómo crear la tarea y ejecutar la inferencia.

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 del código de ejemplo de Hand Landmarker permite al usuario cambiar entre modos de procesamiento. Este enfoque hace que el código de creación de tareas sea más complicado y pueden no ser adecuados para tu caso de uso. Puedes ver este código en la función setupHandLandmarker() en HandLandmarkerHelper.kt .

Opciones de configuración

Esta tarea tiene 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 de la tarea. Existen tres modos:

IMAGE: Es el modo para entradas de una sola imagen.

VIDEO: es el modo de los fotogramas decodificados de un video.

LIVE_STREAM: Es el modo para una transmisión en vivo de entradas. datos, como los de una cámara. En este modo, resultListener debe se llama para configurar un objeto de escucha que reciba resultados de forma asíncrona. 		{IMAGE, VIDEO, LIVE_STREAM} IMAGE
numHands La cantidad máxima de manos que detecta el detector de puntos de referencia de la mano. Any integer > 0 1
minHandDetectionConfidence La puntuación de confianza mínima para la detección de la mano considerado exitoso en el modelo de detección de palma. 0.0 - 1.0 0.5
minHandPresenceConfidence La puntuación de confianza mínima para la puntuación de presencia de la mano en la mano de detección de puntos de referencia. 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 de punto de referencia de la mano es inferior este umbral, Hand Landmarker, se activa el modelo de detección de la palma. De lo contrario, el algoritmo de seguimiento de manos ligeras determina la ubicación de para las detecciones de puntos de referencia posteriores. 0.0 - 1.0 0.5
minTrackingConfidence La puntuación de confianza mínima para que se considere el seguimiento de la mano y exitoso. Este es el umbral de IoU del cuadro delimitador entre manos en el fotograma actual y el último. En los modos Video y Transmisión de El marcador de posición de mano (hand Landmarker) si el seguimiento falla, activa la mano de detección de intrusiones. De lo contrario, omitirá la detección de manos. 0.0 - 1.0 0.5
resultListener Establece el objeto de escucha de resultados para recibir los resultados de la detección. de forma asíncrona cuando el marcador de posición de la mano está en modo de transmisión en vivo. Solo es aplicable cuando el modo de ejecución está configurado en LIVE_STREAM N/A N/A
errorListener Configura un objeto de escucha de errores opcional. N/A N/A

Preparar los datos

Hand Landmarker 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, incluidos el cambio de tamaño, la rotación y el valor. normalización.

En el siguiente código, se muestra cómo entregar datos para su procesamiento. Tesis incluyen detalles sobre cómo manejar datos de imágenes, archivos de video y datos transmisiones continuas de video por Internet.

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 la el código de ejemplo de Landmarker, la preparación de los datos se maneja en HandLandmarkerHelper.kt .

Ejecuta la tarea

Según el tipo de datos con el que estés trabajando, usa el HandLandmarker.detect...() específico para ese tipo de datos. Usa detect() para imágenes individuales detectForVideo() para los fotogramas en archivos de video detectAsync() para las transmisiones de video por Internet. Al realizar detecciones en un transmisión de video por Internet, asegúrese de ejecutar las detecciones en un subproceso independiente para evitar bloqueando el subproceso de la interfaz de usuario.

En las siguientes muestras de código, se muestran ejemplos simples de cómo ejecutar el marcador de posición de mano. en estos diferentes modos de datos:

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 el modo de video o de transmisión en vivo, también debes proporciona la marca de tiempo del fotograma de entrada para la tarea Hand Landmarker.
  • Cuando se ejecuta en el modo de imagen o video, la tarea Landmarker de la mano bloquear el subproceso actual hasta que termine de procesar la imagen de entrada o marco. 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 se muestra inmediatamente. Invocará su resultado con el resultado de la detección cada vez que haya terminado de procesar una marco de entrada. Si se llama a la función de detección cuando se hace la tarea Hand Landmarker esté ocupado procesando otro fotograma, la tarea ignorará el nuevo marco de entrada.

En la código de ejemplo de Landmarker de la mano, los elementos detect, detectForVideo y Las funciones detectAsync se definen en el HandLandmarkerHelper.kt .

Cómo controlar y mostrar resultados

El marcador de posición de la mano genera un objeto de resultado del sistema de puntos de referencia de la mano para cada detección cuando se ejecute. El objeto resultante contiene puntos de referencia en coordenadas de imágenes, mano puntos de referencia en coordenadas mundiales y la mano derecha(mano izquierda/derecha) del dispositivo detectado manos.

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

El resultado 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 dominante representa si las manos detectadas son la izquierda o la derecha.

  • Puntos de referencia

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

  • Monumentos universales

    Los 21 puntos de referencia de las 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:

El código de ejemplo de Hand Landmarker muestra cómo mostrar el resultados que devolvió la tarea, consulta la OverlayView para obtener más información.