Guida al riconoscimento dei gesti per Python

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

Puoi vedere questa attività in azione visualizzando la demo web. Per maggiori 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 dei gesti fornisce un'implementazione completa di questa attività in Python per riferimento futuro. Questo codice ti aiuta a testare questa attività e a iniziare a creare il tuo riconoscitore dei gesti delle mani. Puoi visualizzare, eseguire e modificare il codice di esempio del Rilevamento dei gesti utilizzando solo il browser web.

Se stai implementando il Rilevamento dei gesti 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 dei gesti. 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à di riconoscimento dei gesti MediaPipe 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 dell'attività Gesture Recognizer:

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

Modello

L'attività Rilevamento dei gesti di MediaPipe richiede un bundle di modelli addestrati compatibile con questa attività. Per ulteriori informazioni sui modelli addestrati disponibili per il Rilevamento dei gesti, 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'

Specifica il percorso del modello all'interno del parametro Nome modello, come mostrato di seguito:

base_options = BaseOptions(model_asset_path=model_path)

Crea l'attività

L'attività MediaPipe Gesture Recognizer utilizza la funzione create_from_options per configurare l'attività. 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 video.

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à ha 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 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 riconosci, riconosci_per_video e riconosci_asincrono per attivare le deduzioni. Per il riconoscimento dei gesti, questo comporta la preelaborazione dei dati di input, il rilevamento delle mani nell'immagine, il rilevamento dei punti di riferimento delle mani e il riconoscimento dei gesti delle mani 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 segue:

• Quando esegui l'app in modalità video o in modalità live streaming, devi anche fornire all'attività Rilevamento dei gesti il timestamp del frame di input.
• Quando viene eseguito nel modello di immagine o video, il compito del RICONOSCIMENTO GESTI 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à Gesture Recognizer non blocca il thread corrente, ma restituisce immediatamente. Evocherà il suo ascoltatore di risultati con il risultato del riconoscimento ogni volta che ha terminato l'elaborazione di un frame di input. Se la funzione di riconoscimento viene chiamata quando il compito del Rilevatore di gesti è impegnato a elaborare un altro frame, il compito ignorerà il nuovo frame di input.

Per un esempio completo di esecuzione di un Riconoscitore di gesti su un'immagine, consulta l'esempio di codice per maggiori dettagli.

Gestire e visualizzare i risultati

Il Gesto Recognizer genera un oggetto di risultato del rilevamento dei gesti per ogni esecuzione del riconoscimento. L'oggetto risultato contiene i punti di riferimento delle mani nelle coordinate dell'immagine, i punti di riferimento delle mani nelle coordinate del mondo, l'uso della mano(mano sinistra/destra) e le categorie dei gesti delle mani 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 dominanza indica se le mani rilevate sono la mano sinistra o la mano destra.

• Gesti

  Le categorie di gesti riconosciute delle mani rilevate.

• 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ù piccolo è il valore, più il punto di riferimento è vicino alla fotocamera. L'intensità di z utilizza approssimativamente 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 coordinate 3D reali in metri con l'origine nel 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 seguenti immagini mostrano una visualizzazione dell'output dell'attività:

Il codice di esempio del Rilevamento dei gesti mostra come visualizzare i risultati di riconoscimento restituiti dall'attività. Per maggiori dettagli, consulta l'esempio di codice.