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 com apps Android. O exemplo de código descrito nestas instruções está disponível no GitHub.
Para ver essa tarefa em ação, acesse a demonstração da Web. 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 MediaPipe Tasks é uma implementação simples de um app Reconhecedor de gestos para Android. O exemplo usa a câmera de um dispositivo Android físico para detectar gestos da mão continuamente, além de usar imagens e vídeos da galeria do dispositivo para detectar gestos estaticamente.
Use o app como ponto de partida para seu próprio app Android ou consulte-o ao modificar um app já existente. O código de exemplo do Reconhecedor de gestos está hospedado no GitHub (em inglês).
Fazer o download do código
As instruções a seguir mostram como criar uma cópia local do código de exemplo usando a ferramenta de linha de comando git.
Para fazer o download do código de exemplo:
- Clone o repositório git usando o seguinte comando:
git clone https://github.com/google-ai-edge/mediapipe-samples
- Como opção, configure sua instância git para usar a finalização da compra esparsa
para que você tenha apenas os arquivos do app de exemplo do reconhecedor de gestos:
cd mediapipe git sparse-checkout init --cone git sparse-checkout set examples/gesture_recognizer/android
.
Depois de criar uma versão local do código de exemplo, você poderá importar o projeto para o Android Studio e executar o app. Para conferir instruções, consulte o Guia de configuração para Android.
Principais componentes
Os arquivos abaixo contêm o código essencial para esse aplicativo de exemplo de reconhecimento de gestos da mão:
- GestureRecognizerHelper.kt: inicializa o reconhecedor de gestos, processa o modelo e delega a seleção.
- MainActivity.kt:
implementa o aplicativo, incluindo a chamada de
GestureRecognizerHelper
eGestureRecognizerResultsAdapter
. - GestureRecognizerResultsAdapter.kt: gerencia e formata os resultados.
Configuração
Esta seção descreve as principais etapas para configurar seu ambiente de desenvolvimento e projetos de código especificamente para usar o Reconhecedor de gestos. Para ter informações gerais sobre como configurar seu ambiente de desenvolvimento para usar tarefas do MediaPipe, incluindo requisitos de versão da plataforma, consulte o Guia de configuração para Android.
Dependências
A tarefa do reconhecedor de gestos usa a biblioteca
com.google.mediapipe:tasks-vision
. Adicione esta dependência ao arquivo build.gradle
do seu app Android:
dependencies {
implementation 'com.google.mediapipe:tasks-vision:latest.release'
}
Modelo
A tarefa do reconhecedor de gestos do MediaPipe requer um pacote de modelos treinados e 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, faça o download do modelo e armazene-o no diretório do projeto:
<dev-project-root>/src/main/assets
Especifique o caminho do modelo no parâmetro ModelAssetPath
. No
código de exemplo,
o modelo é definido no arquivo
GestureRecognizerHelper.kt
:
baseOptionBuilder.setModelAssetPath(MP_RECOGNIZER_TASK)
Criar a tarefa
A tarefa do reconhecedor de gestos do MediaPipe usa a função createFromOptions()
para
configurar a tarefa. A função createFromOptions()
aceita valores para as opções de configuração. Para mais informações sobre as opções de configuração,
consulte Opções de configuração.
O Reconhecedor de gestos oferece suporte a três tipos de dados de entrada: imagens estáticas, arquivos de vídeo e transmissões de vídeo ao vivo. Ao criar a tarefa, é necessário especificar o modo de execução correspondente ao tipo de dados de entrada. Escolha a guia correspondente ao tipo de dados de entrada para conferir como criar a tarefa e executar a inferência.
Imagem
val baseOptionsBuilder = BaseOptions.builder().setModelAssetPath(MP_RECOGNIZER_TASK) val baseOptions = baseOptionBuilder.build() val optionsBuilder = GestureRecognizer.GestureRecognizerOptions.builder() .setBaseOptions(baseOptions) .setMinHandDetectionConfidence(minHandDetectionConfidence) .setMinTrackingConfidence(minHandTrackingConfidence) .setMinHandPresenceConfidence(minHandPresenceConfidence) .setRunningMode(RunningMode.IMAGE) val options = optionsBuilder.build() gestureRecognizer = GestureRecognizer.createFromOptions(context, options)
Video
val baseOptionsBuilder = BaseOptions.builder().setModelAssetPath(MP_RECOGNIZER_TASK) val baseOptions = baseOptionBuilder.build() val optionsBuilder = GestureRecognizer.GestureRecognizerOptions.builder() .setBaseOptions(baseOptions) .setMinHandDetectionConfidence(minHandDetectionConfidence) .setMinTrackingConfidence(minHandTrackingConfidence) .setMinHandPresenceConfidence(minHandPresenceConfidence) .setRunningMode(RunningMode.VIDEO) val options = optionsBuilder.build() gestureRecognizer = GestureRecognizer.createFromOptions(context, options)
Transmissão ao vivo
val baseOptionsBuilder = BaseOptions.builder().setModelAssetPath(MP_RECOGNIZER_TASK) val baseOptions = baseOptionBuilder.build() val optionsBuilder = GestureRecognizer.GestureRecognizerOptions.builder() .setBaseOptions(baseOptions) .setMinHandDetectionConfidence(minHandDetectionConfidence) .setMinTrackingConfidence(minHandTrackingConfidence) .setMinHandPresenceConfidence(minHandPresenceConfidence) .setResultListener(this::returnLivestreamResult) .setErrorListener(this::returnLivestreamError) .setRunningMode(RunningMode.LIVE_STREAM) val options = optionsBuilder.build() gestureRecognizer = GestureRecognizer.createFromOptions(context, options)
A implementação de código de exemplo do Identificador de gestos permite que o usuário alterne entre
modos de processamento. A abordagem torna o código de criação da tarefa mais complicado e
pode não ser apropriada para seu caso de uso. É possível conferir esse código na função setupGestureRecognizer()
no arquivo GestureRecognizerHelper.kt
.
Opções de configuração
Esta tarefa tem as seguintes opções de configuração para apps Android:
Nome da opção | Descrição | Intervalo de valor | Valor padrão | |
---|---|---|---|---|
runningMode |
Define o modo de execução da tarefa. Há três
modos: IMAGE: o modo para entradas de imagem única. VIDEO: o modo para frames decodificados de um vídeo. LIVE_STREAM: é o modo para uma transmissão ao vivo de dados de entrada, como de uma câmera. Nesse modo, o resultListener precisa ser chamado para configurar um listener para receber resultados de forma assíncrona. |
{IMAGE, VIDEO, LIVE_STREAM } |
IMAGE |
|
numHands |
O número máximo de mãos pode ser detectado pelo GestureRecognizer .
|
Any integer > 0 |
1 |
|
minHandDetectionConfidence |
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 |
|
minHandPresenceConfidence |
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 |
|
minTrackingConfidence |
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 |
|
cannedGesturesClassifierOptions |
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"] |
|
|
|
customGesturesClassifierOptions |
Opções para configurar o comportamento do classificador de gestos personalizados. |
|
|
|
resultListener |
Define o listener de resultados para receber os resultados da classificação de forma assíncrona quando o reconhecedor de gestos está no modo de transmissão ao vivo.
Só pode ser usado quando o modo de corrida está definido como LIVE_STREAM |
ResultListener |
N/A | N/A |
errorListener |
Define um listener de erro opcional. | ErrorListener |
N/A | N/A |
preparar dados
O Reconhecedor de gestos funciona com imagens, arquivos de vídeo e transmissões de vídeo ao vivo. A tarefa lida com o pré-processamento da entrada de dados, incluindo redimensionamento, rotação e normalização de valores.
O código a seguir demonstra como transferir dados para processamento. Esses exemplos incluem detalhes sobre como lidar com dados de imagens, arquivos de vídeo e streams de vídeo ao vivo.
Imagem
import com.google.mediapipe.framework.image.BitmapImageBuilder import com.google.mediapipe.framework.image.MPImage // Convert the input Bitmap object to an MPImage object to run inference val mpImage = BitmapImageBuilder(image).build()
Video
import com.google.mediapipe.framework.image.BitmapImageBuilder import com.google.mediapipe.framework.image.MPImage val argb8888Frame = if (frame.config == Bitmap.Config.ARGB_8888) frame else frame.copy(Bitmap.Config.ARGB_8888, false) // Convert the input Bitmap object to an MPImage object to run inference val mpImage = BitmapImageBuilder(argb8888Frame).build()
Transmissão ao vivo
import com.google.mediapipe.framework.image.BitmapImageBuilder import com.google.mediapipe.framework.image.MPImage // Convert the input Bitmap object to an MPImage object to run inference val mpImage = BitmapImageBuilder(rotatedBitmap).build()
No
código de exemplo do Identificador de gestos, a preparação de dados é processada no
arquivo
GestureRecognizerHelper.kt
.
Executar a tarefa
O Reconhecedor de gestos usa as funções recognize
, recognizeForVideo
e recognizeAsync
para acionar inferências. Para o reconhecimento de gestos, isso envolve o pré-processamento de dados de entrada, a detecção de mãos na imagem, a detecção de pontos de referência das mãos e o reconhecimento de gestos de mão nos pontos de referência.
O código a seguir demonstra como executar o processamento com o modelo de tarefa. Esses exemplos incluem detalhes sobre como lidar com dados de imagens, arquivos de vídeo e streams de vídeo ao vivo.
Imagem
val result = gestureRecognizer?.recognize(mpImage)
Video
val timestampMs = i * inferenceIntervalMs gestureRecognizer?.recognizeForVideo(mpImage, timestampMs) ?.let { recognizerResult -> resultList.add(recognizerResult) }
Transmissão ao vivo
val mpImage = BitmapImageBuilder(rotatedBitmap).build() val frameTime = SystemClock.uptimeMillis() gestureRecognizer?.recognizeAsync(mpImage, frameTime)
Observe o seguinte:
- Ao executar no modo de vídeo ou de transmissão ao vivo, também é necessário fornecer o carimbo de data/hora do frame de entrada para a tarefa do reconhecedor de gestos.
- Quando executada no modo de imagem ou vídeo, a tarefa do reconhecedor de gestos vai bloquear a linha de execução atual até que ela termine de processar a imagem ou o frame de entrada. Para evitar o bloqueio da interface do usuário, execute o processamento em uma linha de execução em segundo plano.
- Quando executada no modo de transmissão ao vivo, a tarefa do reconhecedor de gestos não bloqueia a linha de execução atual, mas é retornada imediatamente. Ele vai invocar o listener de resultados com o resultado do reconhecimento sempre que terminar de processar um frame de entrada. Se a função de reconhecimento for chamada quando a tarefa do reconhecedor de gestos estiver ocupada processando outro frame, a tarefa vai ignorar o novo frame de entrada.
No
código de exemplo do Reconhecedor de gestos, as funções recognize
, recognizeForVideo
e
recognizeAsync
são definidas no
arquivo
GestureRecognizerHelper.kt
.
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:
No
código de exemplo do Reconhecedor de gestos, a classe GestureRecognizerResultsAdapter
no
arquivo GestureRecognizerResultsAdapter.kt
processa os resultados.