A tarefa do reconhecedor de gestos do MediaPipe permite reconhecer gestos da mão em tempo real e oferecer os resultados reconhecidos e os pontos de referência das mãos detectadas. Estas instruções mostram como usar o reconhecedor de gestos com aplicativos Python.
Para ver essa tarefa em ação, acesse 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 Reconhecedor de gestos fornece uma implementação completa dessa tarefa em Python para sua referência. Esse código ajuda a testar essa tarefa e começar a criar seu próprio reconhecedor de gestos de mão. É possível ver, executar e editar o exemplo de código (link em inglês) do reconhecedor de gestos usando apenas o navegador da Web.
Se você estiver implementando o reconhecedor de gestos para o Raspberry Pi, consulte o app de exemplo do Raspberry Pi (link em inglês).
Configuração
Esta seção descreve as principais etapas para configurar seu ambiente de desenvolvimento e projetos de código especificamente para usar o Reconhecedor de gestos. Para informações gerais sobre a configuração do ambiente de desenvolvimento para uso de tarefas do MediaPipe, incluindo requisitos de versão da plataforma, consulte o Guia de configuração para Python.
Pacotes
A tarefa do reconhecedor de gestos do MediaPipe 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 abaixo para acessar as funções da tarefa do reconhecedor de gestos:
import mediapipe as mp
from mediapipe.tasks import python
from mediapipe.tasks.python import vision
Modelo
A tarefa do reconhecedor de gestos do MediaPipe requer um pacote de modelos treinados e compatível com essa tarefa. Para mais informações sobre os modelos treinados disponíveis para o reconhecedor de gestos, consulte a seção Modelos de 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 Model Name, conforme mostrado abaixo:
base_options = BaseOptions(model_asset_path=model_path)
Criar a tarefa
A tarefa do reconhecedor de gestos do MediaPipe usa a função create_from_options
para configurar a
tarefa. A função create_from_options
aceita valores a serem processados pelas 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 de construção de tarefas para imagens, arquivos de vídeo e streams de vídeo ao vivo.
Imagem
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. # ...
Video
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. # ...
Transmissão ao vivo
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:
Nome da opção | Descrição | Intervalo de valor | Valor padrão | |
---|---|---|---|---|
running_mode |
Define o modo de execução da tarefa. Há três
modos: IMAGE: o modo para entradas de imagem única. VIDEO: o modo para frames decodificados de um vídeo. LIVE_STREAM: é o modo para uma transmissão ao vivo de dados de entrada, como de uma câmera. Nesse modo, o resultListener precisa ser chamado para configurar um listener para receber resultados de forma assíncrona. |
{IMAGE, VIDEO, LIVE_STREAM } |
IMAGE |
|
num_hands |
O número máximo de mãos pode ser detectado pelo GestureRecognizer .
|
Any integer > 0 |
1 |
|
min_hand_detection_confidence |
A pontuação de confiança mínima para que a detecção da mão seja considerada bem-sucedida no modelo de detecção de palma. | 0.0 - 1.0 |
0.5 |
|
min_hand_presence_confidence |
A pontuação de confiança mínima da pontuação de presença na mão no modelo de detecção de pontos de referência da mão. No modo de vídeo e no modo de transmissão ao vivo do Reconhecedor de gestos, se a pontuação de confiança de presença da mão do modelo de ponto de referência da mão estiver abaixo desse limite, o modelo de detecção de palma será acionado. Caso contrário, um algoritmo leve de rastreamento de mão será usado para determinar o local das mãos e, posteriormente, detectar pontos de referência. | 0.0 - 1.0 |
0.5 |
|
min_tracking_confidence |
A pontuação de confiança mínima para que o rastreamento da mão seja considerado bem-sucedido. Este é o limite de IoU da caixa delimitadora entre ponteiros no frame atual e no último frame. No modo de vídeo e no modo de streaming do Reconhecedor de gestos, se o rastreamento falhar, o reconhecedor de gestos acionará a detecção da mão. Caso contrário, a detecção da mão será ignorada. | 0.0 - 1.0 |
0.5 |
|
canned_gestures_classifier_options |
Opções para configurar o comportamento do classificador de gestos predefinidos. Os gestos automáticos são ["None", "Closed_Fist", "Open_Palm", "Pointing_Up", "Thumb_Down", "Thumb_Up", "Victory", "ILoveYou"] |
|
|
|
custom_gestures_classifier_options |
Opções para configurar o comportamento do classificador de gestos personalizados. |
|
|
|
result_callback |
Define o listener de resultados para receber os resultados da classificação de forma assíncrona quando o reconhecedor de gestos está no modo de transmissão ao vivo.
Só pode ser usado quando o modo de corrida está definido como LIVE_STREAM |
ResultListener |
N/A | N/A |
preparar dados
Prepare sua entrada como um arquivo de imagem ou uma matriz numpy e a converta em um
objeto mediapipe.Image
. Se a entrada for um arquivo de vídeo ou uma transmissão ao vivo de uma
webcam, você poderá usar uma biblioteca externa, como
OpenCV, para carregar os frames de entrada como matrizes
numpy.
Imagem
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)
Video
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)
Transmissão ao vivo
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 reconhecedor de gestos usa as funções "reconhecer", "reconhecer_for_video" e "reconhecer_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 das mãos e o reconhecimento de gestos de mão nos pontos de referência.
O código a seguir demonstra como executar o processamento com o modelo de tarefa.
Imagem
# 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)
Video
# 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)
Transmissão ao vivo
# 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 reconhecedor de gestos o carimbo de data/hora do frame de entrada.
- Quando executada no modelo de imagem ou vídeo, a tarefa do reconhecedor de gestos vai bloquear a linha de execução atual até que ela termine de processar a imagem ou o frame de entrada.
- Quando executada no modo de transmissão ao vivo, a tarefa do reconhecedor de gestos não bloqueia a linha de execução atual, mas é retornada imediatamente. Ele vai invocar o listener de resultados com o resultado do 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 da execução de um reconhecedor de gestos em uma imagem, consulte o exemplo de código (link em inglês) para mais detalhes.
Gerenciar e mostrar resultados
O reconhecedor de gestos 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 de mão em coordenadas de imagem, pontos de referência de mão em coordenadas mundiais, "handedness" (mão esquerda/direita) e categorias de gestos de mão das mãos detectadas.
Veja a seguir um exemplo dos dados de saída dessa tarefa:
A GestureRecognizerResult
resultante contém quatro componentes, e cada componente é uma matriz, em que cada elemento contém o resultado detectado de um único ponteiro detectado.
Mão
A mão dominante representa se as mãos detectadas são esquerdas ou direitas.
Gestos
As categorias de gestos reconhecidas das mãos detectadas.
Pontos de referência
Há 21 pontos de referência, cada um composto pelas coordenadas
x
,y
ez
. As coordenadasx
ey
são normalizadas para [0.0, 1.0] de acordo com a largura e a altura da imagem, respectivamente. A coordenadaz
representa a profundidade do ponto de referência, sendo a profundidade no pulso a origem. Quanto menor o valor, mais perto o ponto de referência estará da câmera. A magnitude dez
usa aproximadamente a mesma escala dex
.Marcos mundiais
Os pontos de referência de 21 ponteiros também são apresentados em coordenadas mundiais. Cada ponto de referência é composto por
x
,y
ez
, representando coordenadas 3D reais em metros, com a origem no centro geométrico do ponteiro.
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 Reconhecedor de gestos demonstra como mostrar os resultados de reconhecimento retornados da tarefa. Consulte o exemplo de código para mais detalhes.