Przewodnik po rozpoznawaniu gestów w przeglądarce

Zadanie rozpoznawania gestów MediaPipe umożliwia rozpoznawanie gestów dłoni w czasie rzeczywistym i wyświetla wyniki rozpoznawanych gestów oraz ich punkty orientacyjne. W tych instrukcjach pokazujemy, jak używać Modułu rozpoznawania gestów w aplikacjach internetowych i JavaScript.

Aby zobaczyć, jak działa to zadanie, obejrzyj prezentację. Więcej informacji o możliwościach, modelach i opcjach konfiguracji tego zadania znajdziesz w sekcji Omówienie.

Przykładowy kod

Przykładowy kod narzędzia do rozpoznawania gestów zawiera pełną implementację tego zadania w JavaScript. Ten kod pomoże Ci przetestować to zadanie i zacząć tworzyć własną aplikację do rozpoznawania gestów. Możesz wyświetlać, uruchamiać i edytować przykładowy kod do rozpoznawania gestów tylko w przeglądarce.

Konfiguracja

W tej sekcji opisujemy najważniejsze czynności, które należy wykonać, by skonfigurować środowisko programistyczne pod kątem używania funkcji rozpoznawania gestów. Ogólne informacje o konfigurowaniu środowiska programistycznego do obsługi stron internetowych i JavaScript, w tym o wymaganiach dotyczących wersji platformy, znajdziesz w przewodniku po konfiguracji na potrzeby stron internetowych.

Pakiety JavaScript

Kod modułu rozpoznawania gestów jest dostępny w pakiecie MediaPipe @mediapipe/tasks-vision NPM. Aby znaleźć i pobrać te biblioteki, wykonaj instrukcje podane w przewodniku po konfiguracji dotyczącym platformy.

Wymagane pakiety możesz zainstalować za pomocą NPM za pomocą tego polecenia:

npm install @mediapipe/tasks-vision

Jeśli chcesz zaimportować kod zadania przez usługę sieci dostarczania treści (CDN), dodaj ten kod w tagu <head> w pliku HTML:

<!-- 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>

Model

Zadanie rozpoznawania gestów MediaPipe wymaga wytrenowanego modelu zgodnego z tym zadaniem. Więcej informacji o dostępnych wytrenowanych modelach na potrzeby rozpoznawania gestów znajdziesz w przeglądzie zadań w sekcji poświęconej modelom.

Wybierz i pobierz model, a następnie zapisz go w katalogu projektu:

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

Tworzenie zadania

Użyj jednej z funkcji rozpoznawania gestów createFrom...(), aby przygotować zadanie do uruchamiania wnioskowania. Użyj funkcji createFromModelPath() ze ścieżką względną lub bezwzględną do wytrenowanego pliku modelu. Jeśli model jest już załadowany do pamięci, możesz użyć metody createFromModelBuffer().

Poniższy przykładowy kod pokazuje, jak skonfigurować zadanie za pomocą funkcji createFromOptions(). Funkcja createFromOptions umożliwia dostosowanie modułu rozpoznawania gestów za pomocą opcji konfiguracyjnych. Więcej informacji o opcjach konfiguracji znajdziesz w artykule Opcje konfiguracji.

Poniższy kod pokazuje, jak skompilować i skonfigurować zadanie z opcjami niestandardowymi:

// Create task for image file processing:
const vision = await FilesetResolver.forVisionTasks(
  // path/to/wasm/root
  "https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@latest/wasm "
);
const gestureRecognizer = await GestureRecognizer.createFromOptions(vision, {
  baseOptions: {
    modelAssetPath: "https://storage.googleapis.com/mediapipe-tasks/gesture_recognizer/gesture_recognizer.task"
  },
  numHands: 2
});

Opcje konfiguracji

To zadanie ma następujące opcje konfiguracji aplikacji internetowych:

Nazwa opcji Opis Zakres wartości Wartość domyślna
runningMode Ustawia tryb działania zadania. Są 2 tryby:

IMAGE: tryb wprowadzania pojedynczych obrazów.

