Guia de detecção de pontos de referência na mão para Android

A tarefa "Mão de referência do MediaPipe" permite detectar os pontos de referência dos ponteiros em uma imagem. Estas instruções mostram como usar o ponteiro com apps Android. A exemplo de código descrito nestas instruções está disponível em GitHub.

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 ponteiro para Android. O exemplo usa a câmera de um dispositivo Android físico para detectar continuamente pontos de referência da mão, e também pode usar imagens e vídeos do galeria de dispositivos para detectar estaticamente pontos de referência da mão.

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 Hand Pointser está hospedado em 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ê tem apenas os arquivos do app de exemplo do Hand Pointser: 
    cd mediapipe
git sparse-checkout init --cone
git sparse-checkout set examples/hand_landmarker/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 crucial para esse ponto de referência da mão. aplicativo de exemplo de detecção:

  • HandLandmarkerHelper.kt: Inicializa o detector de pontos de referência da mão e processa o modelo e o delegado
  • MainActivity.kt (link em inglês): Implementa o aplicativo, incluindo a chamada de HandLandmarkerHelper.

Configuração

Esta seção descreve as principais etapas para configurar seu ambiente de desenvolvimento e projetos de código especificamente para usar o Hand Pointser. 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 "Ponto de referência da mão" 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 "Mão de referência do MediaPipe" requer um pacote de modelo treinado que seja compatível com para essa tarefa. Para mais informações sobre os modelos treinados disponíveis para o ponteiro, 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 HandLandmarkerHelper.kt arquivo:

baseOptionBuilder.setModelAssetPath(MP_HAND_LANDMARKER_TASK)

Criar a tarefa

A tarefa "Mão de referência do MediaPipe" usa a função createFromOptions() para configurar o tarefa. A função createFromOptions() aceita valores para a configuração. . Para mais informações sobre as opções de configuração, consulte Opções de configuração.

O ponto de referência de mão é compatível com três tipos de dados de entrada: imagens estáticas, arquivos de vídeo e transmissão ao vivo. Você precisa especificar o modo de corrida correspondente 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_HAND_LANDMARKER_TASK)
val baseOptions = baseOptionBuilder.build()

val optionsBuilder =
    HandLandmarker.HandLandmarkerOptions.builder()
        .setBaseOptions(baseOptions)
        .setMinHandDetectionConfidence(minHandDetectionConfidence)
        .setMinTrackingConfidence(minHandTrackingConfidence)
        .setMinHandPresenceConfidence(minHandPresenceConfidence)
        .setNumHands(maxNumHands)
        .setRunningMode(RunningMode.IMAGE)

val options = optionsBuilder.build()

handLandmarker =
    HandLandmarker.createFromOptions(context, options)

Vídeo

val baseOptionsBuilder = BaseOptions.builder().setModelAssetPath(MP_HAND_LANDMARKER_TASK)
val baseOptions = baseOptionBuilder.build()

val optionsBuilder =
    HandLandmarker.HandLandmarkerOptions.builder()
        .setBaseOptions(baseOptions)
        .setMinHandDetectionConfidence(minHandDetectionConfidence)
        .setMinTrackingConfidence(minHandTrackingConfidence)
        .setMinHandPresenceConfidence(minHandPresenceConfidence)
        .setNumHands(maxNumHands)
        .setRunningMode(RunningMode.VIDEO)

val options = optionsBuilder.build()

handLandmarker =
    HandLandmarker.createFromOptions(context, options)

Transmissão ao vivo

val baseOptionsBuilder = BaseOptions.builder().setModelAssetPath(MP_HAND_LANDMARKER_TASK)
val baseOptions = baseOptionBuilder.build()

val optionsBuilder =
    HandLandmarker.HandLandmarkerOptions.builder()
        .setBaseOptions(baseOptions)
        .setMinHandDetectionConfidence(minHandDetectionConfidence)
        .setMinTrackingConfidence(minHandTrackingConfidence)
        .setMinHandPresenceConfidence(minHandPresenceConfidence)
        .setNumHands(maxNumHands)
        .setResultListener(this::returnLivestreamResult)
        .setErrorListener(this::returnLivestreamError)
        .setRunningMode(RunningMode.VIDEO)

