Przedstawiamy Google AI Edge Portal: benchmark Edge AI na dużą skalę. Zarejestruj się, aby poprosić o dostęp podczas wersji prywatnej.

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

Zadanie MediaPipe Hand Landmarker umożliwia wykrywanie punktów orientacyjnych dłoni na obrazie. Z tych instrukcji dowiesz się, jak używać narzędzia Hand Landmarker w aplikacjach internetowych i JavaScript.

Więcej informacji o możliwościach, modelach i opcjach konfiguracji tego zadania znajdziesz w Przeglądzie.

Przykładowy kod

Przykładowy kod do wykrywania dłoni zawiera kompletną implementację tego zadania w JavaScript. Ten kod pomoże Ci przetestować to zadanie i zacząć tworzyć własną aplikację do wykrywania punktów charakterystycznych dłoni. Możesz wyświetlać, uruchamiać i edytować przykład wykrywania punktów charakterystycznych dłoni w przeglądarce internetowej.

Konfiguracja

W tej sekcji opisujemy najważniejsze kroki konfigurowania środowiska programistycznego, które umożliwia korzystanie z modelu Hand Landmarker. Ogólne informacje o konfigurowaniu środowiska programistycznego dla sieci i JavaScriptu, w tym wymagania dotyczące wersji platformy, znajdziesz w przewodniku konfiguracji dla sieci.

Pakiety JavaScript

Kod narzędzia Hand Landmarker jest dostępny w pakiecie MediaPipe @mediapipe/tasks-vision NPM. Te biblioteki możesz znaleźć i pobrać, postępując zgodnie z instrukcjami w przewodniku konfiguracji platformy.

Wymagane pakiety możesz zainstalować za pomocą NPM, używając tego polecenia:

npm install @mediapipe/tasks-vision

Jeśli chcesz zaimportować kod zadania za pomocą usługi sieci dystrybucji 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.mjs"
    crossorigin="anonymous"></script>
</head>

Model

Zadanie MediaPipe Hand Landmarker wymaga wytrenowanego modelu, który jest z nim zgodny. Więcej informacji o dostępnych wytrenowanych modelach do wykrywania punktów orientacyjnych dłoni znajdziesz w sekcji Modele w omówieniu zadania.

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 createFrom...() Hand Landmarker, aby przygotować zadanie do uruchomienia 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 narzędzia Hand Landmarker za pomocą opcji konfiguracji. Więcej informacji o opcjach konfiguracji znajdziesz w artykule Opcje konfiguracji.

Poniższy kod pokazuje, jak utworzyć 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 te opcje konfiguracji w przypadku aplikacji internetowych i aplikacji napisanych w języku JavaScript:

Nazwa opcji	Opis	Zakres wartości	Wartość domyślna
`runningMode`	Ustawia tryb uruchamiania zadania. Dostępne są 2 tryby: OBRAZ: tryb dla pojedynczych obrazów. WIDEO: tryb dla zdekodowanych klatek filmu lub transmisji na żywo danych wejściowych, np. z kamery.	{`IMAGE, VIDEO`}	`IMAGE`
`numHands`	Maksymalna liczba rąk wykrywanych przez detektor punktów charakterystycznych dłoni.	`Any integer > 0`	`1`
`minHandDetectionConfidence`	Minimalny poziom ufności wykrycia dłoni, który jest uznawany za udany w modelu wykrywania dłoni.	`0.0 - 1.0`	`0.5`
`minHandPresenceConfidence`	Minimalny poziom ufności dla wyniku obecności dłoni w modelu wykrywania punktów charakterystycznych dłoni. W trybie wideo i transmisji na żywo, jeśli wskaźnik ufności obecności dłoni z modelu punktów charakterystycznych dłoni jest niższy od tego progu, model punktów charakterystycznych dłoni uruchamia model wykrywania dłoni. W przeciwnym razie lekki algorytm śledzenia rąk określa położenie dłoni w celu późniejszego wykrywania punktów orientacyjnych.	`0.0 - 1.0`	`0.5`
`minTrackingConfidence`	Minimalny poziom ufności, przy którym śledzenie rąk jest uznawane za udane. Jest to próg współczynnika podobieństwa ramek ograniczających między dłońmi w bieżącej i ostatniej klatce. W trybie wideo i trybie strumieniowania w przypadku funkcji Hand Landmarker, jeśli śledzenie się nie powiedzie, funkcja Hand Landmarker uruchamia wykrywanie dłoni. W przeciwnym razie pomija wykrywanie dłoni.	`0.0 - 1.0`	`0.5`

