bangla-ocr 1.0.3

Best Bangla/Bengali OCR - Transformer-based text recognition for handwritten & printed Bangla. Works on Colab, Kaggle, local. Zero dependency conflicts.

Bangla OCR 🇧🇩

The Best Bangla/Bengali OCR Package - Recognize Bangla text from images with zero dependency conflicts!

✨ Why Bangla OCR?

• 🔤 Accurate: State-of-the-art Transformer architecture for Bangla text recognition
• 🚀 Zero Conflicts: Works with ANY version of PyTorch, NumPy - no dependency hell!
• ☁️ Cloud Ready: Works instantly on Google Colab, Kaggle, AWS, GCP, Azure
• 💻 Cross-Platform: Windows, Linux, macOS, Apple Silicon (M1/M2/M3/M4)
• 🎯 Smart Fallbacks: Works even without OpenCV (uses PIL as fallback)
• 📥 Multiple Inputs: Accepts file paths, PIL Images, numpy arrays, URLs, and bytes
• ⚡ Fast: GPU acceleration with CUDA and Apple MPS support

📦 Installation

pip install bangla-ocr

That's it! Works everywhere - Colab, Kaggle, local, Docker, cloud!

Optional: With OpenCV (slightly better preprocessing)

pip install bangla-ocr[cv-headless]  # Recommended for servers/Colab/Kaggle
pip install bangla-ocr[cv]           # For local development with GUI
pip install bangla-ocr[full]         # Everything included

🚀 Quick Start

from bangla_ocr import BanglaOCR

# Initialize (automatically downloads model on first run)
ocr = BanglaOCR()

# Recognize text from an image
text = ocr.recognize('bangla_image.jpg')
print(text)  # Output: বাংলা টেক্সট

📖 Usage Examples

From File Path

text = ocr.recognize('path/to/image.jpg')

From PIL Image

from PIL import Image
img = Image.open('image.png')
text = ocr.recognize(img)

From NumPy Array

import numpy as np
arr = np.array(Image.open('image.jpg'))
text = ocr.recognize(arr)

From URL

text = ocr.recognize('https://example.com/bangla_image.jpg')

From Bytes

with open('image.jpg', 'rb') as f:
    img_bytes = f.read()
text = ocr.recognize(img_bytes)

Batch Prediction

texts = ocr.predict_batch(
    ['img1.jpg', 'img2.jpg', 'img3.jpg'],
    show_progress=True
)
for text in texts:
    print(text)

🔧 Advanced Configuration

Check System Status

from bangla_ocr import check_dependencies, print_info

# Print formatted info
print_info()

# Get dependency status
status = check_dependencies()
print(status)
# {'torch': True, 'cuda': True, 'mps': False, 'opencv': True, ...}

Device Selection

# Auto-detect best device (default)
ocr = BanglaOCR()

# Force specific device
ocr = BanglaOCR(device='cpu')   # CPU
ocr = BanglaOCR(device='cuda')  # NVIDIA GPU
ocr = BanglaOCR(device='mps')   # Apple Silicon

Custom Model Parameters

ocr = BanglaOCR(
    model_path='custom_model.pth',
    tokenizer_path='tokenizer.pk',
    d_model=256,           # Hidden dimension
    nheads=4,              # Attention heads
    num_decoder_layers=4   # Decoder layers
)

Get Model Info

ocr = BanglaOCR()
print(ocr.info)
# {'version': '1.0.0', 'device': 'cuda', 'd_model': 256, ...}

🏗️ Architecture

Input Image → ResNet-18 (CNN Encoder) → Transformer Decoder → Bangla Text

• Encoder: ResNet-18 backbone for visual feature extraction
• Positional Encoding: Sine encodings for spatial information
• Decoder: Transformer with multi-head attention
• Output: Character-level Bangla vocabulary

📋 Requirements

Package	Version	Notes
Python	≥ 3.8	3.9-3.12 recommended
PyTorch	≥ 1.9.0	Any version works
torchvision	≥ 0.10.0	Any version works
NumPy	≥ 1.19.0	Any version works
Pillow	≥ 8.0.0	Always used
OpenCV	Optional	PIL fallback available

🌍 Platform Compatibility

Platform	Status	Acceleration
Google Colab	✅ Perfect	CUDA
Kaggle	✅ Perfect	CUDA/TPU
Windows 10/11	✅ Perfect	CUDA
Linux (Ubuntu, etc.)	✅ Perfect	CUDA
macOS Intel	✅ Perfect	CPU
macOS Apple Silicon	✅ Perfect	MPS
Docker	✅ Perfect	CUDA
AWS/GCP/Azure	✅ Perfect	CUDA

🏋️ Training

Install training dependencies:

pip install bangla-ocr[train]

See the training guide for details.

📚 Citation

@inproceedings{ghosh2023bangla,
  title={Towards Full-page Offline Bangla Handwritten Text Recognition},
  author={Ghosh, A.},
  booktitle={IEEE SILCON},
  year={2023}
}

📄 License

MIT License - see LICENSE for details.

🤝 Contributing

Contributions welcome! Please submit a Pull Request.