ocr-document-converter 3.1.0

Enterprise-grade OCR and document conversion tool with dual OCR engines

OCR Document Converter 🔍📄

Transform any document into searchable, editable text with enterprise-grade OCR technology

Designed and Built by Beau Lewis

Enterprise-Grade OCR • Multi-Language • AI-Powered • Cross-Platform • Professional GUI

A powerful, enterprise-ready OCR (Optical Character Recognition) document converter with advanced image processing, multi-language support, and intelligent text extraction. Features Tesseract and EasyOCR engines, batch processing, and professional deployment options.

🚀 Quick Start • ✨ Features • 📄 Formats • 🛠️ Installation • ⚙️ Configuration • 📖 Usage • 📁 Project Structure • 🤝 Contributing

---

🎯 What is OCR Document Converter?

OCR Document Converter is a professional-grade, enterprise-ready OCR application that extracts text from images and documents using advanced AI-powered engines. Built with dual OCR backends (Tesseract & EasyOCR), intelligent preprocessing, and multi-language support for maximum accuracy.

🌟 Why Choose OCR Document Converter?

• 🔍 Dual OCR Engines: Tesseract 5.0+ and EasyOCR for maximum accuracy
• 🌍 Multi-Language: Support for 80+ languages with automatic detection
• 🚀 Lightning Fast: Multi-threaded processing with intelligent caching
• 🎯 Universal Format Support: JPG, PNG, TIFF, BMP, GIF, WebP, PDF
• 🖥️ Cross-Platform: Native integration on Windows, macOS, and Linux
• 🎨 Modern GUI: Professional interface with drag-and-drop support
• 📊 Batch Processing: Handle multiple files simultaneously
• ⚡ Smart Preprocessing: Automatic image enhancement and optimization
• 💾 Intelligent Caching: 24-hour file caching system for efficiency
• 🔧 Zero External APIs: Works completely offline

---

🚀 Quick Start

🖱️ Easiest Way - Automated Setup

1. Clone this repository:

   git clone https://github.com/Beaulewis1977/quick_ocr_doc_converter.git
   cd quick_ocr_doc_converter
   

2. Run the automated setup:

   python setup_ocr_environment.py
   

3. Launch the application:

   python universal_document_converter_ocr.py
   

   Or use one of the launchers:

   • Windows: Double-click run_ocr_converter.bat or ⚡ Quick Launch OCR.bat
   • Cross-platform: python launch_ocr.py
   • CLI: python cli.py input.pdf -o output.txt -t txt --ocr

🔧 Manual Installation

1. Install Python dependencies:

   pip install -r requirements.txt
   

2. Install Tesseract OCR:

   • Windows: Download from GitHub Releases
   • macOS: brew install tesseract
   • Linux: sudo apt-get install tesseract-ocr

3. Install additional language packs (optional):

   # Example for German and French
   sudo apt-get install tesseract-ocr-deu tesseract-ocr-fra
   

---

✨ Features

🔍 OCR Engines

• Tesseract 5.0+: Industry-standard OCR with 100+ language support
• EasyOCR: AI-powered neural network OCR for enhanced accuracy
• Automatic Engine Selection: Chooses best engine based on image characteristics
• Fallback System: Switches engines automatically if one fails

🌍 Multi-Language Support

• 80+ Languages: Including English, Spanish, French, German, Chinese, Japanese, Arabic, Russian
• Automatic Language Detection: Smart detection of document language
• Mixed Language Documents: Handles documents with multiple languages
• Custom Language Models: Support for specialized OCR models

🎨 Image Processing

• Smart Preprocessing: Automatic noise reduction, contrast enhancement
• Format Detection: Intelligent handling of different image formats
• Resolution Optimization: Automatic DPI adjustment for best OCR results
• Rotation Correction: Automatic text orientation detection and correction
• Skew Correction: Fixes tilted or skewed documents

🚀 Performance & Efficiency

• Multi-Threading: Parallel processing for batch operations
• Intelligent Caching: 24-hour file caching system
• Memory Optimization: Efficient handling of large files
• Progress Tracking: Real-time progress indicators
• Background Processing: Non-blocking operations