Przygotuj dane

Model Hand Landmarker może wykrywać punkty charakterystyczne dłoni na obrazach w dowolnym formacie obsługiwanym przez przeglądarkę hosta. Zadanie to obejmuje też wstępne przetwarzanie danych wejściowych, w tym zmianę rozmiaru, obracanie i normalizację wartości. Aby wykrywać punkty charakterystyczne dłoni w filmach, możesz używać interfejsu API do szybkiego przetwarzania po jednej klatce naraz. Sygnatura czasowa klatki pozwala określić, kiedy punkty charakterystyczne dłoni pojawiają się w filmie.

Uruchamianie zadania

Model Hand Landmarker używa metod detect() (w trybie image) i detectForVideo() (w trybie video) do wywoływania wnioskowania. Zadanie przetwarza dane, próbuje wykryć punkty charakterystyczne dłoni, a następnie raportuje wyniki.

Wywołania metod detect() i detectForVideo() klasy Hand Landmarker działają synchronicznie i blokują wątek interfejsu. Jeśli wykryjesz punkty orientacyjne dłoni w klatkach wideo z kamery urządzenia, każde wykrycie blokuje główny wątek. Możesz temu zapobiec, wdrażając procesy robocze, które będą uruchamiać metody detect() i detectForVideo() w innym wątku.

Poniższy kod pokazuje, jak wykonać 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();
  });
}

Bardziej szczegółowe informacje o wdrażaniu zadania wykrywania punktów charakterystycznych dłoni znajdziesz w przykładzie.

Obsługa i wyświetlanie wyników

Detektor punktów charakterystycznych dłoni generuje obiekt wyniku detektora punktów charakterystycznych dłoni dla każdego wykrycia. Obiekt wyniku zawiera punkty charakterystyczne dłoni we współrzędnych obrazu, punkty charakterystyczne dłoni we współrzędnych świata oraz informację o tym, czy wykryte dłonie są lewe czy prawe.

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

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

Ręka dominująca

Ręka dominująca określa, czy wykryte dłonie to lewa czy prawa ręka.
Punkty orientacyjne

Wyróżniamy 21 punktów orientacyjnych dłoni, z których każdy składa się ze współrzędnych x, y i z. Współrzędne x i y są normalizowane do zakresu [0.0, 1.0] odpowiednio przez szerokość i wysokość obrazu. Współrzędna z reprezentuje głębokość punktu orientacyjnego, a punktem początkowym jest głębokość na nadgarstku. Im mniejsza wartość, tym bliżej aparatu znajduje się punkt orientacyjny. Wartość z jest w przybliżeniu w tej samej skali co x.
Punkty orientacyjne na świecie

21 punktów orientacyjnych dłoni jest też przedstawionych we współrzędnych świata. Każdy punkt orientacyjny składa się z wartości x, y i z, które reprezentują rzeczywiste współrzędne 3D w metrach, a punktem początkowym jest geometryczny środek 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)

Obraz poniżej przedstawia wizualizację wyniku zadania:

Ręka z kciukiem uniesionym do góry, na której widać szkielet

Przykładowy kod wykrywacza dłoni pokazuje, jak wyświetlać wyniki zwrócone przez zadanie. Zobacz przykład.