Guia de reconhecimento de gestos para Python

A tarefa do MediaPipe Gesture Recognizer permite reconhecer gestos da mão em tempo real e fornece os resultados reconhecidos e os pontos de referência das mãos detectadas. Estas instruções mostram como usar o GestureRecognizer com aplicativos Python.

Para conferir essa tarefa em ação, assista a demonstração da Web. Para mais informações sobre os recursos, modelos e opções de configuração dessa tarefa, consulte a Visão geral.

Exemplo de código

O código de exemplo do Gesture Recognizer fornece uma implementação completa dessa tarefa em Python para sua referência. Esse código ajuda a testar essa tarefa e a criar seu próprio reconhecedor de gestos com a mão. É possível conferir, executar e editar o código de exemplo do Gesture Recognizer usando apenas o navegador da Web.

Se você estiver implementando o Gesture Recognizer para Raspberry Pi, consulte o app de exemplo do Raspberry Pi.

Configuração

Esta seção descreve as principais etapas para configurar seu ambiente de desenvolvimento e projetos de código especificamente para usar o Gesture Recognizer. Para informações gerais sobre como configurar o ambiente de desenvolvimento para usar as tarefas do MediaPipe, incluindo os requisitos da versão da plataforma, consulte o Guia de configuração para Python.

Pacotes

A tarefa do MediaPipe Gesture Recognizer requer o pacote PyPI do mediapipe. É possível instalar e importar essas dependências com o seguinte:

$ python -m pip install mediapipe

Importações

Importe as classes a seguir para acessar as funções de tarefa do Gesture Recognizer:

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

Modelo

A tarefa do MediaPipe Gesture Recognizer requer um pacote de modelo treinado compatível com essa tarefa. Para mais informações sobre os modelos treinados disponíveis para o Gesture Recognizer, consulte a seção "Modelos" da visão geral da tarefa.

Selecione e faça o download do modelo e armazene-o em um diretório local:

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

Especifique o caminho do modelo no parâmetro "Nome do modelo", conforme mostrado abaixo:

base_options = BaseOptions(model_asset_path=model_path)

Criar a tarefa

A tarefa do MediaPipe Gesture Recognizer usa a função create_from_options para configurar a tarefa. A função create_from_options aceita valores para opções de configuração. Para mais informações sobre as opções de configuração, consulte Opções de configuração.

O código a seguir demonstra como criar e configurar essa tarefa.

Esses exemplos também mostram as variações da construção de tarefas para imagens, arquivos de vídeo e transmissões de vídeo ao vivo.

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
GestureRecognizer = mp.tasks.vision.GestureRecognizer
GestureRecognizerOptions = mp.tasks.vision.GestureRecognizerOptions
VisionRunningMode = mp.tasks.vision.RunningMode

# Create a gesture recognizer instance with the image mode:
options = GestureRecognizerOptions(
    base_options=BaseOptions(model_asset_path='/path/to/model.task'),
    running_mode=VisionRunningMode.IMAGE)
with GestureRecognizer.create_from_options(options) as recognizer:
  # The detector is initialized. Use it here.
  # ...
    

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
GestureRecognizer = mp.tasks.vision.GestureRecognizer
GestureRecognizerOptions = mp.tasks.vision.GestureRecognizerOptions
VisionRunningMode = mp.tasks.vision.RunningMode

# Create a gesture recognizer instance with the video mode:
options = GestureRecognizerOptions(
    base_options=BaseOptions(model_asset_path='/path/to/model.task'),
    running_mode=VisionRunningMode.VIDEO)
with GestureRecognizer.create_from_options(options) as recognizer:
  # The detector is initialized. Use it here.
  # ...
    

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
GestureRecognizer = mp.tasks.vision.GestureRecognizer
GestureRecognizerOptions = mp.tasks.vision.GestureRecognizerOptions
GestureRecognizerResult = mp.tasks.vision.GestureRecognizerResult
VisionRunningMode = mp.tasks.vision.RunningMode

# Create a gesture recognizer instance with the live stream mode:
def print_result(result: GestureRecognizerResult, output_image: mp.Image, timestamp_ms: int):
    print('gesture recognition result: {}'.format(result))

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

