Guida al rilevamento dei punti di riferimento della mano per Python

L'attività Riferimento mano di MediaPipe ti consente di rilevare i punti di riferimento delle mani in un'immagine. Queste istruzioni mostrano come utilizzare il punto di riferimento manuale 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 punto di riferimento manuale fornisce un'implementazione completa di questa attività in Python come riferimento. Questo codice ti consente di testare l'attività e iniziare a creare un rilevatore dei punti di riferimento. Puoi visualizzare, eseguire e modificare il codice di esempio di Targeter Hand usando il tuo browser web.

Configurazione

Questa sezione descrive i passaggi chiave per configurare l'ambiente di sviluppo e i progetti di codice in modo specifico per l'utilizzo del punto di riferimento manuale. Per informazioni generali sulla configurazione dell'ambiente di sviluppo per l'utilizzo delle attività di MediaPipe, inclusi i requisiti di versione della piattaforma, consulta la Guida alla configurazione per Python.

Pacchetti

L'attività Punto di riferimento manuale di MediaPipe richiede il pacchetto PyPI di mediapipe. Puoi installare e importare queste dipendenze con quanto segue:

$ python -m pip install mediapipe

Importazioni

Importa le seguenti classi per accedere alle funzioni attività Traccia di riferimento mano:

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

Modello

L'attività Punto di riferimento mano di MediaPipe richiede un modello addestrato compatibile con questa attività. Per ulteriori informazioni sui modelli addestrati disponibili per il punto di riferimento manuale, consulta la sezione Modelli della panoramica dell'attività.

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.

Creare l'attività

L'attività Punto di riferimento manuale di MediaPipe utilizza la funzione create_from_options per configurarla. 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 creazione delle 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 della creazione di un Punto di riferimento manuale da utilizzare con un'immagine, consulta l'esempio di codice.

Opzioni di configurazione

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

Preparazione dei dati

Prepara l'input come file immagine o array numpy, quindi convertilo in un oggetto mediapipe.Image. Se l'input è un file video o un live streaming proveniente 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 punto di riferimento manuale utilizza le funzioni detect, detect_for_video e detect_async per attivare le inferenze. Per il rilevamento dei punti di riferimento delle mani, ciò comporta la pre-elaborazione dei dati di input, il rilevamento delle mani nell'immagine e il rilevamento dei 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 riportato di seguito:

• Quando l'esecuzione è in modalità video o live streaming, devi anche fornire all'attività Mano del punto di riferimento il timestamp del frame di input.
• Quando viene eseguita nell'immagine o nel modello video, l'attività Mano del punto di riferimento bloccherà il thread corrente finché non completa l'elaborazione dell'immagine o del frame di input.
• Quando è in esecuzione in modalità live streaming, l'attività Mano del punto di riferimento non blocca il thread corrente, ma torna immediatamente. Richiama il proprio listener dei risultati con il risultato del rilevamento ogni volta che ha terminato l'elaborazione di un frame di input. Se la funzione di rilevamento viene richiamata quando l'attività del punto di riferimento mano è impegnata a elaborare un altro frame, l'attività ignorerà il nuovo frame di input.

Per un esempio completo dell'esecuzione di un punto di riferimento manuale su un'immagine, consulta l'esempio di codice per maggiori dettagli.

Gestire e visualizzare i risultati

Il Punto di riferimento della mano genera un oggetto risultato del punto di riferimento della mano per ogni esecuzione di rilevamento. L'oggetto risultato contiene punti di riferimento della mano nelle coordinate dell'immagine, punti di riferimento della mano 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 risultati seguenti per una singola mano rilevata:

• Mano dominante

  La mano indica se la mano viene rilevata sia destra che sinistra.

• Punti di riferimento

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

• Punti di riferimento mondiali

  I punti di riferimento a 21 mani sono presentati anche nelle coordinate mondiali. Ogni punto di riferimento è composto da x, y e z e rappresenta le coordinate 3D del mondo reale in metri con l'origine in corrispondenza del 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 del punto di riferimento manuale mostra come visualizzare i risultati restituiti dall'attività. Per i dettagli, consulta l'esempio di codice.