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

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 le repère de main avec les applications Android. L'exemple de code décrit dans ces instructions est disponible sur GitHub.

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 MediaPipe Tasks est une implémentation simple d'une application Hand Marker pour Android. L'exemple utilise la caméra d'un appareil Android physique pour détecter en permanence les points de repère de la main. Il peut également utiliser des images et des vidéos de la galerie de l'appareil pour détecter de manière statique les points de repère de la main.

Vous pouvez utiliser l'application comme point de départ pour votre propre application Android, ou vous y référer lorsque vous modifiez une application existante. L'exemple de code Main Repère est hébergé sur GitHub.

Télécharger le code

Les instructions suivantes vous expliquent comment créer une copie locale de l'exemple de code à l'aide de l'outil de ligne de commande git.

Pour télécharger l'exemple de code, procédez comme suit:

  1. Clonez le dépôt git à l'aide de la commande suivante : 
    git clone https://github.com/google-ai-edge/mediapipe-samples
  2. Vous pouvez éventuellement configurer votre instance Git pour qu'elle utilise le paiement creux afin de n'avoir que les fichiers de l'application exemple Hand Marker :
    cd mediapipe
git sparse-checkout init --cone
git sparse-checkout set examples/hand_landmarker/android

Après avoir créé une version locale de l'exemple de code, vous pouvez importer le projet dans Android Studio et exécuter l'application. Pour obtenir des instructions, consultez le guide de configuration pour Android.

Composants clés

Les fichiers suivants contiennent le code crucial pour cet exemple d'application de détection de points de repère de main:

  • HandLandmarkerHelper.kt initialise le détecteur de points de repère de la main, et gère la sélection du modèle et des délégués.
  • MainActivity.kt : met en œuvre l'application, y compris en appelant HandLandmarkerHelper.

Préparation

Cette section décrit les étapes clés de la configuration de votre environnement de développement et de vos projets de code spécifiquement pour l'utilisation du composant Main Marker. Pour obtenir des informations générales sur la configuration de votre environnement de développement pour l'utilisation des tâches MediaPipe, y compris sur les exigences de version de la plate-forme, consultez le guide de configuration pour Android.

Dépendances

La tâche "Point de repère de main" utilise la bibliothèque com.google.mediapipe:tasks-vision. Ajoutez cette dépendance au fichier build.gradle de votre application Android:

dependencies {
    implementation 'com.google.mediapipe:tasks-vision:latest.release'
}

Modèle

La tâche MediaPipe Hand marker nécessite un groupe de modèles entraînés compatibles 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 le modèle, puis stockez-le dans le répertoire de votre projet:

<dev-project-root>/src/main/assets

Spécifiez le chemin d'accès du modèle dans le paramètre ModelAssetPath. Dans l'exemple de code, le modèle est défini dans le fichier HandLandmarkerHelper.kt:

baseOptionBuilder.setModelAssetPath(MP_HAND_LANDMARKER_TASK)

Créer la tâche

La tâche MediaPipe Main Marker utilise la fonction createFromOptions() pour configurer la tâche. La fonction createFromOptions() accepte des valeurs pour les options de configuration. Pour en savoir plus sur les options de configuration, consultez la section Options de configuration.

Il accepte trois types de données d'entrée: les images fixes, les fichiers vidéo et le flux en direct. Vous devez spécifier le mode d'exécution correspondant à votre type de données d'entrée lors de la création de la tâche. Choisissez l'onglet correspondant à votre type de données d'entrée pour voir comment créer la tâche et exécuter l'inférence.

Images

val baseOptionsBuilder = BaseOptions.builder().setModelAssetPath(MP_HAND_LANDMARKER_TASK)
val baseOptions = baseOptionBuilder.build()

val optionsBuilder =
    HandLandmarker.HandLandmarkerOptions.builder()
        .setBaseOptions(baseOptions)
        .setMinHandDetectionConfidence(minHandDetectionConfidence)
        .setMinTrackingConfidence(minHandTrackingConfidence)
        .setMinHandPresenceConfidence(minHandPresenceConfidence)
        .setNumHands(maxNumHands)
        .setRunningMode(RunningMode.IMAGE)

val options = optionsBuilder.build()

handLandmarker =
    HandLandmarker.createFromOptions(context, options)

Vidéo

val baseOptionsBuilder = BaseOptions.builder().setModelAssetPath(MP_HAND_LANDMARKER_TASK)
val baseOptions = baseOptionBuilder.build()

val optionsBuilder =
    HandLandmarker.HandLandmarkerOptions.builder()
        .setBaseOptions(baseOptions)
        .setMinHandDetectionConfidence(minHandDetectionConfidence)
        .setMinTrackingConfidence(minHandTrackingConfidence)
        .setMinHandPresenceConfidence(minHandPresenceConfidence)
        .setNumHands(maxNumHands)
        .setRunningMode(RunningMode.VIDEO)

val options = optionsBuilder.build()

handLandmarker =
    HandLandmarker.createFromOptions(context, options)

Diffusion en direct

val baseOptionsBuilder = BaseOptions.builder().setModelAssetPath(MP_HAND_LANDMARKER_TASK)
val baseOptions = baseOptionBuilder.build()

