Guia de detecção de pontos de referência manuais para Python

A tarefa "Mão de referência do MediaPipe" permite detectar os pontos de referência dos ponteiros em uma imagem. Estas instruções mostram como usar o Hand Pointser com Python. A exemplo de código descrito nestas instruções está disponível em GitHub.

Para mais informações sobre recursos, modelos e opções de configuração, desta tarefa, consulte a Visão geral.

Exemplo de código

O código de exemplo para o marcador da mão fornece uma implementação completa deste em Python para sua referência. Esse código ajuda a testar a tarefa a criar seu próprio detector de pontos de referência. Você pode exibir, executar e edite o Código de exemplo do indicador de ponto de referência manual usando apenas seu navegador da Web.

Configuração

Esta seção descreve as principais etapas para configurar seu ambiente de desenvolvimento e projetos de código especificamente para usar o Hand Pointser. 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 Guia de configuração para Python.

Pacotes

A tarefa MediaPipe Hand Pointser requer o pacote PyPI do mediapipe. Você pode instalar e importar 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 marco de mão:

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

Modelo

A tarefa "Mão de referência do MediaPipe" requer um modelo treinado que seja compatível com esse tarefa. Para mais informações sobre os modelos treinados disponíveis para o ponteiro, consulte na seção de visão geral da tarefa Modelos.

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'

Use o parâmetro model_asset_path do objeto BaseOptions para especificar o caminho do modelo a ser usado. Para conferir um exemplo de código, consulte a próxima seção.

Criar a tarefa

A tarefa "Ponto de referência de mão" do MediaPipe usa a função create_from_options para para configurar a tarefa. A função create_from_options aceita valores das opções de configuração. Para mais informações sobre configurações opções, 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 transmissões ao vivo.

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

Para obter um exemplo completo de como criar um ponto de referência de mão para uso com uma imagem, consulte o exemplo de código.

Opções de configuração

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

Preparar dados

Prepare sua entrada como um arquivo de imagem ou uma matriz numpy, e depois converter em um objeto mediapipe.Image. Se a entrada for um arquivo de vídeo ou transmissão ao vivo por webcam, é possível usar uma biblioteca externa, como OpenCV para carregar os frames de entrada como numpy matrizes de dados.

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 ponteiro usa os parâmetros detect, detect_for_video e detect_async para acionar inferências. Para a detecção de pontos de referência da mão, isso envolve pré-processamento de dados de entrada, detecção das mãos na imagem e detecção da mão pontos de referência.

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

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

Observe o seguinte:

• Ao executar nos modos de vídeo ou de transmissão ao vivo, você também precisa forneça à tarefa "Mão de referência" o carimbo de data/hora do frame de entrada.
• Ao executar na imagem ou no modelo de vídeo, a tarefa do ponto de referência da mão bloquear a linha de execução atual até que ela termine de processar a imagem de entrada ou frame.
• Quando a exibição é feita no modo de transmissão ao vivo, a tarefa "Ponteiro de mão" não é bloqueada thread atual, mas retorna imediatamente. Ele vai invocar seu resultado com o resultado da detecção sempre que ele terminar o processamento um frame de entrada. Se a função de detecção for chamada quando o ponteiro estiver ocupada processando outro frame, a tarefa ignorará o novo frame de entrada.

Para ver um exemplo completo de uso de um ponteiro em uma imagem, consulte o exemplo de código para mais detalhes.

Gerenciar e exibir resultados

O ponto de referência da mão gera um objeto de resultado do ponteiro para cada detecção correr. O objeto de resultado contém pontos de referência de mão em coordenadas de imagem, mão pontos de referência em coordenadas mundiais e mão esquerda/direita do objeto detectado mãos.

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

A saída HandLandmarkerResult contém três componentes. Cada componente é uma matriz, onde cada elemento contém os seguintes resultados para uma única mão detectada:

• Mão dominante

  A mão dominante indica se as mãos detectadas são esquerdas ou direitas.

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

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)

A imagem abaixo mostra uma visualização da saída da tarefa:

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