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
ez
. Le coordinatex
ey
sono normalizzate su [0,0, 1,0] rispettivamente in base alla larghezza e all'altezza dell'immagine. La coordinataz
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 diz
utilizza approssimativamente la stessa scala dix
.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
ez
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