Guide de détection des points de repère manuels pour Python

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 composant Hand Marker avec Python. 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 de Hand Markdowner fournit une implémentation complète de cette tâche en Python à titre de référence. Ce code vous aide à tester cette tâche et à créer votre propre détecteur de points de repère main. Vous pouvez afficher, exécuter et modifier l'exemple de code Main Repère à l'aide de votre navigateur Web.

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 Python.

Colis

La tâche MediaPipe Handmarker nécessite le package PyPI médiapipe. Vous pouvez installer et importer ces dépendances avec la commande suivante:

$ python -m pip install mediapipe

Importations

Importez les classes suivantes pour accéder aux fonctions des tâches du repère de main:

import mediapipe as mp
from mediapipe.tasks import python
from mediapipe.tasks.python import vision

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 le modèle, puis stockez-le dans un répertoire local:

model_path = '/absolute/path/to/gesture_recognizer.task'

Utilisez le paramètre model_asset_path de l'objet BaseOptions pour spécifier le chemin d'accès du modèle à utiliser. Pour obtenir un exemple de code, consultez la section suivante.

Créer la tâche

La tâche MediaPipe Handmarker utilise la fonction create_from_options pour configurer la tâche. La fonction create_from_options accepte des valeurs pour les options de configuration à gérer. Pour en savoir plus sur les options de configuration, consultez la section Options de configuration.

Le code suivant montre comment créer et configurer cette tâche.

Ces exemples montrent également les variantes de construction des tâches pour les images, les fichiers vidéo et le flux en direct.

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
HandLandmarker = mp.tasks.vision.HandLandmarker
HandLandmarkerOptions = mp.tasks.vision.HandLandmarkerOptions
VisionRunningMode = mp.tasks.vision.RunningMode

# Create a hand landmarker instance with the image mode:
options = HandLandmarkerOptions(
    base_options=BaseOptions(model_asset_path='/path/to/model.task'),
    running_mode=VisionRunningMode.IMAGE)
with HandLandmarker.create_from_options(options) as landmarker:
  # The landmarker is initialized. Use it here.
  # ...
    

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
HandLandmarker = mp.tasks.vision.HandLandmarker
HandLandmarkerOptions = mp.tasks.vision.HandLandmarkerOptions
VisionRunningMode = mp.tasks.vision.RunningMode

# Create a hand landmarker instance with the video mode:
options = HandLandmarkerOptions(
    base_options=BaseOptions(model_asset_path='/path/to/model.task'),
    running_mode=VisionRunningMode.VIDEO)
with HandLandmarker.create_from_options(options) as landmarker:
  # The landmarker is initialized. Use it here.
  # ...
    

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
HandLandmarker = mp.tasks.vision.HandLandmarker
HandLandmarkerOptions = mp.tasks.vision.HandLandmarkerOptions
HandLandmarkerResult = mp.tasks.vision.HandLandmarkerResult
VisionRunningMode = mp.tasks.vision.RunningMode

# Create a hand landmarker instance with the live stream mode:
def print_result(result: HandLandmarkerResult, output_image: mp.Image, timestamp_ms: int):
    print('hand landmarker result: {}'.format(result))

options = HandLandmarkerOptions(
    base_options=BaseOptions(model_asset_path='/path/to/model.task'),
    running_mode=VisionRunningMode.LIVE_STREAM,
    result_callback=print_result)
with HandLandmarker.create_from_options(options) as landmarker:
  # The landmarker is initialized. Use it here.
  # ...
    

Pour obtenir un exemple complet de création d'un repère de main à utiliser avec une image, consultez l'exemple de code.

Options de configuration

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

Préparation des données

Préparez votre entrée en tant que fichier image ou tableau Numpy, puis convertissez-la en objet mediapipe.Image. Si votre entrée est un fichier vidéo ou un flux vidéo en direct à partir d'une webcam, vous pouvez utiliser une bibliothèque externe telle que OpenCV pour charger vos images d'entrée sous forme de tableaux Numpy.

import mediapipe as mp

# Load the input image from an image file.
mp_image = mp.Image.create_from_file('/path/to/image')

# Load the input image from a numpy array.
mp_image = mp.Image(image_format=mp.ImageFormat.SRGB, data=numpy_image)
    

import mediapipe as mp

# Use OpenCV’s VideoCapture to load the input video.

# Load the frame rate of the video using OpenCV’s CV_CAP_PROP_FPS
# You’ll need it to calculate the timestamp for each frame.

# Loop through each frame in the video using VideoCapture#read()

# Convert the frame received from OpenCV to a MediaPipe’s Image object.
mp_image = mp.Image(image_format=mp.ImageFormat.SRGB, data=numpy_frame_from_opencv)
    

import mediapipe as mp

# Use OpenCV’s VideoCapture to start capturing from the webcam.

# Create a loop to read the latest frame from the camera using VideoCapture#read()

# Convert the frame received from OpenCV to a MediaPipe’s Image object.
mp_image = mp.Image(image_format=mp.ImageFormat.SRGB, data=numpy_frame_from_opencv)
    

Exécuter la tâche

Il utilise les fonctions de détection, detect_for_video et detect_async pour déclencher des inférences. Pour la détection des points de repère manuels, cela implique le prétraitement des données d'entrée, la détection des mains dans l'image et la détection des points de repère manuels.

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

# Perform hand landmarks detection on the provided single image.
# The hand landmarker must be created with the image mode.
hand_landmarker_result = landmarker.detect(mp_image)
    

# Perform hand landmarks detection on the provided single image.
# The hand landmarker must be created with the video mode.
hand_landmarker_result = landmarker.detect_for_video(mp_image, frame_timestamp_ms)
    

# Send live image data to perform hand landmarks detection.
# The results are accessible via the `result_callback` provided in
# the `HandLandmarkerOptions` object.
# The hand landmarker must be created with the live stream mode.
landmarker.detect_async(mp_image, frame_timestamp_ms)
    

Veuillez noter les points suivants :

• Lors de l'exécution en mode vidéo ou en mode de diffusion en direct, vous devez également fournir à la tâche Main Marker l'horodatage de l'image d'entrée.
• Lors de l'exécution dans l'image ou le modèle 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.
• 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.

Pour obtenir un exemple complet d'exécution d'un repère de main sur une image, 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. Pour en savoir plus, consultez cet exemple de code.