Guida al riconoscimento dei gesti per il web

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"]` Impostazioni internazionali dei nomi visualizzati: le impostazioni internazionali da utilizzare per i nomi visualizzati specificati tramite gli eventuali metadati del modello TFLite. Numero massimo di risultati: il numero massimo di risultati di classificazione con il punteggio più alto da restituire. Se < 0, verranno restituiti tutti i risultati disponibili. Soglia di punteggio: il punteggio al di sotto dei quali i risultati vengono rifiutati. Se impostato su 0, verranno restituiti tutti i risultati disponibili. Lista consentita delle categorie: la lista consentita dei nomi delle categorie. Se il campo non è vuoto, i risultati di classificazione la cui categoria non è presente in questo set verranno filtrati. Esclusiva a vicenda con la lista bloccata. Lista bloccata categoria: la lista bloccata dei nomi di categoria. Se il campo non è vuoto, i risultati di classificazione la cui categoria rientra in questo set verranno filtrati. Esclusiva a vicenda con lista consentita.	Impostazioni internazionali dei nomi visualizzati: `any string` N. massimo di risultati: `any integer` Soglia punteggio: `0.0-1.0` Lista consentita della categoria: `vector of strings` Lista bloccata categoria: `vector of strings`	Impostazioni internazionali dei nomi visualizzati: `"en"` N. massimo di risultati: `-1` Soglia punteggio: `0` Lista consentita della categoria: vuota Lista bloccata categoria: vuota
`custom_gestures_classifier_options`	Opzioni per configurare il comportamento del classificatore di gesti personalizzati. Impostazioni internazionali dei nomi visualizzati: le impostazioni internazionali da utilizzare per i nomi visualizzati specificati tramite gli eventuali metadati del modello TFLite. Numero massimo di risultati: il numero massimo di risultati di classificazione con il punteggio più alto da restituire. Se < 0, verranno restituiti tutti i risultati disponibili. Soglia di punteggio: il punteggio al di sotto dei quali i risultati vengono rifiutati. Se impostato su 0, verranno restituiti tutti i risultati disponibili. Lista consentita delle categorie: la lista consentita dei nomi delle categorie. Se il campo non è vuoto, i risultati di classificazione la cui categoria non è presente in questo set verranno filtrati. Esclusiva a vicenda con la lista bloccata. Lista bloccata categoria: la lista bloccata dei nomi di categoria. Se il campo non è vuoto, i risultati di classificazione la cui categoria rientra in questo set verranno filtrati. Esclusiva a vicenda con lista consentita.	Impostazioni internazionali dei nomi visualizzati: `any string` N. massimo di risultati: `any integer` Soglia punteggio: `0.0-1.0` Lista consentita della categoria: `vector of strings` Lista bloccata categoria: `vector of strings`	Impostazioni internazionali dei nomi visualizzati: `"en"` N. massimo di risultati: `-1` Soglia punteggio: `0` Lista consentita della categoria: vuota Lista bloccata categoria: vuota

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 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à:

Per un'implementazione più completa della creazione di un'attività di riconoscimento gesti, consulta l'esempio di codice.