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

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.

Estas instruções mostram como usar o ponto de referência de postura para apps da Web e JavaScript. 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 JavaScript para sua referência. Esse código ajuda você a testar essa tarefa e começar a criar seu próprio app de ponto de referência de poses. É possível ver, executar e editar o exemplo de código (link em inglês) "Pose stageer" usando apenas o navegador da Web.

Configuração

Nesta seção, descrevemos as principais etapas para configurar seu ambiente de desenvolvimento especificamente para usar o Pose extras. Para informações gerais sobre a configuração do ambiente de desenvolvimento Web e JavaScript, incluindo requisitos da versão da plataforma, consulte o Guia de configuração para Web.

Pacotes JavaScript

O código do ponto de referência está disponível no pacote @mediapipe/tasks-vision NPM 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 por meio do NPM usando o seguinte comando:

npm install @mediapipe/tasks-vision

Se você quiser importar o código da tarefa por um serviço da rede de fornecimento de conteúdo (CDN), adicione o seguinte código à 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 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 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 extras" para preparar a tarefa para executar inferências. Use a função createFromModelPath() com um caminho relativo ou absoluto para o arquivo de 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 marcador de posição 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

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

VIDEO: 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 ponto de referência da postura. Integer > 0 1
minPoseDetectionConfidence A pontuação de confiança mínima para que a detecção de poses seja considerada bem-sucedida. Float [0.0,1.0] 0.5
minPosePresenceConfidence A pontuação de confiança mínima da pontuação de presença de poses na detecção de pontos de referência de poses. Float [0.0,1.0] 0.5
minTrackingConfidence A pontuação de confiança mínima para que o rastreamento de poses seja considerado bem-sucedido. Float [0.0,1.0] 0.5
outputSegmentationMasks Define se o "Pose extras" gera uma máscara de segmentação para a pose detectada. Boolean False

preparar dados

O Pose Markdown pode detectar poses em imagens em qualquer formato compatível com o navegador do host. A tarefa também lida com o pré-processamento da entrada de dados, incluindo redimensionamento, rotação e normalização de valores. Para pontos de referência de poses em vídeos, você pode usar 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 ponto de referência "Pose" usa os métodos detect() (com modo de execução IMAGE) e detectForVideo() (com modo de execução VIDEO) para acionar inferências. A tarefa processa os dados, tenta representar posições de ponto de referência e, em seguida, relata os resultados.

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

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

Imagem

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

Video

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 ver uma implementação mais completa da execução de uma tarefa "Pose Markdown", consulte o exemplo de código (link em inglês).

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 stageer" demonstra como mostrar os resultados retornados da tarefa. Consulte o exemplo de código (link em inglês).