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

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 ponto de referência de mão para apps da Web e JavaScript.

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 ponteiro fornece uma implementação completa desse em JavaScript para sua referência. Esse código ajuda a testar a tarefa começou a criar seu próprio app de detecção de pontos de referência da mão. Você pode exibir, executar e editar o exemplo de código do ponto de referência da mão; usando apenas seu navegador da Web.

Configuração

Esta seção descreve as principais etapas para configurar seu ambiente de desenvolvimento especificamente para o uso do ponto de referência manual. Para informações gerais a configuração do seu ambiente de desenvolvimento da Web e JavaScript, incluindo requisitos de versão da plataforma, consulte Guia de configuração para a Web.

Pacotes JavaScript

O código do ponto de referência da mão está disponível no MediaPipe @mediapipe/tasks-vision NPM (em inglês). Você pode encontre e faça o download dessas bibliotecas seguindo as instruções na plataforma Guia de configuração.

Instale 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 uma rede de fornecimento de conteúdo (CDN) adicione o seguinte código no cabeçalho <head> no seu arquivo HTML:

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

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 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 ponto de referência de mão para preparar a tarefa para executar inferências. Usar a createFromModelPath() função com um caminho relativo ou absoluto para o arquivo de modelo treinado. Se o modelo já estiver carregado na memória, é possível usar createFromModelBuffer().

O exemplo de código abaixo demonstra o uso da função createFromOptions() para para configurar a tarefa. A função createFromOptions permite personalizar Pontos de referência manuais com opções de configuração. Para mais informações sobre configurações opções, consulte Opções de configuração.

O código a seguir demonstra como criar e configurar a tarefa com comandos opções:

const vision = await FilesetResolver.forVisionTasks(
  // path/to/wasm/root
  "https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@latest/wasm"
);
const handLandmarker = await HandLandmarker.createFromOptions(
    vision,
    {
      baseOptions: {
        modelAssetPath: "hand_landmarker.task"
      },
      numHands: 2
    });

Opções de configuração

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

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

IMAGEM: 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
numHands O número máximo de ponteiros detectados pelo detector de pontos de referência da mão. Any integer > 0 1
minHandDetectionConfidence 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
minHandPresenceConfidence A pontuação de confiança mínima para a pontuação de presença da mão modelo de detecção de pontos de referência. Nos modos "Vídeo" e "Transmissão ao vivo", 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, o ponteiro aciona o modelo de detecção de palma. Caso contrário, um algoritmo de rastreamento de mão leve determina a localização as mãos para detecções subsequentes de pontos de referência. 0.0 - 1.0 0.5
minTrackingConfidence 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 Pontos de referência de mão: se o rastreamento falhar, ele 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

Preparar dados

O ponteiro pode detectar pontos de referência da mão em imagens em qualquer formato compatível com o navegador host. A tarefa também lida com o pré-processamento de entrada de dados, incluindo redimensionamento, rotação e normalização de valores. Para detectar pontos de referência da mão em vídeos, você pode usar a API para processar rapidamente um frame por vez, usando a marcação de tempo do frame para determinar quando os pontos de referência da mão ocorrem no vídeo.

Executar a tarefa

O ponto de referência da mão usa o detect() (com o modo de corrida image) e Métodos detectForVideo() (com o modo de execução video) para acionar ou inferências. A tarefa processa os dados, tenta detectar pontos de referência da mão e e informa os resultados.

As chamadas para os métodos detect() e detectForVideo() do marco de mão são executadas. de forma síncrona e bloquear a linha de execução da interface do usuário. Se você detectar pontos de referência da mão nos frames de vídeo da câmera de um dispositivo, cada detecção bloqueia fio Para evitar isso, implemente workers da Web para executar o detect(). e detectForVideo() em outra linha de execução.

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

Imagem

const image = document.getElementById("image") as HTMLImageElement;
const handLandmarkerResult = handLandmarker.detect(image);

Vídeo

await handLandmarker.setOptions({ runningMode: "video" });

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

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

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

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

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