Auto completador de Documentos: Um assistente Desktop com OCR e Tkinter para Automação de Documentos

Adriano Anthony | Desenvolvedor de Software

Repositório: https://github.com/adrianoanthonymma16-boop/auto_completador_documentos

Branches: legacy (versão estável sem OCR) e atual (desenvolvimento ativo com OCR)

1. Introdução

Este artigo descreve o processo de desenvolvimento do Auto Completador de Documentos, uma aplicação desktop desenvolvida em Python que soluciona um problema prático enfrentado por profissionais que lidam com grandes volumes de documentos padronizados. A ferramenta permite extrair informações de imagens e PDFs utilizando OCR (Optical Character Recognition) e preencher automaticamente modelos de documentos nos formatos ODT e DOCX.

O projeto surgiu da observação de um gargalo comum em ambientes administrativos e jurídicos: o preenchimento manual e repetitivo de documentos como contratos, formulários e relatórios. A proposta central era criar uma ferramenta offline, acessível e eficiente que eliminasse esse processo manual, reduzindo erros e tempo gasto.

2. Infraestrutura e Arquitetura do Projeto

A arquitetura do sistema foi projetada para ser modular, extensível e de fácil manutenção. A aplicação é estruturada em camadas bem definidas, com separação clara entre interface, lógica de negócio e persistência de dados.

2.1. Organização do Repositório

O repositório segue uma estrutura hierárquica que reflete a separação de responsabilidades. A pasta src contém todo o código-fonte principal, dividido em módulos especializados: interface.py para a camada de apresentação, ocr.py para extração de texto, modelo_odt.py e modelo_docx.py para manipulação de documentos, historico.py para persistência, e validadores.py para validação de dados. A pasta data armazena os recursos estáticos, como modelos de exemplo e imagens para testes. O diretório dist concentra os artefatos de distribuição, incluindo builds do PyInstaller e instaladores autoextraíveis gerados para facilitar a implantação. A estrutura tests abriga os testes automatizados, garantindo a confiabilidade do sistema. Por fim, os diretórios docs e .github contêm a documentação e os workflows de integração contínua, respectivamente.

2.2. Camadas Arquiteturais

A aplicação foi desenvolvida seguindo o padrão de arquitetura em camadas. A camada de apresentação é responsável pela interação com o usuário e utiliza Tkinter com ttkbootstrap para fornecer uma interface gráfica intuitiva e responsiva, com suporte a temas claros e escuros, abas organizadas e atalhos de teclado para agilizar o fluxo de trabalho. Esta camada se comunica com a camada de negócio para executar as operações solicitadas.

A camada de negócio contém a inteligência da aplicação. Módulos como ocr.py, modelo_odt.py e modelo_docx.py implementam a extração de texto, o pré-processamento de imagens e a manipulação de documentos. Validações de dados são realizadas por validadores.py, garantindo que as informações extraídas estejam no formato esperado.

A camada de persistência gerencia o armazenamento e recuperação de dados. O módulo historico.py utiliza arquivos JSON para manter o registro de todos os documentos gerados, incluindo dados como modelo utilizado, data e placeholders preenchidos. Além disso, a aplicação conta com um sistema de backup automático que salva o estado atual a cada 60 segundos, prevenindo perda de informações.

2.3. Fluxo de Dados

O fluxo de dados na aplicação segue um padrão bem definido. O usuário carrega um modelo de documento, que é analisado para extrair placeholders no formato {{nome}}. Em seguida, o usuário adiciona imagens ou PDFs contendo os dados a serem extraídos. A camada de negócio aplica pré-processamento de imagem utilizando técnicas como equalização de histograma, binarização e redimensionamento para otimizar a extração de texto. O OCR é executado e os dados extraídos são validados antes de serem apresentados ao usuário. O usuário mapeia cada placeholder a uma área específica da imagem, definindo a correspondência entre os campos do documento e os dados extraídos. Finalmente, o sistema substitui os placeholders pelos dados mapeados e gera o documento preenchido, armazenando o registro no histórico.

3. Frameworks e Tecnologias Utilizadas

3.1. Tesseract OCR

O Tesseract é o motor de OCR de código aberto mais popular da atualidade. Desenvolvido inicialmente pela HP e atualmente mantido pelo Google, ele é capaz de reconhecer texto em mais de 100 idiomas. No projeto, o Tesseract é o cérebro da extração de dados a partir de imagens e PDFs. Sua integração é feita através da biblioteca pytesseract, que fornece uma interface Python para o motor. A acurácia do reconhecimento foi otimizada com a aplicação de técnicas de pré-processamento, como a equalização de histograma CLAHE e a binarização adaptativa, que melhoram significativamente a qualidade da imagem antes da extração.

3.2. Tkinter e ttkbootstrap

