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

La tâche MediaPipe Hand Markerer vous permet de détecter les points de repère des mains dans une image. Ces instructions vous expliquent comment utiliser Hand Markerer avec des applications Android. La 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 section Présentation.

Exemple de code

L'exemple de code MediaPipe Tasks est une implémentation simple d'un Hand Markerer. pour Android. L'exemple utilise l'appareil photo d'un appareil Android physique pour détectent en continu les repères de la main, et peuvent aussi utiliser des images et des vidéos la galerie de l'appareil pour détecter de manière statique les points de repère de l'aiguille.

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 Hand Markerer est hébergé GitHub

Télécharger le code

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

Pour télécharger l'exemple de code:

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 utiliser le paiement creuse. Vous n'avez donc que les fichiers de l'application exemple Hand Markerer:

   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 les Guide de configuration pour Android

Composants clés

Les fichiers suivants contiennent le code crucial de ce point de repère "main" exemple d'application de détection:

• HandLandmarkerHelper.kt : Initialise le détecteur de points de repère à main, et gère le modèle et la délégation de votre choix.
• MainActivity.kt : Implémentation de l'application, y compris en appelant HandLandmarkerHelper

Configuration

Cette section décrit les étapes clés à suivre pour configurer votre environnement de développement de code spécifiquement pour utiliser Hand Markerer. Pour obtenir des informations générales sur configurer votre environnement de développement pour utiliser les tâches MediaPipe, y compris versions de la plate-forme requises, consultez la Guide de configuration pour Android

Dépendances

La tâche Hand Markerer utilise l'com.google.mediapipe:tasks-vision. bibliothèque. 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 traceur nécessite un lot de modèles entraînés compatible avec cette tâche. Pour en savoir plus sur les modèles entraînés disponibles pour Hand Markerer, 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 exemple de code, le modèle est défini dans la HandLandmarkerHelper.kt :

baseOptionBuilder.setModelAssetPath(MP_HAND_LANDMARKER_TASK)

Créer la tâche

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

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

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)
    

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)
    

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 d'implémentation de code Hand Markerer permet à l'utilisateur de passer différents modes de traitement. L'approche rend le code de création de la tâche plus compliqué et peuvent ne pas être adaptés à votre cas d'utilisation. Ce code figure dans la fonction setupHandLandmarker() dans HandLandmarkerHelper.kt .

Options de configuration

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

Préparer les données

Hand Markerer utilise des images, des fichiers vidéo et des flux vidéo en direct. La tâche gère le prétraitement de l'entrée des données, y compris le redimensionnement, la rotation et la valeur. normalisation.

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

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

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

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 Exemple de code Hand Markerer. La préparation des données est gérée dans le HandLandmarkerHelper.kt .

Exécuter la tâche

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

Les exemples de code suivants illustrent des exemples simples d'exécution de Hand Markerer. dans ces différents modes de données:

val result = handLandmarker?.detect(mpImage)
    

val timestampMs = i * inferenceIntervalMs

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

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

handLandmarker?.detectAsync(mpImage, frameTime)
    

Veuillez noter les points suivants :

• Lorsque vous êtes en mode vidéo ou flux en direct, vous devez également fournir le code temporel de la trame d'entrée à la tâche Hand Markerer.
• Lors de l'exécution en mode image ou vidéo, la tâche Hand Markerer bloquer le thread actuel jusqu'à ce qu'il ait fini de traiter l'image d'entrée ou cadre. Pour éviter de bloquer l'interface utilisateur, exécutez le traitement dans un thread d'arrière-plan.
• En mode diffusion en direct, la tâche Hand Markerer ne bloque pas le thread actuel, mais renvoie immédiatement. Elle appellera son résultat avec le résultat de la détection chaque fois que le traitement d'une trame d'entrée. Si la fonction de détection est appelée lorsque la tâche Hand Markerer est occupé à traiter une autre trame, la tâche ignore la nouvelle trame d'entrée.

Dans Exemple de code pour Hand Markerer, les champs detect, detectForVideo et Les fonctions detectAsync sont définies dans HandLandmarkerHelper.kt .

Gérer et afficher les résultats

Pour chaque détection, Hand Markerer génère un objet permettant de marquer une main. exécuter. L'objet résultant contient des points de repère "main" dans les coordonnées de l'image, "main" points de repère en coordonnées mondiales et main dominante(main gauche/droite) du mains libres.

Voici un exemple de 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 de main, chacun composé des coordonnées x, y et z. La Les coordonnées x et y sont normalisées à [0,0, 1,0] par la largeur de l'image et et leur hauteur. La coordonnée z représente la profondeur du point de repère, avec la profondeur au poignet étant l'origine. Plus la valeur est faible, plus la à l'objectif de l'appareil photo. L'amplitude de z utilise à peu près la même échelle que x

• Monuments mondiaux

  Les 21 points de repère sont également représentés par des coordonnées mondiales. Chaque point de repère se compose de x, y et z, qui représentent des coordonnées 3D réelles dans mètres avec l'origine 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 Hand Markerer montre comment afficher le renvoyés par la tâche, consultez la OverlayView pour en savoir plus.