Guide de détection des points de repère de la main pour le Web

La tâche MediaPipe Main Markdown vous permet de détecter les points de repère des mains dans une image. Ces instructions vous expliquent comment utiliser l'outil de repère de main pour les applications Web et JavaScript.

Pour en savoir plus sur les fonctionnalités, les modèles et les options de configuration de cette tâche, consultez la présentation.

Exemple de code

L'exemple de code de Hand Markdowner fournit une implémentation complète de cette tâche en JavaScript à titre de référence. Ce code vous aide à tester cette tâche et à créer votre propre application de détection de points de repère manuellement. Vous pouvez afficher, exécuter et modifier l'exemple de code "Handmarker" en utilisant simplement votre navigateur Web.

Préparation

Cette section décrit les étapes clés pour configurer votre environnement de développement de manière spécifique à l'utilisation du composant Main Marker. Pour obtenir des informations générales sur la configuration de votre environnement de développement Web et JavaScript, y compris les exigences de version de la plate-forme, consultez le guide de configuration pour le Web.

Packages JavaScript

Il est disponible via le package MediaPipe @mediapipe/tasks-vision NPM. Vous pouvez trouver et télécharger ces bibliothèques en suivant les instructions du guide de configuration de la plate-forme.

Vous pouvez installer les packages requis via NPM à l'aide de la commande suivante:

npm install @mediapipe/tasks-vision

Si vous souhaitez importer le code de la tâche via un service de réseau de diffusion de contenu (CDN), ajoutez le code suivant dans la balise <head> de votre fichier 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>

Modèle

La tâche MediaPipe Main Marker nécessite un modèle entraîné compatible avec cette tâche. Pour en savoir plus sur les modèles entraînés disponibles pour le jeu de repères de main, consultez la section Modèles de la présentation des tâches.

Sélectionnez et téléchargez un modèle, puis stockez-le dans le répertoire de votre projet:

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

Créer la tâche

Utilisez l'une des fonctions createFrom...() du repère de main pour préparer la tâche à l'exécution des inférences. Utilisez la fonction createFromModelPath() avec un chemin d'accès relatif ou absolu au fichier du modèle entraîné. Si votre modèle est déjà chargé en mémoire, vous pouvez utiliser la méthode createFromModelBuffer().

L'exemple de code ci-dessous montre comment utiliser la fonction createFromOptions() pour configurer la tâche. La fonction createFromOptions vous permet de personnaliser le repère de main à l'aide d'options de configuration. Pour en savoir plus sur les options de configuration, consultez la section Options de configuration.

Le code suivant montre comment créer et configurer la tâche avec des options personnalisées:

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
    });

Options de configuration

Cette tâche dispose des options de configuration suivantes pour les applications Web et JavaScript:

Nom de l'option	Description	Plage de valeurs	Valeur par défaut
`runningMode`	Définit le mode d'exécution de la tâche. Il existe deux modes: IMAGE: mode pour les entrées d'une seule image. VIDEO: mode pour les images décodées d'une vidéo ou d'une diffusion en direct de données d'entrée, par exemple depuis une caméra.	{`IMAGE, VIDEO`}	`IMAGE`
`numHands`	Nombre maximal de mains détectées par le détecteur de points de repère Main.	`Any integer > 0`	`1`
`minHandDetectionConfidence`	Score de confiance minimal pour que la détection de la main soit considérée comme réussie dans le modèle de détection de la paume de la main.	`0.0 - 1.0`	`0.5`
`minHandPresenceConfidence`	Score de confiance minimal pour le score de présence de la main dans le modèle de détection de points de repère de la main. En mode Vidéo et en mode diffusion en direct, si le score de confiance de présence de la main du modèle de point de repère de la main est inférieur à ce seuil, le repère de main déclenche le modèle de détection de la paume de la main. Sinon, un algorithme léger de suivi de la main détermine la position des mains pour les détections de points de repère ultérieures.	`0.0 - 1.0`	`0.5`
`minTrackingConfidence`	Score de confiance minimal pour que le suivi manuel soit considéré comme réussi. Il s'agit du seuil IoU du cadre de délimitation entre les aiguilles de la trame actuelle et de la dernière image. En mode Vidéo et en mode Flux de Hand marker, en cas d'échec du suivi, celui-ci déclenche la détection des mains. Sinon, la détection des mains est ignorée.	`0.0 - 1.0`	`0.5`

Préparation des données

Il peut détecter les points de repère de la main dans les images, dans n'importe quel format compatible avec le navigateur hôte. Cette tâche gère également le prétraitement de l'entrée des données, y compris le redimensionnement, la rotation et la normalisation des valeurs. Pour détecter les points de repère de la main dans les vidéos, vous pouvez utiliser l'API pour traiter rapidement une image à la fois, en utilisant l'horodatage de l'image pour déterminer à quel moment les points de repère de la main apparaissent dans la vidéo.

Exécuter la tâche

Le repère de main utilise les méthodes detect() (avec le mode d'exécution image) et detectForVideo() (avec le mode d'exécution video) pour déclencher des inférences. La tâche traite les données, tente de détecter les points de repère de la main, puis consigne les résultats.

Les appels aux méthodes detect() et detectForVideo() du repère de main s'exécutent de manière synchrone et bloquent le thread de l'interface utilisateur. Si vous détectez des points de repère de la main dans les images vidéo de l'appareil photo d'un appareil, chaque détection bloque le thread principal. Vous pouvez empêcher cela en implémentant des nœuds de calcul Web pour exécuter les méthodes detect() et detectForVideo() sur un autre thread.

Le code suivant montre comment exécuter le traitement avec le modèle de tâche:

Images

const image = document.getElementById("image") as HTMLImageElement;
const handLandmarkerResult = handLandmarker.detect(image);

Vidéo

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();
  });
}

Pour une implémentation plus complète de l'exécution d'une tâche de repère de main, consultez l'exemple de code.

Gérer et afficher les résultats

Le repère de main génère un objet de résultat de repère de main pour chaque exécution de détection. L'objet de résultat contient des points de repère de la main en coordonnées d'image, des points de repère en coordonnées mondiales et la main dominante(main gauche/droite) des mains détectées.

Voici un exemple des données de sortie de cette tâche:

La sortie HandLandmarkerResult contient trois composants. Chaque composant est un tableau, où chaque élément contient les résultats suivants pour une seule main détectée:

Main dominante

La main dominante indique si les mains détectées sont des mains gauches ou droites.
Points de repère

Il y a 21 points de repère pour les mains, chacun composé des coordonnées x, y et z. Les coordonnées x et y sont normalisées à [0,0, 1,0] en fonction de la largeur et de la hauteur de l'image, respectivement. La coordonnée z représente la profondeur du point de repère, la profondeur au niveau du poignet correspondant à l'origine. Plus la valeur est faible, plus le point de repère est proche de la caméra. La magnitude de z utilise à peu près la même échelle que x.
Monuments internationaux

Les points de repère des 21 mains sont également indiqués en coordonnées mondiales. Chaque point de repère est composé de x, y et z, représentant des coordonnées 3D réelles en mètres avec le point de départ au centre géométrique de la main.

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'image suivante montre une visualisation du résultat de la tâche:

L'exemple de code de l'outil Main Marker montre comment afficher les résultats renvoyés par la tâche. Consultez l'exemple de code.