Guida al rilevamento dei punti di riferimento della mano per Python

L'attività Punto di riferimento della mano di MediaPipe consente di rilevare i punti di riferimento delle mani in un'immagine. Queste istruzioni mostrano come utilizzare il puntatore della mano con Python. La l'esempio di codice descritto in queste istruzioni è disponibile GitHub.

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

Esempio di codice

Il codice d'esempio di Hand Taper fornisce un'implementazione completa un'attività in Python come riferimento. Questo codice ti consente di testare l'attività e ottenere ha iniziato a costruire il proprio rilevatore di punti di riferimento con la mano. Puoi visualizzare, eseguire modifica il Esempio di codice di Riferimento manuale usando solo il browser web.

Configurazione

Questa sezione descrive i passaggi chiave per configurare l'ambiente di sviluppo e per creare un modello di codice specifico per l'uso di Hand riferimentoer. Per informazioni generali su configurare l'ambiente di sviluppo per l'utilizzo delle attività di MediaPipe, tra cui: i requisiti di versione della piattaforma, consulta Guida alla configurazione per Python.

Pacchetti

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

$ python -m pip install mediapipe

Importazioni

Importa i seguenti corsi per accedere alle funzioni attività di riferimento a mano:

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

Modello

L'attività Tappa a mano di MediaPipe richiede un modello addestrato compatibile con questo dell'attività. Per ulteriori informazioni sui modelli addestrati disponibili per la funzione di riferimento della mano, consulta la panoramica delle attività nella sezione Modelli.

Seleziona e scarica il modello, quindi archivialo 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à Punto di riferimento della mano di MediaPipe utilizza la funzione create_from_options per configurare l'attività. La funzione create_from_options accetta valori per gestire le opzioni di configurazione. Per ulteriori informazioni sulla configurazione vedi Opzioni di configurazione.

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

Questi esempi mostrano anche le varianti della costruzione dell'attività per le 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 puntatore della mano da utilizzare con un'immagine, consulta la sezione esempio di codice.

Opzioni di configurazione

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

Preparazione dei dati

Prepara l'input come file immagine o array numpy, e poi convertilo in un oggetto mediapipe.Image. Se l'input è un file video o trasmettere in live streaming da webcam, puoi utilizzare una raccolta esterna come OpenCV per caricare i frame di input come numpy di grandi dimensioni.

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à

La funzione di riferimento della mano utilizza detect, detect_for_video e detect_async per attivare le inferenze. Per il rilevamento dei punti di riferimento della mano, ciò prevede pre-elaborazione dei dati di input, rilevamento delle mani nell'immagine e rilevamento della mano punti di riferimento.

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 è attiva la modalità video o live streaming, devi anche indica il timestamp del frame di input per l'attività Hand Taper.
• Quando viene eseguita nel modello di immagine o video, l'attività Indicatore della mano bloccare il thread corrente finché non termina di elaborare l'immagine di input o frame.
• Quando viene eseguita in modalità live streaming, l'attività Riferimento mano non blocca il thread corrente, ma restituisce immediatamente. Richiamerà il suo risultato listener con il risultato del rilevamento ogni volta che termina l'elaborazione un frame di input. Se la funzione di rilevamento viene richiamata quando il puntatore della mano l'attività è impegnata a elaborare un altro frame, l'attività ignorerà il nuovo frame di input.

Per un esempio completo dell'esecuzione di una tapparelle a mano su un'immagine, consulta la esempio di codice per maggiori dettagli.

Gestire e visualizzare i risultati

La funzione di riferimento della mano genera un oggetto risultato del dispositivo di riferimento della mano per ogni rilevamento vengono eseguiti tutti i test delle unità. L'oggetto risultato contiene punti di riferimento a mano nelle coordinate dell'immagine, mano punti di riferimento nelle coordinate del mondo e mano(mano sinistra/destra) dell' mani.

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 mano indica se le mani rilevate sono mani sinistra o destra.

• Punti di riferimento

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

• Punti di riferimento mondiali

  I punti di riferimento con 21 mani sono anche presentati in coordinate mondiali. Ogni punto di riferimento è composto da x, y e z, che rappresentano le coordinate 3D del mondo reale metri con l'origine al 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 d'esempio di Mano del punto di riferimento illustra come visualizzare i risultati restituiti dall'attività, controlla esempio di codice per maggiori dettagli.