Ti presentiamo Google AI Edge Portal: esegui il benchmarking dell'IA di Edge su larga scala. Registrati per richiedere l'accesso durante l'anteprima privata.

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 Hand Landmarker per app web e JavaScript.

Per saperne di più sulle funzionalità, sui modelli e sulle opzioni di configurazione di questa attività, consulta la panoramica.

Codice di esempio

Il codice di esempio per Hand Landmarker fornisce un'implementazione completa di questa attività in JavaScript come riferimento. 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 l'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 Hand Landmarker è disponibile tramite il pacchetto @mediapipe/tasks-vision NPM di 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.mjs"
    crossorigin="anonymous"></script>
</head>

Modello

L'attività MediaPipe Hand Landmarker richiede un modello addestrato compatibile con questa attività. Per saperne di più sui modelli addestrati disponibili per Hand Landmarker, consulta la sezione Modelli della panoramica dell'attività.

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

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

Creare l'attività

Utilizza una delle funzioni createFrom...() di Hand Landmarker per preparare l'attività per l'esecuzione delle 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 Hand Landmarker con 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à ha 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 modalità: 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 da una videocamera.	{`IMAGE, VIDEO`}	`IMAGE`
`numHands`	Il numero massimo di mani rilevate dal rilevatore di punti di riferimento della mano.	`Any integer > 0`	`1`
`minHandDetectionConfidence`	Il punteggio di confidenza minimo per il rilevamento della mano da considerare riuscito nel modello di rilevamento del palmo.	`0.0 - 1.0`	`0.5`
`minHandPresenceConfidence`	Il punteggio di confidenza 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 rilevamento dei punti di riferimento della mano è inferiore a questa soglia, Hand Landmarker attiva il modello di rilevamento del palmo. In caso contrario, un algoritmo di tracciamento delle mani leggero determina la posizione della mano o delle mani per i rilevamenti successivi dei punti di riferimento.	`0.0 - 1.0`	`0.5`
`minTrackingConfidence`	Il punteggio di confidenza minimo affinché il tracciamento delle mani venga considerato riuscito. Questa è la soglia IoU del riquadro di delimitazione tra le mani nel fotogramma corrente e nell'ultimo fotogramma. In modalità Video e Stream di Hand Landmarker, se il monitoraggio non riesce, Hand Landmarker attiva il rilevamento della mano. In caso contrario, salta il rilevamento della mano.	`0.0 - 1.0`	`0.5`

Preparazione dei dati

Hand Landmarker 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 frame 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à

Hand Landmarker 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 riporta i risultati.

Le chiamate ai metodi Hand Landmarker 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 videocamera di un dispositivo, ogni rilevamento blocca il thread principale. Puoi evitarlo implementando i web worker 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à Hand Landmarker, consulta l'esempio.

Gestire e visualizzare i risultati

Hand Landmarker genera un oggetto risultato di Hand Landmarker per ogni esecuzione del rilevamento. L'oggetto risultato contiene i punti di riferimento della mano nelle coordinate dell'immagine, i punti di riferimento della mano nelle coordinate mondiali e la lateralità(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 lateralità indica se le mani rilevate sono la mano sinistra o la mano destra.
Punti di riferimento

Esistono 21 punti di riferimento della mano, ognuno 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. La magnitudo di z utilizza all'incirca la stessa scala di x.
Punti di riferimento mondiali

I 21 punti di riferimento della mano vengono presentati anche nelle coordinate mondiali. Ogni punto di riferimento è composto da x, y e z, che rappresentano le coordinate 3D del mondo reale in 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à:

Una mano che fa il gesto del pollice in su con la struttura scheletrica della mano mappata

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