josias 0.2.1

Biblioteca Python avançada para automação de interface gráfica com OCR e processamento de imagem avançado

Josias 🤖✨

Josias é uma nova e avançada ferramenta em Python para automação de interface gráfica (RPA / GUI Automation). Ela foi projetada para resolver os principais problemas de automação visual tradicional: rigidez de resolução, travamento de mouse físico, falta de rastreabilidade em falhas de OCR e instabilidade em sistemas que exigem recuperação de erros.

Combinando Tesseract OCR avançado, 19 filtros de pré-processamento de imagem em tempo real, detecção de escala dinâmica e cliques virtuais não-intrusivos (Win32 API), a Josias garante automações robustas e resilientes.

---

📖 Sumário

1. Prerrequisitos & Instalação
2. Arquitetura & Configuração
3. Localização e Cliques de Imagem (Escala Dinâmica)
4. Reconhecimento Óptico de Caracteres (OCR Inteligente)
5. Localização Relativa (Âncora + Alvo)
6. Gerenciador de Espera Inteligente (Smart Wait)
7. Controle de Teclado e Atalhos
8. Mouse Virtual Win32 (Segundo Plano)
9. Sistema de Overlays Visuais (Destaques na Tela)
10. Mecanismo de Backtracking (Recuperação de Falhas)
11. Depurador Visual de OCR (Visual Debug Dump)
12. Interface de Linha de Comando (CLI)

---

📦 Prerrequisitos & Instalação

1. Instalando o Tesseract OCR (Obrigatório)

A biblioteca requer o executável do Tesseract instalado na máquina para realizar as operações de OCR.

• Windows: Baixe o instalador de 32 ou 64 bits em UB-Mannheim Tesseract Wiki. Instale no caminho padrão: C:\Program Files\Tesseract-OCR\.
• Linux (Ubuntu/Debian): sudo apt-get update && sudo apt-get install tesseract-ocr tesseract-ocr-por
• macOS: brew install tesseract

[!NOTE] Por padrão, a biblioteca Josias busca o executável automaticamente no caminho C:\Program Files\Tesseract-OCR\tesseract.exe. Caso tenha instalado em outro diretório, veja a seção de configurações abaixo.

2. Instalando a Biblioteca

Navegue até a pasta raiz da biblioteca no terminal e instale-a localmente em modo editável:

pip install -e .

---

⚙️ Arquitetura & Configuração

O comportamento da biblioteca pode ser configurado de três formas complementares, respeitando a seguinte ordem de prioridade (a mais alta sobrescreve as anteriores):

1. Parâmetros passados diretamente na inicialização da classe Josias(config_dict).
2. Variáveis de ambiente com o prefixo JOSIAS_.
3. Arquivo de configuração de projeto (.josias.json, .josias.yaml ou .josias.yml) no diretório atual de execução.
4. Valores padrões internos da biblioteca.

Exemplo de arquivo .josias.json (no diretório de trabalho do seu robô):

{
  "tesseract_path": "C:\\Program Files\\Tesseract-OCR\\tesseract.exe",
  "confidence_threshold": 75.0,
  "use_virtual_mouse": true,
  "debug_ocr": true,
  "debug_ocr_dir": "logs_ocr_debug",
  "show_overlay": true,
  "overlay_color": "blue"
}

Exemplo de uso via Variáveis de Ambiente (Terminal):

set JOSIAS_USE_VIRTUAL_MOUSE=True
set JOSIAS_DEBUG_OCR=True
python meu_robo.py

Inicialização em Python:

from josias import Josias

# Sem argumentos: carrega arquivo .json/.yaml automaticamente ou usa os padrões do sistema
bot = Josias()

# Com argumentos explícitos:
custom_bot = Josias({
    "confidence_threshold": 80.0,
    "overlay_color": "green",
    "wait_timeout": 15
})

---

🖼️ Localização e Cliques de Imagem (Escala Dinâmica)

A detecção de imagens da biblioteca Josias possui tolerância a variações de escala (quando um elemento muda levemente de tamanho devido à resolução do monitor).

Métodos Principais:

