AI Virtual Mouse Controller
GitHub
guia detalhado · leitura tranquila · ~15 min

Senta, pega um café,
vamos pelo começo.

Esse é o guia longo. Foi escrito pensando em quem nunca abriu um terminal na vida e quer ver o projeto funcionando hoje. Sem pular etapas, sem assumir que você já sabe nada. Se você já é técnico e quer só os comandos, dá uma olhada no manual rápido da home.

o que tem nesse guia
  1. 01O que é isso, na real?
  2. 02O que você precisa antes de começar
  3. 03Instalar o Python (versão certa)
  4. 04Instalar o Git (ou baixar ZIP)
  5. 05Baixar o projeto na sua máquina
  6. 06Criar o ambiente virtual (venv)
  7. 07Instalar as dependências
  8. 08Rodar pela primeira vez
  9. 09Aprender os gestos com calma
  10. 10Encerrar o programa direito
  11. 11Como abrir da próxima vez
  12. 12Customizar (só se você quiser)
  13. 13Ligar o holograma da mão
01 o que é isso, na real

Em uma frase, o que esse projeto faz.

Liga a sua webcam, identifica os pontos da sua mão, e usa o movimento da mão para mover o cursor do mouse. Cada gesto vira uma ação real: mover, clicar, arrastar, pausar.

§ traduzindo do termo técnico

A gente vai usar três palavras o tempo todo nesse guia. Vale memorizar agora.

Python — é uma linguagem de programação. Pra rodar esse projeto, você precisa do Python instalado no computador. É um programa, igual qualquer outro.

Terminal — é uma janela preta onde você digita comandos com o teclado, em vez de clicar em botões. Vai parecer estranho no começo. No Windows ele se chama PowerShell ou Prompt de Comando.

Repositório — é como chamamos uma pasta de código de um projeto. O nosso fica no GitHub, num endereço público. Você vai baixar uma cópia dele.

02 o que você precisa

Antes de começar, confere aí.

Lista honesta. Não precisa de hardware caro, GPU, sensor especial. Mas precisa dessas coisas.

01

Computador com Windows 10 ou 11

É a plataforma principal de teste. macOS e Linux funcionam, mas alguns comandos vão ser diferentes. Esse guia usa exemplos de Windows.

02

Webcam funcionando

Pode ser a integrada do notebook ou uma USB qualquer. 720p ou superior. Se ela aparece em chamada de vídeo do Teams ou Zoom, ela serve aqui.

03

~500 MB de espaço em disco

O projeto em si é pequeno, mas as dependências (MediaPipe, OpenCV, etc.) ocupam espaço. Garante que tem espaço sobrando antes de começar.

04

Conexão com a internet

Só para baixar o projeto e as dependências, uma vez. Depois disso funciona offline, sem chamar nenhum servidor.

05

Luz decente no ambiente

Não precisa ser estúdio. Mas evita contraluz (janela atrás de você). O modelo enxerga melhor quando a mão tá iluminada de frente.

06

30 minutos da sua atenção

Se for sua primeira vez instalando Python e usando terminal, separa esse tempo. Sem pressa. Vai dar certo.

03 instalar o python

Passo 1 — O Python.

Antes de qualquer coisa, você precisa do Python instalado. Versão 3.11 ou 3.12. Não tente com 3.13 ou superior — o MediaPipe ainda não suporta.

1.1

Verifique se você já tem Python

Abre o PowerShell (procura por "PowerShell" no menu Iniciar) e cola o comando:

powershell
python --version

Se aparecer Python 3.11.x ou Python 3.12.x, você já tem — pula para o passo 2. Se aparecer outra coisa, ou erro tipo 'python' is not recognized, continua aqui.

1.2

Baixe o instalador oficial

Vai em python.org/downloads/release/python-3119/ e desce a página até "Files". Procure por Windows installer (64-bit) e clique para baixar.

O arquivo vai pra sua pasta Downloads, com nome parecido com python-3.11.9-amd64.exe.

1.3

Instale — atenção nessa parte

Clica duas vezes no arquivo baixado. Quando o instalador abrir:

  1. Marque a caixa "Add python.exe to PATH" na parte de baixo da janela. Essa é a parte mais importante. Se você esquecer, nada vai funcionar depois.
  2. Clica em "Install Now".
  3. Espera terminar. Quando aparecer "Setup was successful", fecha.

se a tela mostrar "Disable path length limit" no final, clica para habilitar. não é obrigatório, mas evita dor de cabeça futura.

1.4

Confirma que funcionou

Fecha o PowerShell e abre de novo (importante, senão ele não "vê" o Python recém-instalado). Roda:

powershell
python --version
pip --version

Deve aparecer algo como Python 3.11.9 e pip 24.0 .... Se aparecer, você tá pronto pro próximo passo.

