Przewodnik dotyczący wykrywania punktów orientacyjnych dłoni w Pythonie

Zadanie MediaPipe Hand Pointer umożliwia wykrywanie punktów orientacyjnych dłoni na zdjęciu. Te instrukcje pokazują, jak korzystać z narzędzia ręcznego w Pythonie. Przykładowy kod opisany w tych instrukcjach jest dostępny na GitHub.

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 Pythonie. Ten kod pomoże Ci przetestować to zadanie i rozpocząć tworzenie własnego wzorca do wykrywania punktów orientacyjnych. Możesz wyświetlać, uruchamiać i edytować przykładowy kod narzędzia Ręczny punkt orientacyjny w samej przeglądarce.

Konfiguracja

W tej sekcji opisujemy najważniejsze czynności, jakie należy wykonać, aby skonfigurować środowisko programistyczne i projekty kodu tak, aby używały tego narzędzia. Ogólne informacje o konfigurowaniu środowiska programistycznego na potrzeby zadań MediaPipe, w tym o wymaganiach dotyczących wersji platformy, znajdziesz w przewodniku konfiguracji dla Pythona.

Pakiety

Zadanie MediaPipe Hand Pointer wymaga pakietu Mediapipe PyPI. Możesz zainstalować i zaimportować te zależności za pomocą:

$ python -m pip install mediapipe

Importowane dane

Aby uzyskać dostęp do funkcji zadania Notatnik ręki, zaimportuj następujące klasy:

import mediapipe as mp
from mediapipe.tasks import python
from mediapipe.tasks.python import vision

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 lokalnym:

model_path = '/absolute/path/to/gesture_recognizer.task'

Użyj parametru model_asset_path obiektu BaseOptions, aby określić ścieżkę modelu, który ma zostać użyty. Przykładowy kod znajdziesz w następnej sekcji.

Tworzenie zadania

Zadanie tworzenia punktu orientacyjnego MediaPipe ręcznie konfiguruje to zadanie za pomocą funkcji create_from_options. Funkcja create_from_options akceptuje wartości opcji konfiguracji. Więcej informacji o opcjach konfiguracji znajdziesz w artykule Opcje konfiguracji.

Poniższy kod pokazuje, jak skompilować i skonfigurować to zadanie.

W tych przykładach widać też różne wersje konstrukcji zadań dla obrazów, plików wideo i transmisji na żywo.

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
HandLandmarker = mp.tasks.vision.HandLandmarker
HandLandmarkerOptions = mp.tasks.vision.HandLandmarkerOptions
VisionRunningMode = mp.tasks.vision.RunningMode

# Create a hand landmarker instance with the image mode:
options = HandLandmarkerOptions(
    base_options=BaseOptions(model_asset_path='/path/to/model.task'),
    running_mode=VisionRunningMode.IMAGE)
with HandLandmarker.create_from_options(options) as landmarker:
  # The landmarker is initialized. Use it here.
  # ...
    

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
HandLandmarker = mp.tasks.vision.HandLandmarker
HandLandmarkerOptions = mp.tasks.vision.HandLandmarkerOptions
VisionRunningMode = mp.tasks.vision.RunningMode

# Create a hand landmarker instance with the video mode:
options = HandLandmarkerOptions(
    base_options=BaseOptions(model_asset_path='/path/to/model.task'),
    running_mode=VisionRunningMode.VIDEO)
with HandLandmarker.create_from_options(options) as landmarker:
  # The landmarker is initialized. Use it here.
  # ...
    

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
HandLandmarker = mp.tasks.vision.HandLandmarker
HandLandmarkerOptions = mp.tasks.vision.HandLandmarkerOptions
HandLandmarkerResult = mp.tasks.vision.HandLandmarkerResult
VisionRunningMode = mp.tasks.vision.RunningMode

# Create a hand landmarker instance with the live stream mode:
def print_result(result: HandLandmarkerResult, output_image: mp.Image, timestamp_ms: int):
    print('hand landmarker result: {}'.format(result))

