Guia de reconhecimento de gestos para Web

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

Confira esta tarefa em ação na demonstração. 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 do Gesture Recognizer oferece uma implementação completa dessa tarefa em JavaScript para sua referência. Esse código ajuda a testar essa tarefa e a criar seu próprio app de reconhecimento de gestos. Você pode conferir, executar e editar o exemplo de código do Gesture Recognizer 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 Gesture Recognizer. 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 GestoRecognizer 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 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 seguinte código à 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 MediaPipe Gesture Recognizer requer um modelo treinado compatível com essa tarefa. Para mais informações sobre os modelos treinados disponíveis para o Gesture Recognizer, consulte a seção "Modelos" da 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 Gesture Recognizer 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 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. 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`
`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 de mão seja considerada bem-sucedida no modelo de detecção de palma.	`0.0 - 1.0`	`0.5`
`min_hand_presence_confidence`	O nível mínimo de confiança da pontuação de presença da mão no modelo de detecção de ponto de referência da mão. No modo de vídeo e no modo de transmissão ao vivo do Gesture Recognizer, 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 palmas será acionado. Caso contrário, um algoritmo de rastreamento de mão leve é usado para determinar a localização da mão para a detecção de pontos de referência subsequentes.	`0.0 - 1.0`	`0.5`
`min_tracking_confidence`	A pontuação de confiança mínima para que o rastreamento de mãos seja considerado bem-sucedido. Esse é o limite de IoU da caixa delimitadora entre as mãos no frame atual e no último. No modo de vídeo e no modo de transmissão do reconhecedor de gestos, se o rastreamento falhar, o reconhecedor de gestos aciona a detecção da mão. Caso contrário, a detecção de mão será ignorada.	`0.0 - 1.0`	`0.5`
`canned_gestures_classifier_options`	Opções para configurar o comportamento do classificador de gestos pré-definidos. 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. Resultados máximos: o número máximo de resultados de classificação com a maior pontuação a serem retornados. Se for < 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 categoria: a lista de permissões de nomes de categorias. Se não estiver vazio, os resultados de classificação cuja categoria não estiver neste conjunto serão filtrados. Mutuamente exclusivo com a lista de bloqueio. Lista de bloqueio de categorias: lista de nomes de categorias. Se não estiver vazio, os resultados de classificação com a categoria neste conjunto serão filtrados. Mutuamente exclusivo com a lista de permissões.	Localidade dos nomes de exibição: `any string` Resultados máximos: `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`	Localidade dos nomes de exibição: `"en"` Resultados máximos: `-1` Limite de pontuação: `0` Lista de permissões de categoria: vazia Lista de bloqueio de categorias: 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. Resultados máximos: o número máximo de resultados de classificação com a maior pontuação a serem retornados. Se for < 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 categoria: a lista de permissões de nomes de categorias. Se não estiver vazio, os resultados de classificação cuja categoria não estiver neste conjunto serão filtrados. Mutuamente exclusivo com a lista de bloqueio. Lista de bloqueio de categorias: lista de nomes de categorias. Se não estiver vazio, os resultados de classificação com a categoria neste conjunto serão filtrados. Mutuamente exclusivo com a lista de permissões.	Localidade dos nomes de exibição: `any string` Resultados máximos: `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`	Localidade dos nomes de exibição: `"en"` Resultados máximos: `-1` Limite de pontuação: `0` Lista de permissões de categoria: vazia Lista de bloqueio de categorias: vazia

Preparar dados

O Gesture Recognizer pode reconhecer gestos em imagens em qualquer formato aceito pelo navegador host. A tarefa também processa a entrada de dados, incluindo redimensionamento, rotação e normalização de valores. Para reconhecer gestos em vídeos, use 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 o modo de execução 'image') e recognizeForVideo() (com o modo de execução 'video') para acionar inferências. A tarefa processa os dados, tenta reconhecer gestos de mão e informa os resultados.

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

Imagem

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

Vídeo

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 Gesture Recognizer são executadas simultaneamente 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 vai bloquear a linha de execução principal. Para evitar isso, implemente workers da Web para executar os métodos recognize() e recognizeForVideo() em outra linha de execução.

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

Processar e mostrar resultados

O Gesture Recognizer 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 das mãos em coordenadas da imagem, pontos de referência das mãos em coordenadas mundiais, lateralidade(mão esquerda/direita) e categorias de gestos das mãos detectadas.

Confira a seguir um exemplo dos dados de saída desta tarefa:

O GestureRecognizerResult resultante contém quatro componentes, e cada componente é uma matriz, em que cada elemento contém o resultado detectado de uma única mão detectada.

Mão dominante

A dominância da mão representa se as mãos detectadas são esquerda ou direita.
Gestos

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

Há 21 pontos de referência da mão, cada um composto por coordenadas x, y e z. As coordenadas x e y são normalizadas para [0,0, 1,0] pela largura e altura da imagem, respectivamente. A coordenada z representa a profundidade do ponto de referência, com a profundidade no pulso sendo a origem. Quanto menor o valor, mais próximo o ponto de referência está da câmera. A magnitude de z usa aproximadamente a mesma escala de x.
Pontos turísticos do mundo

Os 21 pontos de referência da mão 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.

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:

Uma mão em um movimento de polegar para cima com a estrutura esquelética da mão mapeada

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