A tarefa MediaPipe Hand Landmarker permite detectar os pontos de referência das mãos em uma imagem.
Use esta tarefa para localizar os pontos-chave das mãos e renderizar efeitos visuais nelas. Essa tarefa opera em dados de imagem com um modelo de aprendizado de máquina (ML) como
dados estáticos ou um fluxo contínuo e gera pontos de referência da mão em coordenadas
de imagem, pontos de referência da mão em coordenadas do mundo e lateralidade(mão esquerda/direita)
de várias mãos detectadas.
Para começar a usar essa tarefa, siga um destes guias de implementação para sua
plataforma de destino. Estes guias específicos para plataformas orientam você em uma implementação
básica desta tarefa, incluindo um modelo recomendado e um exemplo de código
com opções de configuração recomendadas:
Esta seção descreve os recursos, entradas, saídas e opções de configuração
desta tarefa.
Recursos
Processamento de imagem de entrada: o processamento inclui rotação, redimensionamento,
normalização e conversão de espaço de cores.
Limite de pontuação: filtre os resultados com base nas pontuações de previsão.
Entradas da tarefa
Saídas de tarefas
O Hand Landmarker aceita uma entrada de um dos seguintes tipos de dados:
Imagens estáticas
Frames de vídeo decodificados
Feed de vídeo ao vivo
O Hand Landmarker gera os seguintes resultados:
Mão dominante das mãos detectadas
Pontos de referência das mãos detectadas nas coordenadas da imagem
Pontos de referência de mãos detectadas em coordenadas mundiais
Opções de configuração
Esta tarefa tem as seguintes opções de configuração:
Nome da opção
Descrição
Intervalo de valor
Valor padrão
running_mode
Define o modo de execução da tarefa. Há três
modos:
IMAGE: o modo para entradas de imagem única.
VÍDEO: o modo para quadros decodificados de um vídeo.
LIVE_STREAM: o modo de 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
num_hands
O número máximo de mãos detectadas pelo detector de pontos de referência da mão.
Any integer > 0
1
min_hand_detection_confidence
A pontuação de confiança mínima para que a detecção de mão seja
considerada bem-sucedida no modelo de detecção de palma.
0.0 - 1.0
0.5
min_hand_presence_confidence
A pontuação de confiança mínima para a pontuação de presença de mão no modelo
de detecção de ponto de referência da mão. No modo de vídeo e na 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 Landmarker vai acionar o modelo de detecção de palma. Caso contrário, um
algoritmo de rastreamento de mão leve determina a localização da
mão para detecções de marco subsequentes.
0.0 - 1.0
0.5
min_tracking_confidence
A pontuação de confiança mínima para que o rastreamento de mãos seja considerado
bem-sucedido. Esse é o limite de IoU da caixa delimitadora entre as mãos no
frame atual e no último. No modo de vídeo e no modo de transmissão do
Hand Landmarker, se o rastreamento falhar, o Hand Landmarker aciona a detecção
da mão. Caso contrário, a detecção de mãos é ignorada.
0.0 - 1.0
0.5
result_callback
Define o listener de resultado para receber os resultados de detecção
de forma assíncrona quando o marcador de mão está no modo de transmissão ao vivo.
Aplicável apenas quando o modo de execução está definido como LIVE_STREAM
N/A
N/A
Modelos
O Hand Landmarker usa um pacote de modelos com dois modelos empacotados: um de detecção de palma
e um de detecção de pontos de referência da mão. Você precisa de um pacote de modelos que
contenha esses dois modelos para executar essa tarefa.
O pacote de modelo de marco da mão detecta a localização do ponto principal de 21
coordenadas de juntas da mão nas regiões da mão detectadas. O modelo foi treinado
em aproximadamente 30 mil imagens do mundo real, além de vários modelos de mãos sintéticas
renderizados sobre vários planos de fundo.
O pacote de modelo de ponto de referência da mão contém um modelo de detecção de palma e um modelo
de detecção de pontos de referência da mão. O modelo de detecção de palmas localiza as mãos na
imagem de entrada, e o modelo de detecção de pontos de referência da mão identifica pontos de referência específicos
da mão na imagem cortada da mão definida pelo modelo de detecção de palmas.
Como a execução do modelo de detecção de palmas é demorada, no modo de execução de vídeo ou
transmissão ao vivo, o Hand Landmarker usa a caixa delimitadora definida pelo modelo
de pontos de referência da mão em um frame para localizar a região das mãos em frames
posteriores. O Hand Landmarker só vai acionar novamente o modelo de detecção de palmas se o modelo
de pontos de referência da mão não identificar mais a presença de mãos ou não conseguir rastrear
as mãos no frame. Isso reduz o número de vezes que o Hand Landmarker aciona
o modelo de detecção de palma.
Comparações de mercado de tarefas
Confira os comparativos de mercado da tarefa para todo o pipeline com base nos modelos pré-treinados
acima. O resultado da latência é a latência média no Pixel 6 usando CPU / GPU.
[[["Fácil de entender","easyToUnderstand","thumb-up"],["Meu problema foi resolvido","solvedMyProblem","thumb-up"],["Outro","otherUp","thumb-up"]],[["Não contém as informações de que eu preciso","missingTheInformationINeed","thumb-down"],["Muito complicado / etapas demais","tooComplicatedTooManySteps","thumb-down"],["Desatualizado","outOfDate","thumb-down"],["Problema na tradução","translationIssue","thumb-down"],["Problema com as amostras / o código","samplesCodeIssue","thumb-down"],["Outro","otherDown","thumb-down"]],["Última atualização 2025-01-13 UTC."],[],[],null,["# Hand landmarks detection guide\n\nThe MediaPipe Hand Landmarker task lets you detect the landmarks of the hands in an image.\nYou can use this task to locate key points of hands and render visual effects on\nthem. This task operates on image data with a machine learning (ML) model as\nstatic data or a continuous stream and outputs hand landmarks in image\ncoordinates, hand landmarks in world coordinates and handedness(left/right hand)\nof multiple detected hands.\n\n[Try it!arrow_forward](https://mediapipe-studio.webapps.google.com/demo/hand_landmarker)\n\nGet Started\n-----------\n\nStart using this task by following one of these implementation guides for your\ntarget platform. These platform-specific guides walk you through a basic\nimplementation of this task, including a recommended model, and code example\nwith recommended configuration options:\n\n- **Android** - [Code\n example](https://github.com/google-ai-edge/mediapipe-samples/tree/main/examples/hand_landmarker/android)\n - [Guide](./android)\n- **Python** - [Code\n example](https://colab.research.google.com/github/googlesamples/mediapipe/blob/main/examples/hand_landmarker/python/hand_landmarker.ipynb)\n - [Guide](./python)\n- **Web** - [Code example](https://codepen.io/mediapipe-preview/pen/gOKBGPN) - [Guide](./web_js)\n\nTask details\n------------\n\nThis section describes the capabilities, inputs, outputs, and configuration\noptions of this task.\n\n### Features\n\n- **Input image processing** - Processing includes image rotation, resizing, normalization, and color space conversion.\n- **Score threshold** - Filter results based on prediction scores.\n\n| Task inputs | Task outputs |\n|----------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| The Hand Landmarker accepts an input of one of the following data types: - Still images \u003c!-- --\u003e - Decoded video frames \u003c!-- --\u003e - Live video feed | The Hand Landmarker outputs the following results: - Handedness of detected hands \u003c!-- --\u003e - Landmarks of detected hands in image coordinates \u003c!-- --\u003e - Landmarks of detected hands in world coordinates |\n\n### Configurations options\n\nThis task has the following configuration options:\n\n| Option Name | Description | Value Range | Default Value |\n|---------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------|---------------|\n| `running_mode` | Sets the running mode for the task. There are three modes: \u003cbr /\u003e IMAGE: The mode for single image inputs. \u003cbr /\u003e VIDEO: The mode for decoded frames of a video. \u003cbr /\u003e LIVE_STREAM: The mode for a livestream of input data, such as from a camera. In this mode, resultListener must be called to set up a listener to receive results asynchronously. | {`IMAGE, VIDEO, LIVE_STREAM`} | `IMAGE` |\n| `num_hands` | The maximum number of hands detected by the Hand landmark detector. | `Any integer \u003e 0` | `1` |\n| `min_hand_detection_confidence` | The minimum confidence score for the hand detection to be considered successful in palm detection model. | `0.0 - 1.0` | `0.5` |\n| `min_hand_presence_confidence` | The minimum confidence score for the hand presence score in the hand landmark detection model. In Video mode and Live stream mode, if the hand presence confidence score from the hand landmark model is below this threshold, Hand Landmarker triggers the palm detection model. Otherwise, a lightweight hand tracking algorithm determines the location of the hand(s) for subsequent landmark detections. | `0.0 - 1.0` | `0.5` |\n| `min_tracking_confidence` | The minimum confidence score for the hand tracking to be considered successful. This is the bounding box IoU threshold between hands in the current frame and the last frame. In Video mode and Stream mode of Hand Landmarker, if the tracking fails, Hand Landmarker triggers hand detection. Otherwise, it skips the hand detection. | `0.0 - 1.0` | `0.5` |\n| `result_callback` | Sets the result listener to receive the detection results asynchronously when the hand landmarker is in live stream mode. Only applicable when running mode is set to `LIVE_STREAM` | N/A | N/A |\n\nModels\n------\n\nThe Hand Landmarker uses a model bundle with two packaged models: a palm detection\nmodel and a hand landmarks detection model. You need a model bundle that\ncontains both these models to run this task.\n| **Attention:** This MediaPipe Solutions Preview is an early release. [Learn more](/edge/mediapipe/solutions/about#notice).\n\n| Model name | Input shape | Quantization type | Model Card | Versions |\n|----------------------------------------------------------------------------------------------------------------------------------------------|----------------------|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------|\n| [HandLandmarker (full)](https://storage.googleapis.com/mediapipe-models/hand_landmarker/hand_landmarker/float16/latest/hand_landmarker.task) | 192 x 192, 224 x 224 | float 16 | [info](https://storage.googleapis.com/mediapipe-assets/Model%20Card%20Hand%20Tracking%20(Lite_Full)%20with%20Fairness%20Oct%202021.pdf) | [Latest](https://storage.googleapis.com/mediapipe-models/hand_landmarker/hand_landmarker/float16/latest/hand_landmarker.task) |\n\nThe hand landmark model bundle detects the keypoint localization of 21\nhand-knuckle coordinates within the detected hand regions. The model was trained\non approximately 30K real-world images, as well as several rendered synthetic\nhand models imposed over various backgrounds.\n\nThe hand landmarker model bundle contains a palm detection model and a hand\nlandmarks detection model. The Palm detection model locates hands within the\ninput image, and the hand landmarks detection model identifies specific hand\nlandmarks on the cropped hand image defined by the palm detection model.\n\nSince running the palm detection model is time consuming, when in video or live\nstream running mode, Hand Landmarker uses the bounding box defined by the hand\nlandmarks model in one frame to localize the region of hands for subsequent\nframes. Hand Landmarker only re-triggers the palm detection model if the hand\nlandmarks model no longer identifies the presence of hands or fails to track the\nhands within the frame. This reduces the number of times Hand Landmarker tiggers\nthe palm detection model.\n\nTask benchmarks\n---------------\n\nHere's the task benchmarks for the whole pipeline based on the above pre-trained\nmodels. The latency result is the average latency on Pixel 6 using CPU / GPU.\n\n| Model Name | CPU Latency | GPU Latency |\n|-----------------------|-------------|-------------|\n| HandLandmarker (full) | 17.12ms | 12.27ms |"]]