Guia de reconhecimento de gestos para Python

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

Para ver essa tarefa em ação, visualizando o demonstração Para mais informações sobre os recursos, modelos e opções de configuração do para realizar esta tarefa, consulte a Visão geral.

Exemplo de código

O código de exemplo para o Reconhecedor de gestos do Google oferece uma implementação completa em Python para sua referência. Esse código ajuda a testar a tarefa começou a criar seu próprio reconhecedor de gestos da mão. Você pode exibir, executar e editar o exemplo do Reconhecedor de gestos código usando apenas seu navegador da Web.

Se você estiver implementando o Reconhecedor de gestos para o Raspberry Pi, consulte a Exemplo do Raspberry Pi app.

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 a configuração do seu ambiente de desenvolvimento para usar tarefas do MediaPipe, incluindo requisitos de versão da plataforma, consulte o Guia de configuração do Python.

Pacotes

A tarefa Reconhecedor de gestos do MediaPipe requer o pacote PyPI do mediaPipe. É possível instalar e importe essas dependências com o seguinte:

$ python -m pip install mediapipe

Importações

Importe as seguintes classes para acessar as funções de tarefa do Reconhecedor de gestos:

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

Modelo

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

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

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

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

base_options = BaseOptions(model_asset_path=model_path)

Criar a tarefa

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

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

Esses exemplos também mostram as variações da construção da tarefa 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.
  # ...
    

Vídeo

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. Existem três modos:

IMAGEM: o modo para entradas de imagem única.

VÍDEO: o modo para frames decodificados de um vídeo.

