Руководство по обнаружению ориентиров рук для Python

Задача MediaPipe Hand Landmarker позволяет обнаруживать ориентиры рук на изображении. Эти инструкции покажут вам, как использовать Hand Landmarker с Python. Пример кода, описанный в этой инструкции, доступен на GitHub .

Дополнительные сведения о возможностях, моделях и параметрах конфигурации этой задачи см. в разделе Обзор .

Пример кода

Пример кода Hand Landmarker предоставляет вам полную реализацию этой задачи на Python. Этот код поможет вам протестировать эту задачу и приступить к созданию собственного детектора ориентиров. Вы можете просматривать, запускать и редактировать пример кода Hand Landmarker, используя только веб-браузер.

Если вы реализуете Hand Landmarker для Raspberry Pi, обратитесь к примеру приложения Raspberry Pi .

Настраивать

В этом разделе описаны ключевые шаги по настройке среды разработки и проектов кода специально для использования Hand Landmarker. Общие сведения о настройке среды разработки для использования задач MediaPipe, включая требования к версии платформы, см. в руководстве по настройке Python .

Пакеты

Для задачи MediaPipe Hand Landmarker требуется пакет mediapipe PyPI. Вы можете установить и импортировать эти зависимости следующим образом:

$ python -m pip install mediapipe

Импорт

Импортируйте следующие классы для доступа к функциям задачи Hand Landmarker:

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

Модель

Для задачи MediaPipe Hand Landmarker требуется обученная модель, совместимая с этой задачей. Дополнительную информацию о доступных обученных моделях для Hand Landmarker смотрите в разделе «Модели обзора задач».

Выберите и скачайте модель, а затем сохраните ее в локальном каталоге:

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

Используйте параметр model_asset_path объекта BaseOptions , чтобы указать путь к используемой модели. Пример кода см. в следующем разделе.

Создать задачу

Задача MediaPipe Hand Landmarker использует функцию create_from_options для настройки задачи. Функция create_from_options принимает значения для обрабатываемых параметров конфигурации. Дополнительные сведения о параметрах конфигурации см. в разделе Параметры конфигурации .

Следующий код демонстрирует, как создать и настроить эту задачу.

В этих примерах также показаны варианты построения задач для изображений, видеофайлов и прямой трансляции.

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.
  # ...
    

Полный пример создания Hand Landmarker для использования с изображением см. в примере кода .

Варианты конфигурации

Эта задача имеет следующие параметры конфигурации для приложений Python:

Подготовьте данные

Подготовьте входные данные в виде файла изображения или массива numpy, а затем преобразуйте их в объект mediapipe.Image . Если ваши входные данные представляют собой видеофайл или прямую трансляцию с веб-камеры, вы можете использовать внешнюю библиотеку, такую ​​как OpenCV, для загрузки входных кадров в виде числовых массивов.

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)
    

Запустить задачу

Hand Landmarker использует функции обнаружения, обнаружения_для_видео и обнаружения_async для инициирования выводов. Для обнаружения ориентиров рук это включает предварительную обработку входных данных, обнаружение рук на изображении и обнаружение ориентиров рук.

Следующий код демонстрирует, как выполнить обработку с помощью модели задачи.

# 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)
    

Обратите внимание на следующее:

• При работе в режиме видео или в режиме прямой трансляции вы также должны предоставить задаче Hand Landmarker временную метку входного кадра.
• При запуске изображения или видеомодели задача Hand Landmarker блокирует текущий поток до тех пор, пока он не завершит обработку входного изображения или кадра.
• При работе в режиме прямой трансляции задача Hand Landmarker не блокирует текущий поток, а немедленно возвращается. Он будет вызывать свой прослушиватель результатов с результатом обнаружения каждый раз, когда завершает обработку входного кадра. Если функция обнаружения вызывается, когда задача Hand Landmarker занята обработкой другого кадра, задача будет игнорировать новый входной кадр.

Полный пример использования Hand Landmarker на изображении см. в примере кода .

Обработка и отображение результатов

Hand Landmarker генерирует объект результата ручного ориентира для каждого запуска обнаружения. Объект результата содержит ориентиры рук в координатах изображения, ориентиры рук в мировых координатах и ​​направление руки (левая/правая) обнаруженных рук.

Ниже показан пример выходных данных этой задачи:

Выходные данные HandLandmarkerResult содержат три компонента. Каждый компонент представляет собой массив, где каждый элемент содержит следующие результаты для одной обнаруженной руки:

• Рукава

  Handedness показывает, являются ли обнаруженные руки левыми или правыми.

• Достопримечательности

  Имеется 21 ручной ориентир, каждый из которых состоит из координат x , y и z . Координаты x и y нормализуются на [0,0, 1,0] по ширине и высоте изображения соответственно. Координата z представляет глубину ориентира, при этом глубина на запястье является началом координат. Чем меньше значение, тем ближе ориентир к камере. Величина z использует примерно тот же масштаб, что и x .

• Достопримечательности мира

  21 ориентир также представлен в мировых координатах. Каждый ориентир состоит из x , y и z , представляющих реальные трехмерные координаты в метрах с началом координат в геометрическом центре руки.

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)

На следующем изображении показана визуализация результатов задачи:

Пример кода Hand Landmarker демонстрирует, как отображать результаты, возвращаемые задачей, подробности см. в примере кода .