options = HandLandmarkerOptions(
    base_options=BaseOptions(model_asset_path='/path/to/model.task'),
    running_mode=VisionRunningMode.LIVE_STREAM,
    result_callback=print_result)
with HandLandmarker.create_from_options(options) as landmarker:
  # The landmarker is initialized. Use it here.
  # ...
    

Pełny przykład tworzenia mapy orientacyjnej do użycia z obrazem znajdziesz w przykładowym kodzie.

Opcje konfiguracji

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

Przygotuj dane

Przygotuj dane wejściowe jako plik graficzny lub tablicę numpy, a następnie przekonwertuj je na obiekt mediapipe.Image. Jeśli dane wejściowe to plik wideo lub transmisja na żywo z kamery internetowej, możesz użyć zewnętrznej biblioteki, takiej jak OpenCV, aby wczytać klatki wejściowe jako tablice numeryczne.

import mediapipe as mp

# Load the input image from an image file.
mp_image = mp.Image.create_from_file('/path/to/image')

# Load the input image from a numpy array.
mp_image = mp.Image(image_format=mp.ImageFormat.SRGB, data=numpy_image)
    

import mediapipe as mp

# Use OpenCV’s VideoCapture to load the input video.

# Load the frame rate of the video using OpenCV’s CV_CAP_PROP_FPS
# You’ll need it to calculate the timestamp for each frame.

# Loop through each frame in the video using VideoCapture#read()

# Convert the frame received from OpenCV to a MediaPipe’s Image object.
mp_image = mp.Image(image_format=mp.ImageFormat.SRGB, data=numpy_frame_from_opencv)
    

import mediapipe as mp

# Use OpenCV’s VideoCapture to start capturing from the webcam.

# Create a loop to read the latest frame from the camera using VideoCapture#read()

# Convert the frame received from OpenCV to a MediaPipe’s Image object.
mp_image = mp.Image(image_format=mp.ImageFormat.SRGB, data=numpy_frame_from_opencv)
    

Uruchamianie zadania

Punkt orientacyjny Ręka wyzwala wnioskowania, korzystając z funkcji wykrywania, wykrywania_filmu i wykrywania_async. Wykrywanie punktów orientacyjnych obejmuje wstępne przetwarzanie danych wejściowych, wykrywanie rąk na zdjęciu i wykrywanie ich punktów orientacyjnych.

Poniższy kod pokazuje, jak wykonać przetwarzanie za pomocą modelu zadań.

# Perform hand landmarks detection on the provided single image.
# The hand landmarker must be created with the image mode.
hand_landmarker_result = landmarker.detect(mp_image)
    

# Perform hand landmarks detection on the provided single image.
# The hand landmarker must be created with the video mode.
hand_landmarker_result = landmarker.detect_for_video(mp_image, frame_timestamp_ms)
    

# Send live image data to perform hand landmarks detection.
# The results are accessible via the `result_callback` provided in
# the `HandLandmarkerOptions` object.
# The hand landmarker must be created with the live stream mode.
landmarker.detect_async(mp_image, frame_timestamp_ms)
    

Uwaga:

• Gdy urządzenie działa w trybie wideo lub w trybie transmisji na żywo, musisz też podać dla zadania Oznaczenie dłonią sygnaturę czasową klatki wejściowej.
• Uruchomione w obrazie lub modelu wideo zadanie Wskażnik dłoni będzie blokować bieżący wątek do momentu zakończenia przetwarzania obrazu wejściowego lub klatki.
• W trybie transmisji na żywo zadanie Oznaczenie ręki nie blokuje bieżącego wątku, ale wraca natychmiast. Wywołuje on detektor wyników z wynikiem wykrywania za każdym razem, gdy zakończy przetwarzanie ramki wejściowej. Jeśli funkcja wykrywania zostanie wywołana, gdy zadanie Mapa witryny jest zajęte przetwarzaniem kolejnej klatki, zadanie zignoruje nową ramkę wejściową.

Pełny przykład uruchomienia mapy orientacyjnej na zdjęciu 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 komponentu wskazuje sposób wyświetlania wyników zwróconych w zadaniu. Szczegółowe informacje znajdziesz w przykładowym kodzie.