Guia de reconhecimento de gestos para Android

A tarefa Reconhecedor de gestos do MediaPipe permite reconhecer gestos das mãos em tempo real e fornece resultados de gestos de mão reconhecidos e pontos de referência da mão do 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 saber como essa tarefa funciona, acesse o demonstração na Web. 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 do MediaPipe Tasks é uma implementação simples de um Reconhecedor de gestos para Android. O exemplo usa a câmera de um dispositivo Android físico para detectar continuamente gestos das mãos, e também pode usar imagens e vídeos do galeria de dispositivos para detectar gestos estaticamente.

Você pode usar o app como ponto de partida para seu próprio app Android ou consultá-lo ao modificar um aplicativo existente. O exemplo de código do Reconhecedor de gestos está hospedado GitHub.

Fazer o download do código

As instruções a seguir mostram como criar uma cópia local do 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 do Git para usar a finalização esparsa. então, você terá 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ê pode importar o projeto no Android Studio e executar o app. Para instruções, consulte a Guia de configuração para Android.

Principais componentes

Os arquivos a seguir contêm o código essencial para esse gesto de reconhecimento facial:

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 informações gerais a configuração do seu ambiente de desenvolvimento para usar tarefas do MediaPipe, incluindo requisitos de versão da plataforma, consulte Guia de configuração para Android.

Dependências

A tarefa Reconhecedor de gestos usa o com.google.mediapipe:tasks-vision biblioteca. Adicione esta dependência ao arquivo build.gradle do seu app Android:

dependencies {
    implementation 'com.google.mediapipe:tasks-vision:latest.release'
}

Modelo

A tarefa Reconhecedor de gestos do MediaPipe requer um pacote de modelo treinado compatível com para essa tarefa. Para mais informações sobre modelos treinados disponíveis para o Reconhecedor de gestos, consulte a seção Modelos na visão geral da tarefa.

Selecione e 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. Na exemplo de código, o modelo é definido no GestureRecognizerHelper.kt arquivo:

baseOptionBuilder.setModelAssetPath(MP_RECOGNIZER_TASK)

Criar a tarefa

A tarefa Reconhecedor de gestos do MediaPipe usa a função createFromOptions() para definir 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 streams de vídeo ao vivo. Você precisa especificar o modo de corrida correspondente o tipo de dados de entrada ao criar a tarefa. Escolha a guia correspondente ao seu tipo de dados de entrada para ver 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)
    

Vídeo

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 Reconhecedor de gestos permite que o usuário alterne entre os modos de processamento. A abordagem torna o código de criação da tarefa mais complicado podem não ser adequados para seu caso de uso. Confira esse código função setupGestureRecognizer() na 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. Existem três modos:

IMAGEM: o modo para entradas de imagem única.

VÍDEO: o modo para frames decodificados de um vídeo.

LIVE_STREAM: o modo de transmissão ao vivo da entrada dados de uma câmera, por exemplo. Neste modo, resultListener deve ser chamado para configurar um listener e receber resultados de forma assíncrona.
{IMAGE, VIDEO, LIVE_STREAM} IMAGE
numHands O número máximo de ponteiros pode ser detectado pelo o GestureRecognizer. Any integer > 0 1
minHandDetectionConfidence 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
minHandPresenceConfidence 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
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 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
cannedGesturesClassifierOptions 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
    customGesturesClassifierOptions 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
    resultListener Define o listener de resultados para receber os resultados da classificação. de forma assíncrona quando o reconhecedor de gestos estiver 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 streaming de vídeo ao vivo. A tarefa lida com o pré-processamento de entrada de dados, incluindo redimensionamento, rotação e valor. normalização.

    O código a seguir demonstra como transferir dados para processamento. Ts os exemplos incluem detalhes sobre como lidar com dados de imagens, arquivos de vídeo e streams de vídeo.

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

    Vídeo

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

    Na de exemplo do Reconhecedor de gestos, a preparação de dados é tratada GestureRecognizerHelper.kt .

    Executar a tarefa

    O Reconhecedor de gestos usa recognize, recognizeForVideo e recognizeAsync para acionar inferências. Para o reconhecimento de gestos, isso envolve pré-processamento de dados de entrada, detecção das mãos na imagem, detecção da mão pontos de referência e reconhecimento de gestos manuais de 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 transmissões de vídeo ao vivo.

    Imagem

    val result = gestureRecognizer?.recognize(mpImage)
        

    Vídeo

    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 nos modos de vídeo ou de transmissão ao vivo, você também precisa fornecer o carimbo de data/hora do frame de entrada para a tarefa Reconhecedor de gestos.
    • Quando executado na imagem ou no modo de vídeo, a tarefa Reconhecedor de gestos bloquear a linha de execução atual até que ela termine de processar a imagem de entrada ou frame. Para evitar o bloqueio da interface do usuário, execute o processamento em um linha de execução em segundo plano.
    • Quando o app é executado no modo de transmissão ao vivo, a tarefa Reconhecedor de gestos não é bloqueada thread atual, mas retorna imediatamente. Ele vai invocar seu resultado um listener com o resultado de reconhecimento sempre que ele termina de processar um frame de entrada. Se a função de reconhecimento for chamada quando o Reconhecedor de gestos estiver ocupada processando outro frame, a tarefa ignorará o novo frame de entrada.

    Na Exemplo de código do reconhecedor de gestos, recognize, recognizeForVideo e As funções recognizeAsync são definidas GestureRecognizerHelper.kt .

    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 nas imagens abaixo uma visualização da saída da tarefa:

    Na Exemplo de código do reconhecedor de gestos, a classe GestureRecognizerResultsAdapter no GestureRecognizerResultsAdapter.kt gerencia os resultados.