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

L'attività Riferimento mano di MediaPipe ti consente di rilevare i punti di riferimento delle mani in un'immagine. Queste istruzioni mostrano come utilizzare il punto di riferimento manuale per le app web e JavaScript.

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 punto di riferimento manuale fornisce un'implementazione completa di questa attività in JavaScript come riferimento. Questo codice ti consente di testare questa attività e iniziare a creare un'app per il rilevamento dei punti di riferimento. Puoi visualizzare, eseguire e modificare il codice di esempio del punto di riferimento manuale utilizzando semplicemente il tuo browser web.

Configurazione

Questa sezione descrive i passaggi chiave per configurare l'ambiente di sviluppo in modo specifico per l'utilizzo del punto di riferimento manuale. 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 punto di riferimento manuale è disponibile tramite il pacchetto @mediapipe/tasks-vision NPM 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à Punto di riferimento mano di MediaPipe richiede un modello addestrato compatibile con questa attività. Per ulteriori informazioni sui modelli addestrati disponibili per il punto di riferimento manuale, consulta la sezione Modelli della panoramica dell'attività.

Seleziona e scarica un modello, quindi archivialo all'interno della directory del progetto:

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

Creare l'attività

Utilizza una delle funzioni createFrom...() del punto di riferimento mano 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 consente di personalizzare il punto di riferimento manuale con 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:

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à prevede le seguenti opzioni di configurazione per le applicazioni web e JavaScript:

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`
`numHands`	Il numero massimo di mani rilevate dal rilevatore dei punti di riferimento della mano.	`Any integer > 0`	`1`
`minHandDetectionConfidence`	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`
`minHandPresenceConfidence`	Il punteggio di affidabilità minimo per il punteggio della presenza della mano nel modello di rilevamento dei punti di riferimento della mano. In modalità Video e Live streaming, se il punteggio di confidenza della presenza della mano del modello del punto di riferimento della mano è inferiore a questa soglia, il punto di riferimento della mano attiva il modello di rilevamento del palmo. Altrimenti, un algoritmo di tracciamento delle mani leggero determina la posizione delle mani per i successivi rilevamenti dei punti di riferimento.	`0.0 - 1.0`	`0.5`
`minTrackingConfidence`	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à flusso del punto di riferimento mano, se il tracciamento non va a buon fine, il punto di riferimento mano attiva il rilevamento della mano. In caso contrario, il rilevamento della mano non viene eseguito.	`0.0 - 1.0`	`0.5`

Preparazione dei dati

Il punto di riferimento manuale è in grado di rilevare i punti di riferimento della mano 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 rilevare i punti di riferimento della mano nei video, puoi utilizzare l'API per elaborare rapidamente un fotogramma alla volta, utilizzando il timestamp del frame per determinare quando si verificano i punti di riferimento della mano all'interno del video.

Esegui l'attività

Il punto di riferimento della mano utilizza i metodi detect() (con modalità di esecuzione image) e 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 poi registra i risultati.

Le chiamate ai metodi del punto di riferimento manuale detect() e detectForVideo() vengono eseguite in modo sincrono e bloccano il thread dell'interfaccia utente. Se rilevi punti di riferimento della mano nei fotogrammi video della fotocamera di un dispositivo, ogni rilevamento blocca il thread principale. Puoi evitare che ciò accada implementando i web worker per l'esecuzione dei metodi 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à Punto di riferimento manuale, vedi l'esempio di codice.

Gestire e visualizzare i risultati

Il Punto di riferimento della mano genera un oggetto risultato del punto di riferimento della mano per ogni esecuzione di rilevamento. L'oggetto risultato contiene punti di riferimento della mano nelle coordinate dell'immagine, punti di riferimento della mano nelle coordinate del mondo e mano(mano sinistra/destra) delle mani rilevate.

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 risultati seguenti per una singola mano rilevata:

Mano dominante

La mano indica se la mano viene rilevata sia destra che sinistra.
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.

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 di esempio del punto di riferimento manuale mostra come visualizzare i risultati restituiti dall'attività. Consulta l'esempio di codice