🎯 User Interface

• Professional GUI: Modern, intuitive interface
• Drag & Drop: Easy file handling
• Batch Processing: Multiple file selection and processing
• Settings Panel: Comprehensive configuration options
• Preview Mode: View processed results before saving
• Export Options: Multiple output formats and destinations

---

📄 Supported Formats

📥 Input Formats

Format	Extension	Description	OCR Quality
JPEG	.jpg, .jpeg	Standard photo format	⭐⭐⭐⭐
PNG	.png	Lossless image format	⭐⭐⭐⭐⭐
TIFF	.tiff, .tif	High-quality document format	⭐⭐⭐⭐⭐
BMP	.bmp	Windows bitmap format	⭐⭐⭐⭐
GIF	.gif	Animated/static images	⭐⭐⭐
WebP	.webp	Modern web format	⭐⭐⭐⭐
PDF	.pdf	Document format (image-based)	⭐⭐⭐⭐⭐

📤 Output Formats

• Plain Text (.txt) - Clean, formatted text
• Rich Text (.rtf) - Formatted text with styling
• Microsoft Word (.docx) - Professional documents
• PDF (.pdf) - Searchable PDF with OCR layer
• JSON (.json) - Structured data with metadata
• CSV (.csv) - Tabular data extraction

---

⚙️ Configuration

🔧 OCR Engine Settings

Tesseract Configuration

# tesseract_config.json
{
    "engine": "tesseract",
    "language": "eng+fra+deu",  # Multiple languages
    "oem": 3,                   # OCR Engine Mode (0-3)
    "psm": 6,                   # Page Segmentation Mode (0-13)
    "dpi": 300,                 # Target DPI for processing
    "preprocessing": {
        "denoise": true,
        "contrast_enhance": true,
        "rotation_correction": true
    }
}

EasyOCR Configuration

# easyocr_config.json
{
    "engine": "easyocr",
    "languages": ["en", "fr", "de"],
    "gpu": false,               # Use GPU acceleration
    "batch_size": 1,
    "workers": 0,               # Number of worker threads
    "confidence_threshold": 0.5
}

🎛️ Application Settings

GUI Configuration

# gui_settings.json
{
    "theme": "modern",          # UI theme
    "auto_preview": true,       # Show preview automatically
    "batch_size": 10,          # Max files per batch
    "output_directory": "./output",
    "cache_duration": 24,       # Hours to keep cache
    "language_detection": true,
    "progress_notifications": true
}

Processing Settings

# processing_config.json
{
    "max_threads": 4,           # Parallel processing threads
    "memory_limit": "2GB",      # Maximum memory usage
    "timeout": 300,             # Processing timeout (seconds)
    "retry_attempts": 3,        # Retry failed operations
    "temp_directory": "./temp",
    "log_level": "INFO"         # DEBUG, INFO, WARNING, ERROR
}

🌍 Language Configuration

Available Languages

# Install additional Tesseract language packs
sudo apt-get install tesseract-ocr-[LANG]

# Common language codes:
# eng (English), fra (French), deu (German), spa (Spanish)
# chi_sim (Chinese Simplified), jpn (Japanese), ara (Arabic)
# rus (Russian), kor (Korean), hin (Hindi), por (Portuguese)

Language Detection Settings

# language_config.json
{
    "auto_detect": true,
    "fallback_language": "eng",
    "confidence_threshold": 0.8,
    "supported_languages": [
        "eng", "fra", "deu", "spa", "ita", "por",
        "rus", "chi_sim", "jpn", "kor", "ara", "hin"
    ]
}

---

📖 Usage

🖥️ GUI Application

1. Launch the application:

   python universal_document_converter_ocr.py
   

2. Basic OCR Process:

   • Drag and drop files into the application window
   • Select OCR engine (Tesseract/EasyOCR/Auto)
   • Choose output format and destination
   • Click "Start OCR" to begin processing

