Guida al rilevamento dei punti di riferimento della mano per Python

L'attività MediaPipe Hand Landmarker consente di rilevare i punti di riferimento delle mani in un'immagine. Queste istruzioni mostrano come utilizzare il rilevamento di landmark della mano con Python. L'esempio di codice descritto in queste istruzioni è disponibile su GitHub.

Per ulteriori informazioni sulle funzionalità, sui modelli e sulle opzioni di configurazione di questa attività, consulta la Panoramica.

Esempio di codice

Il codice di esempio per il rilevamento di landmark della mano fornisce un'implementazione completa di questa attività in Python come riferimento. Questo codice è utile per testare l'attività e iniziare a creare un rilevatore di punti di riferimento con la mano. Puoi visualizzare, eseguire e modificare il codice di esempio di identificazione di punti di riferimento della mano utilizzando solo il browser web.

Se stai implementando il rilevamento di punti di riferimento della mano per Raspberry Pi, consulta l'app di esempio per Raspberry Pi.

Configurazione

Questa sezione descrive i passaggi chiave per configurare l'ambiente di sviluppo e i progetti di codice specificamente per utilizzare il rilevamento di punti di riferimento della mano. Per informazioni generali sulla configurazione dell'ambiente di sviluppo per l'utilizzo delle attività MediaPipe, inclusi i requisiti della versione della piattaforma, consulta la guida alla configurazione per Python.

Pacchetti

L'attività MediaPipe Hand Landmarker richiede il pacchetto PyPI mediapipe. Puoi installare e importare queste dipendenze con quanto segue:

$ python -m pip install mediapipe

Importazioni

Importa le seguenti classi per accedere alle funzioni della funzionalità di rilevamento di punti di riferimento della mano:

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

Modello

L'attività MediaPipe Hand Landmarker richiede un modello addestrato compatibile con questa attività. Per ulteriori informazioni sui modelli addestrati disponibili per Hand Scoreer, consulta la panoramica delle attività nella sezione Modelli.

Seleziona e scarica il modello, quindi memorizzalo in una directory locale:

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

Utilizza il parametro model_asset_path dell'oggetto BaseOptions per specificare il percorso del modello da utilizzare. Per un esempio di codice, consulta la sezione successiva.

Crea l'attività

L'attività MediaPipe Hand Landmarker utilizza la funzione create_from_options per impostarla. La funzione create_from_options accetta valori per le opzioni di configurazione da gestire. Per ulteriori informazioni sulle opzioni di configurazione, consulta Opzioni di configurazione.

Il codice seguente mostra come creare e configurare questa attività.

Questi esempi mostrano anche le varianti della costruzione dell'attività per immagini, file video e live streaming.

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

Per un esempio completo di creazione di un indicatore di mano da utilizzare con un'immagine, consulta l'esempio di codice.

Opzioni di configurazione

Questa attività ha le seguenti opzioni di configurazione per le applicazioni Python:

Preparazione dei dati

Prepara l'input come file immagine o array numpy, poi convertilo in un oggetto mediapipe.Image. Se l'input è un file video o un live streaming da una webcam, puoi utilizzare una libreria esterna come OpenCV per caricare i frame di input come array 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)
    

Esegui l'attività

Il rilevamento di landmark della mano utilizza le funzioni detect, detect_for_video e detect_async per attivare le deduzioni. Per il rilevamento dei punti di riferimento delle mani, è necessario pre-elaborare i dati di input, rilevare le mani nell'immagine e rilevare i punti di riferimento delle mani.

Il seguente codice mostra come eseguire l'elaborazione con il modello di attività.

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

Tieni presente quanto segue:

• Quando esegui l'operazione in modalità video o live streaming, devi anche fornire all'attività di rilevamento di landmark della mano il timestamp del frame di input.
• Quando viene eseguito nel modello di immagine o video, l'attività di rilevamento di landmark della mano blocca il thread corrente fino al termine dell'elaborazione dell'immagine o del frame di input.
• Quando viene eseguita in modalità live streaming, l'attività Riferimento mano non blocca il thread corrente, ma restituisce immediatamente. Evocherà il suo ascoltatore di risultati con il risultato del rilevamento ogni volta che ha terminato l'elaborazione di un frame di input. Se la funzione di rilevamento viene chiamata quando l'attività Punti di riferimento a mano è impegnata a elaborare un altro frame, l'attività ignorerà il nuovo frame di input.

Per un esempio completo dell'esecuzione di un puntatore della mano su un'immagine, vedi l'esempio di codice per i dettagli.

Gestire e visualizzare i risultati

Il rilevamento dei punti di riferimento della mano genera un oggetto di risultato del rilevamento dei punti di riferimento della mano per ogni esecuzione del rilevamento. L'oggetto risultato contiene punti di riferimento a mano nelle coordinate dell'immagine, punti di riferimento nelle coordinate del mondo e mano(mano sinistra/destra) delle mani rilevate.

Di seguito è riportato un esempio dei dati di output di questa attività:

L'output HandLandmarkerResult contiene tre componenti. Ogni componente è un array, in cui ogni elemento contiene i seguenti risultati per una singola mano rilevata:

• Mano dominante

  La dominanza indica se le mani rilevate sono la mano sinistra o la mano destra.

• Punti di riferimento

  Esistono 21 punti di riferimento della mano, ciascuno composto da coordinate x, y e z. Le coordinate x e y sono normalizzate in [0,0, 1,0] in base alla larghezza e all'altezza dell'immagine, rispettivamente. La coordinata z rappresenta la profondità del punto di riferimento, con la profondità al polso come origine. Più basso è il valore, più vicino è il punto di riferimento alla fotocamera. La grandezza di z utilizza più o meno la stessa scala di x.

• Monumenti del mondo

  I 21 punti di riferimento della mano sono presentati anche in coordinate mondiali. Ogni punto di riferimento è composto da x, y e z, che rappresentano le coordinate 3D reali in metri con l'origine nel centro geometrico della 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)

L'immagine seguente mostra una visualizzazione dell'output dell'attività:

Il codice di esempio di Hand Joiner mostra come visualizzare i risultati restituiti dall'attività. Per i dettagli, vedi l'esempio di codice.