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

L'attività MediaPipe Hand Landmarker consente di rilevare i punti di riferimento delle mani in un'immagine. Queste istruzioni mostrano come utilizzare il rilevamento di punti di riferimento della mano 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 rilevamento di punti di riferimento della mano fornisce un'implementazione completa di questa attività in JavaScript per riferimento futuro. Questo codice ti aiuta a testare questa attività e a iniziare a creare la tua app di rilevamento dei punti di riferimento della mano. Puoi visualizzare, eseguire e modificare il codice di esempio di Hand Landmarker utilizzando solo il browser web.

Configurazione

Questa sezione descrive i passaggi chiave per configurare l'ambiente di sviluppo specificamente per l'utilizzo di Hand Landmarker. Per informazioni generali sulla configurazione dell'ambiente di sviluppo web e JavaScript, inclusi i requisiti della versione della piattaforma, consulta la guida alla configurazione per il web.

Pacchetti JavaScript

Il codice di rilevamento di punti di riferimento della mano è disponibile tramite il pacchetto @mediapipe/tasks-vision NPM MediaPipe. Puoi trovare e scaricare queste librerie seguendo le istruzioni riportate nella guida alla configurazione della piattaforma.

Puoi installare i pacchetti richiesti tramite NPM utilizzando il seguente comando:

npm install @mediapipe/tasks-vision

Se vuoi importare il codice dell'attività tramite un servizio 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à MediaPipe Hand Landmarker richiede un modello addestrato compatibile con questa attività. Per ulteriori informazioni sui modelli addestrati disponibili per il rilevamento di punti di riferimento della mano, consulta la sezione Modelli della panoramica dell'attività.

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

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

Crea l'attività

Utilizza una delle funzioni createFrom...() di rilevamento di landmark della mano per preparare l'attività all'esecuzione di inferenze. Utilizza la funzione createFromModelPath() con un percorso relativo o assoluto al file del modello addestrato. Se il modello è già 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 segnatore di punti di riferimento della mano con le opzioni di configurazione. Per ulteriori informazioni sulle opzioni di configurazione, consulta Opzioni di configurazione.

Il seguente codice 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à offre 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 dell'attività. Esistono due modi:

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

VIDEO: la modalità per i frame decodificati di un video o di un live streaming di dati di input, ad esempio di una videocamera.		 {IMAGE, VIDEO} IMAGE
numHands Il numero massimo di mani rilevate dal Rilevamento di punti di riferimento della mano. Any integer > 0 1
minHandDetectionConfidence Il punteggio di attendibilità minimo per il rilevamento della mano deve essere considerato positivo nel modello di rilevamento del palmo. 0.0 - 1.0 0.5
minHandPresenceConfidence Il punteggio di attendibilità minimo per il punteggio di 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 di landmark della mano è inferiore a questa soglia, il rilevamento dei landmark della mano attiva il modello di rilevamento del palmo. In caso contrario, un algoritmo di monitoraggio delle mani leggero determina la posizione delle mani per i rilevamenti successivi dei punti di riferimento. 0.0 - 1.0 0.5
minTrackingConfidence Il punteggio di attendibilità minimo per il rilevamento delle mani deve essere considerato positivo. Questa è la soglia IoU del riquadro di delimitazione tra le mani nel frame corrente e nell'ultimo frame. In modalità Video e Stream di Segnale di riferimento della mano, se il monitoraggio non va a buon fine, Segnale di riferimento della mano attiva il rilevamento della mano. In caso contrario, salta il rilevamento della mano. 0.0 - 1.0 0.5

Preparazione dei dati

Il rilevamento dei punti di riferimento della mano può rilevare i punti di riferimento della mano nelle immagini in qualsiasi formato supportato dal browser host. L'attività gestisce anche la preelaborazione dell'input dei dati, tra cui ridimensionamento, rotazione e normalizzazione dei valori. 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 fotogramma per determinare quando si verificano i punti di riferimento della mano all'interno del video.

Esegui l'attività

Il rilevamento di landmark 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 della mano e poi genera un report sui risultati.

Le chiamate ai metodi detect() e detectForVideo() di Hand Landmarker vengono eseguite in modo sincrono e bloccano il thread dell'interfaccia utente. Se rilevi punti di riferimento delle mani nei fotogrammi video della fotocamera di un dispositivo, ogni rilevamento blocca il thread principale. Puoi evitarlo implementando i worker web per eseguire i 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à di rilevamento di punti di riferimento della mano, consulta l'esempio di codice.

Gestire e visualizzare i risultati

Il rilevamento dei punti di riferimento della mano genera un oggetto di risultato del rilevamento dei punti di riferimento della mano per ogni esecuzione del rilevamento. L'oggetto risultato contiene i landmark delle mani nelle coordinate dell'immagine, i landmark delle mani nelle coordinate del mondo e l'uso della 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 seguenti risultati per una singola mano rilevata:

  • Mano dominante

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

  • Punti di riferimento

    Esistono 21 punti di riferimento della mano, ciascuno composto da coordinate x, y e z. Le coordinate x e y sono normalizzate in [0,0, 1,0] in base alla larghezza e all'altezza dell'immagine, rispettivamente. La coordinata z rappresenta la profondità del punto di riferimento, con la profondità al polso come origine. Più piccolo è il valore, più il punto di riferimento è vicino alla fotocamera. L'intensità di z utilizza approssimativamente la stessa scala di x.

  • Monumenti del mondo

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

Una mano con il pollice in su con la struttura scheletrica della mano mappata

Il codice di esempio di Hand Landmarker mostra come visualizzare i risultati restituiti dall'attività. Consulta l'esempio di codice