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.
Requires Python: >=3.8
Keywords: ocr, bangla, bengali, handwriting, text-recognition, transformer, deep-learning, pytorch, colab, kaggle, image-to-text, bangla-ocr, bengali-ocr, optical-character-recognition

# Bangla OCR 🇧🇩

**The Best Bangla/Bengali OCR Package** - Recognize Bangla text from images with zero dependency conflicts!

[![PyPI version](https://badge.fury.io/py/bangla-ocr.svg)](https://badge.fury.io/py/bangla-ocr)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Downloads](https://pepy.tech/badge/bangla-ocr)](https://pepy.tech/project/bangla-ocr)

## ✨ 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

```bash
pip install bangla-ocr
```

That's it! Works everywhere - Colab, Kaggle, local, Docker, cloud!

### Optional: With OpenCV (slightly better preprocessing)
```bash
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

```python
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
```python
text = ocr.recognize('path/to/image.jpg')
```

### From PIL Image
```python
from PIL import Image
img = Image.open('image.png')
text = ocr.recognize(img)
```

### From NumPy Array
```python
import numpy as np
arr = np.array(Image.open('image.jpg'))
text = ocr.recognize(arr)
```

### From URL
```python
text = ocr.recognize('https://example.com/bangla_image.jpg')
```

### From Bytes
```python
with open('image.jpg', 'rb') as f:
    img_bytes = f.read()
text = ocr.recognize(img_bytes)
```

### Batch Prediction
```python
texts = ocr.predict_batch(
    ['img1.jpg', 'img2.jpg', 'img3.jpg'],
    show_progress=True
)
for text in texts:
    print(text)
```

## 🔧 Advanced Configuration

### Check System Status
```python
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
```python
# 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
```python
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
```python
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:
```bash
pip install bangla-ocr[train]
```

See the [training guide](https://github.com/ayan-cs/bangla-ocr-transformer) for details.

## 📚 Citation

```bibtex
@inproceedings{ghosh2023bangla,
  title={Towards Full-page Offline Bangla Handwritten Text Recognition},
  author={Ghosh, A.},
  booktitle={IEEE SILCON},
  year={2023}
}
```

## 📄 License

MIT License - see [LICENSE](LICENSE) for details.

## 🤝 Contributing

Contributions welcome! Please submit a Pull Request.