Resumo
A demo lê até duas mãos pela câmera com o MediaPipe Hand Landmarker e classifica 11 gestos por regras sobre os 21 pontos da mão. Uma votação por maioria em 5 quadros estabiliza a leitura, e a interface anuncia o gesto ao leitor de tela.
Case de projeto
- Projeto próprio
- Visão computacional no navegador
- Câmera do usuário
- Repositório público
Reconhecimento de Gestos de Mão em Tempo Real
Reconhecimento de 11 gestos de mão pela câmera, no navegador, com regras explicáveis e degradação para CPU.
Demo web que reconhece 11 gestos de mão pela câmera, no navegador, com MediaPipe, regras explicáveis e troca de GPU para CPU. Nenhum vídeo sai da máquina.
- Regras explicáveis
- Pipeline por quadro de vídeo
- Degradação para CPU
- Acessível por leitor de tela
Repositório público; referência auditada na branch main, commit abacb02.
Resumo
Problema
Interfaces por gesto costumam exigir instalação local ou enviar vídeo para um servidor, e classificadores opacos não explicam por que um gesto foi reconhecido.
Meu papel
A versão web foi escrita sobre a lógica da versão Python, com fixtures compartilhadas entre as duas.
- Gestos reconhecidos
- 11
- Repositório público / web/src/lib/gestures/analyze.ts / commit abacb02
- Testes unitários da versão web
- 25
- Repositório público / contagem de declarações em web/, CI no GitHub Actions / commit abacb02
- Testes ponta a ponta com axe
- 12
- Repositório público / contagem de declarações em web/e2e / commit abacb02
Dados e premissas
Os quadros vêm da câmera do usuário e são processados no navegador. Os testes usam cerca de 15 poses sintéticas compartilhadas entre TypeScript e Python; o reconhecimento com mão real foi conferido manualmente.
- Mãos simultâneas
- 2
- Janela de suavização
- 5 quadros
- Atualização da interface
- cerca de 10 Hz
- Modelo
- 7,8 MB, via CDN
Estrutura dos dados
Entidades modeladas
- Leitura de mão (pontos, lateralidade)
- Gesto estabilizado por mão
Pipeline de quadro
Da câmera ao gesto anunciado, em uma única página Next.js.
Captura
getUserMedia e requestVideoFrameCallback, com requestAnimationFrame como alternativa, descartando quadros repetidos.
Inferência
detectForVideo do Hand Landmarker na thread principal, em GPU com troca para CPU.
Estado
Rastreador por mão com votação por maioria em 5 quadros.
Render
Overlay dos pontos em Canvas 2D a cada quadro inferido; interface React a cerca de 10 Hz.
Sinais do pipeline
O que a demo mede e mostra durante a sessão.
| Definição | Unidade | Regra de cálculo | Uso | Limitação |
|---|---|---|---|---|
| Tempo de inferênciaDuração de cada chamada ao modelo. | ms | Diferença de performance.now() em volta de detectForVideo. | Mostrar o custo do modelo no painel de sessão. | Depende do hardware e do delegate em uso. |
| Gesto estabilizadoGesto mais frequente nos últimos 5 quadros da mão. | rótulo | Votação por maioria por mão. | Evitar trocas de gesto quadro a quadro. | Atrasa a resposta em alguns quadros. |
Tempo de inferência
Duração de cada chamada ao modelo.
- Unidade
- ms
- Regra de cálculo
- Diferença de performance.now() em volta de detectForVideo.
- Uso
- Mostrar o custo do modelo no painel de sessão.
- Limitação
- Depende do hardware e do delegate em uso.
Gesto estabilizado
Gesto mais frequente nos últimos 5 quadros da mão.
- Unidade
- rótulo
- Regra de cálculo
- Votação por maioria por mão.
- Uso
- Evitar trocas de gesto quadro a quadro.
- Limitação
- Atrasa a resposta em alguns quadros.
Decisões técnicas
Regras sobre pontos em vez de classificador treinado
- Motivo
- Cada gesto tem uma explicação legível e testável com poses sintéticas.
- Consequência / trade-off
- As regras assumem a palma voltada para a câmera.
requestVideoFrameCallback
- Motivo
- Processa só quadros de vídeo novos.
- Consequência / trade-off
- Exige alternativa por requestAnimationFrame em navegadores sem suporte.
GPU com troca para CPU
- Motivo
- A demo continua quando o delegate de GPU falha.
- Consequência / trade-off
- Na CPU, a inferência fica mais lenta.
Outras decisões técnicas
Inferência na thread principal
- Motivo
- Mantém o pipeline simples.
- Consequência / trade-off
- A inferência não é separada da taxa de quadro; um Worker ou um limite em Hz desacoplaria as duas.
Evidências
Aplicação e código verificados sem login na branch main, commit abacb02.
Aplicação pública
Demo publicada
Página inicial, demo, painel de sessão e página sobre.
Abrir evidênciaReferência de código
Regras de gesto
Padrão de dedos, pinça e OK para os 11 gestos.
Abrir evidênciaReferência de códigoweb/src/lib/gestures/analyze.ts
Referência de código
Suavização por maioria
Votação em 5 quadros por mão.
Abrir evidênciaReferência de códigoweb/src/lib/gestures/smoothing.ts
Referência de código
Pipeline da câmera
Agendamento por quadro, inferência, troca para CPU e anúncio acessível.
Abrir evidênciaReferência de códigoweb/src/components/demo/CameraDemo.tsx
Referências de implementação
Referência de código
Estados de erro
Contexto inseguro, permissão negada, câmera ocupada e falha do modelo.
Referência de códigoweb/src/lib/camera.ts
Repositório público
Repositório no commit auditado
Snapshot público usado nesta auditoria.
Abrir evidênciaMedidas verificáveis
- medido
- 26
- Testes da versão Python
- Contagem de declarações, rodados no CI.
- medido
- 15
- Poses sintéticas compartilhadas
- fixtures/gestures/hand-poses.json, usadas pelas duas versões.
- configuração
- 1,5 s
- Intervalo mínimo dos anúncios
- Limite dos anúncios para leitor de tela.
Contagens do repositório no commit auditado. Não há medida de acurácia com mão real.
Repositório público, commit abacb02.
O que o projeto demonstra
- Visão computacional no navegador, sem servidor.
- Pipeline de quadro com descarte de quadros repetidos.
- Degradação graciosa de GPU para CPU.
- Interação sem contato acessível a leitor de tela.
Limitações e próximos passos
Limitações
- Exige câmera e HTTPS; o modelo vem de um CDN.
- Não há medida de acurácia com mão real.
- A inferência roda na thread principal, acoplada à taxa de quadro.
Próximos passos
- Mover a inferência para um Worker ou limitá-la em Hz.
- Medir acurácia com um conjunto de mãos reais rotulado.
Vídeo e mídia
Telas
Capturas da demo publicada.
Detalhes técnicos opcionais
Como executar
- cd web && npm ci && npm run dev
- Versão desktop (Python 3.12): pip install -r requirements.txt e python -m hand_gestures
Próximo projeto
Receita Pública Intelligence Platform
Produto analítico web demonstrativo para explorar arrecadação sintética, metas, variações temporais e composição das receitas em uma interface executiva.
Ver case completo