Leitfaden zur Erkennung von Handmarken im Web

Mit der MediaPipe Hand Landmarker-Aufgabe können Sie die Landmarken der Hände in einem Bild erkennen. In dieser Anleitung erfahren Sie, wie Sie den Hand Landmarker für Web- und JavaScript-Anwendungen verwenden.

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 JavaScript. Mit diesem Code können Sie diese Aufgabe testen und mit der Entwicklung einer eigenen Anwendung zur Erkennung von Handlandmarken beginnen. Sie können das Hand Landmarker Beispiel einfach in Ihrem Webbrowser ansehen, ausführen und bearbeiten.

Einrichtung

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

JavaScript-Pakete

Der Hand Landmarker-Code ist über das MediaPipe @mediapipe/tasks-vision NPM-Paket verfügbar. Sie können diese Bibliotheken gemäß der Anleitung im Einrichtungsleitfaden für die Plattform suchen und herunterladen.

Sie können die erforderlichen Pakete mit dem folgenden Befehl über NPM installieren:

npm install @mediapipe/tasks-vision

Wenn Sie den Aufgabencode über einen CDN-Dienst (Content Delivery Network) importieren möchten, fügen Sie den folgenden Code im Tag `<head>` in Ihrer HTML-Datei hinzu:

<!-- You can replace JSDeliver with another CDN if you prefer to -->
<head>
  <script src="https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision/vision_bundle.mjs"
    crossorigin="anonymous"></script>
</head>

Modell

Für die MediaPipe Hand Landmarker-Aufgabe ist ein trainiertes Modell erforderlich, das mit dieser Aufgabe kompatibel ist. Weitere Informationen zu den verfügbaren trainierten Modellen für Hand Landmarker finden Sie unter Aufgabenübersicht Modelle Abschnitt.

Wählen Sie ein Modell aus, laden Sie es herunter und speichern Sie es in Ihrem Projektverzeichnis:

<dev-project-root>/app/shared/models/

Aufgabe erstellen

Verwenden Sie eine der createFrom...()-Funktionen von Hand Landmarker, um die Aufgabe für die Ausführung von Inferenzvorgängen vorzubereiten. Verwenden Sie die Funktion createFromModelPath() mit einem relativen oder absoluten Pfad zur trainierten Modelldatei. Wenn Ihr Modell bereits in den Arbeitsspeicher geladen wurde, können Sie die Methode createFromModelBuffer() verwenden.

Das folgende Codebeispiel zeigt die Verwendung der Funktion createFromOptions() zum Einrichten der Aufgabe. Mit der Funktion createFromOptions können Sie den Hand Landmarker mit Konfigurationsoptionen anpassen. Weitere Informationen zu Konfigurations optionen finden Sie unter Konfigurationsoptionen.

Der folgende Code zeigt, wie Sie die Aufgabe mit benutzerdefinierten Optionen erstellen und konfigurieren:

const vision = await FilesetResolver.forVisionTasks(
  // path/to/wasm/root
  "https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@latest/wasm"
);
const handLandmarker = await HandLandmarker.createFromOptions(
    vision,
    {
      baseOptions: {
        modelAssetPath: "hand_landmarker.task"
      },
      numHands: 2
    });

Konfigurationsoptionen

Für diese Aufgabe sind die folgenden Konfigurationsoptionen für Web- und JavaScript-Anwendungen verfügbar:

Option Beschreibung Wertebereich Standardwert
runningMode Legt den Ausführungsmodus für die Aufgabe fest. Es gibt zwei Modi:

IMAGE: Der Modus für einzelne Bildeingaben.

