GutenOCR Application

A comprehensive OCR application powered by GutenOCR Vision Language Models with CPU/GPU support, featuring a user-friendly interface and combined Docling integration.

🌟 Features

• Multiple Models: Support for GutenOCR-3B (faster) and GutenOCR-7B (more accurate)
• CPU/GPU Support: Works on both CPU and GPU (GPU recommended for speed)
• Dual Web Interfaces:
  • Standard GutenOCR UI for OCR tasks
  • Dedicated Docling + GutenOCR UI for advanced document processing
• Batch Processing: Process entire directories recursively
• Combined Processing: Integration with Docling for enhanced document processing
• Document Structure Extraction: Extract tables, layouts, and document structure
• Flexible Tasks: Reading, detection, localized reading, conditional detection
• Multiple Output Formats: TEXT, TEXT2D, LINES, WORDS, PARAGRAPHS, LATEX, BOX
• Multi-Format Support: PDF, DOCX, PPTX, images, HTML, Markdown
• Timestamped Output: All results saved with timestamps
• Docker Support: Ready-to-use Docker containers for CPU and GPU
• Kubernetes Ready: Complete K8s deployment configurations
• Automation Scripts: Automated start, stop, and GitHub push scripts

📋 Table of Contents

• Installation
• Quick Start
• Usage
• Architecture
• Docker Deployment
• Kubernetes Deployment
• API Reference
• Configuration
• Troubleshooting
• Contributing
• License

🚀 Installation

Prerequisites

• Python 3.10 or higher
• pip or uv package manager
• (Optional) CUDA-capable GPU for faster processing
• (Optional) Docker for containerized deployment
• (Optional) Kubernetes cluster for production deployment

Local Installation

1. Clone the repository:

git clone https://github.com/YOUR_USERNAME/GutenOCR-Test.git
cd GutenOCR-Test

2. Create a virtual environment:

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

pip install -r requirements.txt

🎯 Quick Start

Option 1: Standard GutenOCR UI

Start the standard OCR web interface:

./scripts/start.sh --mode gradio

Access the UI at: http://localhost:7860

Option 2: Docling + GutenOCR UI (NEW! 🎉)

Start the advanced document processing interface:

./scripts/start.sh --mode docling-ui

Access the UI at: http://localhost:7861

Features:

• Document structure extraction with Docling
• Table detection and extraction
• High-quality OCR with GutenOCR
• Support for PDF, DOCX, PPTX, and images
• Combined processing modes

Option 3: Command Line (Combined Processor)

Process documents directly:

./scripts/start.sh --mode combined

Option 4: Docker

Start with Docker (CPU):

./scripts/start.sh --mode docker-cpu

Start with Docker (GPU):

./scripts/start.sh --mode docker-gpu

📖 Usage

Standard GutenOCR UI

Purpose: Fast OCR processing for images

1. Setup Tab: Initialize the model

   • Select model (3B or 7B)
   • Choose CPU or GPU
   • Click "Initialize Model"

2. Single Image Tab: Process individual images

   • Upload an image
   • Select task type and output format
   • Click "Process Image"

3. Batch Processing Tab: Process multiple images

   • Place images in ./input directory
   • Select processing options
   • Click "Start Batch Processing"
   • Results saved to ./output directory

Docling + GutenOCR Combined UI (NEW!)

Purpose: Advanced document processing with structure extraction

Access: http://localhost:7861

1. Setup Tab: Initialize the combined processor

   • Select model (3B or 7B)
   • Choose CPU or GPU
   • Enable/disable Docling integration
   • Click "Initialize Processor"
   • View processor capabilities

2. Single Document Tab: Process individual documents

   • Upload a document (PDF, DOCX, PPTX, or image)
   • Configure processing options:
     • Extract Structure: Use Docling to extract document structure
     • Extract Tables: Detect and extract tables from documents
     • Perform OCR: Use GutenOCR for text extraction
   • Click "Process Document"
   • View extracted content and download results

3. Batch Processing Tab: Process multiple documents

   • Place documents in ./input directory
   • Configure processing options
   • Click "Start Batch Processing"
   • View processing summary
   • Results saved to ./output directory with detailed JSON

4. Help Tab: Comprehensive usage guide and troubleshooting

Supported Formats:

• PDF, DOCX, PPTX (with Docling)
• PNG, JPG, JPEG, TIFF, BMP, GIF, WEBP (images)
• HTML, Markdown (with Docling)