3. Batch Processing:

   • Select multiple files using Ctrl+Click
   • Configure batch settings in the Settings panel
   • Monitor progress in real-time
   • Review results in the output directory

💻 Command Line Interface (CLI)

The OCR Document Converter includes a powerful CLI for automation and integration.

Basic Usage

# Single file OCR
python cli.py document.jpg -o result.txt -t txt --ocr

# Convert without OCR
python cli.py document.pdf -o document.md -t md

# Batch processing
python cli.py *.jpg -o converted/ -t txt --ocr

# Specify OCR language
python cli.py scan.png -o text.txt --ocr --language fra

VFP9/VB6 Integration via CLI

# For VFP9/VB6 users - simple command line execution
python cli.py input.md -o output.rtf -t rtf --quiet

Advanced Options

# Full command with all options
python ocr_engine/ocr_engine.py \
    --input document.pdf \
    --output result.docx \
    --engine easyocr \
    --language en,fr,de \
    --confidence 0.7 \
    --preprocessing \
    --format docx \
    --dpi 300

Command Line Arguments

Argument	Description	Example
--input	Input file/pattern	document.jpg, "*.png"
--output	Output file	result.txt
--output-dir	Output directory	./results/
--engine	OCR engine	tesseract, easyocr, auto
--language	Language codes	eng, eng+fra, en,fr,de
--confidence	Confidence threshold	0.5 to 1.0
--format	Output format	txt, docx, pdf, json
--dpi	Target DPI	150, 300, 600
--preprocessing	Enable preprocessing	Flag (no value)
--batch-size	Batch processing size	5, 10, 20
--threads	Number of threads	1, 4, 8

🔧 Python API

Basic OCR

from ocr_engine import OCREngine

# Initialize OCR engine
ocr = OCREngine(engine='tesseract', language='eng')

# Process single file
result = ocr.extract_text('document.jpg')
print(result.text)

# Save to file
ocr.save_result(result, 'output.txt', format='txt')

Advanced Usage

from ocr_engine import OCREngine, OCRConfig

# Custom configuration
config = OCRConfig(
    engine='easyocr',
    languages=['en', 'fr'],
    confidence_threshold=0.8,
    preprocessing=True,
    dpi=300
)

# Initialize with config
ocr = OCREngine(config=config)

# Batch processing
files = ['doc1.jpg', 'doc2.png', 'doc3.pdf']
results = ocr.process_batch(files)

for file, result in results.items():
    print(f"{file}: {result.confidence:.2f}")
    ocr.save_result(result, f"{file}.txt")

Error Handling

from ocr_engine import OCREngine, OCRError

try:
    ocr = OCREngine()
    result = ocr.extract_text('document.jpg')
    
    if result.confidence < 0.5:
        print("Warning: Low confidence OCR result")
    
except OCRError as e:
    print(f"OCR Error: {e}")
except FileNotFoundError:
    print("Input file not found")
except Exception as e:
    print(f"Unexpected error: {e}")

---

📁 Project Structure

ocr_document_converter/
├── 📁 ocr_engine/                    # Core OCR engine modules
│   ├── __init__.py                   # Package initialization
│   ├── ocr_engine.py                 # Main OCR engine class
│   ├── ocr_engine_minimal.py         # Lightweight OCR implementation
│   ├── image_processor.py            # Image preprocessing utilities
│   ├── format_detector.py            # File format detection
│   └── ocr_integration.py            # Integration layer
│
├── 📁 gui/                           # GUI components
│   ├── universal_document_converter_ocr.py      # Main GUI application
│   ├── universal_document_converter_enhanced.py # Enhanced GUI features
│   └── ocr_gui_integration.py        # GUI-OCR integration
│
├── 📁 tests/                         # Test suite
│   ├── test_ocr_integration.py       # Integration tests
│   ├── validate_ocr_integration.py   # Validation scripts
│   └── test_data/                    # Sample test files
│       ├── sample_document.jpg
│       ├── multi_language.png
│       └── low_quality.pdf
│
├── 📁 config/                        # Configuration files
│   ├── tesseract_config.json         # Tesseract settings
│   ├── easyocr_config.json          # EasyOCR settings
│   ├── gui_settings.json            # GUI preferences
│   └── language_config.json         # Language settings
│
├── 📁 output/                        # Default output directory
├── 📁 temp/                          # Temporary processing files
├── 📁 cache/                         # OCR result cache
├── 📁 logs/                          # Application logs
│
├── 📄 requirements.txt               # Python dependencies
├── 📄 setup_ocr_environment.py       # Automated setup script
├── 📄 README.md                      # This comprehensive guide
├── 📄 OCR_README.md                  # Technical OCR documentation
├── 📄 OCR_INTEGRATION_COMPLETE.md    # Integration completion notes
├── 📄 .gitignore                     # Git ignore rules
└── 📄 LICENSE                        # MIT License

