AI Virtual Mouse Controller

Controle seu computador com gestos da mão.

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

AI-powered virtual mouse controller for Windows, macOS, and Linux. Control the mouse cursor, left and right clicks, drag-and-drop, and presentations with real-time hand gestures captured by a standard webcam. Built with Python, OpenCV, MediaPipe Hands, and PyAutoGUI; runs locally without sending camera images to the cloud.

🖐️ mover

🤏 clique

🤞 clique direito

✌️ duplo clique

✊ pausa

Site oficial →  ·  Guia de uso →  ·  Changelog →

O que é

O AI Virtual Mouse Controller é um mouse virtual com reconhecimento de gestos pela webcam. 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.10+ · OpenCV · MediaPipe · PyAutoGUI · NumPy · PySide6 (holograma 3D via OpenGL do Qt)

Instalar

Requer Python 3.10 ou mais novo (testado de 3.10 a 3.14) + webcam.

pip install ai-virtual-mouse-controller
avmc

Windows — "avmc não é reconhecido"? O instalador novo do Python (padrão no 3.14) não põe a pasta Scripts no PATH. Rode uma vez:

py -m avmc

O AVMC abre e adiciona essa pasta ao PATH do seu usuário (sem admin). A partir daí, num terminal novo, avmc funciona. Pra não mexer no PATH, defina AVMC_NO_PATH_SETUP=1.

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

Vindo da 1.1.2 ou anterior? O projeto trocou opencv-python por opencv-contrib-python (mesmo cv2, usado pelo MediaPipe). Remova o antigo pra os dois não disputarem a mesma pasta:

pip uninstall -y opencv-python
pip install --force-reinstall --no-deps "opencv-contrib-python>=4.10,<5"

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: o rastreamento usa a Tasks API (HandLandmarker), disponível em mediapipe >= 0.10.18. O modelo (core/models/hand_landmarker.task) vem dentro do pacote — roda offline, sem download extra.

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 (mão 3D estilo headset VR: hand_pose → hand_mesh → shader OpenGL do Qt, com fallback 2D QPainter), 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
scripts/     # eval_motion.py: mede jitter/atraso/cliques com mãos sintéticas
tests/       # unitários + gate de qualidade de movimento
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/OpenGL) 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.