Quando usar
Quando o sistema não tem API (ERP antigo, Oracle Forms, Citrix, Totvs, Delphi ou app desktop legado) e você precisa clicar e digitar como se fosse um operador humano.
Biblioteca Python
Windows
ERP & Legado
v1.0.8 no PyPI
Faça o computador
clicar e digitar por você.
O pyvizion olha a tela como uma pessoa olharia: encontra um botão ou uma palavra, clica em cima e digita o que você mandar. Serve para automatizar sistemas que não têm API, como ERPs antigos, Oracle Forms, Delphi, Totvs e Citrix.
$
pip install pyvizion
3 linhas
para clicar num botão a partir de uma imagem
~5 ms
para capturar a tela inteira com mss
~6× mais rápido
quando você indica a região da janela
1.0.8
versão estável disponível no PyPI
Para que serve o pyvizion
O pyvizion é uma biblioteca Python leve e determinística. Você instala com pip, importa no seu script e automatiza telas de sistemas no Windows (ERP, Oracle Forms, Delphi, Totvs e Citrix) sem depender de APIs ou plataformas pesadas.
O que ele resolve
Localiza botões recortados ou palavras escritas na tela, clica com precisão milimétrica e preenche campos em sequência. Também espera telas carregarem antes de agir.
O que ele não é
Não é um robô de IA imprevisível. É automação determinística por visão de imagem e OCR: você tem 100% de controle de cada clique e digitação do seu robô.
Como funciona na prática
Você escreve em poucas linhas o mesmo caminho que faria manualmente com o teclado e o mouse. O pyvizion executa cada etapa em sequência lógica:
Mostre onde clicar
Você escolhe o alvo: pode ser a foto de um botão recortado (imagem) ou a palavra escrita nele (ex.: "Confirmar").
O robô acha na tela
Ele examina a tela do computador instantaneamente e descobre onde o botão ou palavra está aparecendo.
Clica com precisão
O clique do mouse vai direto ao centro do que encontrou, com precisão no lugar certo e sem errar o alvo.
Digita e navega
Preenche campos com números ou textos, pula de campo com a tecla Tab e aperta Enter se você mandar.
Espera e tenta de novo
Se a tela demorar para carregar, ele espera com segurança. E se algo sumir, tenta de novo antes de desistir.
Simulação em Tempo Real
Demonstração interativa de execução
Veja exatamente como o pyvizion localiza textos na tela, fixa a caixa de OCR, move o cursor virtual e aciona o clique no sistema legado.
ERP Corporativo - Faturamento v4.2 [Win32 Legado]
● LIVE RUNTIME
Filial:
01 - Matriz São Paulo (Produção)
Cliente / Razão:
ACME INDÚSTRIA & COMÉRCIO LTDA
Documento:
NF-e 000.492.190 - Série 1
Valor Total:
R$ 14.850,00
Status:
Aguardando Confirmação
Ciclo de Execução
Fluxograma oficial do pyvizion
Entenda como cada biblioteca atua no ciclo determinístico de automação: da captura da tela via mss, passando pelo processamento com OpenCV e Tesseract, até a execução com PyAutoGUI e o controle de retry com timeout.
1. Captura de Tela (mss)
O mss tira prints diretos da memória de vídeo em ~5 ms, sem travar o processador e com suporte total a múltiplos monitores.
2. Processamento (OpenCV / Tesseract)
O OpenCV faz casamento de padrões (template matching) para achar botões recortados. O Tesseract OCR lê caracteres e palavras na tela.
3. Execução de Ação (PyAutoGUI)
Calcula o centro das coordenadas detectadas e dispara cliques físicos ou virtuais (sem mexer o mouse), além de digitação com macros.
4. Retry / Timeout Seguro
Se o elemento não estiver pronto, repete o ciclo de captura e busca até o timeout ou retorna False sem derrubar o robô.
Arquitetura e requisitos mínimos
Construído para ser leve, confiável e focado na realidade dos computadores corporativos no Windows.
Tecnologias integradas
- Python 3.9+: compatível com ambientes modernos e corporativos.
- mss: captura de tela ultrarrápida em milissegundos.
- OpenCV: localização de recortes PNG com tolerância a DPI scaling.
- Tesseract OCR: leitura e busca de palavras direto na imagem.
- PyAutoGUI: envio de cliques e teclas com fail-safe nos cantos.
- pywinauto: controle e foco de janelas do Windows (Win32).
Requisitos do sistema
- Sistema operacional: Windows 10 ou 11 (recomendado e completo).
- Tesseract OCR: instalado no caminho padrão (UB-Mannheim).
- Visibilidade: a tela ou janela do aplicativo deve estar visível.
- Recortes de imagem: prints nítidos em PNG dos botões alvo.
- Linux / macOS: suporte básico (sem clique virtual e sem controle de janela).
Mapa mental rápido de uso
pyvizion
├── 1. Preparar ambiente
│ ├── pip install pyvizion
│ └── instalar Tesseract OCR (UB-Mannheim)
├── 2. Definir alvos na tela
│ ├── Imagem: recorte PNG do botão (salvar.png)
│ └── Texto: palavra a ser lida via OCR ("Confirmar")
├── 3. Executar ações
│ ├── click_image / click_text
│ ├── sendtext com macros: "admin{tab}senha{enter}"
│ └── esperas: wait_until_found / wait_until_gone
└── 4. Tratar o retorno
├── True: ação executada com sucesso
├── False / None: elemento não encontrado (tratar no código)
└── Exception: arquivo inexistente ou Tesseract não instaladoPasso a passo: seu primeiro robô
Leva cerca de 10 minutos. Você só precisa do Python 3.9+ instalado no Windows. Todos os comandos abaixo são executados no terminal (PowerShell ou Prompt de Comando).
-
1. Instale o pyvizion
Baixa a biblioteca e suas dependências diretamente do PyPI oficial.
pip install pyvizion -
2. Instale o Tesseract OCR
É o motor que lê os textos na tela. Baixe pelo instalador oficial para Windows: UB-Mannheim Tesseract OCR. Mantenha a pasta padrão (
C:\Program Files\Tesseract-OCR). Se for automatizar telas em português, marque o pacote de idioma Portuguese durante a instalação. -
3. Verifique seu ambiente com o doctor
O pyvizion vem com uma ferramenta de diagnóstico integrada que valida se o Tesseract e as bibliotecas estão prontos.
python -m pyvizion doctor -
4. Recorte o botão desejado
Abra a tela do sistema, aperte Win + Shift + S e recorte apenas o botão (ex.:
menu.png). Salve o recorte numa pastaimagensao lado do seu script. Você também pode tirar print pelo próprio pyvizion:python -m pyvizion screenshot tela.png -
5. Escreva seu script Python
Crie um arquivo
robo.py. Cada linha é uma instrução sequencial, na mesma ordem que você faria manualmente:from pyvizion import Vizion # Inicia o robô apontando a pasta de imagens e o idioma do OCR vz = Vizion({"image_folders": ["imagens"], "tesseract_lang": "por"}) # Clica no botão pela imagem recortada vz.click_image("menu.png") # Clica onde estiver escrito "Relatórios" na tela vz.click_text("Relatórios") # Clica no campo "Código", digita 12345 e aperta Enter vz.click_text("Código", sendtext="12345{enter}") -
6. Execute e acompanhe
Deixe o aplicativo visível na tela e rode o script. Para parar a execução a qualquer instante (fail-safe de segurança), basta jogar o mouse para o canto superior esquerdo da tela!
python robo.py
Sobre macros de digitação (novidade da versão 1.0.8)
O parâmetro sendtext aceita atalhos como {tab}, {enter} e {ctrl}a.
O uso de macros é 100% opcional. Se preferir, use apenas texto direto normal.
Modo simples (sem macros)
# Digita texto simples diretamente no campo clicado
vz.click_text("Código", sendtext="12345")
# Ou separa em duas etapas explícitas
vz.click_text("Código")
vz.type_text("12345")Sem chaves, o texto é digitado de forma direta e literal, sem interpretação de macros.
Modo avançado (com macros)
# Preenche um campo, aperta Tab e digita no próximo
vz.click_text("Usuário", sendtext="admin{tab}senha{enter}")
# Seleciona todo o conteúdo anterior, apaga e digita
vz.click_text("Código", sendtext="{ctrl}a{del}12345")Ideal para fluxos em ERPs onde a navegação entre campos é feita com Tab e confirmações com Enter.
Tabela de teclas e macros disponíveis
| Objetivo | Sintaxe no sendtext |
Comportamento |
|---|---|---|
| Digitar em campo vazio | "12345" |
Digita o valor diretamente |
| Limpar e redigitar | "{ctrl}a{del}12345" |
Seleciona tudo, deleta e digita o novo valor |
| Ir para o próximo campo | "12345{tab}" |
Digita e dispara a tecla Tab |
| Confirmar formulário | "12345{enter}" |
Digita e dispara a tecla Enter |
| Preencher múltiplos campos | "01/01/2026{tab}31/01/2026" |
Preenche data inicial, pula com Tab e preenche data final |
| Pular vários campos | "{tab*3}" |
Repete a tecla Tab 3 vezes consecutivas |
| Pausa entre comandos | "admin{tab}{wait 1}senha" |
Aguarda 1 segundo antes de continuar a digitar |
| Teclas especiais comuns | {esc}, {backspace}, {f1}...{f12}, {up}, {down} |
Navegação e atalhos de função padrão do teclado |
Exemplos prontos (copie e use)
Padrões comuns que resolvem a maioria das automações corporativas. Copie o trecho, ajuste o nome do arquivo ou texto e execute.
1. Esperar tela carregar ou ampulheta sumir
Em vez de colocar time.sleep(10) no chute, espere o elemento aparecer ou o indicador de carregamento sumir:
# Espera até 15 segundos o botão aparecer e clica
vz.click_image("salvar.png", wait_until_found=True, wait_timeout=15)
# Espera até 60 segundos a ampulheta ou loading sumir
vz.wait_until_gone("ampulheta.png", timeout=60)2. Preencher formulário com Tab e Enter
Preencha formulários inteiros em sequência rápida simulando o comportamento de digitação humano:
# Clica no campo de login e navega com Tab
vz.click_text("Usuário", sendtext="admin{tab}senhaForte2026{enter}")
# Limpa campo pré-preenchido antes de digitar
vz.click_text("Código", sendtext="{ctrl}a{del}99281")3. Tentar de novo se falhar (Backtrack)
Se um menu dropdown fechar ou um clique falhar, o backtrack reexecuta o passo anterior e tenta de novo:
# Se "Relatórios" não for encontrado, reabre "Menu" e tenta novamente
vz.click_image("menu.png", backtrack=True)
vz.click_text("Relatórios", backtrack=True)4. Focar janela e buscar só numa área (6× mais rápido)
Restringir a busca à área da janela do ERP acelera a captura e evita clicar em outro aplicativo aberto:
# Traz a janela para frente e obtém suas coordenadas
vz.focus_window("Oracle Applications")
area = vz.window_region("Oracle Applications")
# Busca OCR apenas dentro da janela do Oracle
vz.click_text("Salvar", region=area)Comparativo honesto
O pyvizion mantém os mesmos métodos clássicos que você já conhece no ecossistema Python, mas com arquitetura moderna, alta velocidade e robustez para ambientes Windows.
| Recurso / Cenário | PyAutoGUI puro / bot-vision-suite 1.3 | pyvizion 1.0.8 (Atual) |
|---|---|---|
| Velocidade de captura de tela | Lenta (30 a 100 ms por captura com PIL) | ~5 ms por captura com mss |
| Zoom do Windows (DPI 125% / 150%) | Falha frequentemente por distorção de escala | Resiliente: lida com escalonamento DPI sem quebrar |
| Busca por texto (OCR) | Lê a tela inteira a cada iteração | Permite restringir a region (~6× mais rápido) |
| Múltiplos monitores | Problemas com coordenadas negativas no monitor secundário | Totalmente compatível com multi-monitores |
| Controle de janelas | Não possui controle nativo de janelas | focus_window e window_region integrados |
| Clique virtual (sem mover mouse) | Não suportado | use_virtual_mouse nativo no Windows |
| Diagnóstico de ambiente | Nenhum diagnóstico | python -m pyvizion doctor integrado |
Dúvidas frequentes (FAQ)
Soluções para as situações mais comuns durante a configuração e execução.
Aparece o erro TesseractNotFoundError. Como resolver?
O Tesseract OCR não está instalado ou não está no caminho padrão. Baixe pelo instalador UB-Mannheim para Windows e mantenha o caminho sugerido (C:\Program Files\Tesseract-OCR). Depois, rode python -m pyvizion doctor no terminal para confirmar.
O robô não está encontrando meu botão recortado. O que fazer?
Tire o print direto da tela na mesma resolução em que o robô vai rodar. Recorte apenas o ícone ou texto do botão, sem incluir bordas variáveis ou fundos que mudam. Se o botão possuir versões diferentes (ativo/inativo/hover), use vz.click_any(["btn_v1.png", "btn_v2.png", "Salvar"]).
Ele não reconhece palavras com acentos em português?
O idioma padrão do Tesseract é inglês. Ao iniciar o pyvizion, configure o idioma português: Vizion({"tesseract_lang": "por"}). Lembre-se de ter marcado o pacote de idioma Portuguese durante a instalação do Tesseract.
Como descubro as coordenadas de uma área específica da tela?
O pyvizion possui utilitários CLI incluídos. Execute python -m pyvizion pick e clique nos dois cantos da área desejada para ver a tupla region=(x, y, largura, altura). Para acompanhar a posição do mouse em tempo real, use python -m pyvizion position.
No Citrix ou Área de Trabalho Remota o texto não é colado?
Por padrão o pyvizion usa colagem rápida via clipboard para agilizar a digitação. Algumas sessões remotas bloqueiam o clipboard compartilhado. Basta configurar o modo de digitação caractere por caractere: Vizion({"typing_mode": "type"}).
Posso usar o computador enquanto o robô está em execução?
Sim! Ativando o modo de clique virtual: Vizion({"use_virtual_mouse": True}) (exclusivo para Windows), o robô envia mensagens Win32 de clique sem mover o ponteiro físico do mouse. Apenas certifique-se de que a janela do app não seja minimizada nem totalmente encoberta.
O pyvizion funciona em Linux ou macOS?
Funciona com limitações: no Linux e macOS não há suporte a clique virtual sem mover o mouse nem controle de janelas Win32. O foco principal e suporte completo do pyvizion é o ambiente Windows corporativo.