Leitfaden zur Erkennung von Handmarken im Web

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 für Web- und JavaScript-Apps verwenden.

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

Codebeispiel

Der Beispielcode für Hand Landmarken bietet eine vollständige Implementierung dieser Aufgabe in JavaScript. Mit diesem Code können Sie diese Aufgabe testen und mit der Erstellung Ihrer eigenen App zur Erkennung von Sehenswürdigkeiten beginnen. Sie können den Beispielcode für Hand Landmarken einfach in Ihrem Webbrowser aufrufen, ausführen und bearbeiten.

Einrichtung

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

JavaScript-Pakete

Der Hand-Landmark-Code ist über das MediaPipe-@mediapipe/tasks-vision NPM-Paket verfügbar. Folgen Sie der Anleitung im Einrichtungsleitfaden für die Plattform, um diese Bibliotheken zu suchen und herunterzuladen.

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

npm install @mediapipe/tasks-vision

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

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

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 ein Modell aus, laden Sie es herunter und speichern Sie es dann in Ihrem Projektverzeichnis:

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

Aufgabe erstellen

Verwenden Sie eine der createFrom...()-Funktionen für Hand Landmarken, um die Aufgabe zum Ausführen von Inferenzen vorzubereiten. Verwenden Sie die Funktion createFromModelPath() mit einem relativen oder absoluten Pfad zur trainierten Modelldatei. Wenn das Modell bereits in den Arbeitsspeicher geladen ist, können Sie die Methode createFromModelBuffer() verwenden.

Das folgende Codebeispiel zeigt, wie Sie die Aufgabe mit der Funktion createFromOptions() einrichten. Mit der Funktion createFromOptions können Sie die Handmarkierer-Funktion mit Konfigurationsoptionen anpassen. Weitere Informationen zu Konfigurationsoptionen 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

Diese Aufgabe bietet die folgenden Konfigurationsoptionen für Web- und JavaScript-Anwendungen:

Option	Beschreibung	Wertebereich	Standardwert
`runningMode`	Legt den Ausführungsmodus für die Task fest. Es gibt zwei Modi: IMAGE: Der Modus für Einzelbildeingaben. VIDEO: Der Modus für decodierte Frames eines Videos oder in einem Livestream mit Eingabedaten, z. B. von einer Kamera.	{`IMAGE, VIDEO`}	`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`

Daten vorbereiten

Hand Landmarker kann Handmarkierungen in Bildern in jedem Format erkennen, das vom Hostbrowser unterstützt wird. Die Aufgabe übernimmt auch die Vorverarbeitung der Dateneingabe, einschließlich Größenanpassung, Rotation und Wertenormalisierung. Um Handmarkierungen in Videos zu erkennen, können Sie die API verwenden, um einen Frame nach dem anderen schnell zu verarbeiten. Verwenden Sie dabei den Zeitstempel des Frames, um zu bestimmen, wann diese Handmarkierungen im Video vorkommen.

Task ausführen

Die Hand-Markierungsfunktion verwendet die Methoden detect() (mit dem Ausführungsmodus image) und detectForVideo() (im Ausführungsmodus video), um Inferenzen auszulösen. Die Aufgabe verarbeitet die Daten, versucht, Handmarkierungen zu erkennen, und meldet dann die Ergebnisse.

Aufrufe der Hand-Markierungsmethoden detect() und detectForVideo() werden synchron ausgeführt und blockieren den Benutzeroberflächen-Thread. Wenn Sie Orientierungspunkte 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-Landmark-Aufgabe finden Sie im Code-Beispiel.

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 (siehe Code-Beispiel).