VIDEO: Der Modus für decodierte Frames eines Videos oder für einen Livestream von Eingabedaten, z. B. von einer Kamera.		 {IMAGE, VIDEO} IMAGE
numHands Die maximale Anzahl der Hände, die vom Hand Landmarker erkannt werden. Any integer > 0 1
minHandDetectionConfidence Der Mindestkonfidenzwert für die Handerkennung, damit sie im Modell zur Erkennung von Handflächen als erfolgreich gilt. 0.0 - 1.0 0.5
minHandPresenceConfidence Der Mindestkonfidenzwert für die Handpräsenz im Hand Landmarkenerkennungsmodell. Wenn im Video- und Livestreammodus, wenn der Konfidenzwert für die Handpräsenz aus dem Modell zur Erkennung von Handlandmarken unter diesem Schwellenwert liegt, löst Hand Landmarker das Modell zur Erkennung von Handflächen aus. Andernfalls wird mit einem einfachen Handtracking-Algorithmus die Position der Hände für nachfolgende Landmarkenerkennungen bestimmt. 0.0 - 1.0 0.5
minTrackingConfidence Der Mindestkonfidenzwert für das Handtracking, damit es als erfolgreich gilt. Dies ist der IoU-Schwellenwert für den Begrenzungsrahmen zwischen den Händen im aktuellen Frame und im letzten Frame. Wenn die Verfolgung im Video- und Streammodus von Hand Landmarker fehlschlägt, löst Hand Landmarker die Hand Erkennung aus. Andernfalls wird die Handerkennung übersprungen. 0.0 - 1.0 0.5

Daten vorbereiten

Hand Landmarker kann Handlandmarken in Bildern in jedem Format erkennen, das vom Hostbrowser unterstützt wird. Die Aufgabe übernimmt auch die Vorverarbeitung der Dateneingabe, einschließlich Größenänderung, Drehung und Wertnormalisierung. Wenn Sie Handlandmarken in Videos erkennen möchten, können Sie mit der API schnell einen Frame nach dem anderen verarbeiten. Dabei wird der Zeitstempel des Frames verwendet, um zu bestimmen, wann die Handlandmarken im Video auftreten.

Aufgabe ausführen

Hand Landmarker verwendet die Methoden detect() (mit dem Ausführungsmodus image) und detectForVideo() (mit dem Ausführungsmodus video), um Inferenzvorgänge auszulösen. Die Aufgabe verarbeitet die Daten, versucht, Handlandmarken zu erkennen, und gibt dann die Ergebnisse aus.

Aufrufe der Methoden detect() und detectForVideo() von Hand Landmarker werden synchron ausgeführt und blockieren den Thread der Benutzeroberfläche. Wenn Sie Handlandmarken in Videoframes von der Kamera eines Geräts erkennen, blockiert jede Erkennung den Hauptthread. Sie können dies verhindern, indem Sie Web-Worker implementieren, um die Methoden detect() und detectForVideo() in einem anderen Thread auszuführen.

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

Bild

const image = document.getElementById("image") as HTMLImageElement;
const handLandmarkerResult = handLandmarker.detect(image);

Video

await handLandmarker.setOptions({ runningMode: "video" });

let lastVideoTime = -1;
function renderLoop(): void {
  const video = document.getElementById("video");

  if (video.currentTime !== lastVideoTime) {
    const detections = handLandmarker.detectForVideo(video);
    processResults(detections);
    lastVideoTime = video.currentTime;
  }

  requestAnimationFrame(() => {
    renderLoop();
  });
}

Eine vollständigere Implementierung der Ausführung einer Hand Landmarker-Aufgabe finden Sie im Beispiel.

Ergebnisse verarbeiten und anzeigen

Hand Landmarker generiert für jede Erkennungsausführung ein Ergebnisobjekt für Hand Landmarker. Das Ergebnisobjekt enthält Handlandmarken in Bildkoordinaten, Handlandmarken in Weltkoordinaten und die Händigkeit(linke/rechte Hand) der erkannten Hände.

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

Die Ausgabe HandLandmarkerResult 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

    Die Händigkeit gibt an, ob die erkannten Hände linke oder rechte Hände sind.

  • Landmarken

    Es gibt 21 Handlandmarken, die jeweils aus x-, y- und z-Koordinaten bestehen. Die x- und y-Koordinaten werden durch die Bildbreite bzw. -höhe auf [0.0, 1.0] normalisiert. Die z-Koordinate stellt die Landmarkentiefe dar, wobei die Tiefe am Handgelenk der Ursprung ist. Je kleiner der Wert, desto näher ist die Landmarke an der Kamera. Die Größe von z verwendet ungefähr dieselbe Skala wie x.

  • Weltlandmarken

    Die 21 Handlandmarken werden auch in Weltkoordinaten dargestellt. Jede Landmarke besteht aus x, y und z, die dreidimensionale Koordinaten in Metern in der realen Welt darstellen. Der Ursprung befindet sich im geometrischen Mittelpunkt der Hand.

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:

Eine Hand, die den Daumen nach oben streckt. Das Skelett der Hand ist zu sehen.

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