WIDEO: tryb dla zdekodowanych klatek filmu lub strumienia danych wejściowych na żywo, np. z kamery.		 {IMAGE, VIDEO} IMAGE
num_hands GestureRecognizer może wykryć maksymalną liczbę rąk. Any integer > 0 1
min_hand_detection_confidence Minimalny stopień pewności, że wykrywanie dłoni zostanie uznane za udane w modelu wykrywania dłoni. 0.0 - 1.0 0.5
min_hand_presence_confidence Minimalny wynik ufności wskaźnika obecności ręki w modelu wykrywania punktów orientacyjnych ręki. W trybie wideo i w trybie transmisji na żywo Modułu rozpoznawania gestów, jeśli wynik wiarygodności modelu ręki z modelu punktu orientacyjnego dłoni jest poniżej tego progu, uruchamia model wykrywania dłoni. W przeciwnym razie do określenia lokalizacji rąk używany jest uproszczony algorytm śledzenia punktów orientacyjnych. 0.0 - 1.0 0.5
min_tracking_confidence Minimalny wynik pewności, że śledzenie dłoni zostanie uznane za udane. Jest to próg interfejsu użytkownika w ramce ograniczającej między rękami w bieżącej a ostatniej klatce. W trybie wideo i trybie strumienia Modułu rozpoznawania gestów, jeśli śledzenie nie powiedzie się, rozpoznawanie gestów aktywuje wykrywanie dłoni. W przeciwnym razie wykrywanie rąk zostanie pominięte. 0.0 - 1.0 0.5
canned_gestures_classifier_options Opcje konfigurowania działania klasyfikatora gotowych gestów. Gotowe gesty to ["None", "Closed_Fist", "Open_Palm", "Pointing_Up", "Thumb_Down", "Thumb_Up", "Victory", "ILoveYou"]
  • Język wyświetlanych nazw: język, który ma być używany dla wyświetlanych nazw określonych za pomocą metadanych modelu TFLite (jeśli występują).
  • Maksymalna liczba wyników: maksymalna liczba najwyżej wyników do zwrócenia. Jeśli wartość jest mniejsza niż 0, zostaną zwrócone wszystkie dostępne wyniki.
  • Próg wyniku: wynik, poniżej którego wyniki są odrzucane. Jeśli ma wartość 0, zwracane są wszystkie dostępne wyniki.
  • Lista dozwolonych kategorii: lista dozwolonych nazw kategorii. Jeśli pole nie jest puste, wyniki klasyfikacji, których kategoria nie należy do tego zbioru, zostaną odfiltrowane. Wzajemnie wykluczają się z listą odrzuconych.
  • Lista odrzuconych kategorii: lista odrzuconych nazw kategorii. Jeśli pole nie jest puste, wyniki klasyfikacji, których kategoria należy do tego zbioru, zostaną odfiltrowane. Wzajemnie wykluczające się dzięki liście dozwolonych.
    		•
    • Język wyświetlanych nazw: any string
    • Maksymalna liczba wyników: any integer
    • Próg wyniku: 0.0-1.0
    • Lista dozwolonych kategorii: vector of strings
    • Lista odrzuconych kategorii: vector of strings
    • Język wyświetlanych nazw: "en"
    • Maksymalna liczba wyników: -1
    • Próg wyniku: 0
    • Lista dozwolonych kategorii: pusta
    • Lista odrzuconych kategorii: pusta
    custom_gestures_classifier_options Opcje konfigurowania działania klasyfikatora gestów niestandardowych.
  • Język wyświetlanych nazw: język, który ma być używany dla wyświetlanych nazw określonych za pomocą metadanych modelu TFLite (jeśli występują).
  • Maksymalna liczba wyników: maksymalna liczba najwyżej wyników do zwrócenia. Jeśli wartość jest mniejsza niż 0, zostaną zwrócone wszystkie dostępne wyniki.
  • Próg wyniku: wynik, poniżej którego wyniki są odrzucane. Jeśli ma wartość 0, zwracane są wszystkie dostępne wyniki.
  • Lista dozwolonych kategorii: lista dozwolonych nazw kategorii. Jeśli pole nie jest puste, wyniki klasyfikacji, których kategoria nie należy do tego zbioru, zostaną odfiltrowane. Wzajemnie wykluczają się z listą odrzuconych.
  • Lista odrzuconych kategorii: lista odrzuconych nazw kategorii. Jeśli pole nie jest puste, wyniki klasyfikacji, których kategoria należy do tego zbioru, zostaną odfiltrowane. Wzajemnie wykluczające się dzięki liście dozwolonych.
    		•
    • Język wyświetlanych nazw: any string
    • Maksymalna liczba wyników: any integer
    • Próg wyniku: 0.0-1.0
    • Lista dozwolonych kategorii: vector of strings
    • Lista odrzuconych kategorii: vector of strings
    • Język wyświetlanych nazw: "en"
    • Maksymalna liczba wyników: -1
    • Próg wyniku: 0
    • Lista dozwolonych kategorii: pusta
    • Lista odrzuconych kategorii: pusta

    Przygotuj dane

    Moduł rozpoznawania gestów rozpoznaje gesty na obrazach w dowolnym formacie obsługiwanym przez przeglądarkę hosta. Zadaniem tego zadania jest również wstępne przetwarzanie danych wejściowych, w tym zmiana rozmiaru, rotacja i normalizacja wartości. Do rozpoznawania gestów w filmach możesz za pomocą interfejsu API szybko przetwarzać kolejne klatki, na podstawie sygnatury czasowej klatki, aby określić, kiedy mają one miejsce w filmie.

    Uruchamianie zadania

    Rozpoznawanie gestów inicjuje wnioskowania przy użyciu metod recognize() (w trybie biegania 'image') i recognizeForVideo() (w trybie biegania 'video'). Zadanie przetwarza dane, próbuje rozpoznać gesty rąk i raportuje wyniki.

    Ten kod pokazuje, jak wykonywać przetwarzanie za pomocą modelu zadań:

    Obraz

    const image = document.getElementById("image") as HTMLImageElement;
