Guía de reconocimiento de gestos para Python

La tarea del Reconocedor de gestos de MediaPipe te permite reconocer gestos manuales en tiempo real y proporciona los resultados reconocidos de los gestos manuales y los puntos de referencia de las manos detectadas. En estas instrucciones, se muestra cómo usar el Reconocedor de gestos con aplicaciones de Python.

Puedes ver esta tarea en acción en la demo web. 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 del detector de gestos proporciona una implementación completa de esta tarea en Python como referencia. Este código te ayuda a probar esta tarea y comenzar a compilar tu propio reconocedor de gestos con la mano. Puedes ver, ejecutar y editar el código de ejemplo del detector de gestos solo con tu navegador web.

Si implementas el Gestor de gestos para Raspberry Pi, consulta la app de ejemplo de Raspberry Pi.

Configuración

En esta sección, se describen los pasos clave para configurar tu entorno de desarrollo y codificar proyectos específicamente para usar el Reconocedor de gestos. Para 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 de Python.

Paquetes

La tarea del Reconocedor de gestos de MediaPipe requiere el paquete mediapipe de PyPI. Puedes instalar y importar estas dependencias con lo siguiente:

$ python -m pip install mediapipe

Importaciones

Importa las siguientes clases para acceder a las funciones de tareas del Gestor de gestos:

import mediapipe as mp
from mediapipe.tasks import python
from mediapipe.tasks.python import vision

Modelo

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

Selecciona y descarga el modelo, y guárdalo en un directorio local:

model_path = '/absolute/path/to/gesture_recognizer.task'

Especifica la ruta de acceso del modelo dentro del parámetro Nombre del modelo, como se muestra a continuación:

base_options = BaseOptions(model_asset_path=model_path)

Crea la tarea

La tarea del reconocedor de gestos de MediaPipe usa la función create_from_options para configurar la tarea. La función create_from_options acepta valores para que las opciones de configuración los controlen. Para obtener más información sobre las opciones de configuración, consulta Opciones de configuración.

En el siguiente código, se muestra cómo compilar y configurar esta tarea.

Estos ejemplos también muestran las variaciones de la construcción de tareas para imágenes, archivos de video y transmisiones de video en vivo.

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
GestureRecognizer = mp.tasks.vision.GestureRecognizer
GestureRecognizerOptions = mp.tasks.vision.GestureRecognizerOptions
VisionRunningMode = mp.tasks.vision.RunningMode

# Create a gesture recognizer instance with the image mode:
options = GestureRecognizerOptions(
    base_options=BaseOptions(model_asset_path='/path/to/model.task'),
    running_mode=VisionRunningMode.IMAGE)
with GestureRecognizer.create_from_options(options) as recognizer:
  # The detector is initialized. Use it here.
  # ...
    

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
GestureRecognizer = mp.tasks.vision.GestureRecognizer
GestureRecognizerOptions = mp.tasks.vision.GestureRecognizerOptions
VisionRunningMode = mp.tasks.vision.RunningMode

# Create a gesture recognizer instance with the video mode:
options = GestureRecognizerOptions(
    base_options=BaseOptions(model_asset_path='/path/to/model.task'),
    running_mode=VisionRunningMode.VIDEO)
with GestureRecognizer.create_from_options(options) as recognizer:
  # The detector is initialized. Use it here.
  # ...
    

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
GestureRecognizer = mp.tasks.vision.GestureRecognizer
GestureRecognizerOptions = mp.tasks.vision.GestureRecognizerOptions
GestureRecognizerResult = mp.tasks.vision.GestureRecognizerResult
VisionRunningMode = mp.tasks.vision.RunningMode

# Create a gesture recognizer instance with the live stream mode:
def print_result(result: GestureRecognizerResult, output_image: mp.Image, timestamp_ms: int):
    print('gesture recognition result: {}'.format(result))

options = GestureRecognizerOptions(
    base_options=BaseOptions(model_asset_path='/path/to/model.task'),
    running_mode=VisionRunningMode.LIVE_STREAM,
    result_callback=print_result)
with GestureRecognizer.create_from_options(options) as recognizer:
  # The detector is initialized. Use it here.
  # ...
    

Opciones de configuración

Esta tarea tiene las siguientes opciones de configuración para aplicaciones de Python:

Preparar los datos

