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.
Immagine
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. # ...
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 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. # ...
Live streaming
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:
Nome opzione | Descrizione | Intervallo di valori | Valore predefinito | |
---|---|---|---|---|
running_mode |
Imposta la modalità di esecuzione per l'attività. Esistono tre
modalità: IMAGE: la modalità per gli input di singole immagini. VIDEO: la modalità per i fotogrammi decodificati di un video. LIVE_STREAM: la modalità per un live streaming di dati di input, ad esempio da una videocamera. In questa modalità, resultListener deve essere chiamato per configurare un listener per ricevere i risultati in modo asincrono. |
{IMAGE, VIDEO, LIVE_STREAM } |
IMAGE |
|
num_hands |
Il numero massimo di mani può essere rilevato dall'GestureRecognizer .
|
Any integer > 0 |
1 |
|
min_hand_detection_confidence |
Il punteggio di affidabilità minimo affinché il rilevamento della mano venga considerato efficace nel modello di rilevamento del palmo. | 0.0 - 1.0 |
0.5 |
|
min_hand_presence_confidence |
Il punteggio di affidabilità minimo del punteggio della presenza di persone nel modello di rilevamento dei punti di riferimento della mano. In modalità Video e in live streaming del Riconoscimento gesti, se il punteggio di sicurezza della presenza della mano del modello del punto di riferimento della mano è inferiore a questa soglia, viene attivato il modello di rilevamento del palmo. Altrimenti, viene utilizzato un algoritmo di tracciamento della mano leggero per determinare la posizione delle lancette e del successivo rilevamento dei punti di riferimento. | 0.0 - 1.0 |
0.5 |
|
min_tracking_confidence |
Il punteggio di affidabilità minimo affinché la registrazione della mano venga considerata riuscita. Si tratta della soglia IoU del riquadro di delimitazione tra le mani nel frame corrente e nell'ultimo frame. In modalità Video e in modalità stream del Riconoscimento di gesti, se il rilevamento non va a buon fine, quest'ultimo attiva il rilevamento delle mani. In caso contrario, il rilevamento della mano viene ignorato. | 0.0 - 1.0 |
0.5 |
|
canned_gestures_classifier_options |
Opzioni per configurare il comportamento predefinito del classificatore di gesti. I gesti predefiniti sono ["None", "Closed_Fist", "Open_Palm", "Pointing_Up", "Thumb_Down", "Thumb_Up", "Victory", "ILoveYou"] |
|
|
|
custom_gestures_classifier_options |
Opzioni per configurare il comportamento del classificatore di gesti personalizzati. |
|
|
|
result_callback |
Imposta il listener dei risultati per ricevere i risultati della classificazione in modo asincrono quando il riconoscimento dei gesti è in modalità live streaming.
Può essere utilizzato solo quando la modalità di esecuzione è impostata su LIVE_STREAM |
ResultListener |
N/A | N/A |
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.
Immagine
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)
Video
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)
Live streaming
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à.
Immagine
# 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)
Video
# 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)
Live streaming
# 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
ez
. Le coordinatex
ey
sono normalizzate su [0,0, 1,0] rispettivamente in base alla larghezza e all'altezza dell'immagine. La coordinataz
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 diz
utilizza approssimativamente la stessa scala dix
.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
ez
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.