const gestureRecognitionResult = gestureRecognizer.recognize(image);

    Wideo

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

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

  if (video.currentTime !== lastVideoTime) {
    const gestureRecognitionResult = gestureRecognizer.recognizeForVideo(video);
    processResult(gestureRecognitionResult);
    lastVideoTime = video.currentTime;
  }

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

    Wywołania metod rozpoznawania gestów recognize() i recognizeForVideo() są zsynchronizowane i blokują wątek interfejsu użytkownika. Jeśli rozpoznasz gesty w klatkach wideo pochodzące z aparatu urządzenia, każde rozpoznawanie zablokuje wątek główny. Aby temu zapobiec, zaimplementuj instancje robocze, które uruchamiają metody recognize() i recognizeForVideo() w innym wątku.

    Pełną implementację uruchamiania zadania Rozpoznawanie gestów znajdziesz w przykładowym kodzie.

    Obsługa i wyświetlanie wyników

    Narzędzie do rozpoznawania gestów generuje obiekt wyniku wykrywania gestów przy każdym uruchomieniu rozpoznawania gestów. Otrzymany obiekt zawiera punkty orientacyjne dłoni we współrzędnych zdjęcia, punkty orientacyjne we współrzędnych świata, ręczność(lewa/prawa ręka) oraz kategorie wykrytej dłoni.

    Poniżej znajdziesz przykład danych wyjściowych z tego zadania:

    Wynikowy GestureRecognizerResult zawiera 4 komponenty, a każdy z nich jest tablicą, w której każdy element zawiera wykryty wynik pojedynczej wykrytej dłoni.

    • Ręka dominująca

      Ręka wskazuje, czy wykryte ręce są lewą czy prawą ręką.

    • Gesty

      Rozpoznawane kategorie gestów wykrytych dłoni.

    • Punkty orientacyjne

      Jest 21 punktów orientacyjnych wskazujących dłonie, a każdy z nich składa się ze współrzędnych x, y i z. Współrzędne x i y są normalizowane do wartości [0,0, 1,0] odpowiednio do szerokości i wysokości obrazu. Współrzędna z reprezentuje głębokość punktu orientacyjnego, przy czym głębokość na nadgarstku jest punktem początkowym. Im mniejsza wartość, tym zbliża się punkt orientacyjny do aparatu. Siła działania z jest mniej więcej zbliżona do skali x.

    • Punkty orientacyjne na świecie

      We współrzędnych świata są również przedstawione 21 punktów orientacyjnych. Każdy punkt orientacyjny składa się z elementów x, y i z, które reprezentują rzeczywiste współrzędne 3D w metrach z punktem początkowym w środku geometrycznym dłoni.

    GestureRecognizerResult:
  Handedness:
    Categories #0:
      index        : 0
      score        : 0.98396
      categoryName : Left
  Gestures:
    Categories #0:
      score        : 0.76893
      categoryName : Thumb_Up
  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)

    Na tych obrazach pokazano wizualizację wyników zadania:

    Pełną implementację tworzenia zadania rozpoznawania gestów znajdziesz w przykładowym kodzie.