• find_image(image_path, region=None, confidence=0.9, max_attempts=3, specific=True, wait_until_found=False, wait_until_disappears=False, wait_timeout=None, scales=None)
• click_image(image_path, ...) (Aceita os mesmos parâmetros de busca + ações do mouse)

Parâmetros Importantes:

• specific: Se True (padrão), procura a imagem apenas na escala nativa 1.0. Se False, testa múltiplas escalas paralelamente.
• scales: Lista de escalas numéricas para redimensionar o template durante a varredura (ex: [1.0, 0.95, 1.05]).
• mouse_button: 'left' (esquerdo), 'right' (direito), 'double' (duplo clique) ou 'move_to' (apenas posiciona).

Exemplo Didático:

# Clica em um botão na tela procurando em escala de 100%, 95% ou 105% de tamanho
# Se o botão não for encontrado imediatamente, tenta por até 3 vezes ajustando a confiança
bot.click_image(
    image_path="assets/btn_salvar.png",
    confidence=0.9,
    specific=False,
    scales=[1.0, 0.95, 1.05],
    mouse_button="double"
)

---

📝 Reconhecimento Óptico de Caracteres (OCR Inteligente)

Quando o elemento visual a ser interagido contém textos variáveis, o OCR é a melhor abordagem. Josias oferece controle avançado de Whitelist (filtragem de caracteres) para evitar leituras ambíguas.

Métodos Principais:

• find_text(text, region, filter_type="both", confidence_threshold=75.0, ...)
• click_text(text, region, ...)
• extract_text_from_region(region, filter_type="both", ...)

Filtros de Caracteres (filter_type):

• 'numbers': Limpa e valida apenas algarismos numéricos (0-9). Excelente para ler valores e códigos de barra.
• 'letters': Limpa e valida apenas caracteres alfabéticos (a-z, A-Z).
• 'both': Permite qualquer caractere alfanumérico (padrão).

Exemplo Didático:

# Procura e clica exclusivamente nos dígitos "12345" em uma região específica
# O filtro 'numbers' impede que sujeiras ou ruídos na tela gerem falsos positivos
sucesso = bot.click_text(
    text="12345",
    region=(200, 150, 300, 100),
    filter_type="numbers",
    confidence_threshold=80.0
)

---

📍 Localização Relativa (Âncora + Alvo)

Em muitas interfaces (como formulários do SAP ou Oracle), existem campos de input vazios que não possuem imagem estável ou texto para clicar diretamente. No entanto, eles estão sempre posicionados ao lado de um rótulo estático (a âncora).

Josias resolve isso calculando a distância Euclidiana entre uma âncora única e um elemento genérico.

# Localiza o rótulo estável ("rótulo_campo.png") e clica no campo de texto genérico ("campo_input.png")
# mais próximo, contanto que esteja a no máximo 150 pixels de distância
bot.click_relative_image(
    anchor_image="assets/lbl_nome.png",
    target_image="assets/input_vazio.png",
    max_distance=150,
    mouse_button="left"
)

---

⏳ Gerenciador de Espera Inteligente (Smart Wait)

Evite o uso de time.sleep() fixo em seus scripts. A Josias fornece rotinas de loop ativo não-bloqueante para aguardar condições visuais da tela.

Parâmetros de Espera Dinâmica:

• wait_until_found: Aguarda até o elemento aparecer na tela (timeout configurável).
• wait_until_disappears: Aguarda até que o elemento suma da tela (ex: barra de carregamento).
• wait_timeout: Tempo limite em segundos (se não informado, usa o valor da configuração).

Exemplos Didáticos:

# 1. Espera uma tela de carregamento sumir antes de prosseguir
bot.find_image("assets/loading_spinner.png", wait_until_disappears=True, wait_timeout=60)

# 2. Clica no botão "Confirmar" assim que ele aparecer na tela
bot.click_text("Confirmar", wait_until_found=True, wait_timeout=30)

---

⌨️ Controle de Teclado e Atalhos

Além de digitação caractere por caractere, Josias permite injetar atalhos de sistema e sequências de comandos complexas usando strings de formatação especial.

Comandos de Texto Especiais (sendtext):

