Guida al riconoscimento dei gesti per il web

L'attività Riconoscimento gesti di MediaPipe ti consente di riconoscere i gesti delle mani in tempo reale e fornisce i risultati riconosciuti relativi ai gesti della mano e i punti di riferimento della mano mani rilevate. Queste istruzioni mostrano come utilizzare il riconoscimento gesti per le app web e JavaScript.

Puoi vedere questa attività in azione visualizzando la demo. Per ulteriori informazioni su funzionalità, modelli e opzioni di configurazione di questa attività, consulta la Panoramica.

Esempio di codice

Il codice di esempio del riconoscimento gesti fornisce un'implementazione completa in JavaScript come riferimento. Questo codice ti consente di testare l'attività e ottenere ha iniziato a creare la tua app di riconoscimento dei gesti. Puoi visualizzare, eseguire Modificare il codice di esempio del riconoscimento gesti usando solo il browser web.

Configurazione

Questa sezione descrive i passaggi chiave per configurare l'ambiente di sviluppo in modo specifico per usare il riconoscimento gesti. Per informazioni generali su configurare l'ambiente di sviluppo web e JavaScript, incluse i requisiti di versione della piattaforma, consulta Guida alla configurazione per il web.

Pacchetti JavaScript

Il codice del riconoscimento dei gesti è disponibile tramite MediaPipe @mediapipe/tasks-vision Pacchetto NPM. Puoi trovare e scaricare queste librerie seguendo le istruzioni nella piattaforma Guida alla configurazione.

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 una 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 di MediaPipe richiede un modello addestrato compatibile con dell'attività. Per ulteriori informazioni sui modelli addestrati disponibili per il riconoscimento gesti, vedi la panoramica delle attività nella sezione Modelli.

Seleziona e scarica il modello, quindi archivialo nella directory del progetto:

<dev-project-root>/app/shared/models/

Crea l'attività

Usa una delle funzioni createFrom...() di riconoscimento dei gesti per per preparare l'attività per l'esecuzione delle inferenze. Usa createFromModelPath() con un percorso relativo o assoluto al file del modello addestrato. Se il modello è già caricato in memoria, puoi utilizzare createFromModelBuffer().

L'esempio di codice seguente mostra l'utilizzo della funzione createFromOptions() per configurare l'attività. La funzione createFromOptions ti consente di personalizzare Riconoscimento dei gesti con opzioni di configurazione. Per ulteriori informazioni sulla configurazione vedi Opzioni di configurazione.

Il codice seguente mostra come creare e configurare l'attività con opzioni:

// 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à include 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 metodi modalità:

IMAGE: la modalità per gli input di immagini singole.