val options = optionsBuilder.build()

handLandmarker =
    HandLandmarker.createFromOptions(context, options)

A implementação de código de exemplo do ponteiro 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 setupHandLandmarker() na HandLandmarkerHelper.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 detectados pelo detector de pontos de referência da mão. 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 para a pontuação de presença da mão modelo de detecção de pontos de referência. Nos modos "Vídeo" e "Transmissão ao vivo", 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, o ponteiro aciona o modelo de detecção de palma. Caso contrário, um algoritmo de rastreamento de mão leve determina a localização as mãos para detecções subsequentes 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 Pontos de referência de mão: se o rastreamento falhar, ele 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
resultListener Define o listener de resultados para receber os resultados da detecção. de forma assíncrona quando o ponto de referência da mão estiver no modo de transmissão ao vivo. Aplicável apenas quando o modo de corrida está definido como LIVE_STREAM N/A N/A
errorListener Define um listener de erro opcional. N/A N/A

Preparar dados

O ponto de referência manual 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 exemplo de código de ponto de referência da mão, a preparação dos dados é processada no HandLandmarkerHelper.kt .

Executar a tarefa

Dependendo do tipo de dados com os quais você está trabalhando, use o Método HandLandmarker.detect...() específico para esse tipo de dados. Usar detect() para imagens individuais; detectForVideo() para frames em arquivos de vídeo detectAsync() para streams de vídeo. Quando você realiza detecções stream de vídeo, execute as detecções em uma linha de execução separada para evitar bloquear a linha de execução da interface do usuário.

Os exemplos de código a seguir mostram exemplos simples de como executar o ponteiro nesses diferentes modos de dados:

Imagem

val result = handLandmarker?.detect(mpImage)

Vídeo

val timestampMs = i * inferenceIntervalMs

handLandmarker?.detectForVideo(mpImage, timestampMs)
    ?.let { detectionResult ->
        resultList.add(detectionResult)
    }

Transmissão ao vivo

val mpImage = BitmapImageBuilder(rotatedBitmap).build()
val frameTime = SystemClock.uptimeMillis()

handLandmarker?.detectAsync(mpImage, frameTime)

Observe o seguinte:

  • Ao executar nos modos de vídeo ou de transmissão ao vivo, você também precisa forneça o carimbo de data/hora do frame de entrada para a tarefa "Mão de referência".
  • Ao executar na imagem ou no modo de vídeo, a tarefa do ponto de referência da mão 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 a exibição é feita no modo de transmissão ao vivo, a tarefa "Ponteiro de mão" não é bloqueada thread atual, mas retorna imediatamente. Ele vai invocar seu resultado com o resultado da detecção sempre que ele terminar de processar um erro. frame de entrada. Se a função de detecção for chamada quando a tarefa "Mão de referência" estiver ocupado processando outro frame, a tarefa ignorará o novo frame de entrada.

Na Exemplo de código de ponto de referência da mão, detect, detectForVideo e As funções detectAsync são definidas HandLandmarkerHelper.kt .

Gerenciar e exibir resultados

O ponto de referência da mão gera um objeto de resultado do ponteiro para cada detecção correr. O objeto de resultado contém pontos de referência de mão em coordenadas de imagem, mão pontos de referência em coordenadas mundiais e mão esquerda/direita do objeto detectado mãos.

Confira abaixo um exemplo dos dados de saída desta tarefa:

A saída HandLandmarkerResult contém três componentes. Cada componente é uma matriz, onde cada elemento contém os seguintes resultados para uma única mão detectada:

  • Mão dominante

    A mão dominante indica se as mãos detectadas são esquerdas ou direitas.

  • 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.

HandLandmarkerResult:
  Handedness:
    Categories #0:
      index        : 0
      score        : 0.98396
      categoryName : Left
  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)

A imagem abaixo mostra uma visualização da saída da tarefa:

O código de exemplo do ponteiro demonstra como exibir o resultados retornados da tarefa, consulte a OverlayView para mais detalhes.