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

A tarefa "MediaPipe Pose extraser" permite detectar pontos de referência de corpos humanos em uma imagem ou um vídeo. Você pode usar essa tarefa para identificar as principais localizações do corpo, analisar a postura e categorizar movimentos. Essa tarefa usa modelos de machine learning (ML) que funcionam com imagens ou vídeos únicos. A tarefa gera pontos de referência de poses corporais em coordenadas de imagem e em coordenadas mundiais tridimensionais.

O exemplo de código descrito nestas instruções está disponível no GitHub. 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 "Pose extras" fornece uma implementação completa dessa tarefa em Python para sua referência. Esse código ajuda você a testar essa tarefa e começar a criar seu próprio ponto de referência de poses. É possível ver, executar e editar o código de exemplo do Poste Markdown (em inglês) usando apenas seu navegador da Web.

Se você estiver implementando o Pose Markdown para Raspberry Pi, consulte o app de exemplo do Raspberry Pi (em inglês).

Configuração

Nesta seção, descrevemos as principais etapas para configurar seu ambiente de desenvolvimento e projetos de código para usar o Pose extras. Para informações gerais sobre a configuração do ambiente de desenvolvimento para o uso de tarefas do MediaPipe, incluindo requisitos de versão da plataforma, consulte o Guia de configuração para Python.

Pacotes

A tarefa MediaPipe Pose extras precisa do pacote PyPI do MediaPipe. Você pode instalar e importar essas dependências com o seguinte comando:

$ python -m pip install mediapipe

Importações

Importe as seguintes classes para acessar as funções da tarefa "Pose extras" (Ponto de referência):

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

Modelo

A tarefa MediaPipe Pose Pointser requer um modelo treinado compatível com ela. Para mais informações sobre os modelos treinados disponíveis para "Posse de ponto de referência", 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/pose_landmarker.task'

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

Criar a tarefa

A tarefa MediaPipe Pose extras usa a função create_from_options para configurar a tarefa. A função create_from_options aceita valores para as opções de configuração processar. Para mais informações, 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 da tarefa para imagens, arquivos de vídeo e transmissão ao vivo.

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
PoseLandmarker = mp.tasks.vision.PoseLandmarker
PoseLandmarkerOptions = mp.tasks.vision.PoseLandmarkerOptions
VisionRunningMode = mp.tasks.vision.RunningMode

options = PoseLandmarkerOptions(
    base_options=BaseOptions(model_asset_path=model_path),
    running_mode=VisionRunningMode.IMAGE)

with PoseLandmarker.create_from_options(options) as landmarker:
  # The landmarker is initialized. Use it here.
  # ...
    

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
PoseLandmarker = mp.tasks.vision.PoseLandmarker
PoseLandmarkerOptions = mp.tasks.vision.PoseLandmarkerOptions
VisionRunningMode = mp.tasks.vision.RunningMode

# Create a pose landmarker instance with the video mode:
options = PoseLandmarkerOptions(
    base_options=BaseOptions(model_asset_path=model_path),
    running_mode=VisionRunningMode.VIDEO)

with PoseLandmarker.create_from_options(options) as landmarker:
  # The landmarker is initialized. Use it here.
  # ...
    

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
PoseLandmarker = mp.tasks.vision.PoseLandmarker
PoseLandmarkerOptions = mp.tasks.vision.PoseLandmarkerOptions
PoseLandmarkerResult = mp.tasks.vision.PoseLandmarkerResult
VisionRunningMode = mp.tasks.vision.RunningMode

# Create a pose landmarker instance with the live stream mode:
def print_result(result: PoseLandmarkerResult, output_image: mp.Image, timestamp_ms: int):
    print('pose landmarker result: {}'.format(result))

options = PoseLandmarkerOptions(
    base_options=BaseOptions(model_asset_path=model_path),
    running_mode=VisionRunningMode.LIVE_STREAM,
    result_callback=print_result)

with PoseLandmarker.create_from_options(options) as landmarker:
  # The landmarker is initialized. Use it here.
  # ...
    

