Guida al rilevamento dei punti di riferimento per il web

L'attività Punto di riferimento per la posa di MediaPipe consente di rilevare i punti di riferimento di corpi umani in un'immagine o in un video. Puoi utilizzare questa attività per identificare le posizioni chiave del corpo, analizzare la postura e classificare i movimenti. Questa attività usa modelli di machine learning (ML) che funzionano con singole immagini o video. L'attività restituisce i punti di riferimento nelle coordinate dell'immagine e nelle coordinate tridimensionali.

Queste istruzioni mostrano come utilizzare il punto di riferimento per le posizioni 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 Pose fornisce un'implementazione completa di questa attività in JavaScript come riferimento. Questo codice ti consente di testare questa attività e iniziare a creare la tua app per il riferimento per le pose. Puoi visualizzare, eseguire e modificare il codice di esempio dell'indicatore di posa usando il tuo browser web.

Configurazione

Questa sezione descrive i passaggi chiave per configurare l'ambiente di sviluppo in modo specifico per l'utilizzo di Punto di riferimento per posa. 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 per la posa è 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 -->
<head>
  <script src="https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision/vision_bundle.js"
    crossorigin="anonymous"></script>
</head>

Modello

L'attività Punto di riferimento per la posizione di MediaPipe richiede un modello addestrato compatibile con questa attività. Per ulteriori informazioni sui modelli addestrati disponibili per il punto di riferimento Pose, 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 per la posizione 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à 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 l'indicatore di riferimento per posa 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 poseLandmarker = await poseLandmarker.createFromOptions(
    vision,
    {
      baseOptions: {
        modelAssetPath: "path/to/model"
      },
      runningMode: runningMode
    });

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
numPoses Il numero massimo di pose che possono essere rilevate dall'elemento di riferimento per le pose. Integer > 0 1
minPoseDetectionConfidence Il punteggio di affidabilità minimo affinché il rilevamento della posa venga considerato riuscito. Float [0.0,1.0] 0.5
minPosePresenceConfidence Il punteggio di affidabilità minimo del punteggio di presenza della posa nel rilevamento dei punti di riferimento della posa. Float [0.0,1.0] 0.5
minTrackingConfidence Il punteggio di affidabilità minimo affinché il monitoraggio della posa venga considerato riuscito. Float [0.0,1.0] 0.5
outputSegmentationMasks Indica se il punto di riferimento per la posa restituisce una maschera di segmentazione per la posa rilevata. Boolean False

Preparazione dei dati

Il punto di riferimento per la posa è in grado di rilevare le pose 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 inserire le pose come punto di riferimento nei video, puoi utilizzare l'API per elaborare rapidamente un fotogramma alla volta, utilizzando il timestamp del fotogramma per determinare quando le pose sono presenti nel video.

Esegui l'attività

L'indicatore di riferimento per la posizione utilizza i metodi detect() (con modalità di corsa IMAGE) e detectForVideo() (con modalità di corsa VIDEO) per attivare le inferenze. L'attività elabora i dati, tenta di applicare le pose dei punti di riferimento e segnala i risultati.

Le chiamate ai metodi del punto di riferimento detect() e detectForVideo() vengono eseguite in modo sincrono e bloccano l'interposizione del thread dell'utente. Se rilevi le pose nei frame 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 poseLandmarkerResult = poseLandmarker.detect(image);

Video

await poseLandmarker.setOptions({ runningMode: "VIDEO" });

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

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

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

Per un'implementazione più completa dell'esecuzione di un'attività di riferimento per la posizione, consulta l'esempio di codice.

Gestire e visualizzare i risultati

Il punto di riferimento per la posizione restituisce un oggetto poseLandmarkerResult per ogni esecuzione di rilevamento. L'oggetto risultato contiene le coordinate di ogni punto di riferimento per la posa.

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

PoseLandmarkerResult:
  Landmarks:
    Landmark #0:
      x            : 0.638852
      y            : 0.671197
      z            : 0.129959
      visibility   : 0.9999997615814209
      presence     : 0.9999984502792358
    Landmark #1:
      x            : 0.634599
      y            : 0.536441
      z            : -0.06984
      visibility   : 0.999909
      presence     : 0.999958
    ... (33 landmarks per pose)
  WorldLandmarks:
    Landmark #0:
      x            : 0.067485
      y            : 0.031084
      z            : 0.055223
      visibility   : 0.9999997615814209
      presence     : 0.9999984502792358
    Landmark #1:
      x            : 0.063209
      y            : -0.00382
      z            : 0.020920
      visibility   : 0.999976
      presence     : 0.999998
    ... (33 world landmarks per pose)
  SegmentationMasks:
    ... (pictured below)

L'output contiene sia coordinate normalizzate (Landmarks) sia coordinate mondiali (WorldLandmarks) per ogni punto di riferimento.

L'output contiene le seguenti coordinate normalizzate (Landmarks):

  • x e y: coordinate dei punti di riferimento normalizzate tra 0,0 e 1,0 per la larghezza e l'altezza dell'immagine (x) (y).

  • z: la profondità importante, con la profondità al punto centrale dei fianchi come origine. Più basso è il valore, più il punto di riferimento è vicino alla fotocamera. L'entità di z utilizza all'incirca la stessa scala di x.

  • visibility: la probabilità che il punto di riferimento sia visibile all'interno dell'immagine.

L'output contiene le seguenti coordinate mondiali (WorldLandmarks):

  • x, y e z: coordinate tridimensionali nel mondo reale in metri, con il punto medio dei fianchi come origine.

  • visibility: la probabilità che il punto di riferimento sia visibile all'interno dell'immagine.

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

La maschera di segmentazione facoltativa rappresenta la probabilità che ogni pixel appartenga a una persona rilevata. La seguente immagine è una maschera di segmentazione dell'output dell'attività:

Il codice di esempio del punto di riferimento per la posa mostra come visualizzare i risultati restituiti dall'attività. Consulta l'esempio di codice