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.