La tarea Reconocedor de gestos de MediaPipe te permite reconocer gestos de la mano en tiempo real y proporciona los resultados reconocidos de gestos manuales y puntos de referencia de las manos detectadas. En estas instrucciones, se muestra cómo usar el reconocedor de gestos con apps para Android. La muestra de código que se describe en estas instrucciones está disponible en GitHub.
Puedes ver esta tarea en acción en la demostración web. 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 reconocimiento de gestos para Android. En el ejemplo, se usa la cámara de un dispositivo Android físico para detectar de forma continua los gestos de la mano y también se pueden usar imágenes y videos de la galería del dispositivo a fin de detectar gestos de forma estática.
Puedes usarla como punto de partida de tu propia app para Android o consultarla cuando modifiques una app existente. El código de ejemplo del Reconocedor de gestos 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:
- Usa el siguiente comando para clonar el repositorio de Git:
git clone https://github.com/google-ai-edge/mediapipe-samples
- 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 Reconocedor de gestos:
cd mediapipe git sparse-checkout init --cone git sparse-checkout set examples/gesture_recognizer/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 reconocimiento de gestos manuales:
- GestureRecognizerHelper.kt: Inicializa el reconocedor de gestos y controla la selección del modelo y del delegado.
- MainActivity.kt: Implementa la aplicación, incluida la llamada a
GestureRecognizerHelper
yGestureRecognizerResultsAdapter
. - GestureRecognizerResultsAdapter.kt: Maneja y formatea los resultados.
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 Reconocedor de gestos. 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 Reconocedor de gestos 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 reconocimiento de gestos 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 Reconocedor de gestos, consulta la descripción general de la tarea en la sección Modelos.
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 GestureRecognizerHelper.kt
:
baseOptionBuilder.setModelAssetPath(MP_RECOGNIZER_TASK)
Crea la tarea
La tarea Reconocedor de gestos de MediaPipe usa la función createFromOptions()
para configurarla. 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 Reconocedor de gestos admite 3 tipos de datos de entrada: imágenes fijas, 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
val baseOptionsBuilder = BaseOptions.builder().setModelAssetPath(MP_RECOGNIZER_TASK) val baseOptions = baseOptionBuilder.build() val optionsBuilder = GestureRecognizer.GestureRecognizerOptions.builder() .setBaseOptions(baseOptions) .setMinHandDetectionConfidence(minHandDetectionConfidence) .setMinTrackingConfidence(minHandTrackingConfidence) .setMinHandPresenceConfidence(minHandPresenceConfidence) .setRunningMode(RunningMode.IMAGE) val options = optionsBuilder.build() gestureRecognizer = GestureRecognizer.createFromOptions(context, options)
Video
val baseOptionsBuilder = BaseOptions.builder().setModelAssetPath(MP_RECOGNIZER_TASK) val baseOptions = baseOptionBuilder.build() val optionsBuilder = GestureRecognizer.GestureRecognizerOptions.builder() .setBaseOptions(baseOptions) .setMinHandDetectionConfidence(minHandDetectionConfidence) .setMinTrackingConfidence(minHandTrackingConfidence) .setMinHandPresenceConfidence(minHandPresenceConfidence) .setRunningMode(RunningMode.VIDEO) val options = optionsBuilder.build() gestureRecognizer = GestureRecognizer.createFromOptions(context, options)
Transmisión en vivo
val baseOptionsBuilder = BaseOptions.builder().setModelAssetPath(MP_RECOGNIZER_TASK) val baseOptions = baseOptionBuilder.build() val optionsBuilder = GestureRecognizer.GestureRecognizerOptions.builder() .setBaseOptions(baseOptions) .setMinHandDetectionConfidence(minHandDetectionConfidence) .setMinTrackingConfidence(minHandTrackingConfidence) .setMinHandPresenceConfidence(minHandPresenceConfidence) .setResultListener(this::returnLivestreamResult) .setErrorListener(this::returnLivestreamError) .setRunningMode(RunningMode.LIVE_STREAM) val options = optionsBuilder.build() gestureRecognizer = GestureRecognizer.createFromOptions(context, options)
La implementación de código de ejemplo del reconocedor de gestos permite al usuario alternar 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 setupGestureRecognizer()
del archivo GestureRecognizerHelper.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 |
GestureRecognizer puede detectar la cantidad máxima de manos.
|
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 de 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 del Reconocedor de gestos, si la puntuación de confianza de la presencia de la mano del modelo de punto de referencia de la mano está por debajo de este umbral, se activa el modelo de detección de palma. De lo contrario, se usa un algoritmo ligero de seguimiento de la mano para determinar la ubicación de las manos y detectar puntos de referencia posteriormente. | 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. En los modos de video y de transmisión del Reconocedor de gestos, si falla el seguimiento, el Reconocedor de gestos activa la detección de la mano. De lo contrario, se omitirá la detección de la mano. | 0.0 - 1.0 |
0.5 |
|
cannedGesturesClassifierOptions |
Opciones para configurar el comportamiento del clasificador de gestos estándar. Los gestos estándar son ["None", "Closed_Fist", "Open_Palm", "Pointing_Up", "Thumb_Down", "Thumb_Up", "Victory", "ILoveYou"] |
|
|
|
customGesturesClassifierOptions |
Opciones para configurar el comportamiento del clasificador de gestos personalizado. |
|
|
|
resultListener |
Configura el objeto de escucha de resultados para recibir los resultados de clasificación de forma asíncrona cuando el reconocedor de gestos está en el modo de transmisión en vivo.
Solo se puede usar cuando el modo de ejecución está configurado en LIVE_STREAM |
ResultListener |
N/A | N/A |
errorListener |
Establece un objeto de escucha de errores opcional. | ErrorListener |
N/A | N/A |
Preparar los datos
El Reconocedor de gestos 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.
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 del Reconocedor de gestos, la preparación de los datos se controla en el archivo GestureRecognizerHelper.kt
.
Ejecuta la tarea
El Reconocedor de gestos usa las funciones recognize
, recognizeForVideo
y recognizeAsync
para activar las inferencias. Para el reconocimiento de gestos, esto implica el procesamiento previo de los datos de entrada, la detección de las manos en la imagen, los puntos de referencia de la mano y el reconocimiento de los gestos manuales desde los puntos de referencia.
En el siguiente código, se muestra cómo ejecutar el procesamiento con el modelo de tareas. Estas muestras 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
val result = gestureRecognizer?.recognize(mpImage)
Video
val timestampMs = i * inferenceIntervalMs gestureRecognizer?.recognizeForVideo(mpImage, timestampMs) ?.let { recognizerResult -> resultList.add(recognizerResult) }
Transmisión en vivo
val mpImage = BitmapImageBuilder(rotatedBitmap).build() val frameTime = SystemClock.uptimeMillis() gestureRecognizer?.recognizeAsync(mpImage, frameTime)
Ten en cuenta lo siguiente:
- Cuando se ejecuta en el modo de video o de transmisión en vivo, también debes proporcionar la marca de tiempo del fotograma de entrada a la tarea del Reconocedor de gestos.
- Cuando se ejecuta en el modo de imagen o video, la tarea Reconocedor de gestos 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 Reconocedor de gestos no bloquea el subproceso actual, pero se muestra de inmediato. Invocará a su objeto de escucha de resultados con el resultado del reconocimiento cada vez que termine de procesar un marco de entrada. Si se llama a la función de reconocimiento cuando la tarea del Reconocedor de gestos esté ocupada procesando otro fotograma, la tarea ignorará el nuevo fotograma de entrada.
En el código de ejemplo del Reconocedor de gestos, las funciones recognize
, recognizeForVideo
y recognizeAsync
se definen en el archivo GestureRecognizerHelper.kt
.
Cómo controlar y mostrar los resultados
El Reconocedor de gestos genera un objeto de resultado de detección de gestos para cada ejecución de reconocimiento. 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, categorías de mano(izquierda y derecha) y gestos de la mano de las manos detectadas.
A continuación, se muestra un ejemplo de los datos de salida de esta tarea:
El GestureRecognizerResult
resultante contiene cuatro componentes, y cada uno es un array, en el que cada elemento contiene el resultado detectado de una sola mano detectada.
Mano dominante
La mano representa si las manos detectadas son manos izquierdas o derechas.
Gestos
Las categorías de gestos reconocidas de las manos detectadas.
Puntos de referencia
Hay 21 puntos de referencia de la mano, cada uno compuesto por las coordenadas
x
,y
yz
. Las coordenadasx
yy
se normalizan a [0.0, 1.0] por el ancho y la altura de la imagen, respectivamente. La coordenadaz
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 dez
usa más o menos la misma escala quex
.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
yz
, que representan coordenadas 3D del mundo real en metros con el origen en el centro geométrico de la mano.
GestureRecognizerResult:
Handedness:
Categories #0:
index : 0
score : 0.98396
categoryName : Left
Gestures:
Categories #0:
score : 0.76893
categoryName : Thumb_Up
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 las siguientes imágenes, se muestra una visualización del resultado de la tarea:
En el código de ejemplo del Reconocedor de gestos, la clase GestureRecognizerResultsAdapter
del archivo GestureRecognizerResultsAdapter.kt
controla los resultados.