Você pode embutir comandos de controle no início ou no meio do texto a ser digitado:

• {ctrl}a : Selecionar tudo
• {del} : Deletar seleção
• {tab} : Mover foco com Tab
• {enter} : Confirmar com Enter
• {backspace} : Apagar caractere
• {escape} : Pressionar ESC

Comandos de Atalhos Diretos (keyboard_command):

A Josias suporta mais de 100 atalhos mapeados de forma intuitiva, como Ctrl+S, F7, Alt+Tab, Print Screen etc.

Exemplos Didáticos:

# Clica no campo e limpa o valor existente antes de digitar
bot.click_text("Nome do Cliente", sendtext="{ctrl}a{del}Josias Silva{enter}")

# Executa um atalho de teclado direto
bot.keyboard_command("Ctrl+S") # Salva
bot.keyboard_command("F7")     # Executa comando de consulta

---

🖱️ Mouse Virtual Win32 (Segundo Plano)

Esta é uma das principais inovações da biblioteca. Ao configurar use_virtual_mouse: true, a biblioteca abandona as chamadas que deslocam o cursor físico do usuário.

Como funciona?

O Josias captura o manipulador da janela do Windows (Window Handle - HWND) posicionado sob as coordenadas do clique e posta mensagens Win32 diretamente na fila de eventos da aplicação alvo utilizando chamadas nativas em C (ctypes):

• WM_LBUTTONDOWN e WM_LBUTTONUP (Clique esquerdo)
• WM_RBUTTONDOWN e WM_RBUTTONUP (Clique direito)
• WM_MOUSEMOVE (Movimento de cursor)

Vantagens:

• Trabalho sem interrupções: Você pode continuar usando o mouse físico para navegar no navegador, responder chats ou redigir emails enquanto a automação clica silenciosamente no SAP, planilhas Excel ou sistemas ERP em segundo plano.
• Resolução de DPI automática: Ajusta automaticamente as coordenadas de clique conforme a escala de DPI configurada no monitor do Windows (96, 120, 144 DPI etc.).

# Inicializa o bot em modo não-intrusivo
bot = Josias({"use_virtual_mouse": True})

# O clique será enviado via Windows Message API.
# Seu cursor físico NÃO se moverá!
bot.click_text("Menu Principal")

---

🎨 Sistema de Overlays Visuais (Destaques na Tela)

Para facilitar a validação e auditoria em tempo real, a Josias exibe retângulos coloridos ao redor das áreas que estão sendo clicadas.

Como funciona o Fallback de Overlay?

1. Tkinter: Cria uma janela transparente sem bordas no topo da tela com crosshair (mira) centralizada no local exato do clique.
2. Windows GDI (Fallback): Caso o Tkinter falhe devido a restrições de ambiente, a biblioteca desenha o retângulo diretamente no Buffer de Tela da API gráfica do Windows (gdi32.dll) utilizando CreatePen, MoveToEx e LineTo, limpando a tela logo em seguida com InvalidateRect.
3. Console Log (Fallback final): Em ambientes sem interface (como servidores sem display), imprime as coordenadas no logger.

Customização e Teste:

# Altera a cor do retângulo para azul, com espessura de linha 6 pixels e duração de 1,5 segundos
bot.configure_overlay(enabled=True, color="blue", duration=1500, width=6)

# Abre uma demonstração visual desenhando na tela com todas as cores suportadas sequentially
bot.test_overlay_colors()

---

🔄 Mecanismo de Backtracking (Recuperação de Falhas)

Interfaces web e desktop podem oscilar de velocidade ou exibir popups inesperados. O sistema de backtrack garante que, caso a etapa N falhe, o robô retorne para a etapa N-1 para tentar reestabelecer o fluxo correto.

                  ┌──────────────────────┐
                  │   Etapa 1: Cadastro  │◄────────────────┐
                  └──────────┬───────────┘                 │
                             │ (Sucesso)                   │
                             ▼                             │ (Reexecuta anterior)
                  ┌──────────────────────┐                 │
                  │   Etapa 2: Clientes  │─────────────────┤
                  └──────────┬───────────┘ (Falha no click)│
                             │                             │
                             │ (Recuperado)                │
                             ▼                             │
                  ┌──────────────────────┐                 │
                  │ Etapa 3: Digitar Nome│─────────────────┘
                  └──────────────────────┘

