Guia de detecção de pontos de referência para a Web

A tarefa MediaPipe Pose Landmarker permite detectar pontos de referência de corpos humanos em uma imagem ou vídeo. Você pode usar essa tarefa para identificar os principais locais do corpo, analisar a postura e categorizar os movimentos. Esta tarefa usa modelos de aprendizado de máquina (ML) que funcionam com imagens ou vídeos únicos. A tarefa gera pontos de referência da pose do corpo em coordenadas de imagem e em coordenadas mundiais tridimensionais.

Estas instruções mostram como usar o Pose Landmarker para apps da Web e JavaScript. Para mais informações sobre os 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 Pose Landmarker fornece uma implementação completa dessa tarefa em JavaScript para sua referência. Esse código ajuda a testar essa tarefa e a começar a criar seu próprio app de marco de pose. Você pode conferir, executar e editar o exemplo de código do marco de pose usando apenas o navegador da Web.

Configuração

Esta seção descreve as principais etapas para configurar seu ambiente de desenvolvimento específicamente para usar o Pose Landmarker. Para informações gerais sobre como configurar seu ambiente de desenvolvimento da Web e do JavaScript, incluindo os requisitos da versão da plataforma, consulte o Guia de configuração para Web.

Pacotes JavaScript

O código do Landmarker de pose está disponível no pacote NPM @mediapipe/tasks-vision do MediaPipe. É possível encontrar e fazer o download dessas bibliotecas seguindo as instruções no guia de configuração da plataforma.

É possível instalar os pacotes necessários pelo NPM usando o seguinte comando:

npm install @mediapipe/tasks-vision

Se você quiser importar o código da tarefa por meio de um serviço de rede de fornecimento de conteúdo (CDN), adicione o código abaixo à tag <head> no arquivo HTML:

<!-- You can replace JSDeliver with another CDN if you prefer -->
<head>
  <script src="https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision/vision_bundle.js"
    crossorigin="anonymous"></script>
</head>

Modelo

A tarefa de detecção de pontos de referência da pose do MediaPipe requer um modelo treinado compatível com essa tarefa. Para mais informações sobre os modelos treinados disponíveis para o Pose Landmarker, consulte a seção "Modelos" da visão geral da tarefa.

Selecione e faça o download de um modelo e armazene-o no diretório do projeto:

<dev-project-root>/app/shared/models/

Criar a tarefa

Use uma das funções createFrom...() do Pose Landmarker para preparar a tarefa para executar inferências. Use a função createFromModelPath() com um caminho relativo ou absoluto para o arquivo do modelo treinado. Se o modelo já estiver carregado na memória, use o método createFromModelBuffer().

O exemplo de código abaixo demonstra o uso da função createFromOptions() para configurar a tarefa. A função createFromOptions() permite personalizar o Pose Landmarker com 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 abaixo demonstra como criar e configurar a tarefa com opções personalizadas:

const vision = await FilesetResolver.forVisionTasks(
  // path/to/wasm/root
  "https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@latest/wasm"
);
const poseLandmarker = await poseLandmarker.createFromOptions(
    vision,
    {
      baseOptions: {
        modelAssetPath: "path/to/model"
      },
      runningMode: runningMode
    });

Opções de configuração

Esta tarefa tem as seguintes opções de configuração para aplicativos da Web e JavaScript:

Nome da opção Descrição Intervalo de valor Valor padrão
runningMode Define o modo de execução da tarefa. Há dois modos:

IMAGE: o modo para entradas de imagem única.

VÍDEO: o modo para frames decodificados de um vídeo ou em uma transmissão ao vivo de dados de entrada, como de uma câmera.		 {IMAGE, VIDEO} IMAGE
numPoses O número máximo de poses que podem ser detectadas pelo Pose Landmarker. Integer > 0 1
minPoseDetectionConfidence A pontuação de confiança mínima para que a detecção de pose seja considerada bem-sucedida. Float [0.0,1.0] 0.5
minPosePresenceConfidence O valor de confiança mínimo da pontuação de presença de pose na detecção de marco de pose. Float [0.0,1.0] 0.5
minTrackingConfidence A pontuação de confiança mínima para que o rastreamento de pose seja considerado bem-sucedido. Float [0.0,1.0] 0.5
outputSegmentationMasks Indica se o Pose Landmarker vai gerar uma máscara de segmentação para a pose detectada. Boolean False

Preparar dados

O Pose Landmarker pode detectar poses em imagens em qualquer formato compatível com o navegador host. A tarefa também processa a entrada de dados, incluindo redimensionamento, rotação e normalização de valores. Para marcar poses em vídeos, use a API para processar rapidamente um frame por vez, usando o carimbo de data/hora do frame para determinar quando as poses ocorrem no vídeo.

Executar a tarefa

O Pose Landmarker usa os métodos detect() (com o modo de execução IMAGE) e detectForVideo() (com o modo de execução VIDEO) para acionar inferências. A tarefa processa os dados, tenta marcar poses e informa os resultados.

As chamadas para os métodos detect() e detectForVideo() do Pose Landmarker são executadas de forma síncrona e bloqueiam a linha de execução de intercalação do usuário. Se você detectar poses em frames de vídeo da câmera de um dispositivo, cada detecção bloqueará a linha de execução principal. Para evitar isso, implemente workers da Web para executar os métodos detect() e detectForVideo() em outra linha de execução.

O código abaixo demonstra como executar o processamento com o modelo de tarefa:

Imagem

const image = document.getElementById("image") as HTMLImageElement;
const poseLandmarkerResult = poseLandmarker.detect(image);

Vídeo

await poseLandmarker.setOptions({ runningMode: "VIDEO" });

let lastVideoTime = -1;
function renderLoop(): void {
  const video = document.getElementById("video");

  if (video.currentTime !== lastVideoTime) {
    const poseLandmarkerResult = poseLandmarker.detectForVideo(video);
    processResults(detections);
    lastVideoTime = video.currentTime;
  }

  requestAnimationFrame(() => {
    renderLoop();
  });
}

Para uma implementação mais completa da execução de uma tarefa de marcador de pose, consulte o exemplo de código.

Processar e mostrar resultados

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

Confira a seguir um exemplo dos dados de saída desta 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 do mundo (WorldLandmarks) para cada ponto de referência.

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

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

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

  • visibility: a probabilidade de o marco estar 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 de o marco estar visível na imagem.

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

Uma mulher em uma pose de meditação. A pose dela é destacada com um wireframe que indica o posicionamento dos membros e do tronco

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:

Máscara de segmentação da imagem anterior que descreve a forma da mulher

O código de exemplo do Pose Landmarker demonstra como mostrar os resultados retornados pela tarefa. Consulte o exemplo de código.