Leitfaden zur Erkennung von Handmarkierungen für Python

Mit der MediaPipe-Aufgabe „Hand Landmarker“ können Sie die Markierungen der Hände in einem Bild erkennen. In dieser Anleitung erfahren Sie, wie Sie den Landmarker für Hände mit Python verwenden. Der in dieser Anleitung beschriebene Beispielcode 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 den Landmarker für Hände enthält eine vollständige Implementierung dieser Aufgabe in Python. Mit diesem Code können Sie diese Aufgabe testen und mit dem Erstellen Ihres eigenen Markers für die Handerkennung beginnen. Sie können den Beispielcode für Markierungen von Hand mit nur einem Webbrowser aufrufen, ausführen und bearbeiten.

Wenn Sie den Landmarker für die Hand für Raspberry Pi implementieren, lesen Sie die Beispiel-App für Raspberry Pi.

Einrichtung

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

Pakete

Für die MediaPipe-Aufgabe „Hand Landmarker“ ist das PyPI-Paket „mediapipe“ erforderlich. Sie können diese Abhängigkeiten mit den folgenden Befehlen installieren und importieren:

$ python -m pip install mediapipe

Importe

Importieren Sie die folgenden Klassen, um auf die Aufgabenfunktionen von „Hand Landmarker“ zuzugreifen:

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

Modell

Für die MediaPipe-Aufgabe „Hand Landmarker“ ist ein trainiertes Modell erforderlich, das mit dieser Aufgabe kompatibel ist. Weitere Informationen zu verfügbaren trainierten Modellen für die Funktion „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 in einem lokalen Verzeichnis:

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

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

Aufgabe erstellen

Bei der MediaPipe-Aufgabe „Hand Landmarker“ wird die Funktion create_from_options verwendet, um die Aufgabe einzurichten. Die Funktion create_from_options akzeptiert Werte für Konfigurationsoptionen. Weitere Informationen zu Konfigurationsoptionen finden Sie unter Konfigurationsoptionen.

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

Diese Beispiele zeigen auch die verschiedenen Möglichkeiten zur Aufgabenerstellung 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 zum Erstellen eines Markierungspunkts für die Hand für die Verwendung mit einem Bild finden Sie im Codebeispiel.

Konfigurationsoptionen

Für diese Aufgabe gibt es die folgenden Konfigurationsoptionen für Python-Anwendungen:

Daten vorbereiten

Bereiten Sie Ihre Eingabe als Bilddatei oder als Numpy-Array vor und wandeln Sie sie dann in ein mediapipe.Image-Objekt um. Wenn Ihre Eingabe eine Videodatei oder ein Livestream von einer Webcam ist, können Sie eine externe Bibliothek wie OpenCV verwenden, um die 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)
    

Aufgabe ausführen

Der Landmarker für Hände verwendet die Funktionen „detect“, „detect_for_video“ und „detect_async“, um Inferenzen auszulösen. Bei der Erkennung von Handmerkmalen umfasst dies die Vorverarbeitung der Eingabedaten, die Erkennung von Händen im Bild und die Erkennung von Handmerkmalen.

Im folgenden Code wird gezeigt, 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:

• Wenn Sie die Funktion im Video- oder Livestream-Modus ausführen, müssen Sie der Aufgabe „Hand Landmarker“ auch den Zeitstempel des Eingabeframes angeben.
• Wenn die Funktion im Bild- oder Videomodell ausgeführt wird, blockiert die Aufgabe „Hand Landmarker“ den aktuellen Thread, bis die Verarbeitung des Eingabebilds oder ‑frames abgeschlossen ist.
• Wenn die Funktion im Livestream-Modus ausgeführt wird, blockiert die Landmarker-Aufgabe für Hände nicht den aktuellen Thread, sondern gibt sofort eine Antwort zurück. Jedes Mal, wenn die Verarbeitung eines Eingabeframes abgeschlossen ist, wird der Ergebnis-Listener mit dem Erkennungsergebnis aufgerufen. Wenn die Erkennungsfunktion aufgerufen wird, während die Aufgabe „Hand-Landmark-Segmentierung“ gerade einen anderen Frame verarbeitet, wird der neue Eingabeframe ignoriert.

Ein vollständiges Beispiel für die Ausführung eines Hand-Landmarks auf einem Bild finden Sie im Codebeispiel.

Ergebnisse verarbeiten und anzeigen

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

Im Folgenden finden 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:

• Links-/Rechtshänder

  „Handedness“ gibt an, ob die erkannten Hände links- oder rechtshändig sind.

• Landmarken

  Es gibt 21 Landmarken für die Hand, die jeweils aus x-, y- und z-Koordinaten bestehen. Die Koordinaten x und y werden durch die Bildbreite bzw. -höhe auf [0, 0; 1, 0] normalisiert. Die z-Koordinate steht für die Markierungstiefe. Die Tiefe am Handgelenk ist der Ursprung. Je kleiner der Wert, desto näher ist das Wahrzeichen an der Kamera. Die Größe von z wird ungefähr auf derselben Skala wie x dargestellt.

• Sehenswürdigkeiten der Welt

  Die 21 Landmarken für die Hand werden ebenfalls in Weltkoordinaten dargestellt. Jedes Landmark besteht aus x, y und z, die 3D-Koordinaten in Metern mit dem Ursprung im geometrischen Mittelpunkt der Hand darstellen.

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:

Im Beispielcode für die Landmark-Erkennung für Hände wird gezeigt, wie die von der Aufgabe zurückgegebenen Ergebnisse angezeigt werden. Weitere Informationen finden Sie im Codebeispiel.