Guia de reconhecimento de gestos para Web

A tarefa do reconhecedor de gestos do MediaPipe permite reconhecer gestos da mão em tempo real e fornecer os resultados reconhecidos e os pontos de referência das mãos detectadas. Estas instruções mostram como usar o Reconhecedor de gestos para apps da Web e JavaScript.

Para conferir essa tarefa em ação, confira a demonstração. 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 Reconhecedor de gestos 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 reconhecimento de gestos. É possível ver, executar e editar o exemplo de código do reconhecedor de gestos usando apenas o navegador da Web.

Configuração

Esta seção descreve as principais etapas para configurar seu ambiente de desenvolvimento especificamente para usar o Reconhecedor de gestos. 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 reconhecedor de gestos 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 na tag <head> no 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 do reconhecedor de gestos do MediaPipe requer um modelo treinado compatível com essa tarefa. Para mais informações sobre os modelos treinados disponíveis para o reconhecedor de gestos, consulte a seção Modelos de visão geral da tarefa.

Selecione e faça o download do 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 Reconhecedor de gestos 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 reconhecedor de gestos 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:

// Create task for image file processing:
const vision = await FilesetResolver.forVisionTasks(
  // path/to/wasm/root
  "https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@latest/wasm "
);
const gestureRecognizer = await GestureRecognizer.createFromOptions(vision, {
  baseOptions: {
    modelAssetPath: "https://storage.googleapis.com/mediapipe-tasks/gesture_recognizer/gesture_recognizer.task"
  },
  numHands: 2
});