LIVE_STREAM: o modo de transmissão ao vivo da entrada dados de uma câmera, por exemplo. Neste modo, resultListener deve ser chamado para configurar um listener e receber resultados de forma assíncrona.
{IMAGE, VIDEO, LIVE_STREAM} IMAGE
num_hands O número máximo de ponteiros pode ser detectado pelo o GestureRecognizer. Any integer > 0 1
min_hand_detection_confidence A pontuação de confiança mínima para que a detecção de mão seja bem-sucedido no modelo de detecção de palmas. 0.0 - 1.0 0.5
min_hand_presence_confidence A pontuação de confiança mínima da pontuação de presença da mão modelo de detecção de pontos de referência. Nos modos de vídeo e de transmissão ao vivo do Reconhecedor de gestos, se a pontuação de confiança da presença da mão do modelo de ponto de referência da mão estiver abaixo de esse limite, isso aciona o modelo de detecção de palmas. Caso contrário, um O algoritmo leve de rastreamento da mão é usado para determinar a localização as mãos para detecção posterior de 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 as mãos no do frame atual e do último. Nos modos "Vídeo" e "Transmissão" de Reconhecedor de gestos: se o rastreamento falhar, o Reconhecedor de gestos aciona a mão detecção de ameaças. 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 automáticos. Os gestos automáticos são ["None", "Closed_Fist", "Open_Palm", "Pointing_Up", "Thumb_Down", "Thumb_Up", "Victory", "ILoveYou"]
  • Localidade dos nomes de exibição: a localidade a ser usada para os nomes de exibição especificados nos metadados do modelo TFLite, se houver.
  • Máximo de resultados: o número máximo de resultados da classificação com melhor pontuação a serem retornados. Se < 0, todos os resultados disponíveis serão retornados.
  • Limite de pontuação: a pontuação abaixo da qual os resultados são rejeitados. Se definido como 0, todos os resultados disponíveis serão retornados.
  • Lista de permissões de categorias: a lista de permissões com os nomes das categorias. Se não estiver vazio, os resultados da classificação cuja categoria não estiver nesse conjunto serão filtrados. Mutuamente exclusivo com a lista de bloqueio.
  • Lista de bloqueio de categorias: a lista de bloqueio de nomes de categorias. Se não estiver vazio, os resultados da classificação cuja categoria estiver nesse conjunto serão filtrados. Mutuamente exclusivo com a lista de permissões.
    • Localidade dos nomes de exibição: any string
    • Máximo de resultados: any integer
    • Limite de pontuação: 0.0-1.0
    • Lista de permissões de categorias: vector of strings
    • Lista de bloqueio de categorias: vector of strings
    • Localidade dos nomes de exibição: "en"
    • Máximo de resultados: -1
    • Limite de pontuação: 0
    • Lista de permissões de categorias: vazia
    • Lista de bloqueio de categorias: vazia
    custom_gestures_classifier_options Opções para configurar o comportamento do classificador de gestos personalizados.
  • Localidade dos nomes de exibição: a localidade a ser usada para os nomes de exibição especificados nos metadados do modelo TFLite, se houver.
  • Máximo de resultados: o número máximo de resultados da classificação com melhor pontuação a serem retornados. Se < 0, todos os resultados disponíveis serão retornados.
  • Limite de pontuação: a pontuação abaixo da qual os resultados são rejeitados. Se definido como 0, todos os resultados disponíveis serão retornados.
  • Lista de permissões de categorias: a lista de permissões com os nomes das categorias. Se não estiver vazio, os resultados da classificação cuja categoria não estiver nesse conjunto serão filtrados. Mutuamente exclusivo com a lista de bloqueio.
  • Lista de bloqueio de categorias: a lista de bloqueio de nomes de categorias. Se não estiver vazio, os resultados da classificação cuja categoria estiver nesse conjunto serão filtrados. Mutuamente exclusivo com a lista de permissões.
    • Localidade dos nomes de exibição: any string
    • Máximo de resultados: any integer
    • Limite de pontuação: 0.0-1.0
    • Lista de permissões de categorias: vector of strings
    • Lista de bloqueio de categorias: vector of strings
    • Localidade dos nomes de exibição: "en"
    • Máximo de resultados: -1
    • Limite de pontuação: 0
    • Lista de permissões de categorias: vazia
    • Lista de bloqueio de categorias: vazia
    result_callback Define o listener de resultados para receber os resultados da classificação. de forma assíncrona quando o reconhecedor de gestos estiver 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, em seguida, converta-a em um mediapipe.Image. Se sua entrada for um arquivo de vídeo ou uma transmissão ao vivo de um webcam, você pode usar uma biblioteca externa, como OpenCV para carregar os frames de entrada como numpy matrizes de dados.

    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)
        

    Vídeo

    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 "recognize_async" para acionar inferências. Para o reconhecimento de gestos, isso envolve pré-processamento de dados de entrada, detecção das mãos na imagem, detecção da mão pontos de referência e reconhecimento de gestos manuais de 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)
        

    Vídeo

    # 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 nos modos de vídeo ou de transmissão ao vivo, você também precisa forneça à tarefa Reconhecedor de gestos o carimbo de data/hora do frame de entrada.
    • Ao ser executada na imagem ou no modelo de vídeo, a tarefa Reconhecedor de gestos bloquear a linha de execução atual até que ela termine de processar a imagem de entrada ou frame.
    • Quando o app é executado no modo de transmissão ao vivo, a tarefa Reconhecedor de gestos não é bloqueada thread atual, mas retorna imediatamente. Ele vai invocar seu resultado um listener com o resultado de reconhecimento sempre que ele termina de processar um frame de entrada. Se a função de reconhecimento for chamada quando o Reconhecedor de gestos estiver ocupada processando outro frame, a tarefa ignorará a nova entrada frame.

    Para ver um exemplo completo da execução de um Reconhecedor de gestos em uma imagem, consulte o código exemplo para mais detalhes.

    Gerenciar e exibir resultados

    O Reconhecedor de gestos gera um objeto de resultado da detecção de gestos para cada a execução de reconhecimento de voz. O objeto do resultado contém pontos de referência de mão em coordenadas de imagem, pontos de referência à mão em coordenadas mundiais, mão esquerda/direita e mão categorias de gestos das mãos detectadas.

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

    A 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 mão dominante indica se as mãos detectadas são esquerdas ou direitas.

    • Gestos

      As categorias de gestos reconhecidos das mãos detectadas.

    • Pontos de referência

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

    • Marcos Mundiais

      Os pontos de referência de 21 mãos 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)
    

    Confira nas imagens abaixo uma visualização da saída da tarefa:

    O código de exemplo do Reconhecedor de gestos demonstra como exibir o reconhecimento resultados retornados da tarefa, consulte o código exemplo para mais detalhes.