04 instalar o git

Passo 2 — O Git.

Git é o programa que vai baixar o projeto do GitHub pra sua máquina. Se você não quiser instalar Git, pula para a alternativa em ZIP no passo 2.B.

2.A

Opção com Git (recomendado)

Baixa o instalador em git-scm.com/downloads. Roda o instalador clicando em "Next" em tudo — as opções padrão são boas.

Depois, fecha e abre o PowerShell e testa:

powershell
git --version

Deve aparecer algo como git version 2.45.0.windows.1.

2.B

Opção sem Git (atalho)

Se você não quer instalar mais uma coisa, dá pra baixar o projeto direto como arquivo ZIP:

  1. Vai em github.com/ognistie/ai-virtual-mouse-controller
  2. Clica no botão verde "Code"
  3. Escolhe "Download ZIP"
  4. Extrai o ZIP na pasta onde você quer manter o projeto

se você escolher essa opção, pula o passo 3 e vai direto pro passo 4.

05 baixar o projeto

Passo 3 — Clonando o repositório.

Agora você vai trazer uma cópia do projeto pra sua máquina. Esse passo é só com Git. Se você baixou ZIP no passo anterior, pula direto pro passo 4.

3.1

Escolha onde guardar o projeto

Decide uma pasta no seu computador onde você quer que o projeto fique. Por exemplo: C:\Users\Seu_Nome\Documentos\. Vai ser criada uma subpasta chamada ai-virtual-mouse-controller dentro dela.

No PowerShell, navega até essa pasta com o comando cd:

powershell
cd $HOME\Documents

$HOME é um atalho que aponta pra C:\Users\Seu_Nome\ automaticamente. não precisa digitar seu nome.

3.2

Clone o repositório

Roda esse comando. Ele baixa todos os arquivos do projeto.

powershell
git clone https://github.com/ognistie/ai-virtual-mouse-controller.git

Vai aparecer uma sequência de mensagens tipo Cloning into 'ai-virtual-mouse-controller'... seguida de progresso. Quando voltar pro prompt normal, deu certo.

3.3

Entra na pasta do projeto

Agora você precisa estar dentro da pasta do projeto pra rodar os próximos comandos. Roda:

powershell
cd ai-virtual-mouse-controller

O prompt do PowerShell deve mostrar agora algo como PS C:\Users\Seu_Nome\Documents\ai-virtual-mouse-controller>. Esse caminho é onde você tem que estar pra todos os próximos comandos.

06 ambiente virtual

Passo 4 — O venv.

O venv (ambiente virtual) é uma "caixinha" isolada que vai segurar todas as dependências desse projeto sem misturar com outros Python da sua máquina. É boa prática. Sempre faça.

§ analogia que talvez ajude

Imagina que cada projeto Python é uma receita. Algumas receitas pedem farinha de trigo, outras de amendoim, outras sem glúten. Se você for misturando tudo na mesma cozinha, uma hora vai dar errado. O venv é você ter uma cozinha separada pra cada receita. Mais limpo. Sem briga de ingredientes.

4.1

Cria o venv

Dentro da pasta do projeto, roda:

powershell
py -3.11 -m venv .venv

Esse comando cria uma pasta chamada .venv (com o ponto na frente, sim) dentro do projeto. Ela tem o Python isolado dentro. Demora uns 10 segundos.

4.2

Ativa o venv

Cada vez que você for usar o projeto, precisa ativar o venv primeiro. Roda:

powershell
.\.venv\Scripts\Activate.ps1

Se deu certo, o prompt do PowerShell vai mudar e mostrar (.venv) antes do caminho. Tipo: (.venv) PS C:\...\ai-virtual-mouse-controller>. Esse (.venv) é seu sinal de que o ambiente tá ativo.

se aparecer erro tipo "Activate.ps1 cannot be loaded because running scripts is disabled", roda primeiro: Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned. Tem solução em 30 segundos.

07 dependências

Passo 5 — As bibliotecas.

Agora você vai instalar as bibliotecas que o projeto precisa: MediaPipe (visão computacional), OpenCV (manipulação de imagem), PyAutoGUI (controle do cursor), entre outras. Vem uma lista pronta com versões certinhas.

5.1

Atualiza o pip

Pip é o "gerenciador de pacotes" do Python. Ele que vai baixar e instalar as bibliotecas. Boa prática: atualizar ele primeiro.

powershell · com venv ativo
pip install --upgrade pip
5.2

Instala tudo de uma vez

O projeto já tem um arquivo requirements.txt com a lista de tudo que precisa. Roda:

powershell · com venv ativo
pip install -r requirements.txt

Vai aparecer uma cascata de "Collecting...", "Downloading...", "Installing...". Demora de 2 a 5 minutos dependendo da sua internet. Não é normal interromper no meio — deixa terminar.

