Leitfaden zur Erkennung von Handmarkierungen für Android

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 Android-Apps 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 MediaPipe Tasks ist eine einfache Implementierung einer App für Hand-Landmarker für Android. Im Beispiel wird die Kamera eines physischen Android-Geräts verwendet, um Handmarkierungen kontinuierlich zu erkennen. Außerdem können Bilder und Videos aus der Gerätegalerie verwendet werden, um Handmarkierungen statisch zu erkennen.

Sie können die App als Ausgangspunkt für Ihre eigene Android-App verwenden oder sich an ihr orientieren, wenn Sie eine vorhandene App ändern. Der Beispielcode für Landmarker für Hände wird auf GitHub gehostet.

Code herunterladen

In der folgenden Anleitung wird beschrieben, wie Sie mit dem Befehlszeilentool git eine lokale Kopie des Beispielcodes erstellen.

So laden Sie den Beispielcode herunter:

1. Klonen Sie das Git-Repository mit dem folgenden Befehl:

   git clone https://github.com/google-ai-edge/mediapipe-samples
   

2. Optional können Sie Ihre Git-Instanz so konfigurieren, dass eine spärliche Überprüfung verwendet wird, sodass nur die Dateien für die Beispiel-App „Hand Landmarker“ vorhanden sind:

   cd mediapipe
   git sparse-checkout init --cone
   git sparse-checkout set examples/hand_landmarker/android
   

Nachdem Sie eine lokale Version des Beispielcodes erstellt haben, können Sie das Projekt in Android Studio importieren und die App ausführen. Eine Anleitung dazu finden Sie im Einrichtungsleitfaden für Android.

Schlüsselkomponenten

Die folgenden Dateien enthalten den wichtigsten Code für diese Beispielanwendung zur Erkennung von Handmarkierungen:

• HandLandmarkerHelper.kt: Hier wird der Landmark-Detektor für die Hand initialisiert und das Modell und die Auswahl des Stellvertreters verwaltet.
• MainActivity.kt: Implementiert die Anwendung, einschließlich des Aufrufs von HandLandmarkerHelper.

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 Einrichtungsleitfaden für Android.

Abhängigkeiten

Für die Aufgabe „Landmark-Erkennung für Hände“ wird die com.google.mediapipe:tasks-vision-Bibliothek verwendet. Fügen Sie der Datei build.gradle Ihrer Android-App diese Abhängigkeit hinzu:

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

Modell

Für die MediaPipe-Aufgabe „Hand Landmarker“ ist ein trainiertes Modellpaket 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 im Projektverzeichnis:

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

Geben Sie den Pfad des Modells im Parameter ModelAssetPath an. Im Beispielcode wird das Modell in der Datei HandLandmarkerHelper.kt definiert:

baseOptionBuilder.setModelAssetPath(MP_HAND_LANDMARKER_TASK)

Aufgabe erstellen

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

Der Hand-Landmarker unterstützt drei Eingabedatentypen: Standbilder, Videodateien und Livestreams. Beim Erstellen der Aufgabe müssen Sie den Ausführungsmodus angeben, der dem Eingabedatentyp entspricht. Wählen Sie den Tab für den Eingabedatentyp aus, um zu erfahren, wie Sie die Aufgabe erstellen und die Inferenz ausführen.

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)
    

Mit der Beispielcodeimplementierung für die Landmark-Erkennung für Hände kann der Nutzer zwischen den Verarbeitungsmodi wechseln. Dieser Ansatz macht den Code zum Erstellen von Aufgaben komplizierter und ist möglicherweise nicht für Ihren Anwendungsfall geeignet. Sie finden diesen Code in der Funktion setupHandLandmarker() in der Datei HandLandmarkerHelper.kt.

Konfigurationsoptionen

Für diese Aufgabe sind die folgenden Konfigurationsoptionen für Android-Apps verfügbar:

Daten vorbereiten

Die Funktion „Landmark für Hände“ funktioniert mit Bildern, Videodateien und Livestreams. Die Aufgabe übernimmt die Vorverarbeitung der Dateneingabe, einschließlich Größenänderung, Drehung und Wertnormalisierung.

Im folgenden Code wird gezeigt, wie Daten zur Verarbeitung übergeben werden. Diese Beispiele enthalten Details zum Umgang mit Daten aus Bildern, Videodateien und Livestreams.

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

Im Beispielcode für die Markierung von Handobjekten wird die Datenvorbereitung in der Datei HandLandmarkerHelper.kt ausgeführt.

Aufgabe ausführen

Verwenden Sie je nach Datentyp die für diesen Datentyp spezifische HandLandmarker.detect...()-Methode. Verwenden Sie detect() für einzelne Bilder, detectForVideo() für Frames in Videodateien und detectAsync() für Videostreams. Wenn du Erkennungen in einem Videostream durchführst, solltest du sie in einem separaten Thread ausführen, um den UI-Thread nicht zu blockieren.

Die folgenden Codebeispiele zeigen einfache Beispiele für die Ausführung von Hand Landmarker in diesen verschiedenen Datenmodi:

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)
    

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 Videomodus ausgeführt wird, blockiert die Landmarker-Aufgabe für Hände den aktuellen Thread, bis die Verarbeitung des Eingabebilds oder ‑frames abgeschlossen ist. Führen Sie die Verarbeitung in einem Hintergrund-Thread aus, um die Benutzeroberfläche nicht zu blockieren.
• 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 „Landmarker für Hände“ gerade einen anderen Frame verarbeitet, wird der neue Eingabeframe ignoriert.

Im Beispielcode für Markierungen per Hand sind die Funktionen detect, detectForVideo und detectAsync in der Datei HandLandmarkerHelper.kt definiert.

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 in der Klasse OverlayView.