Processing Modes:

• Combined: Uses both Docling (structure) and GutenOCR (OCR)
• Docling Only: Structure extraction without OCR
• GutenOCR Only: OCR without structure extraction

Command Line Interface

Process Single Image

from src.gutenocr_engine import GutenOCREngine

engine = GutenOCREngine(
    model_id="rootsautomation/GutenOCR-3B",
    use_cpu=False  # Set to True for CPU
)

result = engine.process_image(
    image_path="path/to/image.png",
    task_type="reading",
    output_format="TEXT"
)

print(result['text'])

Batch Processing

from src.gutenocr_engine import GutenOCREngine
from src.file_processor import FileProcessor

engine = GutenOCREngine()
processor = FileProcessor()

# Discover images
images = processor.discover_images(recursive=True)

# Process batch
results = engine.batch_process(images)

# Save results
processor.save_results(results, format="json")

Combined Docling + GutenOCR (CLI)

# Command line processing
python src/docling_gutenocr_combined.py \
    --input ./input \
    --output ./output \
    --model rootsautomation/GutenOCR-3B

# Or use the start script
./scripts/start.sh --mode combined

Combined Docling + GutenOCR (Python API)

from src.docling_gutenocr_combined import DoclingGutenOCRProcessor

# Initialize processor
processor = DoclingGutenOCRProcessor(
    gutenocr_model="rootsautomation/GutenOCR-3B",
    use_cpu=False,
    use_docling=True
)

# Process single document
result = processor.process_document(
    file_path="document.pdf",
    extract_structure=True,
    extract_tables=True,
    ocr_images=True
)

print(result['combined_text'])

# Batch process
results = processor.batch_process(
    input_dir="./input",
    output_dir="./output"
)

🏗️ Architecture

Project Structure

GutenOCR-Test/
├── src/
│   ├── gutenocr_engine.py          # Core OCR engine
│   ├── file_processor.py           # File handling and output management
│   ├── gradio_ui.py                # Standard OCR web interface
│   ├── docling_gradio_ui.py        # Docling + GutenOCR web interface (NEW!)
│   └── docling_gutenocr_combined.py # Combined processor
├── docker/
│   ├── Dockerfile.gutenocr         # CPU Docker image
│   ├── Dockerfile.gutenocr-gpu     # GPU Docker image
│   ├── Dockerfile.combined         # Combined processor image
│   ├── docker-compose.yml          # Docker Compose configuration
│   └── .dockerignore               # Docker ignore file
├── kubernetes/
│   ├── deployment-cpu.yaml         # CPU deployment
│   ├── deployment-gpu.yaml         # GPU deployment
│   ├── persistent-volumes.yaml     # Storage configuration
│   ├── configmap.yaml              # Configuration
│   └── ingress.yaml                # Ingress rules
├── scripts/
│   ├── start.sh                    # Start script
│   ├── stop.sh                     # Stop script
│   └── push-to-github.sh           # GitHub automation
├── input/                          # Input images directory
├── output/                         # Output results directory
├── docs/                           # Documentation
├── tests/                          # Test files
├── requirements.txt                # Python dependencies
└── README.md                       # This file

Component Overview

See Architecture Documentation for detailed information.

🐳 Docker Deployment

Build Images

# CPU version
docker build -f docker/Dockerfile.gutenocr -t gutenocr:cpu-latest .

# GPU version
docker build -f docker/Dockerfile.gutenocr-gpu -t gutenocr:gpu-latest .

# Combined processor
docker build -f docker/Dockerfile.combined -t gutenocr:combined-latest .

Run Containers

# CPU version
docker run -d \
    --name gutenocr-cpu \
    -p 7860:7860 \
    -v $(pwd)/input:/app/input \
    -v $(pwd)/output:/app/output \
    gutenocr:cpu-latest

# GPU version (requires nvidia-docker)
docker run -d \
    --name gutenocr-gpu \
    --gpus all \
    -p 7860:7860 \
    -v $(pwd)/input:/app/input \
    -v $(pwd)/output:/app/output \
    gutenocr:gpu-latest

Docker Compose

# Start CPU version
docker-compose -f docker/docker-compose.yml up -d gutenocr-cpu

# Start GPU version
docker-compose -f docker/docker-compose.yml up -d gutenocr-gpu

# Start combined processor
docker-compose -f docker/docker-compose.yml --profile batch up combined-processor

☸️ Kubernetes Deployment

Prerequisites

