AI Virtual Mouse Controller

Controle seu computador com gestos da mão.

Webcam → 21 landmarks → cursor do sistema. Sem hardware extra. Sem GPU.

🖐️ mover

🤏 clique

🤞 clique direito

✌️ duplo clique

✊ pausa

Site oficial →  ·  Guia de uso →  ·  Changelog →

O que é

Sistema gestual de controle de cursor com qualidade comparável a periféricos físicos. O MediaPipe identifica 21 pontos da mão em tempo real, uma state machine traduz gestos em eventos do sistema operacional (move, click, drag, scroll), e um holograma 3D opcional renderiza a mão virtual sobre o desktop.

100% local. Sem nuvem, sem telemetria, sem persistir nada da webcam.

Stack: Python 3.11+ · OpenCV · MediaPipe · PyAutoGUI · NumPy · ModernGL/PySide6 (opcional)

Instalar

Requer Python 3.11 ou 3.12 + webcam.

pip install ai-virtual-mouse-controller
avmc

Posicione a mão a ~50cm da câmera. Atalhos em runtime:

git clone https://github.com/ognistie/ai-virtual-mouse-controller.git
cd ai-virtual-mouse-controller
py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
python main.py

Atualizar

pip install --upgrade ai-virtual-mouse-controller

Conferir a versão instalada:

pip show ai-virtual-mouse-controller

Se quiser pular o cache do pip e baixar do PyPI direto:

pip install --no-cache-dir --upgrade ai-virtual-mouse-controller

Para quem instalou via clone do repo:

cd ai-virtual-mouse-controller
git pull origin main
pip install -r requirements.txt

Histórico de mudanças em CHANGELOG.md.

Gestos

Os cliques (esquerdo e direito) disparam no press — assim que os dedos se encostam — replicando o feedback de um botão físico.

Configuração

Toda a calibração vive em config.py — constantes nomeadas com docstrings explicando o quê, o porquê e o intervalo de ajuste. Principais grupos:

Ajustes em tempo de execução também ficam disponíveis no painel (tecla S) — perfis prontos: smooth, precise, responsive, stable.

Compatibilidade

Mediapipe pin: o projeto usa mediapipe < 0.10.30. Versões 0.10.30+ removeram o módulo mp.solutions.hands que sustenta o pipeline. O pyproject.toml já fixa o limite — não há nada manual pra fazer.

Como funciona

webcam → MediaPipe Hands (21 landmarks)
          ↓
     RobustHandAnchor  ← combina anatomia + estabilidade + edge extrapolation
          ↓
     GestureDetector   ← state machine: shape → event (CLICK, MOVE, DRAG…)
          ↓
     OneEuroSmoother   ← filtro adaptativo de cursor
          ↓
     CursorController  ← PyAutoGUI move o cursor real

Componentes auxiliares: HologramOverlay (renderização 3D opcional via ModernGL), RuntimeSettings (perfis e sliders), PerfTelemetry (timing p50/p99 por estágio).

Estrutura de pastas:

core/        # camera, hand_tracker, gesture_detector, hand_anchor, smoothing
services/    # orquestração do loop principal
config.py    # constantes de calibração documentadas
main.py      # entry point
tests/       # cobertura dos módulos puros (sem cv2/mediapipe)
docs/        # site estático + assets

Contribuir

Issues, PRs e feedback técnico são bem-vindos. Comece em CONTRIBUTING.md. Bugs em issues.

Workflow local rápido:

make dev        # instala deps + hooks
make check      # ruff + mypy + pytest
make test-fast  # só testes rápidos (sem GPU/integration/slow)
make test-gpu   # só testes que precisam de display/GPU real
make test-cov   # com coverage HTML

Testes marcados com gpu (overlay PySide6/ModernGL) ficam fora do pytest default — eles requerem display real e podem crashar em ambientes headless. Rode-os explicitamente com make test-gpu quando estiver mexendo no holograma.