Com a tarefa MediaPipe Hand Pointser, você pode detectar os pontos de referência dos mãos em uma imagem. Estas instruções mostram como usar o ponto de referência da mão com apps Android. O exemplo de código descrito nestas instruções está disponível no GitHub.
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 Hand Markdown para Android. O exemplo usa a câmera de um dispositivo Android físico para detectar continuamente pontos de referência de mãos e também pode usar imagens e vídeos da galeria de dispositivos para detectar estaticamente esses pontos.
Você pode usar o app como ponto de partida para seu próprio app Android ou se referir a ele ao modificar um app já existente. O código de exemplo do Hand Pointser 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 o processo de finalização da compra esparsa,
para que você tenha apenas os arquivos do app de exemplo Hand Markdowner:
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ê 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 a seguir contêm o código crucial para este aplicativo de exemplo de detecção de pontos de referência de ponteiro:
- HandLandmarkerHelper.kt: inicializa o detector de ponto de referência de ponteiro, manipula o modelo e delega a seleção.
- MainActivity.kt:
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 Markdowner. 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 Hand Markdown 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 MediaPipe Hand extras requer um pacote de modelos treinados e compatível com essa tarefa. Para mais informações sobre os modelos treinados disponíveis para o Hand Markdown, 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
HandLandmarkerHelper.kt
:
baseOptionBuilder.setModelAssetPath(MP_HAND_LANDMARKER_TASK)
Criar a tarefa
A tarefa do MediaPipe Hand extras 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 ponto de referência de mão oferece suporte a três tipos de dados de entrada: imagens estáticas, arquivos de vídeo e transmissão 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_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)
Video
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 Hand Markdown 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 setupHandLandmarker()
no arquivo 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. 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 ponteiros detectados pelo detector de pontos de referência de mão. | 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 para a pontuação de presença da 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, 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 Hand Markdown vai acionar o modelo de detecção de palma. Caso contrário, um algoritmo leve de rastreamento de mãos determina a localização das 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 ponteiros no frame atual e no último frame. Nos modos de vídeo e de stream do Hand Markdown, se o rastreamento falhar, o Hand Markdown vai acionar a detecção da mão. Caso contrário, a detecção da mão será ignorada. | 0.0 - 1.0 |
0.5 |
resultListener |
Define o listener de resultado para receber os resultados de detecção
de forma assíncrona quando o ponto de referência da mão está 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 Hand Markdowner 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 Hand extras, a preparação de dados é processada no
arquivo
HandLandmarkerHelper.kt
.
Executar a tarefa
Dependendo do tipo de dados com que você está trabalhando, use o
método HandLandmarker.detect...()
específico para esse tipo de dados. Use
detect()
para imagens individuais,
detectForVideo()
para frames em arquivos de vídeo e
detectAsync()
para streams de vídeo. Ao realizar detecções em um
stream de vídeo, execute as detecções em uma linha de execução separada para evitar
o bloqueio da linha de execução da interface do usuário.
Os exemplos de código a seguir mostram exemplos simples de como executar o Hand Markdown nesses modos de dados diferentes:
Imagem
val result = handLandmarker?.detect(mpImage)
Video
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 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 "hand Markdowner".
- Quando executada no modo de imagem ou vídeo, a tarefa Hand Markdown bloqueará a linha de execução atual até terminar 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 Hand Markdown não bloqueia a linha de execução atual, mas retorna imediatamente. Ele vai invocar o listener de resultados com o resultado da detecção sempre que terminar de processar um frame de entrada. Se a função de detecção for chamada quando a tarefa Hand Markdown estiver ocupada processando outro frame, a tarefa ignorará o novo frame de entrada.
No
código de exemplo do Hand Points, as funções detect
, detectForVideo
e
detectAsync
são definidas no
arquivo
HandLandmarkerHelper.kt
.
Gerenciar e mostrar resultados
O ponteiro do ponto de referência gera um objeto de resultado do ponto de referência da mão para cada execução de detecção. 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 e "handedness" (mão esquerda/direita) das mãos detectadas.
Veja a seguir um exemplo dos dados de saída dessa tarefa:
A saída HandLandmarkerResult
contém três componentes. Cada componente é uma matriz, em que cada elemento contém os seguintes resultados para um único ponteiro detectado:
Mão
A mão dominante representa se as mãos detectadas são esquerdas ou direitas.
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.
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 Hand Markdown demonstra como mostrar os
resultados retornados da tarefa. Consulte a classe
OverlayView
para saber mais.