Guida al riconoscimento dei gesti per Python

L'attività Riconoscimento dei gesti di MediaPipe ti consente di riconoscere i gesti delle mani in tempo reale e fornisce i risultati dei gesti della mano riconosciuti e i punti di riferimento delle mani rilevate. Queste istruzioni mostrano come usare il riconoscimento gesti con le applicazioni Python.

Puoi vedere questa attività in azione visualizzando la demo web. 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 riconoscimento gestuale fornisce un'implementazione completa di questa attività in Python come riferimento. Con questo codice puoi testare l'attività e iniziare a creare un tuo riconoscimento dei gesti della mano. Puoi visualizzare, eseguire e modificare il codice di esempio del Riconoscimento di gesti usando semplicemente il browser web.

Se stai implementando il riconoscimento gesti per Raspber Pi, consulta l'app di esempio Raspber Pi.

Configurazione

In questa sezione vengono descritti i passaggi fondamentali per configurare l'ambiente di sviluppo e codificare i progetti in modo specifico per l'utilizzo del riconoscimento gesti. Per informazioni generali sulla configurazione dell'ambiente di sviluppo per l'utilizzo delle attività MediaPipe, inclusi i requisiti di versione della piattaforma, consulta la Guida alla configurazione per Python.

Pacchetti

L'attività Riconoscimento gesti 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 delle attività del riconoscimento gesti:

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

Modello

L'attività Riconoscimento gesti MediaPipe richiede un bundle di modelli addestrato compatibile con questa attività. Per ulteriori informazioni sui modelli addestrati disponibili per il riconoscimento dei gesti, consulta la sezione Modelli della panoramica delle attività.

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

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

Specifica il percorso del modello all'interno del parametro Model Name, come illustrato di seguito:

base_options = BaseOptions(model_asset_path=model_path)

Creare l'attività

L'attività Riconoscimento gesti MediaPipe utilizza la funzione create_from_options per configurarla. La funzione create_from_options accetta i 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 stream video in diretta.

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
GestureRecognizer = mp.tasks.vision.GestureRecognizer
GestureRecognizerOptions = mp.tasks.vision.GestureRecognizerOptions
VisionRunningMode = mp.tasks.vision.RunningMode

# Create a gesture recognizer instance with the image mode:
options = GestureRecognizerOptions(
    base_options=BaseOptions(model_asset_path='/path/to/model.task'),
    running_mode=VisionRunningMode.IMAGE)
with GestureRecognizer.create_from_options(options) as recognizer:
  # The detector is initialized. Use it here.
  # ...
    

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
GestureRecognizer = mp.tasks.vision.GestureRecognizer
GestureRecognizerOptions = mp.tasks.vision.GestureRecognizerOptions
VisionRunningMode = mp.tasks.vision.RunningMode

# Create a gesture recognizer instance with the video mode:
options = GestureRecognizerOptions(
    base_options=BaseOptions(model_asset_path='/path/to/model.task'),
    running_mode=VisionRunningMode.VIDEO)
with GestureRecognizer.create_from_options(options) as recognizer:
  # The detector is initialized. Use it here.
  # ...
    

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
GestureRecognizer = mp.tasks.vision.GestureRecognizer
GestureRecognizerOptions = mp.tasks.vision.GestureRecognizerOptions
GestureRecognizerResult = mp.tasks.vision.GestureRecognizerResult
VisionRunningMode = mp.tasks.vision.RunningMode

# Create a gesture recognizer instance with the live stream mode:
def print_result(result: GestureRecognizerResult, output_image: mp.Image, timestamp_ms: int):
    print('gesture recognition result: {}'.format(result))

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

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 riconoscimento Gesti utilizza le funzioni di riconoscimento, riconoscere_for_video e riconoscere_async per attivare inferenze. Per il riconoscimento dei gesti, ciò comporta il pre-elaborazione dei dati di input, il rilevamento delle mani nell'immagine, il rilevamento dei punti di riferimento delle mani e il riconoscimento del gesto della mano dai punti di riferimento.

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

# Perform gesture recognition on the provided single image.
# The gesture recognizer must be created with the image mode.
gesture_recognition_result = recognizer.recognize(mp_image)
    

# Perform gesture recognition on the provided single image.
# The gesture recognizer must be created with the video mode.
gesture_recognition_result = recognizer.recognize_for_video(mp_image, frame_timestamp_ms)
    

# Send live image data to perform gesture recognition.
# The results are accessible via the `result_callback` provided in
# the `GestureRecognizerOptions` object.
# The gesture recognizer must be created with the live stream mode.
recognizer.recognize_async(mp_image, frame_timestamp_ms)
    

Tieni presente quanto riportato di seguito:

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

Per un esempio completo dell'esecuzione di un riconoscimento gestuale su un'immagine, vedi questo esempio di codice per maggiori dettagli.

Gestire e visualizzare i risultati

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

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

Il risultato GestureRecognizerResult contiene quattro componenti e ogni componente è un array in cui ogni elemento contiene il risultato rilevato di una singola mano rilevata.

• Mano dominante

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

• Gesti

  Le categorie di gesti riconosciuti delle mani rilevate.

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

GestureRecognizerResult:
  Handedness:
    Categories #0:
      index        : 0
      score        : 0.98396
      categoryName : Left
  Gestures:
    Categories #0:
      score        : 0.76893
      categoryName : Thumb_Up
  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)

Le immagini seguenti mostrano una visualizzazione dell'output dell'attività:

Il codice di esempio del riconoscimento gesti mostra come visualizzare i risultati del riconoscimento restituiti dall'attività. Per informazioni dettagliate, consulta l'esempio di codice.