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

La tarea 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 Python. 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 Hand Landmarker 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 detector de puntos de referencia. Puedes ver, ejecutar y editar el código de ejemplo de Hand Landmarker solo con tu navegador web.

Si implementas el marcador de manos 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 Hand Landmarker. Si deseas obtener información general sobre cómo configurar el 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 Python.

Paquetes

La tarea de marcador de manos de MediaPipe requiere el paquete mediapipe de PyPI. Puedes instalar e importar estas dependencias con lo siguiente:

$ python -m pip install mediapipe

Importaciones

Importa las siguientes clases para acceder a las funciones de tarea de Hand Landmarker:

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

Modelo

La tarea de MediaPipe Hand Landmarker requiere un modelo entrenado que sea compatible con esta tarea. Si deseas obtener más información sobre los modelos entrenados disponibles para Hand Landmarker, consulta la sección Modelos de 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'

Usa el parámetro model_asset_path del objeto BaseOptions para especificar la ruta del modelo que se usará. Para ver un ejemplo de código, consulta la siguiente sección.

Crea la tarea

La tarea de marcador de manos 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.

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

Imagen

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
HandLandmarker = mp.tasks.vision.HandLandmarker
HandLandmarkerOptions = mp.tasks.vision.HandLandmarkerOptions
VisionRunningMode = mp.tasks.vision.RunningMode

# Create a hand landmarker instance with the image mode:
options = HandLandmarkerOptions(
    base_options=BaseOptions(model_asset_path='/path/to/model.task'),
    running_mode=VisionRunningMode.IMAGE)
with HandLandmarker.create_from_options(options) as landmarker:
  # The landmarker is initialized. Use it here.
  # ...

Video

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
HandLandmarker = mp.tasks.vision.HandLandmarker
HandLandmarkerOptions = mp.tasks.vision.HandLandmarkerOptions
VisionRunningMode = mp.tasks.vision.RunningMode

# Create a hand landmarker instance with the video mode:
options = HandLandmarkerOptions(
    base_options=BaseOptions(model_asset_path='/path/to/model.task'),
    running_mode=VisionRunningMode.VIDEO)
with HandLandmarker.create_from_options(options) as landmarker:
  # The landmarker is initialized. Use it here.
  # ...

Transmisión en vivo

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
HandLandmarker = mp.tasks.vision.HandLandmarker
HandLandmarkerOptions = mp.tasks.vision.HandLandmarkerOptions
HandLandmarkerResult = mp.tasks.vision.HandLandmarkerResult
VisionRunningMode = mp.tasks.vision.RunningMode

# Create a hand landmarker instance with the live stream mode:
def print_result(result: HandLandmarkerResult, output_image: mp.Image, timestamp_ms: int):
    print('hand landmarker result: {}'.format(result))

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

Si deseas ver un ejemplo completo de cómo crear un marcador de posición de mano para usarlo con una imagen, consulta el ejemplo de código.

Opciones de configuración

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

Nombre de la opción Descripción Rango de valores Valor predeterminado
running_mode 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
num_hands La cantidad máxima de manos que detecta el detector de puntos de referencia de la mano. Any integer > 0 1
min_hand_detection_confidence 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
min_hand_presence_confidence 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
min_tracking_confidence 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
result_callback Establece el objeto de escucha de resultados para recibir los resultados de la detección de forma asíncrona cuando el punto de referencia de la mano 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

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.

Imagen

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)

Video

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)

Transmisión en vivo

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 marcador de manos usa las funciones detect, detect_for_video y detect_async para activar inferencias. Para la detección de puntos de referencia de la mano, esto implica el procesamiento previo de los datos de entrada, la detección de las manos en la imagen y la detección de puntos de referencia de la mano.

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

Imagen

# Perform hand landmarks detection on the provided single image.
# The hand landmarker must be created with the image mode.
hand_landmarker_result = landmarker.detect(mp_image)

Video

# Perform hand landmarks detection on the provided single image.
# The hand landmarker must be created with the video mode.
hand_landmarker_result = landmarker.detect_for_video(mp_image, frame_timestamp_ms)

Transmisión en vivo

# Send live image data to perform hand landmarks detection.
# The results are accessible via the `result_callback` provided in
# the `HandLandmarkerOptions` object.
# The hand landmarker must be created with the live stream mode.
landmarker.detect_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 de Hand Landmarker la marca de tiempo del fotograma de entrada.
  • Cuando se ejecuta en la imagen o el modelo de video, la tarea Hand Landmarker bloquea el subproceso actual hasta que termine de procesar la imagen o el marco de entrada.
  • 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 una trama 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.

Para ver un ejemplo completo de cómo ejecutar un marcador de mano en una imagen, consulta el ejemplo de código para obtener más información.

Cómo controlar y mostrar 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 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 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, 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.

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 el ejemplo de código para obtener más información.