pyvizion

Framework de automação de interface (RPA desktop) em Python: encontra botões e textos na tela, clica, digita e encadeia fluxos com recuperação de falhas.

O que é

O pyvizion foi feito para operar sistemas legados no Windows (e Linux/macOS onde aplicável): ERPs, Oracle Forms, Delphi/VB6, Java Swing, Citrix/RDP e terminais. Na prática você combina recortes PNG, OCR e teclas — sem depender de API do aplicativo.

Instale com pip install pyvizion. Código e documentação deste repositório; pacote em pypi.org/project/pyvizion. Licença: LICENSE.

from pyvizion import Vizion

vz = Vizion()
vz.click_image("menu.png", backtrack=True)
vz.click_text("Relatórios", backtrack=True)
vz.click_text("Confirmar", sendtext="{enter}")

Versões antigas no PyPI (0.3.x) usavam outra API. Use a série 1.0+ (from pyvizion import Vizion).

📦 Instalação

pip install pyvizion

Uma instalação só, com tudo incluído e já no modo mais rápido.

Tesseract (só para funções de texto — click_text, find_text, read_text):

• Windows: https://github.com/UB-Mannheim/tesseract/wiki — instale em C:\Program Files\Tesseract-OCR\ e marque Portuguese.
• Linux: sudo apt-get install tesseract-ocr tesseract-ocr-por
• macOS: brew install tesseract tesseract-lang

python -m pyvizion doctor      # confere dependências, Tesseract, idiomas e monitores

🎯 Uso rápido

Backtrack entre métodos

vz = Vizion()
vz.click_image("menu.png", backtrack=True)
vz.click_text("Relatórios", backtrack=True)   # falhou? reexecuta o anterior e tenta de novo

Sessão de backtrack

vz.start_task_session()
vz.click_image("button1.png", backtrack=True)
vz.click_text("Clientes", backtrack=True)
vz.click_text("Novo", backtrack=True)
successful, total = vz.end_task_session()
print(f"Sucesso: {successful}/{total}")

Lista de tarefas

from pyvizion import execute_tasks

tasks = [
    {"image": "button.png", "region": (100, 100, 200, 50), "confidence": 0.9,
     "specific": False, "backtrack": True, "delay": 1, "mouse_button": "left"},

    {"text": "Login", "region": (50, 50, 300, 100), "char_type": "letters",
     "backtrack": True, "sendtext": "usuario123{tab}senha{enter}"},

    {"type": "relative_image", "anchor_image": "warning_icon.png",
     "target_image": "ok_button.png", "max_distance": 200},

    {"type": "click", "x": 500, "y": 300, "mouse_button": "right"},
    {"type": "type_text", "text": "Hello World!"},
    {"type": "keyboard_command", "command": "Ctrl+S", "delay": 1},
]

execute_tasks(tasks)            # ou: Vizion().execute_tasks(tasks)

🔧 Métodos

Parâmetros comuns

• region=(x, y, largura, altura) — onde procurar. Use sempre que puder (OCR ~6× mais rápido, sem falsos positivos). vz.window_region("Título") devolve a área de uma janela.
• specific=True — busca só na region. specific=False — tenta a região e depois a tela inteira, em escalas 0,8× a 1,2×.
• mouse_button — "left", "right", "double", "move_to" (só passa o mouse), "middle", "triple".
• filter_type — "letters", "numbers" ou "both". occurrence=2 — a segunda ocorrência em ordem de leitura.
• offset=(dx, dy) — clica deslocado do alvo (ex.: o campo à direita do rótulo).
• timeout= — espera o alvo aparecer por até N segundos.

Os métodos também existem como funções, sem instância: from pyvizion import click_image, find_text, execute_tasks.

📝 Preenchendo campos (sendtext)

sendtext é o texto digitado logo depois do clique. Dentro dele, palavras entre chaves { } são teclas:

vz.click_text("Usuário", offset=(150, 0), sendtext="admin{tab}senha123{enter}")

O que acontece, em ordem:

Receitas do dia a dia

Prefira um passo por campo — fica mais fácil de ler e, se algo falhar, o log mostra exatamente onde:

