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 ti mostrano come usare il riconoscimento gesti per app web e JavaScript.
Puoi vedere questa attività in azione visualizzando la demo. 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 JavaScript come riferimento. Questo codice ti consente di testare questa attività e iniziare a creare la tua app di riconoscimento dei gesti. Puoi visualizzare, eseguire e modificare il codice di esempio del Riconoscimento di gesti usando semplicemente il tuo browser web.
Configurazione
In questa sezione vengono descritti i passaggi fondamentali per configurare l'ambiente di sviluppo in modo specifico per l'utilizzo del riconoscimento gesti. Per informazioni generali sulla configurazione dell'ambiente di sviluppo web e JavaScript, inclusi i requisiti di versione della piattaforma, consulta la Guida alla configurazione per il web.
Pacchetti JavaScript
Il codice del riconoscimento gesti è disponibile tramite il pacchetto NPM @mediapipe/tasks-vision
di MediaPipe. Puoi trovare e scaricare queste librerie seguendo le istruzioni nella Guida alla configurazione della piattaforma.
Puoi installare i pacchetti richiesti tramite Gestione dei partner di rete utilizzando il seguente comando:
npm install @mediapipe/tasks-vision
Se vuoi importare il codice dell'attività tramite un servizio di rete CDN (Content Delivery Network), aggiungi il seguente codice nel tag <head>
del file HTML:
<!-- You can replace JSDeliver with another CDN if you prefer to -->
<head>
<script src="https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision/vision_bundle.js"
crossorigin="anonymous"></script>
</head>
Modello
L'attività Riconoscimento gesti MediaPipe richiede un modello addestrato compatibile con questa attività. Per ulteriori informazioni sui modelli addestrati disponibili per il riconoscimento dei gesti, consulta la panoramica delle attività nella sezione Modelli.
Seleziona e scarica il modello, quindi archivialo all'interno della directory del progetto:
<dev-project-root>/app/shared/models/
Creare l'attività
Utilizza una delle funzioni createFrom...()
del riconoscimento gesti per
preparare l'attività per l'esecuzione di inferenze. Utilizza la funzione createFromModelPath()
con un percorso relativo o assoluto al file del modello addestrato.
Se il modello è già stato caricato in memoria, puoi utilizzare il metodo createFromModelBuffer()
.
L'esempio di codice riportato di seguito mostra l'utilizzo della funzione createFromOptions()
per configurare l'attività. La funzione createFromOptions
ti consente di personalizzare
il riconoscimento gesti con le opzioni di configurazione. Per ulteriori informazioni sulle opzioni di configurazione, consulta Opzioni di configurazione.
Il codice seguente mostra come creare e configurare l'attività con opzioni personalizzate:
// Create task for image file processing:
const vision = await FilesetResolver.forVisionTasks(
// path/to/wasm/root
"https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@latest/wasm "
);
const gestureRecognizer = await GestureRecognizer.createFromOptions(vision, {
baseOptions: {
modelAssetPath: "https://storage.googleapis.com/mediapipe-tasks/gesture_recognizer/gesture_recognizer.task"
},
numHands: 2
});
Opzioni di configurazione
Questa attività prevede le seguenti opzioni di configurazione per le applicazioni web:
Nome opzione | Descrizione | Intervallo di valori | Valore predefinito |
---|---|---|---|
runningMode |
Imposta la modalità di esecuzione per l'attività. Esistono due
modalità: IMAGE: la modalità per gli input di singole immagini. VIDEO: la modalità per i fotogrammi decodificati di un video o durante un live streaming di dati di input, ad esempio da una videocamera. |
{IMAGE, VIDEO } |
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. |
|
|
Preparazione dei dati
Il riconoscimento dei gesti è in grado di riconoscere i gesti nelle immagini in qualsiasi formato supportato dal browser host. L'attività gestisce anche la pre-elaborazione dell'input, come ridimensionamento, rotazione e normalizzazione del valore. Per riconoscere i gesti nei video, puoi utilizzare l'API per elaborare rapidamente un fotogramma alla volta, utilizzando il timestamp del frame per determinare quando si verificano i gesti all'interno del video.
Esegui l'attività
Il riconoscimento gesti utilizza i metodi recognize()
(con modalità di esecuzione 'image'
) e recognizeForVideo()
(con modalità di esecuzione 'video'
) per attivare le inferenze. L'attività elabora i dati, tenta di riconoscere
i gesti della mano e poi registra i risultati.
Il seguente codice mostra come eseguire l'elaborazione con il modello di attività:
Immagine
const image = document.getElementById("image") as HTMLImageElement; const gestureRecognitionResult = gestureRecognizer.recognize(image);
Video
await gestureRecognizer.setOptions({ runningMode: "video" }); let lastVideoTime = -1; function renderLoop(): void { const video = document.getElementById("video"); if (video.currentTime !== lastVideoTime) { const gestureRecognitionResult = gestureRecognizer.recognizeForVideo(video); processResult(gestureRecognitionResult); lastVideoTime = video.currentTime; } requestAnimationFrame(() => { renderLoop(); }); }
Le chiamate ai metodi Riconoscimento gesti recognize()
e recognizeForVideo()
vengono eseguite
in modo sincrono e bloccano il thread dell'interfaccia utente. Se riconosci i gesti nei fotogrammi video della fotocamera di un dispositivo, ogni riconoscimento bloccherà il thread principale. Puoi evitare che ciò accada implementando i web worker per l'esecuzione dei metodi recognize()
e recognizeForVideo()
su un altro thread.
Per un'implementazione più completa dell'esecuzione di un'attività di riconoscimento gesti, consulta l'esempio di codice.
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à:
Per un'implementazione più completa della creazione di un'attività di riconoscimento gesti, consulta l'esempio di codice.