Prepara tu entrada como un archivo de imagen o un array de numpy y, luego, conviértela en un objeto mediapipe.Image. Si tu entrada es un archivo de video o una transmisión en vivo desde una cámara web, puedes usar una biblioteca externa, como OpenCV, para cargar tus fotogramas de entrada como arrays de numpy.

import mediapipe as mp

# Load the input image from an image file.
mp_image = mp.Image.create_from_file('/path/to/image')

# Load the input image from a numpy array.
mp_image = mp.Image(image_format=mp.ImageFormat.SRGB, data=numpy_image)
    

import mediapipe as mp

# Use OpenCV’s VideoCapture to load the input video.

# Load the frame rate of the video using OpenCV’s CV_CAP_PROP_FPS
# You’ll need it to calculate the timestamp for each frame.

# Loop through each frame in the video using VideoCapture#read()

# Convert the frame received from OpenCV to a MediaPipe’s Image object.
mp_image = mp.Image(image_format=mp.ImageFormat.SRGB, data=numpy_frame_from_opencv)
    

import mediapipe as mp

# Use OpenCV’s VideoCapture to start capturing from the webcam.

# Create a loop to read the latest frame from the camera using VideoCapture#read()

# Convert the frame received from OpenCV to a MediaPipe’s Image object.
mp_image = mp.Image(image_format=mp.ImageFormat.SRGB, data=numpy_frame_from_opencv)
    

Ejecuta la tarea

El Gestor de gestos usa las funciones recognize, recognize_for_video y recognize_async para activar inferencias. En el caso del reconocimiento de gestos, esto implica el procesamiento previo de los datos de entrada, la detección de manos en la imagen, la detección de puntos de referencia de la mano y el reconocimiento de gestos de la mano a partir de los puntos de referencia.

En el siguiente código, se muestra cómo ejecutar el procesamiento con el modelo de tareas.

# Perform gesture recognition on the provided single image.
# The gesture recognizer must be created with the image mode.
gesture_recognition_result = recognizer.recognize(mp_image)
    

# Perform gesture recognition on the provided single image.
# The gesture recognizer must be created with the video mode.
gesture_recognition_result = recognizer.recognize_for_video(mp_image, frame_timestamp_ms)
    

# Send live image data to perform gesture recognition.
# The results are accessible via the `result_callback` provided in
# the `GestureRecognizerOptions` object.
# The gesture recognizer must be created with the live stream mode.
recognizer.recognize_async(mp_image, frame_timestamp_ms)
    

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 proporcionarle a la tarea del Reconocedor de gestos la marca de tiempo del fotograma de entrada.
• Cuando se ejecuta en la imagen o el modelo de video, la tarea del Reconocedor de gestos bloqueará el subproceso actual hasta que termine de procesar la imagen o el fotograma de entrada.
• Cuando se ejecuta en el modo de transmisión en vivo, la tarea del detector de gestos no bloquea el subproceso actual, sino que se muestra de inmediato. Invocará su objeto de escucha de resultados con el resultado del reconocimiento cada vez que termine de procesar una trama 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.

Para obtener un ejemplo completo de cómo ejecutar un Gestor de gestos en una imagen, consulta el ejemplo de código para obtener más detalles.

Cómo controlar y mostrar los resultados

El Gesto Recognizer genera un objeto de resultado de detección de gestos para cada ejecución de reconocimiento. El objeto resultante contiene puntos de referencia de la mano en coordenadas de imagen, puntos de referencia de la mano en coordenadas mundiales, lateralidad(mano izquierda o derecha) y categorías de gestos de la mano de las manos detectadas.

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

El GestureRecognizerResult resultante contiene cuatro componentes, y cada componente es un array, en el que cada elemento contiene el resultado detectado de una sola mano detectada.

• Lateralidad

  La mano dominante indica si las manos detectadas son izquierda o derecha.

• 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 coordenadas x, y y z. Las coordenadas x y y se normalizan a [0.0, 1.0] según 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 menor sea el valor, más cerca estará el punto de referencia de la cámara. La magnitud de z usa aproximadamente la misma escala que x.

• 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, y y z, 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 Gestor de gestos, se muestra cómo mostrar los resultados de reconocimiento que se devuelven de la tarea. Consulta el ejemplo de código para obtener más detalles.