vz.click_text("Data Inicial", offset=(150, 0), sendtext="{ctrl}a{del}01/01/2026")
vz.click_text("Data Final",   offset=(150, 0), sendtext="{ctrl}a{del}31/01/2026")
vz.keyboard_command("Enter")

Teclas disponíveis

• Maiúsculas não importam: {Enter} = {enter}.
• Chaves com algo que não é tecla são digitadas normalmente: "valor {total}" digita exatamente isso.
• Acentos e ç saem corretos, e a área de transferência do usuário é restaurada.
• Em Citrix/RDP/terminais que não aceitam colar, use Vizion({"typing_mode": "type"}).

Para apertar só uma tecla, sem texto: vz.keyboard_command("Ctrl+S"), vz.press("tab", 3), vz.hotkey("ctrl", "shift", "s").

📋 Tarefas: todos os tipos

tasks = [
    {"type": "focus_window", "title": "Oracle Applications"},
    {"type": "wait_image", "image": "tela_principal.png", "timeout": 30},
    {"text": "Cliente", "offset": (160, 0), "sendtext": "12345{enter}", "required": True},
    {"type": "wait_image", "image": "ampulheta.png", "gone": True, "timeout": 60},
    {"type": "relative_image", "anchor_text": "Pedido", "target_image": "lupa.png"},
    {"image": "popup_aviso.png", "optional": True, "sendtext": "{enter}"},
    {"type": "wait_text", "text": "Registro salvo", "timeout": 15},
    {"type": "wait", "seconds": 1},
    {"type": "scroll", "clicks": -5},
]

Chaves de qualquer tarefa: mouse_button, delay, sendtext, offset, backtrack, max_attempts, timeout, optional (falha não conta nem faz backtrack), required (falha interrompe a lista), show_overlay, click_hold.

⚙️ Configuração

vz = Vizion({
    "confidence_threshold": 80.0,
    "tesseract_lang": "por",
    "show_overlay": False,
    "image_folders": ["./imagens"],
    "save_failure_screenshots": True,
})

vz.config.set("show_overlay", True)          # alterar depois
vz = Vizion("pyvizion.json")                  # ou de um arquivo .json/.yaml

🛡️ Robustez para sistemas legados

• DPI e vários monitores — modo DPI por monitor, captura de todos os monitores (inclusive coordenadas negativas); a escala de cada monitor (125%, 150%) entra automaticamente na busca.
• OCR tolerante — ignora acentos e maiúsculas, corrige 0/O, 1/l, 5/S, aceita pequenas diferenças e palavras coladas/quebradas, amplia áreas pequenas, inverte texto claro em fundo escuro, roda em paralelo e usa consenso entre leituras.
• Captura rápida — ~5 ms por área.
• Esperas, alternativas (click_any), âncoras (click_relative_image, click_image_near_text), clique deslocado (offset), leitura de campos (read_text), foco de janela.
• Listas seguras — required, optional, stop_on_failure.
• Diagnóstico — prints de falha e python -m pyvizion doctor.

🛠️ Linha de comando

python -m pyvizion doctor               # ambiente
python -m pyvizion screenshot tela.png  # print para recortar suas imagens
python -m pyvizion position             # x/y do mouse em tempo real (Ctrl+C)
python -m pyvizion pick                 # marca região (2 cantos), OCR e trechos para colar no código
python -m pyvizion ocr 100 200 300 40   # lê o texto de uma área (se já souber x,y,w,h)

💡 Dicas

1. Use region (ou vz.window_region("Título")) sempre que puder.
2. Recorte imagens pequenas e únicas (o ícone, não o botão inteiro), em PNG.
3. Prefira wait_until_gone("ampulheta.png") a delay fixo.
4. Comece com focus_window("Título").
5. Instale o idioma por do Tesseract.
6. Para parar o robô, leve o mouse ao canto superior esquerdo da tela.

🧪 Desenvolvimento

pip install -e .[dev]
pytest

📄 Licença

Software proprietário — consulte LICENSE. Desenvolvido por Josias Azevedo da Silva.