5.3

Confere que instalou

No final, deve aparecer algo como Successfully installed mediapipe-0.10.9 opencv-python-4.x .... Pra ter certeza, roda:

powershell
python -c "import cv2, mediapipe; print('tudo certo')"

Se imprimir tudo certo, você pode ir pro passo 6. Se reclamar de algum módulo, confere se o venv tá ativo (o (.venv) tem que aparecer no prompt).

08 rodar pela primeira vez

Passo 6 — A primeira execução.

Tudo pronto. Bora ver isso funcionando. Antes de rodar, abre seu navegador ou alguma app que você queira testar o cursor depois — vai ser bom ter algo já aberto pra clicar.

6.1

Roda o programa principal

Confirma que o venv ainda tá ativo (procura o (.venv) no prompt). Roda:

powershell · com venv ativo
python main.py
6.2

O que você vai ver

Em alguns segundos, três coisas acontecem:

  1. A luz da webcam acende (se a sua tem uma).
  2. Uma janela pequena, de 480×270 pixels, abre no canto inferior direito da tela. Dentro dela aparece o que a câmera tá vendo, com os pontos da mão sobrepostos em vermelho.
  3. No terminal, vão aparecer algumas mensagens informativas (FPS, perfil ativo, etc).

se a janela não aparece, olha atrás das outras janelas. às vezes ela abre embaixo de tudo. ou minimizada na barra de tarefas.

6.3

Testa o primeiro gesto

Posiciona sua mão a uns 50 cm da câmera, palma voltada pra frente, dedos abertos. Movimenta a mão lentamente.

O cursor da tela vai começar a seguir a sua mão. Se não estiver — checa se sua mão tá visível na janelinha. Se a mão aparece nela mas o cursor não move, pode ser que outro programa esteja capturando o cursor (jogo, RDP, etc).

09 os gestos · em detalhe

Cinco gestos. O sexto é bônus.

Cada um foi desenhado para ser inequívoco e durar uma sessão inteira sem cansar a mão. Pratica em frente ao espelho da janelinha antes de usar na rotina.

Mão aberta movendo o cursor

1. Mover o cursor

Abre a mão com a palma virada pra câmera. Movimento lento = controle preciso. Movimento amplo = travessia rápida da tela. O cursor segue a base do dedo médio — não a ponta do indicador — pra não pular no momento do clique.

Dica de iniciante: não tente mover o cursor mexendo só o dedo. Move o pulso inteiro, naturalmente. Sua mão cansa menos.

Pinça polegar e indicador

2. Clique esquerdo

Pinça rápida entre polegar e indicador. O clique dispara no instante do toque, não no release. Diferença real: zero latência percebida — porque é literalmente zero, não "quase zero".

Dica de iniciante: não precisa forçar. Encosta de leve. O sistema enxerga o toque mesmo sem você apertar.

Polegar e médio com indicador estendido

3. Clique direito

Polegar encosta no médio, com o indicador estendido. O indicador estendido é o que evita confusão com o clique esquerdo. Aciona o menu de contexto do sistema operacional.

Dica de iniciante: deixa o indicador bem estendido, não só levemente. Se ele dobrar no meio, o sistema acha que você tá pausando.

Sinal de paz

4. Duplo clique

Sinal de paz (indicador + médio) mantido por aproximadamente 500 ms. O delay é proposital. Sem ele, o duplo clique virava acidente toda vez que você apontava com dois dedos.

Dica de iniciante: conta um "um e" mentalmente. É o tempo certo.

Punho fechado

5. Pausar o cursor

Fecha a mão em punho. O cursor congela na hora. Útil quando você quer reposicionar a mão sem o cursor surfar pela tela junto. Abre a mão = volta a rastrear.

Dica de iniciante: usa esse gesto sempre que precisar coçar o nariz, mexer no cabelo, atender o celular. Sério.

10 encerrar

Passo 7 — Fechar direito.

Quando você terminar de usar, não feche o terminal pelo X. Encerra o programa direito.

opção A

Pela janelinha

Clica na janelinha (480×270) que mostra a câmera, então pressiona ESC. É o jeito recomendado.

opção B

Pelo terminal

No terminal, pressiona Ctrl+C. Funciona, mas pode deixar a câmera ocupada por alguns segundos.

Depois de encerrar, a janelinha fecha, a luz da webcam apaga, e o terminal volta pro prompt normal (ainda com (.venv) ativo). Você pode rodar python main.py de novo a qualquer momento.

11 da próxima vez

Da segunda vez, é mais rápido.

Você não precisa instalar nada de novo. Cada vez que quiser usar o projeto, é só ativar o venv e rodar.

rotina

Os três comandos diários