Exemplo 1: Em lista de tarefas sequenciais (execute_tasks)

from josias import execute_tasks

# Se o robô não conseguir clicar na opção "Clientes" devido a lentidão do menu, 
# ele volta automaticamente e executa o clique em "Cadastros" novamente antes de tentar a etapa 2.
tarefas = [
    { 'text': 'Cadastros', 'region': (100, 100, 200, 50) },
    { 'text': 'Clientes', 'region': (100, 150, 200, 50), 'backtrack': True },
    { 'text': 'Adicionar', 'region': (100, 200, 200, 50), 'backtrack': True }
]

execute_tasks(tarefas)

Exemplo 2: Modo Sessão em código estruturado

Você pode ativar a pilha de backtrack dinamicamente em blocos de comandos normais:

bot.start_task_session()

# Etapa 1
bot.click_text("Configurações")
# Etapa 2: Se falhar em "Segurança", o bot reexecuta a Etapa 1 automaticamente
bot.click_text("Segurança", backtrack=True)

bot.end_task_session()

---

🔬 Depurador Visual de OCR (Visual Debug Dump)

Quando o OCR falha (não encontra o texto com a confiança mínima exigida) ou quando debug_ocr: true está ativo nas configurações, a Josias realiza uma análise forense do processo.

Estrutura da Pasta de Debug Gerada:

Uma pasta com a data, hora e o termo pesquisado será gerada em debug_ocr/ (ou na pasta que você configurou):

debug_ocr/
└── ocr_20260703_194512_Confirmar/
    ├── 00_original_crop.png       # Recorte da tela original enviada ao Tesseract
    ├── method_01_HSV_Enhancement.png  # Crop tratado com realce de saturação
    ├── method_03_Inversao_Fundo.png   # Crop tratado com inversão de texto claro
    ├── ... (até 19 variações de filtros)
    └── ocr_report.txt             # Relatório contendo informações analíticas

Exemplo de Conteúdo do ocr_report.txt:

====================================================
              JOSIAS OCR DIAGNOSTIC REPORT          
====================================================

Data/Hora: 2026-07-03 19:45:12
Texto Alvo: 'Confirmar'
Tipo de Filtro: 'both'
Limiar de Confiança Exigido: 75.0%

>>> ELEMENTO ESCOLHIDO <<<
Método de Imagem: HSV Enhancement (saturação aumentada) - PRIORITÁRIO (Index 1)
Configuração Tesseract: page_layout_psm6 (Config 3)
Texto Encontrado: 'Confirmar'
Confiança Final: 86.42%
Posição Relativa: (45, 12, 110, 25)

--- Histórico de correspondência encontrada ---
1. Metodo: 'HSV Enhancement...' | Config: 'page_layout_psm6' | Texto: 'Confirmar' | Confianca: 86.42%
2. Metodo: 'Inversão...' | Config: 'single_line_psm7' | Texto: 'Confrmar' | Confianca: 61.20%

Desta forma, se o robô falhar na leitura de um campo, você saberá exatamente qual filtro de imagem gerou a melhor legibilidade e poderá ajustar os parâmetros para a próxima execução.

---

💻 Interface de Linha de Comando (CLI)

Após instalar a biblioteca, a ferramenta josias estará disponível diretamente no terminal do seu ambiente virtual.

# 1. Verifica o status do sistema, executável do Tesseract e dependências do Windows
josias status

# 2. Testa e valida a integração direta do OCR, indicando se a leitura está ativa e quais idiomas estão na pasta tessdata
josias test-tesseract

# 3. Executa um teste forense em uma imagem local aplicando os 19 filtros e exibindo o que o Tesseract leu em cada método
josias test-ocr c:\capturas\tela_erro.png

# 4. Gera um template de automacao hibrida (web + desktop) no diretorio de trabalho atual
josias init

# 5. Exibe a versão instalada da biblioteca
josias version