Guia de reconhecimento de gestos para Android

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:

1. Clone o repositório git usando o seguinte comando:

   git clone https://github.com/google-ai-edge/mediapipe-samples
   

2. 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 e GestureRecognizerResultsAdapter.
• 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.

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)
    

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)
    

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:

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.

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()
    

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()
    

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.

val result = gestureRecognizer?.recognize(mpImage)
    

val timestampMs = i * inferenceIntervalMs

gestureRecognizer?.recognizeForVideo(mpImage, timestampMs)
    ?.let { recognizerResult ->
        resultList.add(recognizerResult)
    }
    

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 e z. As coordenadas x e y são normalizadas para [0.0, 1.0] de acordo com a largura e a altura da imagem, respectivamente. A coordenada z 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 de z usa aproximadamente a mesma escala de x.

• 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 e z, 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.