Opções de configuração

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

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`
`num_hands`	O número máximo de mãos pode ser detectado pelo `GestureRecognizer`.	`Any integer > 0`	`1`
`min_hand_detection_confidence`	A pontuação de confiança mínima para que a detecção da mão seja considerada bem-sucedida no modelo de detecção de palma.	`0.0 - 1.0`	`0.5`
`min_hand_presence_confidence`	A pontuação de confiança mínima da pontuação de presença na mão no modelo de detecção de pontos de referência da mão. No modo de vídeo e no modo de transmissão ao vivo do Reconhecedor de gestos, se a pontuação de confiança de presença da mão do modelo de ponto de referência da mão estiver abaixo desse limite, o modelo de detecção de palma será acionado. Caso contrário, um algoritmo leve de rastreamento de mão será usado para determinar o local das mãos e, posteriormente, detectar pontos de referência.	`0.0 - 1.0`	`0.5`
`min_tracking_confidence`	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 ponteiros no frame atual e no último frame. No modo de vídeo e no modo de streaming do Reconhecedor de gestos, se o rastreamento falhar, o reconhecedor de gestos acionará a detecção da mão. Caso contrário, a detecção da mão será ignorada.	`0.0 - 1.0`	`0.5`
`canned_gestures_classifier_options`	Opções para configurar o comportamento do classificador de gestos predefinidos. Os gestos automáticos são `["None", "Closed_Fist", "Open_Palm", "Pointing_Up", "Thumb_Down", "Thumb_Up", "Victory", "ILoveYou"]` Localidade dos nomes de exibição: a localidade a ser usada para os nomes de exibição especificados pelos metadados do modelo TFLite, se houver. Máximo de resultados: o número máximo dos resultados de classificação com a melhor pontuação a serem retornados. Se < 0, todos os resultados disponíveis serão retornados. Limite de pontuação: a pontuação abaixo da qual os resultados são rejeitados. Se definido como 0, todos os resultados disponíveis serão retornados. Lista de permissões de categorias: a lista de permissões de nomes de categorias. Se não estiver em branco, os resultados de classificação em que a categoria não estiver nesse conjunto serão filtrados. Mutuamente exclusivo com a lista de bloqueio. Lista de bloqueio da categoria: a lista de bloqueio de nomes de categorias. Se não estiver em branco, os resultados de classificação relacionados à categoria nesse conjunto serão filtrados. Mutuamente exclusivo com lista de permissões.	Local dos nomes de exibição: `any string` Máximo de resultados: `any integer` Limite de pontuação: `0.0-1.0` Lista de permissões da categoria: `vector of strings` Lista de bloqueio da categoria: `vector of strings`	Local dos nomes de exibição: `"en"` Máximo de resultados: `-1` Limite de pontuação: `0` Lista de permissões de categoria: vazia Lista de bloqueio da categoria: vazia
`custom_gestures_classifier_options`	Opções para configurar o comportamento do classificador de gestos personalizados. Localidade dos nomes de exibição: a localidade a ser usada para os nomes de exibição especificados pelos metadados do modelo TFLite, se houver. Máximo de resultados: o número máximo dos resultados de classificação com a melhor pontuação a serem retornados. Se < 0, todos os resultados disponíveis serão retornados. Limite de pontuação: a pontuação abaixo da qual os resultados são rejeitados. Se definido como 0, todos os resultados disponíveis serão retornados. Lista de permissões de categorias: a lista de permissões de nomes de categorias. Se não estiver em branco, os resultados de classificação em que a categoria não estiver nesse conjunto serão filtrados. Mutuamente exclusivo com a lista de bloqueio. Lista de bloqueio da categoria: a lista de bloqueio de nomes de categorias. Se não estiver em branco, os resultados de classificação relacionados à categoria nesse conjunto serão filtrados. Mutuamente exclusivo com lista de permissões.	Local dos nomes de exibição: `any string` Máximo de resultados: `any integer` Limite de pontuação: `0.0-1.0` Lista de permissões da categoria: `vector of strings` Lista de bloqueio da categoria: `vector of strings`	Local dos nomes de exibição: `"en"` Máximo de resultados: `-1` Limite de pontuação: `0` Lista de permissões de categoria: vazia Lista de bloqueio da categoria: vazia

preparar dados

O reconhecedor de gestos pode reconhecer gestos em imagens em qualquer formato com suporte no 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 reconhecer gestos 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 os gestos ocorrem no vídeo.

Executar a tarefa

O Reconhecedor de gestos usa os métodos recognize() (com modo de execução 'image') e recognizeForVideo() (com modo de execução 'video') para acionar inferências. A tarefa processa os dados, tenta reconhecer gestos da mão e, em seguida, informa os resultados.

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

Imagem

const image = document.getElementById("image") as HTMLImageElement;
const gestureRecognitionResult = gestureRecognizer.recognize(image);

Video

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

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

  if (video.currentTime !== lastVideoTime) {
    const gestureRecognitionResult = gestureRecognizer.recognizeForVideo(video);
    processResult(gestureRecognitionResult);
    lastVideoTime = video.currentTime;
  }

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

As chamadas para os métodos recognize() e recognizeForVideo() do Reconhecedor de gestos são executadas de forma síncrona e bloqueiam a linha de execução da interface do usuário. Se você reconhecer gestos em frames de vídeo da câmera de um dispositivo, cada reconhecimento bloqueará a linha de execução principal. Você pode evitar isso implementando workers da Web para executar os métodos recognize() e recognizeForVideo() em outra linha de execução.

Para conferir uma implementação mais completa da execução de uma tarefa do reconhecedor de gestos, consulte o exemplo de código.

Gerenciar e mostrar resultados

O reconhecedor de gestos gera um objeto de resultado de detecção de gestos para cada execução de reconhecimento. O objeto de resultado contém pontos de referência de mão em coordenadas de imagem, pontos de referência de mão em coordenadas mundiais, "handedness" (mão esquerda/direita) e categorias de gestos de mão das mãos detectadas.

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

A GestureRecognizerResult resultante contém quatro componentes, e cada componente é uma matriz, em que cada elemento contém o resultado detectado de um único ponteiro detectado.

Mão

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

As categorias de gestos reconhecidas das mãos detectadas.
Pontos de referência

Há 21 pontos de referência, cada um composto pelas coordenadas x, y e z. As coordenadas x e y são normalizadas para [0.0, 1.0] de acordo com a largura e a altura da imagem, respectivamente. A coordenada z representa a profundidade do ponto de referência, sendo a profundidade no pulso a origem. Quanto menor o valor, mais perto o ponto de referência estará da câmera. A magnitude de z usa aproximadamente a mesma escala de x.
Marcos mundiais

Os pontos de referência de 21 ponteiros também são apresentados em coordenadas mundiais. Cada ponto de referência é composto por x, y e z, representando coordenadas 3D reais em metros, com a origem no centro geométrico do ponteiro.

GestureRecognizerResult:
  Handedness:
    Categories #0:
      index        : 0
      score        : 0.98396
      categoryName : Left
  Gestures:
    Categories #0:
      score        : 0.76893
      categoryName : Thumb_Up
  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)

As imagens a seguir mostram uma visualização da saída da tarefa:

Para conferir uma implementação mais completa da criação de uma tarefa do reconhecedor de gestos, consulte o exemplo de código.