📋 Key Files Description

File	Purpose	Key Features
ocr_engine/ocr_engine.py	Main OCR processing	Dual engine support, batch processing
universal_document_converter_ocr.py	GUI application	Drag-drop, settings panel, progress tracking
setup_ocr_environment.py	Automated installer	Dependencies, Tesseract, language packs
test_ocr_integration.py	Comprehensive tests	Unit tests, integration tests, benchmarks
validate_ocr_integration.py	Validation suite	System validation, performance tests
requirements.txt	Dependencies	All Python packages with versions

---

🧪 Testing & Validation

🔬 Run Test Suite

# Run all tests
python test_ocr_integration.py

# Run validation suite
python validate_ocr_integration.py

# Run specific test categories
python test_ocr_integration.py --category unit
python test_ocr_integration.py --category integration
python test_ocr_integration.py --category performance

📊 Test Coverage

• Unit Tests: 45+ individual component tests
• Integration Tests: End-to-end OCR workflows
• Performance Tests: Speed and memory benchmarks
• Language Tests: Multi-language OCR accuracy
• Format Tests: All supported input/output formats
• Error Handling: Exception and edge case testing

🎯 Benchmarks

Test Category	Files Tested	Success Rate	Avg. Processing Time
English Text	100+	98.5%	2.3s per page
Multi-Language	50+	95.2%	3.1s per page
Low Quality	30+	87.8%	4.2s per page
Batch Processing	500+	97.1%	1.8s per page

---

📥 Download Options

1️⃣ Complete Application Package (Recommended)

File: Universal-Document-Converter-v3.1.0-Windows-Complete.zip (59 KB)

Contains EVERYTHING including:

• ✅ Full GUI application with OCR
• ✅ CLI interface (cli.py)
• ✅ OCR engines (Tesseract & EasyOCR support)
• ✅ VFP9/VB6 integration (DLL package included)
• ✅ All documentation
• ✅ Automated installer

# Download from GitHub Releases
https://github.com/Beaulewis1977/quick_ocr_doc_converter/releases/latest/download/Universal-Document-Converter-v2.1.0-Windows-Complete.zip

2️⃣ 32-bit DLL Package (VFP9/VB6 Only)

File: UniversalConverter32.dll.zip (12 KB)

For users who ONLY need VFP9/VB6 integration:

• 📦 Lightweight download
• 📁 DLL wrapper files
• 📝 VFP9/VB6 example code
• 📚 Integration documentation
• 🔧 Batch DLL simulator

# Download DLL package only
https://github.com/Beaulewis1977/quick_ocr_doc_converter/releases/latest/download/UniversalConverter32.dll.zip

🛠️ Installation Methods

🚀 Method 1: From Complete Package

1. Download the complete package
2. Extract to any folder
3. Run install.bat as Administrator
4. Launch using desktop shortcut or run_ocr_converter.bat

🚀 Method 2: From Source (Development)

# Clone and setup in one command
git clone https://github.com/Beaulewis1977/quick_ocr_document_converter.git
cd quick_ocr_document_converter
python setup_ocr_environment.py

🔧 Method 2: Manual Installation

Step 1: Python Environment

# Create virtual environment (recommended)
python -m venv ocr_env
source ocr_env/bin/activate  # Linux/Mac
# or
ocr_env\Scripts\activate     # Windows

