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 posición de la mano con Python. 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 ejemplo de código de Hand Landmarker brinda una implementación completa de este en Python para tu referencia. Este código te ayuda a probar esta tarea y obtener empezaste a crear tu propio detector de puntos de referencia. Puedes ver, ejecutar y editar el Código de ejemplo de Landmarker de la mano usando solo el navegador web.

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 Python.

Paquetes

La tarea MediaPipe Hand Landmarker requiere el paquete mediapipe PyPI. Puedes instalar y, luego, 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

Para la tarea MediaPipe Hand Landmarker, se requiere un modelo entrenado 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, luego, 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 de acceso. 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 posición de la mano de MediaPipe usa la función create_from_options para configurar la tarea. La función create_from_options acepta valores para conocer las opciones de configuración que manejar. Para obtener más información sobre la 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 en vivo.

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.
  # ...
    

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.
  # ...
    

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.
  # ...
    

Para ver un ejemplo completo de la creación de un marcador de posición de mano para usar con una imagen, consulta el ejemplo de código de barras.

Opciones de configuración

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

Preparar los datos

Prepara tu entrada como un archivo de imagen o un array de NumPy. y, luego, convertirlo en un objeto mediapipe.Image. Si la entrada es un archivo de video o transmitir en vivo desde una cámara web, puedes usar una biblioteca externa, como OpenCV para cargar tus marcos de entrada como NumPy para los diferentes tipos de arrays.

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 marcador de posición de mano utiliza los componentes detect, detect_for_video y detect_async funciones para activar inferencias. Para la detección de puntos de referencia en 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 la mano puntos de referencia.

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

# 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)
    

# 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)
    

# 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 de transmisión en vivo, también debes y proporcionaremos la marca de tiempo del fotograma de entrada a la tarea Hand Landmarker.
• Cuando se ejecuta en la imagen o el modelo de video, la tarea Hand Landmarker bloquear el subproceso actual hasta que termine de procesar la imagen de entrada o marco.
• 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 objeto de escucha con el resultado de la detección cada vez que haya terminado de procesarse un marco de entrada. Si la función de detección se llama cuando el marcador de posición de la mano la tarea está ocupada procesando otro fotograma, la tarea ignorará el nuevo marco de entrada.

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

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 ejemplo de código para conocer los detalles.