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 Hand Markdown em apps da Web e JavaScript.
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 Hand Markdown oferece uma implementação completa dessa tarefa em JavaScript para sua referência. Esse código ajuda você a testar essa tarefa e começar a criar seu próprio app de detecção de pontos de referência em mãos. É possível ver, executar e editar o exemplo de código do Hand Markdown usando apenas seu navegador da Web.
Configuração
Esta seção descreve as principais etapas para configurar seu ambiente de desenvolvimento especificamente para usar o Hand Pointser. Para informações gerais sobre a configuração do ambiente de desenvolvimento Web e JavaScript, incluindo requisitos da versão da plataforma, consulte o Guia de configuração para Web.
Pacotes JavaScript
O código do Hand Markdown está disponível no pacote @mediapipe/tasks-vision
NPM do MediaPipe. É possível
encontrar e fazer o download dessas bibliotecas seguindo as instruções no
Guia de configuração da plataforma.
É possível instalar os pacotes necessários por meio do NPM usando o seguinte comando:
npm install @mediapipe/tasks-vision
Se você quiser importar o código da tarefa por um serviço da rede de fornecimento de conteúdo (CDN), adicione o seguinte código à tag <head> no arquivo HTML:
<!-- You can replace JSDeliver with another CDN if you prefer to -->
<head>
<script src="https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision/vision_bundle.js"
crossorigin="anonymous"></script>
</head>
Modelo
A tarefa do MediaPipe Hand Pointser requer um modelo treinado compatível com ela. Para mais informações sobre os modelos treinados disponíveis para o Hand Pointser, consulte a seção Modelos de visão geral da tarefa.
Selecione e faça o download de um modelo e armazene-o no diretório do projeto:
<dev-project-root>/app/shared/models/
Criar a tarefa
Use uma das funções createFrom...() do ponto de referência manual para
preparar a tarefa para executar inferências. Use a função createFromModelPath() com um caminho relativo ou absoluto para o arquivo de modelo treinado.
Se o modelo já estiver carregado na memória, use o
método createFromModelBuffer().
O exemplo de código abaixo demonstra o uso da função createFromOptions() para configurar a tarefa. A função createFromOptions permite personalizar o
Marcador de mão com opções de configuração. Para mais informações sobre as opções
de configuração, consulte Opções de configuração.
O código abaixo demonstra como criar e configurar a tarefa com opções personalizadas:
const vision = await FilesetResolver.forVisionTasks(
// path/to/wasm/root
"https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@latest/wasm"
);
const handLandmarker = await HandLandmarker.createFromOptions(
vision,
{
baseOptions: {
modelAssetPath: "hand_landmarker.task"
},
numHands: 2
});
Opções de configuração
Essa tarefa tem as seguintes opções de configuração para aplicativos da Web e JavaScript:
| Nome da opção | Descrição | Intervalo de valor | Valor padrão |
|---|---|---|---|
runningMode |
Define o modo de execução da tarefa. Há dois
modos: IMAGE: o modo para entradas de imagem única. VIDEO: o modo para frames decodificados de um vídeo ou em uma transmissão ao vivo de dados de entrada, como de uma câmera. |
{IMAGE, VIDEO} |
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 |
preparar dados
O Handpointer pode detectar pontos de referência em imagens em qualquer formato com suporte ao navegador do host. A tarefa também lida com o pré-processamento da entrada de dados, incluindo redimensionamento, rotação e normalização de valores. Para detectar pontos de referência de ponteiro em vídeos, você pode usar a API para processar rapidamente um frame por vez usando o carimbo de data/hora do frame para determinar quando esses pontos ocorrem no vídeo.
Executar a tarefa
O ponto de referência manual usa os métodos detect() (com modo de execução image) e
detectForVideo() (com modo de execução video) para acionar
inferências. A tarefa processa os dados, tenta detectar pontos de referência em ponteiros e,
em seguida, informa os resultados.
As chamadas para os métodos detect() e detectForVideo() do Hand Markdown são executadas
de forma síncrona e bloqueiam a linha de execução da interface do usuário. Se a câmera de um dispositivo detectar pontos de referência
em frames de vídeo, cada detecção vai bloquear a linha de execução
principal. É possível evitar isso implementando workers da Web para executar os métodos detect() e detectForVideo() em outra linha de execução.
O código a seguir demonstra como executar o processamento com o modelo de tarefa:
Imagem
const image = document.getElementById("image") as HTMLImageElement;
const handLandmarkerResult = handLandmarker.detect(image);
Video
await handLandmarker.setOptions({ runningMode: "video" });
let lastVideoTime = -1;
function renderLoop(): void {
const video = document.getElementById("video");
if (video.currentTime !== lastVideoTime) {
const detections = handLandmarker.detectForVideo(video);
processResults(detections);
lastVideoTime = video.currentTime;
}
requestAnimationFrame(() => {
renderLoop();
});
}
Para uma implementação mais completa da execução de uma tarefa do Hand Markdown, consulte o exemplo de código.
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,yez. As coordenadasxeysão normalizadas para [0.0, 1.0] de acordo com a largura e a altura da imagem, respectivamente. A coordenadazrepresenta 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 dezusa 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,yez, 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 Pointser demonstra como mostrar os resultados retornados da tarefa. Consulte o exemplo de código (link em inglês).