Para conferir um exemplo completo de como criar um ponto de referência de postura 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 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, use uma biblioteca externa, como a OpenCV (link em inglês), 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 ponto de referência "Pose" usa as funções detect, detect_for_video e detect_async para acionar inferências. Para o ponto de referência de poses, isso envolve o pré-processamento de dados de entrada e a detecção de poses na imagem.

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

# Perform pose landmarking on the provided single image.
# The pose landmarker must be created with the image mode.
pose_landmarker_result = landmarker.detect(mp_image)
    

# Perform pose landmarking on the provided single image.
# The pose landmarker must be created with the video mode.
pose_landmarker_result = landmarker.detect_for_video(mp_image, frame_timestamp_ms)
    

# Send live image data to perform pose landmarking.
# The results are accessible via the `result_callback` provided in
# the `PoseLandmarkerOptions` object.
# The pose landmarker must be created with the live stream mode.
landmarker.detect_async(mp_image, frame_timestamp_ms)
    

Observe o seguinte:

• Quando estiver em execução no modo de vídeo ou de transmissão ao vivo, forneça também à tarefa "Pose extras" o carimbo de data/hora do frame de entrada.
• Quando executada no modelo de imagem ou vídeo, a tarefa "Pose stageer" bloqueia a linha de execução atual até que ela termine de processar a imagem ou frame de entrada.
• Quando executada no modo de transmissão ao vivo, a tarefa "Posse de ponto de referência" retorna imediatamente e não bloqueia a linha de execução atual. Ele vai invocar o listener de resultados com o resultado da detecção sempre que terminar de processar um frame de entrada. Se a função de detecção for chamada quando a tarefa "Posicionar" estiver ocupada no processamento de outro frame, a tarefa ignorará o novo frame de entrada.

Para conferir um exemplo completo da execução de um ponto de referência de postura em uma imagem, consulte o exemplo de código (link em inglês) para mais detalhes.

Gerenciar e mostrar resultados

O ponto de referência de postura retorna um objeto poseLandmarkerResult para cada execução de detecção. O objeto de resultado contém coordenadas para cada ponto de referência de pose.

Veja a seguir um exemplo dos dados de saída dessa tarefa:

PoseLandmarkerResult:
  Landmarks:
    Landmark #0:
      x            : 0.638852
      y            : 0.671197
      z            : 0.129959
      visibility   : 0.9999997615814209
      presence     : 0.9999984502792358
    Landmark #1:
      x            : 0.634599
      y            : 0.536441
      z            : -0.06984
      visibility   : 0.999909
      presence     : 0.999958
    ... (33 landmarks per pose)
  WorldLandmarks:
    Landmark #0:
      x            : 0.067485
      y            : 0.031084
      z            : 0.055223
      visibility   : 0.9999997615814209
      presence     : 0.9999984502792358
    Landmark #1:
      x            : 0.063209
      y            : -0.00382
      z            : 0.020920
      visibility   : 0.999976
      presence     : 0.999998
    ... (33 world landmarks per pose)
  SegmentationMasks:
    ... (pictured below)

A saída contém coordenadas normalizadas (Landmarks) e coordenadas mundiais (WorldLandmarks) para cada ponto de referência.

A saída contém as seguintes coordenadas normalizadas (Landmarks):

• x e y: coordenadas de ponto de referência normalizadas entre 0,0 e 1,0 pela largura da imagem (x) e altura (y).

• z: a profundidade do ponto de referência, com origem no ponto médio dos quadris. Quanto menor o valor, mais próximo o ponto de referência estará da câmera. A magnitude de z usa aproximadamente a mesma escala que x.

• visibility: a probabilidade do ponto de referência ser visível na imagem.

A saída contém as seguintes coordenadas mundiais (WorldLandmarks):

• x, y e z: coordenadas tridimensionais reais em metros, com o ponto médio dos quadris como origem.

• visibility: a probabilidade do ponto de referência ser visível na imagem.

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

A máscara de segmentação opcional representa a probabilidade de cada pixel pertencer a uma pessoa detectada. A imagem a seguir é uma máscara de segmentação da saída da tarefa:

O código de exemplo "Pose extras" demonstra como mostrar os resultados retornados da tarefa. Consulte o exemplo de código para mais detalhes.