Abre o PowerShell, vai pra pasta do projeto, ativa o venv, roda.

powershell · toda vez
cd $HOME\Documents\ai-virtual-mouse-controller
.\.venv\Scripts\Activate.ps1
python main.py

Em uns 5 segundos a janelinha abre e você tá pronto pra usar.

atalho

Cria um atalho na área de trabalho (opcional)

Se você usar todo dia, vale criar um arquivo .bat com esses comandos. Clica com botão direito na área de trabalho → Novo → Documento de Texto. Renomeia ele pra ai-mouse.bat (importante a extensão ser .bat, não .txt). Abre com o Bloco de Notas e cola:

ai-mouse.bat
@echo off
cd /d %USERPROFILE%\Documents\ai-virtual-mouse-controller
call .venv\Scripts\activate.bat
python main.py
pause

Salva. Agora dois cliques no ai-mouse.bat e o projeto abre direto, sem terminal manual.

12 customizar · opcional

Quer mexer? Dá.

Só se você quiser. O projeto funciona sem nenhuma alteração. Mas algumas constantes podem ser ajustadas se você tem motivo específico.

§ caminho do arquivo de configuração

O arquivo se chama config.py e fica na raiz do projeto:

C:\Users\Seu_Nome\Documents\ai-virtual-mouse-controller\config.py

Abre com qualquer editor de texto (Bloco de Notas serve). Você vai ver variáveis em maiúsculo no início. As mais úteis pra ajustar estão abaixo.

config.py

Trocar de webcam

Se você tem mais de uma câmera (notebook + USB, por exemplo) e quer usar a outra:

config.py
CAMERA_INDEX = 0    # webcam padrão
# CAMERA_INDEX = 1  # segunda câmera
# CAMERA_INDEX = 2  # terceira
config.py

Performance em máquina lenta

Se o seu FPS tá baixo (abaixo de 30):

config.py
MODEL_COMPLEXITY = 0    # 0=lite, 1=full
CAMERA_WIDTH = 640      # menor = mais leve
CAMERA_HEIGHT = 360
config.py

Margem da tela

Se o cursor tem dificuldade de chegar nos cantos:

config.py
SCREEN_MARGIN_PERCENTAGE = 0.15    # padrão é 0.20

Valor menor = mão precisa ir até mais perto da borda da câmera pra cursor chegar no canto da tela.

config.py

Âncora do cursor

Por padrão é landmark 9 (base do médio). Se você quiser experimentar:

config.py
CURSOR_ANCHOR_LANDMARK = 9     # padrão
# CURSOR_ANCHOR_LANDMARK = 8   # ponta do indicador
# CURSOR_ANCHOR_LANDMARK = 0   # pulso

Sai do padrão por sua conta e risco. A escolha do 9 tem motivação técnica documentada no README.

13 holograma · opcional

Quer ver sua mão na tela?

O projeto tem um modo opt-in: uma mão holográfica azul-ciano que aparece sobreposta ao desktop e segue seus movimentos em tempo real. Click-through — não bloqueia nada que você tenha na tela.

passo 1

Instala o PySide6 e o ModernGL

O holograma usa PySide6 (Qt for Python) + ModernGL pra renderizar em 3D. São dependências opcionais — o projeto roda normalmente sem elas.

pip · com venv ativo
pip install PySide6 moderngl
passo 2

Roda o projeto e aperta H

No log do startup, você deve ver:

terminal
[AVM] HologramOverlay criado: available=True, click_through=True

Aperta H em runtime. A mão aparece em ~1s.

passo 3

O que você vai ver

  • Silhueta azul-ciano da mão sobre o desktop, seguindo cada movimento
  • Anel pulsante no ponto onde os dedos vão se tocar (o cursor)
  • Bursts no clique: anel ciano expande quando você pinça (esquerdo), azul pro direito
  • Click-through: você continua clicando, selecionando, navegando normal — o overlay não intercepta nada
passo 4

Customizar (opcional)

Em config.py:

config.py
HOLOGRAM_ENABLED = True              # liga no startup (sem precisar H)
HOLOGRAM_HAND_SIZE_PX = 180          # tamanho da mão em px
HOLOGRAM_VIEW_DORSAL = False         # palm view (alinhado com webcam)
HOLOGRAM_PARTICLES_ENABLED = False   # nuvem de particles (default off)
HOLOGRAM_BACKEND = "auto"            # auto / gl / qpainter
— chegou até aqui?

Agora é prática. Boa sorte.

Em alguns minutos de uso, você vai parar de pensar nos gestos. Eles viram instinto. Promete.

Se algum passo travou ou alguma mensagem de erro apareceu, abre uma issue no repositório com a saída completa do terminal — vamos ler.

Voltar pro manual rápido Ir pro GitHub