# Install Python dependencies
pip install -r requirements.txt

Step 2: Tesseract OCR

Windows:

# Download and install from:
# https://github.com/UB-Mannheim/tesseract/wiki
# Add to PATH: C:\Program Files\Tesseract-OCR

macOS:

# Using Homebrew
brew install tesseract

# Install language packs
brew install tesseract-lang

Linux (Ubuntu/Debian):

# Install Tesseract
sudo apt-get update
sudo apt-get install tesseract-ocr

# Install language packs
sudo apt-get install tesseract-ocr-eng tesseract-ocr-fra tesseract-ocr-deu

Linux (CentOS/RHEL):

# Install Tesseract
sudo yum install epel-release
sudo yum install tesseract tesseract-langpack-eng

Step 3: EasyOCR Dependencies

# Install PyTorch (CPU version)
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu

# For GPU support (optional)
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

🐳 Method 3: Docker Installation

# Dockerfile
FROM python:3.9-slim

# Install system dependencies
RUN apt-get update && apt-get install -y \
    tesseract-ocr \
    tesseract-ocr-eng \
    tesseract-ocr-fra \
    tesseract-ocr-deu \
    libgl1-mesa-glx \
    libglib2.0-0

# Copy application
COPY . /app
WORKDIR /app

# Install Python dependencies
RUN pip install -r requirements.txt

# Run application
CMD ["python", "universal_document_converter_ocr.py"]

# Build and run Docker container
docker build -t ocr-converter .
docker run -p 8080:8080 -v $(pwd)/output:/app/output ocr-converter

---

🔧 Troubleshooting

❗ Common Issues

Tesseract Not Found

# Error: TesseractNotFoundError
# Solution: Add Tesseract to PATH
export PATH=$PATH:/usr/local/bin/tesseract  # Linux/Mac
# or add C:\Program Files\Tesseract-OCR to Windows PATH

Low OCR Accuracy

# Try different preprocessing options
config = {
    "preprocessing": {
        "denoise": True,
        "contrast_enhance": True,
        "rotation_correction": True,
        "dpi_optimization": True
    }
}

Memory Issues

# Reduce batch size and enable memory optimization
config = {
    "batch_size": 1,
    "memory_limit": "1GB",
    "enable_gc": True
}

Language Detection Issues

# Specify languages explicitly
config = {
    "language": "eng+fra+deu",  # Multiple languages
    "auto_detect": False
}

📋 Debug Mode

# Enable debug logging
export OCR_DEBUG=1
python universal_document_converter_ocr.py --debug

# Check log files
tail -f logs/ocr_debug.log

🆘 Getting Help

1. Check the logs: logs/ocr_application.log
2. Run validation: python validate_ocr_integration.py
3. Test with sample files: Use files in tests/test_data/
4. Create an issue: GitHub Issues

---

🤝 Contributing

🌟 How to Contribute

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes and add tests
4. Run the test suite: python test_ocr_integration.py
5. Commit your changes: git commit -m 'Add amazing feature'
6. Push to the branch: git push origin feature/amazing-feature
7. Open a Pull Request

🎯 Areas for Contribution

• New OCR Engines: Add support for additional OCR backends
• Language Support: Add new language models and detection
• Image Processing: Improve preprocessing algorithms
• GUI Enhancements: Add new features to the user interface
• Performance: Optimize processing speed and memory usage
• Documentation: Improve guides and API documentation
• Testing: Add more test cases and benchmarks

📝 Development Setup

# Clone your fork
git clone https://github.com/YOUR_USERNAME/quick_ocr_document_converter.git
cd quick_ocr_document_converter

# Create development environment
python -m venv dev_env
source dev_env/bin/activate

# Install development dependencies
pip install -r requirements.txt
pip install -r requirements-dev.txt

# Run tests
python -m pytest tests/

# Run linting
flake8 ocr_engine/
black ocr_engine/

🏷️ Code Style

• Follow PEP 8 Python style guidelines
• Use Black for code formatting
• Add docstrings to all functions and classes
• Write comprehensive tests for new features
• Update documentation for any changes

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🙏 Acknowledgments

