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 die Hand-Markierung mit Android-Apps 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 von MediaPipe Tasks ist eine einfache Implementierung einer Hand-Landmark-App für Android. In diesem Beispiel wird die Kamera eines Android-Geräts verwendet, um kontinuierlich Handmarkierungen zu erkennen. Es können auch 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 darauf zurückgreifen, wenn Sie eine vorhandene App ändern. Der Hand-Landmark-Beispielcode wird auf GitHub gehostet.
Code herunterladen
In der folgenden Anleitung erfahren Sie, wie Sie mit dem git-Befehlszeilentool eine lokale Kopie des Beispielcodes erstellen.
So laden Sie den Beispielcode herunter:
- Klonen Sie das Git-Repository mit dem folgenden Befehl:
git clone https://github.com/google-ai-edge/mediapipe-samples
- Konfigurieren Sie optional die Git-Instanz für die Verwendung von Sparse Checkout, sodass Sie nur die Dateien für die Hand Landmarker-Beispiel-App haben:
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 erforderlichen Code für diese Beispielanwendung zur Erkennung von Handmarkierungen:
- HandLandmarkerHelper.kt: Initialisiert den Hand-Landmark-Detektor und verarbeitet die Modell- und Delegierungsauswahl.
- MainActivity.kt: Implementiert die Anwendung und ruft
HandLandmarkerHelper
auf.
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 Android.
Abhängigkeiten
Für die Aufgabe „Hand Landmarker“ wird die Bibliothek com.google.mediapipe:tasks-vision
verwendet. Füge diese Abhängigkeit in die Datei build.gradle
deiner Android-App ein:
dependencies {
implementation 'com.google.mediapipe:tasks-vision:latest.release'
}
Modell
Die MediaPipe Hand Landmark-Aufgabe erfordert ein trainiertes Modell-Bundle, 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 in Ihrem Projektverzeichnis:
<dev-project-root>/src/main/assets
Geben Sie den Pfad des Modells innerhalb des Parameters ModelAssetPath
an. Im Beispielcode wird das Modell in der Datei HandLandmarkerHelper.kt
definiert:
baseOptionBuilder.setModelAssetPath(MP_HAND_LANDMARKER_TASK)
Aufgabe erstellen
Die MediaPipe Hand Landmark-Aufgabe verwendet die Funktion createFromOptions()
, um die Aufgabe einzurichten. Die Funktion createFromOptions()
akzeptiert Werte für die Konfigurationsoptionen. Weitere Informationen zu Konfigurationsoptionen finden Sie unter Konfigurationsoptionen.
Hand Landmarker unterstützt drei Eingabedatentypen: Standbilder, Videodateien und Livestreams. Beim Erstellen der Aufgabe müssen Sie den Ausführungsmodus angeben, der Ihrem Eingabedatentyp entspricht. Wählen Sie den Tab für Ihren Eingabedatentyp aus, um zu sehen, wie die Aufgabe erstellt und die Inferenz ausgeführt werden soll.
Bild
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)
Video
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)
Livestream
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)
Durch die Implementierung des Beispielcodes für Hand-Markierungen können Nutzer zwischen den Verarbeitungsmodi wechseln. Dadurch wird der Code zur Aufgabenerstellung komplizierter und ist für Ihren Anwendungsfall möglicherweise nicht geeignet. Sie finden diesen Code in der Funktion setupHandLandmarker()
in der Datei HandLandmarkerHelper.kt
.
Konfigurationsoptionen
Diese Aufgabe umfasst die folgenden Konfigurationsoptionen für Android-Apps:
Option | Beschreibung | Wertebereich | Standardwert |
---|---|---|---|
runningMode |
Legt den Ausführungsmodus für die Task fest. Es gibt drei Modi: IMAGE: Der Modus für Einzelbildeingaben. VIDEO: Der Modus für decodierte Frames eines Videos. LIVE_STREAM: Der Modus für einen Livestream der Eingabedaten, z. B. von einer Kamera. In diesem Modus muss resultListener aufgerufen werden, um einen Listener einzurichten, der die Ergebnisse asynchron empfängt. |
{IMAGE, VIDEO, LIVE_STREAM } |
IMAGE |
numHands |
Die maximale Anzahl der Hände, die vom Hand-Ortserkennungserkennung erkannt wurden. | Any integer > 0 |
1 |
minHandDetectionConfidence |
Der Mindestkonfidenzwert für die Handerkennung, um im Handflächenerkennungsmodell als erfolgreich zu gelten. | 0.0 - 1.0 |
0.5 |
minHandPresenceConfidence |
Der minimale Konfidenzwert für den Wert der Handpräsenz im Modell zur Erkennung von Handmarkierungen. Wenn im Video- und Livestreammodus der Konfidenzwert zur Anwesenheit des Hand-Markierungsmodells unter diesem Grenzwert liegt, löst Hand Landmarker das Handflächenerkennungsmodell aus. Andernfalls ermittelt ein einfacher Algorithmus zur Handverfolgung die Position der Hand(en) für nachfolgende Erkennungen von Sehenswürdigkeiten. | 0.0 - 1.0 |
0.5 |
minTrackingConfidence |
Der Mindestkonfidenzwert, der für eine erfolgreiche Verfolgung der Handzeichen erforderlich ist. Dies ist der IoU-Grenzwert des Begrenzungsrahmens zwischen Händen im aktuellen und im letzten Frame. Wenn im Video- und Stream-Modus der Hand-Markdown-Funktion das Tracking fehlschlägt, löst diese Funktion die Handerkennung aus. Andernfalls wird die Handerkennung übersprungen. | 0.0 - 1.0 |
0.5 |
resultListener |
Legt den Ergebnis-Listener so fest, dass die Erkennungsergebnisse asynchron empfangen werden, wenn sich der Hand-Marker im Livestream-Modus befindet.
Gilt nur, wenn der Laufmodus auf LIVE_STREAM eingestellt ist |
– | – |
errorListener |
Legt einen optionalen Fehler-Listener fest. | – | – |
Daten vorbereiten
Hand Landmarker funktioniert mit Bildern, Videodateien und Livestream-Videos. Die Aufgabe übernimmt die Vorverarbeitung der Dateneingabe, einschließlich Größenanpassung, Rotation und Wertnormalisierung.
Der folgende Code zeigt, wie Daten zur Verarbeitung übergeben werden. Sie enthalten Details zur Verarbeitung von Daten aus Bildern, Videodateien und Live-Videostreams.
Bild
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()
Video
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()
Livestream
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 von Hand Landmarker erfolgt die Datenvorbereitung in der Datei HandLandmarkerHelper.kt
.
Task ausführen
Verwenden Sie je nach Datentyp, mit dem Sie arbeiten, die Methode HandLandmarker.detect...()
für diesen Datentyp. Verwenden Sie detect()
für einzelne Bilder, detectForVideo()
für Frames in Videodateien und detectAsync()
für Videostreams. Wenn Sie Erkennungsvorgänge in einem Videostream durchführen, sollten Sie die Erkennung in einem separaten Thread ausführen, damit der Thread der Benutzeroberfläche nicht blockiert wird.
Die folgenden Codebeispiele enthalten einfache Beispiele dafür, wie Hand Landmarker in diesen verschiedenen Datenmodi ausgeführt wird:
Bild
val result = handLandmarker?.detect(mpImage)
Video
val timestampMs = i * inferenceIntervalMs handLandmarker?.detectForVideo(mpImage, timestampMs) ?.let { detectionResult -> resultList.add(detectionResult) }
Livestream
val mpImage = BitmapImageBuilder(rotatedBitmap).build() val frameTime = SystemClock.uptimeMillis() handLandmarker?.detectAsync(mpImage, frameTime)
Wichtige Hinweise:
- Im Video- oder Livestreammodus müssen Sie auch den Zeitstempel des Eingabe-Frames für die Aufgabe „Hand Landmarker“ angeben.
- Im Bild- oder Videomodus blockiert die Aufgabe „Hand Landmarker“ den aktuellen Thread, bis die Verarbeitung des Eingabebilds oder ‐frames abgeschlossen ist. Führen Sie die Verarbeitung in einem Hintergrundthread aus, damit die Benutzeroberfläche nicht blockiert wird.
- 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 Aufgabe „Hand Landmarker“ mit der Verarbeitung eines anderen Frames beschäftigt ist, ignoriert die Aufgabe den neuen Eingabeframe.
Im Beispielcode von Hand Landmarker werden die Funktionen detect
, detectForVideo
und detectAsync
in der Datei HandLandmarkerHelper.kt
definiert.
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
- undz
-Koordinaten bestehen. Die Koordinatenx
undy
werden entsprechend der Bildbreite bzw. -höhe auf [0,0, 1,0] normalisiert. Diez
-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 vonz
wird ungefähr gleich groß wie beix
verwendet.Sehenswürdigkeiten der Welt
Die 21 Sehenswürdigkeiten sind ebenfalls in Weltkoordinaten dargestellt. Jede Sehenswürdigkeit besteht aus
x
,y
undz
. 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 in der Klasse OverlayView
.