Guia de reconhecimento de gestos para Web

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

Para saber como essa tarefa funciona, acesse o demonstração. 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 Reconhecedor de gestos do Google oferece uma implementação completa em JavaScript para sua referência. Esse código ajuda a testar a tarefa começou a criar seu próprio app de reconhecimento de gestos. Você pode exibir, executar e editar o exemplo de código do Reconhecedor de gestos usando apenas seu 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 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 reconhecedor de gestos está disponível pelo @mediapipe/tasks-vision do MediaPipe. 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 na tag <head> do 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 Reconhecedor de gestos do MediaPipe requer um modelo treinado que seja compatível com esse tarefa. Para mais informações sobre modelos treinados disponíveis para o Reconhecedor de gestos, consulte na seção de visão geral da tarefa Modelos.

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. 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 Reconhecedor de gestos 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:

// 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. 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`
`num_hands`	O número máximo de ponteiros pode ser detectado pelo o `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 bem-sucedido no modelo de detecção de palmas.	`0.0 - 1.0`	`0.5`
`min_hand_presence_confidence`	A pontuação de confiança mínima da pontuação de presença da mão modelo de detecção de pontos de referência. Nos modos de vídeo e de transmissão ao vivo do Reconhecedor de gestos, 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, isso aciona o modelo de detecção de palmas. Caso contrário, um O algoritmo leve de rastreamento da mão é usado para determinar a localização as mãos para detecção posterior de 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 as mãos no do frame atual e do último. Nos modos "Vídeo" e "Transmissão" de Reconhecedor de gestos: se o rastreamento falhar, o Reconhecedor de gestos 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`
`canned_gestures_classifier_options`	Opções para configurar o comportamento do classificador de gestos automáticos. 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 nos metadados do modelo TFLite, se houver. Máximo de resultados: o número máximo de resultados da classificação com 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 com os nomes das categorias. Se não estiver vazio, os resultados da classificação cuja categoria não estiver nesse conjunto serão filtrados. Mutuamente exclusivo com a lista de bloqueio. Lista de bloqueio de categorias: a lista de bloqueio de nomes de categorias. Se não estiver vazio, os resultados da classificação cuja categoria estiver nesse conjunto serão filtrados. Mutuamente exclusivo com a lista de permissões.	Localidade 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 de categorias: `vector of strings` Lista de bloqueio de categorias: `vector of strings`	Localidade dos nomes de exibição: `"en"` Máximo de resultados: `-1` Limite de pontuação: `0` Lista de permissões de categorias: 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 nos metadados do modelo TFLite, se houver. Máximo de resultados: o número máximo de resultados da classificação com 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 com os nomes das categorias. Se não estiver vazio, os resultados da classificação cuja categoria não estiver nesse conjunto serão filtrados. Mutuamente exclusivo com a lista de bloqueio. Lista de bloqueio de categorias: a lista de bloqueio de nomes de categorias. Se não estiver vazio, os resultados da classificação cuja categoria estiver nesse conjunto serão filtrados. Mutuamente exclusivo com a lista de permissões.	Localidade 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 de categorias: `vector of strings` Lista de bloqueio de categorias: `vector of strings`	Localidade dos nomes de exibição: `"en"` Máximo de resultados: `-1` Limite de pontuação: `0` Lista de permissões de categorias: vazia Lista de bloqueio de categorias: vazia

Preparar dados

O Reconhecedor de gestos pode reconhecer gestos em imagens em qualquer formato com suporte do 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 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 o recognize() (com o modo de execução 'image') e Métodos recognizeForVideo() (com o modo de execução 'video') para acionar ou inferências. A tarefa processa os dados e tenta reconhecer a mão gestos e, em seguida, relata os resultados.

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

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 reconhecedor de gestos são executadas de forma síncrona e bloquear a linha de execução da interface do usuário. Se você reconhecer gestos quadros de vídeo da câmera de um dispositivo, cada reconhecimento bloqueará a parte principal fio Você pode evitar isso implementando workers da Web para executar o Métodos recognize() e recognizeForVideo() em outra linha de execução.

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

Gerenciar e exibir resultados

O Reconhecedor de gestos gera um objeto de resultado da detecção de gestos para cada a execução de reconhecimento de voz. O objeto do resultado contém pontos de referência de mão em coordenadas de imagem, pontos de referência à mão em coordenadas mundiais, mão esquerda/direita e mão categorias de gestos das mãos detectadas.

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

A 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 mão dominante indica se as mãos detectadas são esquerdas ou direitas.
Gestos

As categorias de gestos reconhecidos das mãos detectadas.
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.

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)

Confira a seguir uma visualização da saída da tarefa:

Para ver uma implementação mais completa da criação de uma tarefa de Reconhecedor de gestos, consulte a exemplo de código.