Guida al rilevamento dei punti di riferimento della mano per il web

L'attività Punto di riferimento della mano di MediaPipe consente di rilevare i punti di riferimento delle mani in un'immagine. Queste istruzioni mostrano come utilizzare la funzione Tapis roulant per le app web e JavaScript.

Per ulteriori informazioni su funzionalità, modelli e opzioni di configurazione di questa attività, consulta la Panoramica.

Esempio di codice

Il codice d'esempio di Hand Joiner 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 rilevamento dei punti di riferimento con la mano. Puoi visualizzare, eseguire Modifica l'esempio di codice di Riferimento a mano. usando solo il browser web.

Configurazione

Questa sezione descrive i passaggi chiave per configurare l'ambiente di sviluppo in particolare per usare la funzione di riferimento della mano. 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 di Hand Scoreer è 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) servizio, aggiungi il seguente codice nel tag <head> nel 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à Tappa a mano di MediaPipe richiede un modello addestrato compatibile con questo dell'attività. Per ulteriori informazioni sui modelli addestrati disponibili per la funzione di riferimento della mano, consulta la panoramica delle attività nella sezione Modelli.

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

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

Crea l'attività

Usa una delle funzioni createFrom...() del puntatore della mano 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 Punto di riferimento manuale 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:

const vision = await FilesetResolver.forVisionTasks(
  // path/to/wasm/root
  "https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@latest/wasm"
);
const handLandmarker = await HandLandmarker.createFromOptions(
    vision,
    {
      baseOptions: {
        modelAssetPath: "hand_landmarker.task"
      },
      numHands: 2
    });

Opzioni di configurazione

Questa attività include le seguenti opzioni di configurazione per web e JavaScript applicazioni:

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
numHands Il numero massimo di mani rilevate dal rilevatore dei punti di riferimento della mano. Any integer > 0 1
minHandDetectionConfidence Il punteggio di confidenza minimo per il rilevamento della mano considerata efficace nel modello di rilevamento della palma. 0.0 - 1.0 0.5
minHandPresenceConfidence Il punteggio di confidenza minimo per il punteggio relativo alla presenza della mano nella mano modello di rilevamento dei punti di riferimento. In modalità Video e Live streaming: se il punteggio di confidenza della presenza della mano dal modello di punto di riferimento della mano è inferiore a questa soglia, la funzione di riferimento della mano attiva il modello di rilevamento della mano. Altrimenti, un algoritmo leggero di rilevamento della mano determina la posizione le mani per i successivi rilevamenti dei punti di riferimento. 0.0 - 1.0 0.5
minTrackingConfidence 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 Punto di riferimento mano, se il rilevamento non va a buon fine, si attiva la mano il rilevamento automatico. In caso contrario, il rilevamento della mano viene saltato. 0.0 - 1.0 0.5

Preparazione dei dati

La funzione di riferimento a mano è in grado di rilevare i punti di riferimento della mano 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 rilevare i punti di riferimento delle mani nei video: puoi utilizzare l'API per elaborare rapidamente un frame alla volta, utilizzando il timestamp dell'inquadratura per determinare quando i punti di riferimento della mano compaiono nel video.

Esegui l'attività

La funzione Tapis roulant utilizza detect() (con modalità di corsa image) e Metodi detectForVideo() (con modalità di esecuzione video) per attivare le inferenze. L'attività elabora i dati, tenta di rilevare i punti di riferimento delle mani e quindi segnala i risultati.

Chiamate all'esecuzione dei metodi detect() e detectForVideo() in modo sincrono e bloccare il thread dell'interfaccia utente. Se rilevi i punti di riferimento delle mani nei fotogrammi video della videocamera di un dispositivo, ogni rilevamento blocca la . Puoi ovviare a questo problema implementando i web worker per eseguire detect() e detectForVideo() su un altro thread.

Il seguente codice mostra come eseguire l'elaborazione con il modello di attività:

Immagine

const image = document.getElementById("image") as HTMLImageElement;
const handLandmarkerResult = handLandmarker.detect(image);

Video

await handLandmarker.setOptions({ runningMode: "video" });

let lastVideoTime = -1;
function renderLoop(): void {
  const video = document.getElementById("video");

  if (video.currentTime !== lastVideoTime) {
    const detections = handLandmarker.detectForVideo(video);
    processResults(detections);
    lastVideoTime = video.currentTime;
  }

  requestAnimationFrame(() => {
    renderLoop();
  });
}

Per un'implementazione più completa dell'esecuzione di un'attività di riferimento a mano, consulta esempio di codice.

Gestire e visualizzare i risultati

La funzione di riferimento della mano genera un oggetto risultato del dispositivo di riferimento della mano per ogni rilevamento vengono eseguiti tutti i test delle unità. L'oggetto risultato contiene punti di riferimento a mano nelle coordinate dell'immagine, mano punti di riferimento nelle coordinate del mondo e mano(mano sinistra/destra) dell' mani.

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

L'output HandLandmarkerResult contiene tre componenti. Ogni componente è un array, in cui ogni elemento contiene i seguenti risultati per una singola mano rilevata:

  • Mano dominante

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

  • 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.

HandLandmarkerResult:
  Handedness:
    Categories #0:
      index        : 0
      score        : 0.98396
      categoryName : Left
  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)

L'immagine seguente mostra una visualizzazione dell'output dell'attività:

Il codice d'esempio di Mano del punto di riferimento illustra come visualizzare i risultati restituiti dall'attività, controlla esempio di codice