La tarea de MediaPipe Hand Landmarker te permite detectar los puntos de referencia de las manos en una imagen. En estas instrucciones, se muestra cómo usar el marcador de manos con apps para Android. El código de muestra que se describe en estas instrucciones está disponible en GitHub.
Para obtener más información sobre las funciones, 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 Hand Landmarker para Android. En el ejemplo, se usa la cámara de un dispositivo Android físico para detectar continuamente los puntos de referencia de la mano y también se pueden usar imágenes y videos de la galería del dispositivo para detectarlos de forma estática.
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 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, sigue estos pasos:
- Clona el repositorio de git con el siguiente comando:
git clone https://github.com/google-ai-edge/mediapipe-samples
- De manera opcional, configura tu instancia de git para usar el control de revisión disperso, de modo que solo tengas 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 a 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 fundamental de esta aplicación de ejemplo de detección de puntos de referencia de la mano:
- HandLandmarkerHelper.kt: Inicializa el detector de puntos de referencia de la mano y controla el modelo y la selección 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 codificar proyectos específicamente para usar Hand Landmarker. Si deseas 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 tarea de marcador de mano 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 MediaPipe Hand Landmarker requiere un paquete de modelos entrenados que sea compatible con esta tarea. Para obtener más información sobre los modelos entrenados disponibles para Hand Landmarker, consulta la sección Modelos de la descripción general de la tarea.
Selecciona y descarga el modelo, y guárdalo en el directorio de tu proyecto:
<dev-project-root>/src/main/assets
Especifica la ruta de acceso 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 de MediaPipe Hand Landmarker usa la función createFromOptions() para configurar la tarea. La función createFromOptions() acepta valores para las opciones de configuración. Para obtener más información sobre las opciones de configuración, consulta Opciones de configuración.
Hand Landmarker admite 3 tipos de datos de entrada: imágenes fijas, archivos de video y transmisión en vivo. Cuando crees la tarea, debes especificar el modo de ejecución correspondiente al 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.
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 los modos de procesamiento. El enfoque hace que el código de creación de tareas sea más complicado y es posible que no sea adecuado 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 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 para los fotogramas decodificados de un video. LIVE_STREAM: Es el modo de transmisión en vivo de datos de entrada, como los de una cámara. En este modo, se debe llamar a resultListener para configurar un objeto de escucha que reciba resultados de forma asíncrona. |
{IMAGE, VIDEO, LIVE_STREAM} |
IMAGE |
numHands |
Es la cantidad máxima de manos que detecta el detector de puntos de referencia de manos. | Any integer > 0 |
1 |
minHandDetectionConfidence |
Es la puntuación de confianza mínima para que la detección de la mano se considere exitosa en el modelo de detección de la palma. | 0.0 - 1.0 |
0.5 |
minHandPresenceConfidence |
Es la 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 el modo de video y en el modo de transmisión en vivo, si la puntuación de confianza de la presencia de la mano del modelo de puntos de referencia de la mano está por debajo de este umbral, el marcador de puntos de referencia de la mano activa el modelo de detección de palmas. De lo contrario, un algoritmo de seguimiento de manos ligero determina la ubicación de las manos para las detecciones de puntos de referencia posteriores. | 0.0 - 1.0 |
0.5 |
minTrackingConfidence |
Es la puntuación de confianza mínima para que el seguimiento de manos se considere exitoso. Este es el umbral de IoU del cuadro de límite entre las manos en el fotograma actual y el último. En el modo de video y el modo de transmisión de Hand Landmarker, si el seguimiento falla, Hand Landmarker activa la detección de la mano. De lo contrario, se omite la detección de manos. | 0.0 - 1.0 |
0.5 |
resultListener |
Establece el objeto de escucha de resultados para que reciba los resultados de detección de forma asíncrona cuando el marcador de manos esté en modo de transmisión en vivo.
Solo se aplica cuando el modo de ejecución se establece en LIVE_STREAM. |
N/A | N/A |
errorListener |
Establece un objeto de escucha de errores opcional. | N/A | N/A |
Preparar los datos
La herramienta de marcadores de manos funciona con imágenes, archivos de video y videos de transmisiones 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. Estos ejemplos incluyen detalles sobre cómo controlar los datos de imágenes, archivos de video y transmisiones de video en vivo.
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 Hand Landmarker, la preparación de datos se controla en el archivo HandLandmarkerHelper.kt.
Ejecuta la tarea
Según el tipo de datos con los que estés trabajando, usa el método HandLandmarker.detect...() específico para ese tipo de datos. Usa detect() para imágenes individuales, detectForVideo() para marcos en archivos de video y detectAsync() para transmisiones de video. Cuando realices detecciones en una transmisión de video, asegúrate de ejecutarlas en un subproceso independiente para evitar bloquear el subproceso de la interfaz de usuario.
En las siguientes muestras de código, se muestran ejemplos simples de cómo ejecutar Hand Landmarker 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 en el modo de transmisión en vivo, también debes proporcionar la marca de tiempo del fotograma de entrada a la tarea de Hand Landmarker.
- Cuando se ejecuta en el modo de imagen o video, la tarea de Hand Landmarker bloqueará el subproceso actual hasta que termine de procesar la imagen o el fotograma 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 de Hand Landmarker no bloquea el subproceso actual, sino que se muestra de inmediato. Invocará su objeto de escucha de resultados con el resultado de la detección cada vez que termine de procesar un fotograma de entrada. Si se llama a la función de detección cuando la tarea de Hand Landmarker está ocupada procesando otro fotograma, la tarea ignorará el nuevo fotograma de entrada.
En el código de ejemplo de Hand Landmarker, las funciones detect, detectForVideo y detectAsync se definen en el archivo HandLandmarkerHelper.kt.
Cómo controlar y mostrar los resultados
El marcador de manos genera un objeto de resultado de marcador de manos para cada ejecución de detección. El objeto de resultado contiene puntos de referencia de la mano en coordenadas de imagen, puntos de referencia de la mano en coordenadas mundiales y la lateralidad(mano izquierda o derecha) de las manos detectadas.
A continuación, se muestra un ejemplo de los datos de resultado 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:
Lateralidad
La mano dominante indica si las manos detectadas son izquierda o derecha.
Puntos de referencia
Hay 21 puntos de referencia de la mano, cada uno compuesto por coordenadas
x,yyz. Las coordenadasxyyse normalizan a [0.0, 1.0] según el ancho y la altura de la imagen, respectivamente. La coordenadazrepresenta la profundidad del punto de referencia, y la profundidad en la muñeca es el origen. Cuanto menor sea el valor, más cerca estará el punto de referencia de la cámara. La magnitud dezusa aproximadamente la misma escala quex.Monumentos universales
Los 21 puntos de referencia de la mano también se presentan en coordenadas mundiales. Cada punto de referencia se compone de
x,yyz, 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 muestra cómo mostrar los resultados que se devuelven de la tarea. Consulta la clase OverlayView para obtener más detalles.