Leitfaden zur Erkennung von Handmarkierungen für Python

Mit der Aufgabe „MediaPipe Hand Landmarker“ können Sie die Markierungen der Hände in einem Bild erkennen. In dieser Anleitung erfahren Sie, wie Sie den Hand Landmarker mit Python verwenden. Das in dieser Anleitung beschriebene Codebeispiel ist auf GitHub verfügbar.

Weitere Informationen zu den Funktionen, Modellen und Konfigurationsoptionen dieser Aufgabe finden Sie in der Übersicht.

Codebeispiel

Der Beispielcode für Hand Landmarker bietet eine vollständige Implementierung dieser Aufgabe in Python zu Referenzzwecken. Mit diesem Code können Sie diese Aufgabe testen und mit dem Erstellen Ihres eigenen Handortserkennungsdetektors beginnen. Sie können den Beispielcode von Hand Landmarker mithilfe Ihres Webbrowsers aufrufen, ausführen und bearbeiten.

Einrichtung

In diesem Abschnitt werden die wichtigsten Schritte zum Einrichten Ihrer Entwicklungsumgebung und Programmierprojekte speziell für die Verwendung von Hand Landmarker beschrieben. Allgemeine Informationen zum Einrichten der Entwicklungsumgebung für die Verwendung von MediaPipe-Aufgaben, einschließlich der Anforderungen an die Plattformversion, finden Sie im Einrichtungsleitfaden für Python.

Pakete

Die MediaPipe Hand Landmark-Aufgabe erfordert das MediaPipe-PyPI-Paket. Sie können diese Abhängigkeiten folgendermaßen installieren und importieren:

$ python -m pip install mediapipe

Importe

Importieren Sie die folgenden Klassen, um auf die Aufgabenfunktionen für Hand-Markierungen zuzugreifen:

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

Modell

Die MediaPipe Hand Landmark-Aufgabe erfordert ein trainiertes Modell, das mit dieser Aufgabe kompatibel ist. Weitere Informationen zu verfügbaren trainierten Modellen für Hand Landmarker finden Sie in der Aufgabenübersicht im Abschnitt „Modelle“.

Wählen Sie das Modell aus, laden Sie es herunter und speichern Sie es dann in einem lokalen Verzeichnis:

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

Verwenden Sie den model_asset_path-Parameter des BaseOptions-Objekts, um den Pfad des zu verwendenden Modells anzugeben. Ein Codebeispiel finden Sie im nächsten Abschnitt.

Aufgabe erstellen

Die MediaPipe Hand Landmark-Aufgabe verwendet die Funktion create_from_options, um die Aufgabe einzurichten. Die Funktion create_from_options akzeptiert Werte, die von Konfigurationsoptionen verarbeitet werden sollen. Weitere Informationen zu Konfigurationsoptionen finden Sie unter Konfigurationsoptionen.

Im folgenden Codebeispiel wird gezeigt, wie diese Aufgabe erstellt und konfiguriert wird.

Diese Beispiele zeigen auch die Variationen der Aufgabenkonstruktion für Bilder, Videodateien und Livestreams.

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

Ein vollständiges Beispiel für das Erstellen einer Handmarkierung zur Verwendung mit einem Bild finden Sie im Codebeispiel.

Konfigurationsoptionen

Diese Aufgabe bietet die folgenden Konfigurationsoptionen für Python-Anwendungen:

Daten vorbereiten

Bereiten Sie Ihre Eingabe als Bilddatei oder NumPy-Array vor und konvertieren Sie sie in ein mediapipe.Image-Objekt. Wenn Ihre Eingabe eine Videodatei oder ein Livestream über eine Webcam ist, können Sie eine externe Bibliothek wie OpenCV verwenden, um Ihre Eingabeframes als NumPy-Arrays zu laden.

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)
    

Task ausführen

Die Hand-Markierungsfunktion verwendet die Funktionen detect, detect_for_video und detect_async, um Inferenzen auszulösen. Bei der Erkennung von Handmarkierungen umfasst dies die Vorverarbeitung der Eingabedaten, die Erkennung von Händen im Bild und die Erkennung von Handmarkierungen.

Der folgende Code zeigt, wie die Verarbeitung mit dem Aufgabenmodell ausgeführt wird.

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

Wichtige Hinweise:

• Im Video- oder Livestreammodus müssen Sie außerdem in der Aufgabe „Hand Landmarker“ den Zeitstempel des Eingabeframes angeben.
• Bei Ausführung im Bild- oder Videomodell blockiert die Aufgabe „Hand Landmarker“ den aktuellen Thread, bis die Verarbeitung des Eingabebilds oder ‐frames abgeschlossen ist.
• Im Livestreammodus blockiert die Hand-Markierungsaufgabe den aktuellen Thread nicht, sondern wird sofort zurückgegeben. Jedes Mal, wenn ein Eingabeframe verarbeitet wurde, ruft er seinen Ergebnis-Listener mit dem Erkennungsergebnis auf. Wenn die Erkennungsfunktion aufgerufen wird, während die Hand-Markierungsaufgabe mit der Verarbeitung eines anderen Frames beschäftigt ist, ignoriert die Aufgabe den neuen Eingabe-Frame.

Ein vollständiges Beispiel für die Ausführung einer Handmarkierung auf einem Bild finden Sie im Codebeispiel.

Ergebnisse verarbeiten und anzeigen

Der Hand Landmarker generiert für jeden Erkennungslauf ein Hand-Landmarker-Ergebnisobjekt. Das Ergebnisobjekt enthält Orientierungspunkte in den Bildkoordinaten, Handmarkierungen in Weltkoordinaten und die Händigkeit(links/rechts) der erkannten Hände.

Im Folgenden sehen Sie ein Beispiel für die Ausgabedaten dieser Aufgabe:

Die HandLandmarkerResult-Ausgabe enthält drei Komponenten. Jede Komponente ist ein Array, wobei jedes Element die folgenden Ergebnisse für eine einzelne erkannte Hand enthält:

• Händigkeit

  Die Händigkeit gibt an, ob die erkannten Hände Links- oder Rechtshänder sind.

• Landmarken

  Es gibt 21 Landschaftsmarkierungen, die jeweils aus x-, y- und z-Koordinaten bestehen. Die Koordinaten x und y werden entsprechend der Bildbreite bzw. -höhe auf [0,0, 1,0] normalisiert. Die z-Koordinate stellt die Tiefe der Sehenswürdigkeit dar, wobei die Tiefe am Handgelenk als Ausgangspunkt dient. Je kleiner der Wert, desto näher liegt das Denkmal an der Kamera. Die Größe von z wird ungefähr gleich groß wie bei x verwendet.

• Sehenswürdigkeiten der Welt

  Die 21 Sehenswürdigkeiten sind ebenfalls in Weltkoordinaten dargestellt. Jede Sehenswürdigkeit besteht aus x, y und z. Diese stellen reale 3D-Koordinaten in Metern mit dem Ursprung im geometrischen Mittelpunkt des Hand dar.

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)

Die folgende Abbildung zeigt eine Visualisierung der Aufgabenausgabe:

Der Beispielcode für Hand-Markierungen zeigt, wie die von der Aufgabe zurückgegebenen Ergebnisse angezeigt werden. Weitere Informationen finden Sie im Code-Beispiel.