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.