VIDEO: La modalità per i fotogrammi decodificati di un in 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 che può essere rilevato GestureRecognizer. Any integer > 0 1
min_hand_detection_confidence Il punteggio di confidenza minimo per il rilevamento della mano considerata efficace nel modello di rilevamento della palma. 0.0 - 1.0 0.5
min_hand_presence_confidence Il punteggio di confidenza minimo del punteggio di presenza della mano nella mano modello di rilevamento dei punti di riferimento. In modalità Video e live streaming del riconoscimento gesti: se il punteggio di sicurezza della presenza della mano del modello di punto di riferimento della mano è inferiore a questa soglia, attiva il modello di rilevamento della mano. Altrimenti, un algoritmo leggero di rilevamento della mano per determinare la posizione mani per il successivo rilevamento dei punti di riferimento. 0.0 - 1.0 0.5
min_tracking_confidence Il punteggio di confidenza minimo per cui deve essere preso in considerazione il monitoraggio della mano riuscito. Questa è la soglia di IoU del riquadro di delimitazione tra le mani nella il frame corrente e l'ultimo. In modalità Video e Stream di Riconoscimento gesti: se il rilevamento non va a buon fine, il riconoscimento attiva la mano il rilevamento automatico. In caso contrario, il rilevamento della mano viene ignorato. 0.0 - 1.0 0.5
canned_gestures_classifier_options Opzioni per configurare il comportamento del classificatore dei gesti predefiniti. 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 i metadati del modello TFLite, se presenti.
  • N. massimo di risultati: il numero massimo di risultati della classificazione con il punteggio più alto da restituire. Se < 0, verranno restituiti tutti i risultati disponibili.
  • Soglia di punteggio: il punteggio al di sotto del quale i risultati vengono rifiutati. Se il valore è 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 è compresa in questo set verranno filtrati. Si escludono a vicenda con lista bloccata.
  • Lista bloccata delle categorie: la lista bloccata dei nomi delle categorie. Se il campo non è vuoto, i risultati della classificazione che appartengono a questa categoria verranno filtrati. Si escludono a vicenda con la 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 dei gesti personalizzati.
  • Impostazioni internazionali dei nomi visualizzati: le impostazioni internazionali da utilizzare per i nomi visualizzati specificati tramite i metadati del modello TFLite, se presenti.
  • N. massimo di risultati: il numero massimo di risultati della classificazione con il punteggio più alto da restituire. Se < 0, verranno restituiti tutti i risultati disponibili.
  • Soglia di punteggio: il punteggio al di sotto del quale i risultati vengono rifiutati. Se il valore è 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 è compresa in questo set verranno filtrati. Si escludono a vicenda con lista bloccata.
  • Lista bloccata delle categorie: la lista bloccata dei nomi delle categorie. Se il campo non è vuoto, i risultati della classificazione che appartengono a questa categoria verranno filtrati. Si escludono a vicenda con la 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 gesti è in grado di riconoscere i gesti nelle immagini in qualsiasi formato supportato browser host. L'attività gestisce anche la pre-elaborazione dell'input di dati, tra cui ridimensionamento, rotazione e normalizzazione dei valori. Per riconoscere i gesti nei video, devi: puoi utilizzare l'API per elaborare rapidamente un frame alla volta, utilizzando il timestamp del frame per determinare quando vengono eseguiti i gesti nel video.

    Esegui l'attività

    Il riconoscimento gesti utilizza recognize() (con modalità di corsa 'image') e Metodi recognizeForVideo() (con modalità di esecuzione 'video') per attivare le inferenze. L'attività elabora i dati, tenta di riconoscere la mano gesti e segnala 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();
  });
}

    Chiamate al metodo di riconoscimento dei gesti recognize() e recognizeForVideo() eseguite in modo sincrono e bloccare il thread dell'interfaccia utente. Se riconosci i gesti in fotogrammi dalla fotocamera di un dispositivo, ogni riconoscimento bloccherà la . Puoi ovviare a questo problema implementando i web worker per eseguire recognize() e recognizeForVideo() su un altro thread.

    Per un'implementazione più completa dell'esecuzione di un'attività di riconoscimento dei gesti, consulta le esempio di codice.

    Gestire e visualizzare i risultati

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

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

    L'elemento GestureRecognizerResult risultante contiene quattro componenti, ognuno dei quali è un array in cui ogni elemento contiene il risultato rilevato di una singola mano rilevata.

    • Mano dominante

      La mano indica se le mani rilevate sono mani sinistra o destra.

    • Gesti

      Le categorie di gesti riconosciute delle mani rilevate.

    • Punti di riferimento

      Ci sono 21 punti di riferimento a mano, ognuno composto da coordinate x, y e z. La Le coordinate di x e y sono normalizzate a [0,0, 1,0] in base alla larghezza dell'immagine e rispettivamente per l'altezza e l'altezza. La coordinata z rappresenta la profondità del punto di riferimento, con la profondità al polso rappresenta l'origine. Più basso è il valore, più vicino sarà è la fotocamera. La grandezza di z utilizza più o meno la stessa scala di x.

    • Punti di riferimento mondiali

      I punti di riferimento con 21 mani sono anche presentati in coordinate mondiali. Ogni punto di riferimento è composto da x, y e z, che rappresentano le coordinate 3D del mondo reale metri con l'origine al 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à:

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