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"] |
|
|
custom_gestures_classifier_options |
Opções para configurar o comportamento do classificador de gestos personalizados. |
|
|
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
ez
. As coordenadasx
ey
são normalizadas para [0.0, 1.0] de acordo com a largura e a altura da imagem, respectivamente. A coordenadaz
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 dez
usa aproximadamente a mesma escala dex
.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
ez
, 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.