val optionsBuilder =
    HandLandmarker.HandLandmarkerOptions.builder()
        .setBaseOptions(baseOptions)
        .setMinHandDetectionConfidence(minHandDetectionConfidence)
        .setMinTrackingConfidence(minHandTrackingConfidence)
        .setMinHandPresenceConfidence(minHandPresenceConfidence)
        .setNumHands(maxNumHands)
        .setResultListener(this::returnLivestreamResult)
        .setErrorListener(this::returnLivestreamError)
        .setRunningMode(RunningMode.VIDEO)

val options = optionsBuilder.build()

handLandmarker =
    HandLandmarker.createFromOptions(context, options)

L'exemple de code de l'outil Main Marker permet à l'utilisateur de basculer entre les modes de traitement. Cette approche complique le code de création de la tâche et peut ne pas être adaptée à votre cas d'utilisation. Vous pouvez voir ce code dans la fonction setupHandLandmarker() du fichier HandLandmarkerHelper.kt.

Options de configuration

Cette tâche dispose des options de configuration suivantes pour les applications Android:

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 trois modes:

IMAGE: mode pour les entrées d'une seule image.

VIDEO: mode pour les images décodées d'une vidéo.

LIVE_STREAM: mode de diffusion en direct de données d'entrée, issues par exemple d'une caméra. Dans ce mode, resultListener doit être appelé pour configurer un écouteur afin de recevoir les résultats de manière asynchrone. 		{IMAGE, VIDEO, LIVE_STREAM} 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
resultListener Définit l'écouteur de résultats de sorte qu'il reçoive les résultats de la détection de manière asynchrone lorsque le repère d'aiguille est en mode flux en direct. S'applique uniquement lorsque le mode d'exécution est défini sur LIVE_STREAM N/A N/A
errorListener Définit un écouteur d'erreurs facultatif. N/A N/A

Préparation des données

Il fonctionne avec des images, des fichiers vidéo et des diffusions en direct. Cette tâche gère le prétraitement des entrées de données, y compris le redimensionnement, la rotation et la normalisation de la valeur.

Le code suivant montre comment transférer des données pour traitement. Ces exemples fournissent des détails sur la façon de gérer les données provenant des images, des fichiers vidéo et des flux vidéo en direct.

Images

import com.google.mediapipe.framework.image.BitmapImageBuilder
import com.google.mediapipe.framework.image.MPImage

// Convert the input Bitmap object to an MPImage object to run inference
val mpImage = BitmapImageBuilder(image).build()

Vidéo

import com.google.mediapipe.framework.image.BitmapImageBuilder
import com.google.mediapipe.framework.image.MPImage

val argb8888Frame =
    if (frame.config == Bitmap.Config.ARGB_8888) frame
    else frame.copy(Bitmap.Config.ARGB_8888, false)

// Convert the input Bitmap object to an MPImage object to run inference
val mpImage = BitmapImageBuilder(argb8888Frame).build()

Diffusion en direct

import com.google.mediapipe.framework.image.BitmapImageBuilder
import com.google.mediapipe.framework.image.MPImage

// Convert the input Bitmap object to an MPImage object to run inference
val mpImage = BitmapImageBuilder(rotatedBitmap).build()

Dans l'exemple de code Main Marker, la préparation des données est gérée dans le fichier HandLandmarkerHelper.kt.

Exécuter la tâche

Selon le type de données que vous utilisez, utilisez la méthode HandLandmarker.detect...() spécifique à ce type de données. Utilisez detect() pour les images individuelles, detectForVideo() pour les images des fichiers vidéo et detectAsync() pour les flux vidéo. Lorsque vous effectuez des détections sur un flux vidéo, veillez à les exécuter sur un thread distinct pour éviter de bloquer le thread de l'interface utilisateur.

Les exemples de code suivants illustrent des exemples simples d'exécution du repère de la main dans ces différents modes de données:

Images

val result = handLandmarker?.detect(mpImage)

Vidéo

val timestampMs = i * inferenceIntervalMs

handLandmarker?.detectForVideo(mpImage, timestampMs)
    ?.let { detectionResult ->
        resultList.add(detectionResult)
    }

Diffusion en direct

val mpImage = BitmapImageBuilder(rotatedBitmap).build()
val frameTime = SystemClock.uptimeMillis()

handLandmarker?.detectAsync(mpImage, frameTime)

Veuillez noter les points suivants :

  • Lorsque vous exécutez le mode vidéo ou le mode de diffusion en direct, vous devez également fournir l'horodatage de l'image d'entrée à la tâche Main Marker.
  • Lors de l'exécution en mode image ou vidéo, la tâche Main Marker bloque le thread actuel jusqu'à ce qu'elle ait fini de traiter l'image ou le frame d'entrée. Pour éviter de bloquer l'interface utilisateur, exécutez le traitement dans un thread d'arrière-plan.
  • Lors de l'exécution en mode de diffusion en direct, la tâche Main Marker ne bloque pas le thread actuel, mais est renvoyée immédiatement. Il appelle son écouteur de résultat avec le résultat de la détection chaque fois qu'il a fini de traiter une trame d'entrée. Si la fonction de détection est appelée lorsque la tâche du repère de main est occupée à traiter une autre image, la tâche ignore la nouvelle image d'entrée.

Dans l'exemple de code Main Marker, les fonctions detect, detectForVideo et detectAsync sont définies dans le fichier HandLandmarkerHelper.kt.

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 de repères de main montre comment afficher les résultats renvoyés par la tâche. Pour en savoir plus, consultez la classe OverlayView.