• Kubernetes cluster (1.20+)
• kubectl configured
• (Optional) NVIDIA GPU Operator for GPU support

Deploy to Kubernetes

# Deploy using automation script
./scripts/start.sh --mode k8s

# Or manually:
kubectl apply -f kubernetes/persistent-volumes.yaml
kubectl apply -f kubernetes/configmap.yaml
kubectl apply -f kubernetes/deployment-cpu.yaml
kubectl apply -f kubernetes/deployment-gpu.yaml
kubectl apply -f kubernetes/ingress.yaml

Check Deployment Status

# Check pods
kubectl get pods -l app=gutenocr

# Check services
kubectl get services -l app=gutenocr

# View logs
kubectl logs -f deployment/gutenocr-cpu

Scale Deployment

# Scale CPU deployment
kubectl scale deployment gutenocr-cpu --replicas=3

# Scale GPU deployment
kubectl scale deployment gutenocr-gpu --replicas=2

📚 API Reference

GutenOCREngine

class GutenOCREngine:
    def __init__(
        self,
        model_id: str = "rootsautomation/GutenOCR-3B",
        device: str = "auto",
        use_cpu: bool = False,
        torch_dtype: Optional[torch.dtype] = None
    )
    
    def process_image(
        self,
        image_path: str,
        task_type: str = "reading",
        output_format: str = "TEXT",
        max_new_tokens: int = 4096,
        custom_prompt: Optional[str] = None
    ) -> Dict[str, Any]
    
    def batch_process(
        self,
        image_paths: List[str],
        task_type: str = "reading",
        output_format: str = "TEXT",
        max_new_tokens: int = 4096
    ) -> List[Dict[str, Any]]

Task Types

• reading: Extract all text from the image
• detection: Locate text regions without transcription
• localized_reading: Read text in specific regions
• conditional_detection: Find specific text queries

Output Formats

• TEXT: Plain text, linearized
• TEXT2D: Layout-preserving text
• LINES: Line-by-line with bounding boxes
• WORDS: Word-by-word with bounding boxes
• PARAGRAPHS: Paragraph-wise with bounding boxes
• LATEX: LaTeX expressions with bounding boxes
• BOX: Bounding boxes only (for detection)

⚙️ Configuration

Environment Variables

# Model configuration
GUTENOCR_MODEL=rootsautomation/GutenOCR-3B
GUTENOCR_USE_CPU=false

# Server configuration
GRADIO_SERVER_NAME=0.0.0.0
GRADIO_SERVER_PORT=7860

# Processing configuration
MAX_NEW_TOKENS=4096
DEFAULT_TASK_TYPE=reading
DEFAULT_OUTPUT_FORMAT=TEXT

Model Selection

• GutenOCR-3B: Faster, lower memory requirements (~6GB VRAM)
• GutenOCR-7B: More accurate, higher memory requirements (~14GB VRAM)

CPU vs GPU

GPU (Recommended):

• Faster processing (10-50x speedup)
• Requires CUDA-capable GPU
• Higher memory requirements

CPU:

• Slower processing
• Works on any machine
• Lower memory requirements
• Set use_cpu=True in engine initialization

🔧 Troubleshooting

Common Issues

Out of Memory Error

Solution: Use GutenOCR-3B instead of 7B, or enable CPU mode

CUDA Not Available

Solution: Install CUDA toolkit or use CPU mode with --cpu flag

Model Download Fails

Solution: Check internet connection and HuggingFace access
Set HF_TOKEN environment variable if needed

Port Already in Use

Solution: Change port in environment variables or stop conflicting service

Performance Optimization

1. Use GPU: Significantly faster than CPU
2. Batch Processing: More efficient for multiple images
3. Model Selection: Use 3B for speed, 7B for accuracy
4. Image Size: Resize large images before processing

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

📄 License

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

The GutenOCR model weights are licensed under CC-BY-NC.

🙏 Acknowledgments

• GutenOCR - Original OCR models
• Qwen2.5-VL - Base vision-language model
• Docling - Document processing
• Gradio - Web interface framework

📞 Support

• Documentation: docs/
• Issues: GitHub Issues
• Discussions: GitHub Discussions

🗺️ Roadmap

• Add support for more languages
• Implement real-time OCR streaming
• Add REST API endpoint
• Improve batch processing performance
• Add more output formats
• Implement caching mechanism
• Add monitoring and metrics

---

Built with ❤️ using GutenOCR