Tkinter é a biblioteca padrão para interfaces gráficas em Python, oferecendo uma maneira simples e direta de construir aplicações desktop. Para dar um visual mais moderno e profissional, foi utilizada a extensão ttkbootstrap, que fornece temas e estilos contemporâneos. Isso permitiu que o aplicativo tivesse uma aparência agradável e consistente em diferentes sistemas operacionais, com suporte a modo escuro e elementos visuais refinados.

3.3. OpenCV e Pré-processamento de Imagem

A acurácia do OCR é diretamente afetada pela qualidade da imagem de entrada. Para maximizar a taxa de reconhecimento, foi implementado um pipeline de pré-processamento com OpenCV. A conversão para escala de cinza reduz a complexidade da imagem sem perder informações relevantes para o reconhecimento. A equalização de histograma CLAHE melhora o contraste local, tornando o texto mais legível em áreas com iluminação irregular. A binarização converte a imagem para preto e branco, eliminando ruídos e destacando o texto. O redimensionamento com interpolação cúbica aumenta a resolução da imagem para melhorar a detecção de caracteres.

3.4. Manipulação de Documentos

O suporte a documentos ODT é realizado através da manipulação direta do formato ZIP, com acesso ao XML de conteúdo para extração e substituição de placeholders. Para DOCX, foram utilizadas bibliotecas especializadas que permitem a manipulação estruturada dos elementos do documento. Ambos os formatos suportam a extração automática de campos, como {{nome}}, {{email}} e {{telefone}}, e sua substituição pelos dados extraídos.

3.5. Persistência e Logging

Para garantir a confiabilidade do sistema, foram implementados mecanismos de persistência e recuperação de dados. O histórico de documentos gerados é armazenado em formato JSON, registrando informações como modelo utilizado, data de geração, placeholders preenchidos e caminho do arquivo final. Além disso, um módulo dedicado a logs registra eventos críticos e erros, facilitando a depuração e o monitoramento do sistema.

3.6. Instalação e Distribuição

O projeto é distribuído através de um instalador autoextraível gerado a partir de scripts shell. Esse instalador empacota a aplicação compilada com PyInstaller, garantindo que o usuário final possa executar a ferramenta sem a necessidade de instalar dependências ou configurar o ambiente Python.

4. Funcionalidades e Fluxo de Trabalho

A aplicação foi projetada com um fluxo de trabalho intuitivo, estruturado em quatro etapas principais. A primeira etapa envolve o carregamento de um modelo de documento contendo placeholders no formato {{nome}}. O sistema extrai automaticamente todos esses marcadores e os apresenta ao usuário em uma lista. Em seguida, o usuário adiciona imagens ou PDFs contendo os dados que serão extraídos, como fotografias de documentos de identificação ou faturas. A etapa de mapeamento permite associar cada placeholder a uma área específica da imagem, utilizando recursos visuais como zoom e pan para selecionar regiões de interesse, garantindo que a extração de dados seja precisa mesmo em documentos com layout complexo. O sistema aplica então o pipeline de pré-processamento mencionado anteriormente e executa o OCR. A última etapa consiste na geração do documento final, onde todos os placeholders são substituídos pelos dados extraídos, produzindo um arquivo pronto para uso.

5. Resultados e Impacto

A aplicação demonstra a viabilidade de soluções offline para automação de documentos, reduzindo o tempo médio de preenchimento em até oitenta por cento em relação ao processo manual. A taxa de acerto do OCR, combinada às técnicas de pré-processamento, alcança níveis satisfatórios mesmo em imagens de qualidade moderada, tornando a ferramenta aplicável a cenários reais de uso. O projeto também ilustra a evolução do desenvolvimento de software, refletida na organização do repositório e na separação de branches. A migração da versão legacy para a atual não apenas expandiu funcionalidades, mas também aprimorou a arquitetura do sistema, tornando-o mais modular, testável e adaptável a mudanças futuras.

6. Considerações Finais

O Auto Completador de Documentos demonstra como Python, combinado com ferramentas open-source como Tesseract e Tkinter, pode gerar soluções práticas e eficientes para problemas cotidianos de automação. O projeto, em constante desenvolvimento, mantém seu foco na acessibilidade e usabilidade, com planos para integração com serviços em nuvem e suporte a novos formatos de documentos. O código completo está disponível publicamente no repositório aberto, com documentação detalhada e instruções de instalação, incentivando contribuições da comunidade e adaptações para diferentes casos de uso.

Repositório: https://github.com/adrianoanthonymma16-boop/auto_completador_documentos

Branch legacy: https://github.com/adrianoanthonymma16-boop/auto_completador_documentos/tree/legacy

Branch atual: https://github.com/adrianoanthonymma16-boop/auto_completador_documentos/tree/atual

Referências

Tesseract OCR – Motor de OCR open-source mantido pelo Google.

OpenCV – Biblioteca de visão computacional aplicada ao pré-processamento de imagens.

Tkinter e ttkbootstrap – Biblioteca padrão para interfaces gráficas em Python e sua extensão para temas modernos.

Python Software Foundation – Linguagem base do projeto, escolhida pela produtividade e ecossistema de bibliotecas.