Opções de configuração

Esta tarefa tem as seguintes opções de configuração para aplicativos Python:

Preparar dados

Prepare a entrada como um arquivo de imagem ou uma matriz NumPy e converta-a em um objeto mediapipe.Image. Se a entrada for um arquivo de vídeo ou uma transmissão ao vivo de uma webcam, use uma biblioteca externa, como o OpenCV, para carregar os frames de entrada como matrizes numpy.

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)
    

Executar a tarefa

O Gesture Recognizer usa as funções recognize, recognize_for_video e recognize_async para acionar inferências. Para o reconhecimento de gestos, isso envolve o pré-processamento de dados de entrada, a detecção de mãos na imagem, a detecção de pontos de referência da mão e o reconhecimento de gestos da mão a partir dos pontos de referência.

O código a seguir demonstra como executar o processamento com o modelo de tarefa.

# Perform gesture recognition on the provided single image.
# The gesture recognizer must be created with the image mode.
gesture_recognition_result = recognizer.recognize(mp_image)
    

# Perform gesture recognition on the provided single image.
# The gesture recognizer must be created with the video mode.
gesture_recognition_result = recognizer.recognize_for_video(mp_image, frame_timestamp_ms)
    

# Send live image data to perform gesture recognition.
# The results are accessible via the `result_callback` provided in
# the `GestureRecognizerOptions` object.
# The gesture recognizer must be created with the live stream mode.
recognizer.recognize_async(mp_image, frame_timestamp_ms)
    

Observe o seguinte:

• Ao executar no modo de vídeo ou de transmissão ao vivo, também é necessário fornecer à tarefa do GestureRecognizer o carimbo de data/hora do frame de entrada.
• Ao ser executada no modelo de imagem ou vídeo, a tarefa do reconhecedor de gestos bloqueia a linha de execução atual até que ela termine de processar a imagem de entrada ou o frame.
• Quando executada no modo de transmissão ao vivo, a tarefa do Gesture Recognizer não bloqueia a linha de execução atual, mas retorna imediatamente. Ele vai invocar o listener de resultado com o resultado de reconhecimento sempre que terminar de processar um frame de entrada. Se a função de reconhecimento for chamada quando a tarefa do reconhecedor de gestos estiver ocupada processando outro frame, a tarefa vai ignorar o novo frame de entrada.

Para conferir um exemplo completo de execução de um Gesture Recognizer em uma imagem, consulte o exemplo de código para mais detalhes.

Processar e mostrar resultados

O Gesture Recognizer gera um objeto de resultado de detecção de gestos para cada execução de reconhecimento. O objeto de resultado contém pontos de referência das mãos em coordenadas da imagem, pontos de referência das mãos em coordenadas mundiais, lateralidade(mão esquerda/direita) e categorias de gestos das mãos detectadas.

Confira a seguir um exemplo dos dados de saída desta tarefa:

O GestureRecognizerResult resultante contém quatro componentes, e cada componente é uma matriz, em que cada elemento contém o resultado detectado de uma única mão detectada.

• Mão dominante

  A dominância da mão representa se as mãos detectadas são esquerda ou direita.

• Gestos

  As categorias de gestos reconhecidas das mãos detectadas.

• Pontos de referência

  Há 21 pontos de referência da mão, cada um composto por coordenadas x, y e z. As coordenadas x e y são normalizadas para [0,0, 1,0] pela largura e altura da imagem, respectivamente. A coordenada z representa a profundidade do ponto de referência, com a profundidade no pulso sendo a origem. Quanto menor o valor, mais próximo o ponto de referência está da câmera. A magnitude de z usa aproximadamente a mesma escala de x.

• Pontos turísticos do mundo

  Os 21 pontos de referência da mão também são apresentados em coordenadas mundiais. Cada ponto de referência é composto por x, y e z, representando coordenadas 3D do mundo real em metros com a origem no centro geométrico da mão.

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)

As imagens a seguir mostram uma visualização da saída da tarefa:

O código de exemplo do Gesture Recognizer demonstra como mostrar os resultados de reconhecimento retornados pela tarefa. Consulte o exemplo de código para mais detalhes.