Przewodnik po wykrywaniu punktów orientacyjnych dłoni w przeglądarce

Zadanie MediaPipe Hand Pointer umożliwia wykrywanie punktów orientacyjnych dłoni na zdjęciu. W tych instrukcjach pokazujemy, jak używać Wskaźnika ręcznego w aplikacjach internetowych i JavaScript.

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 Hand Pointer zawiera pełną implementację tego zadania w języku JavaScript. Ten kod pomoże Ci przetestować to zadanie i rozpocząć tworzenie własnej aplikacji do wykrywania punktów orientacyjnych dłoni. Możesz wyświetlić, uruchomić i edytować przykładowy kod funkcji punktów orientacyjnych dłoni tylko w przeglądarce.

Konfiguracja

W tej sekcji opisujemy najważniejsze czynności, jakie należy wykonać, by skonfigurować środowisko programistyczne pod kątem użycia ręcznego, punktu orientacyjnego. 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 obiektu orientacyjnego 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 do 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 MediaPipe Hand Krakers wymaga wytrenowanego modelu zgodnego z tym zadaniem. Więcej informacji o dostępnych wytrenowanych modelach dla punktów orientacyjnych rąk znajdziesz w omówieniem zadań w sekcji „Modele”.

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 Punkt orientacyjny 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 ręcznego punktu orientacyjnego za pomocą opcji konfiguracji. Więcej informacji o opcjach konfiguracji znajdziesz w artykule Opcje konfiguracji.

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

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
    });

Opcje konfiguracji

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

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`
`numHands`	Maksymalna liczba rąk wykrytych przez detektor punktów orientacyjnych dłoni.	`Any integer > 0`	`1`
`minHandDetectionConfidence`	Minimalny stopień pewności, że wykrywanie dłoni zostanie uznane za udane w modelu wykrywania dłoni.	`0.0 - 1.0`	`0.5`
`minHandPresenceConfidence`	Minimalny wskaźnik ufności dla wyniku obecności ręki w modelu wykrywania punktów orientacyjnych ręki. W trybie wideo i w trybie transmisji na żywo, jeśli wskaźnik ufności obecności ręki dla modelu punktu orientacyjnego dłoni jest poniżej tego progu, komponent wskazuje rękę ręcznie uruchamia model wykrywania dłoni. W przeciwnym razie do wykrywania punktów orientacyjnych potrzebny jest uproszczony algorytm śledzenia dłoni.	`0.0 - 1.0`	`0.5`
`minTrackingConfidence`	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 Wskaźnika ręcznego, jeśli śledzenie nie powiedzie się, wskazujesz rękę ręcznie. W przeciwnym razie pomijane jest wykrywanie rąk.	`0.0 - 1.0`	`0.5`

Przygotuj dane

Narzędzie do rysowania dłoni może wykrywać punkty orientacyjne 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. Aby wykryć punkty orientacyjne w filmach, za pomocą interfejsu API możesz szybko przetwarzać kolejne klatki. Wykorzystując sygnaturę czasową klatki, możesz określić, kiedy w filmie występują punkty orientacyjne.

Uruchamianie zadania

Punkt orientacyjny Ręka do generowania wnioskowania korzysta z metod detect() (w trybie uruchamiania image) i detectForVideo() (w trybie biegu video). Zadanie przetwarza dane, próbuje wykryć punkty orientacyjne na dłoniach, a potem podaje wyniki.

Wywołania metod detect() i detectForVideo() związane z punktem orientacyjnym dłoni są synchronizowane synchronicznie i blokują wątek interfejsu użytkownika. Jeśli wykryjesz punkty orientacyjne na klatkach wideo z kamery urządzenia, każde wykryte wykrywanie zablokuje wątek główny. Aby temu zapobiec, zaimplementuj instancje robocze, które uruchamiają metody detect() i detectForVideo() w innym wątku.

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

Obraz

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

Wideo

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

Pełną implementację uruchamiania zadania Oznaczenie ręki znajdziesz w przykładowym kodzie.

Obsługa i wyświetlanie wyników

Narzędzie do tworzenia punktów orientacyjnych ręcznie generuje obiekt wynikowy wskaźniku ręcznego dla każdego uruchomienia wykrywania. Otrzymany obiekt zawiera punkty orientacyjne dłoni we współrzędnych zdjęcia, punkty orientacyjne we współrzędnych świata i ręczność(lewa/prawa ręka) wykrytych dłoni.

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

Dane wyjściowe HandLandmarkerResult zawierają 3 komponenty. Każdy komponent jest tablicą, w której każdy element zawiera te wyniki dotyczące pojedynczej wykrytej dłoni:

Ręka dominująca

Ręka wskazuje, czy wykryte ręce są lewą czy prawą ręką.
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.

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)

Poniższy obraz przedstawia wizualizację wyników zadania:

Przykładowy kod modułu ręki wskazuje, jak wyświetlać wyniki zwrócone z zadania. Zobacz przykładowy kod.