• Tesseract OCR - Google's open-source OCR engine
• EasyOCR - JaidedAI's neural network OCR
• OpenCV - Computer vision library for image processing
• PyTorch - Machine learning framework for EasyOCR
• Tkinter - Python's standard GUI toolkit

---

🤝 Support Open Source

Building and maintaining OCR Document Converter takes time and resources. While the tool is completely free, your voluntary support helps ensure continued development and improvements.

If this tool has saved you time or added value to your work, consider showing your appreciation:

Venmo: @BeauinTulsa
Ko-fi: https://ko-fi.com/beaulewis

Together, we're making document conversion accessible to everyone. Thank you! 💪

---

📞 Support

• Documentation: OCR_README.md
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: Create an issue for support

---

Made with ❤️ for the OCR community

⭐ Star this repository if it helped you! ⭐

📦 Create Standalone Executable (No Python Required)

1. Double-click create_executable.py
2. Wait for compilation (creates a single .exe file)
3. Share the .exe - works on any Windows computer without Python!

⚡ Manual Launch (Advanced Users)

python universal_document_converter.py

---

✨ Features

🚀 Core Conversion Features

• 📄 Universal Format Support: Convert between 6 input and 5 output formats (30 combinations)
• ⚡ Lightning Fast: Multi-threaded processing with intelligent caching
• 🖱️ Drag & Drop: Intuitive interface with enhanced file/folder drag-and-drop
• 📁 Batch Processing: Convert entire folders recursively with progress tracking
• 🎯 Smart Detection: Automatic file format detection with fallback support
• 🔧 Zero APIs: Works completely offline without external dependencies

⚙️ Enterprise Configuration Management

• 🛠️ Advanced Settings: Comprehensive configuration system with GUI settings panel
• 💾 Settings Persistence: Automatic saving of user preferences and window positions
• 📋 Profile Management: Multiple configuration profiles for different use cases
• 🔄 Import/Export: Share configurations between installations
• ⚡ CLI Configuration: Full command-line configuration support with profiles

🏗️ Performance & Reliability

• 🚀 Multi-Threading: 2-4x performance improvement with configurable worker threads
• 🧠 Intelligent Caching: Prevents redundant conversions of unchanged files
• 📊 Memory Optimization: 50-80% memory reduction for large files through streaming
• 📈 Real-time Progress: Visual progress tracking with detailed conversion results
• 🔍 Professional Logging: Enterprise-grade logging system with file rotation

🌍 Cross-Platform Excellence

• 🖥️ Native Windows Integration: Start Menu shortcuts, taskbar pinning, registry file associations
• 🐧 Linux Desktop Integration: .desktop files, MIME types, applications menu, file manager integration
• 🍎 macOS App Bundle: Native .app bundles, Dock integration, Finder associations, Spotlight search
• 📦 Universal Packaging: .deb, .rpm, AppImage, .dmg, .pkg, and .msi installers
• 🔧 Platform Detection: Automatic platform-specific paths and configurations

🎨 User Experience

• 🖥️ Modern GUI: Clean, responsive interface with tabbed settings
• 🔗 Desktop Integration: Native shortcuts and file associations on all platforms
• 📖 File Opening: Built-in file opening with default applications
• 🎯 Drag & Drop: Enhanced file and folder drag-and-drop support
• 🔒 Privacy First: All processing happens locally on your machine

---

📄 Supported Formats

Input Formats (6)	Output Formats (5)
DOCX - Microsoft Word Documents	Markdown - GitHub-flavored markdown
PDF - Portable Document Format	TXT - Plain text with formatting
TXT - Plain text files	HTML - Clean, semantic HTML
HTML - Web pages and documents	RTF - Rich Text Format
RTF - Rich Text Format	EPUB - Electronic Publication (eBooks)
EPUB - Electronic Publication (eBooks)

Total Conversion Combinations: 30 (6 × 5)

📚 EPUB Support Features

• 📖 Full EPUB Reading: Extracts text