README.md

---
title: LCR OCR API
emoji: 📄
colorFrom: blue
colorTo: green
sdk: docker
app_file: app.py
pinned: false
---

# Local Civil Registry Document Digitization and Data Extraction

## Using CRNN+CTC, Multinomial Naive Bayes, and Named Entity Recognition

**Thesis Project by:**
- Shane Mark C. Blanco
- Princess A. Pasamonte  
- Irish Faith G. Ramirez

**Institution:** Tarlac State University, College of Computer Studies

---

## 📋 Project Overview

This system automates the digitization and data extraction of Philippine Civil Registry documents using advanced machine learning algorithms:

### Target Documents:
- **Form 1A** - Birth Certificate
- **Form 2A** - Death Certificate
- **Form 3A** - Marriage Certificate
- **Form 90** - Application of Marriage License

### Key Features:
✅ OCR for printed and handwritten text  
✅ Automatic document classification  
✅ Named entity extraction (names, dates, places)  
✅ Auto-fill digital forms  
✅ MySQL database storage  
✅ Searchable digital archive  
✅ Data visualization dashboard  

---

## 🏗️ System Architecture

```
Input: Scanned Civil Registry Form
    ↓
1. Image Preprocessing
    ↓
2. CRNN+CTC → Text Recognition
    ↓
3. Multinomial Naive Bayes → Document Classification
    ↓
4. spaCy NER → Entity Extraction
    ↓
5. Data Validation & Storage → MySQL Database
    ↓
Output: Digitized & Searchable Record
```

---

## 🚀 Quick Start

### Prerequisites

- Python 3.8+
- CUDA-capable GPU (recommended) or CPU
- 8GB RAM minimum

### Installation

```bash
# 1. Clone or download the project
cd civil_registry_ocr

# 2. Create virtual environment
python -m venv venv
source venv/bin/activate  # Linux/Mac
venv\Scripts\activate     # Windows

# 3. Install dependencies
pip install -r requirements.txt

# 4. Download spaCy model
python -m spacy download en_core_web_sm
```

### Quick Test

```python
from inference import CivilRegistryOCR

# Load model
ocr = CivilRegistryOCR('checkpoints/best_model.pth')

# Recognize text
text = ocr.predict('test_images/sample_name.jpg')
print(f"Recognized: {text}")
```

---

## 📁 Project Files

### Core Implementation Files:

1. **crnn_model.py** - CRNN+CTC neural network architecture
2. **dataset.py** - Data loading and preprocessing  
3. **train.py** - Model training script
4. **inference.py** - Prediction and inference
5. **utils.py** - Helper functions and metrics
6. **requirements.txt** - Python dependencies
7. **IMPLEMENTATION_GUIDE.md** - Detailed implementation guide

### Additional Components (To be created):

8. **document_classifier.py** - Multinomial Naive Bayes classifier
9. **ner_extractor.py** - Named Entity Recognition
10. **web_app.py** - Web application (Flask/FastAPI)
11. **database.py** - MySQL integration

---

## 📊 Training the Model

### 1. Prepare Your Data

Organize images and labels:
```
data/
  train/
    form1a/
      name_001.jpg
      name_001.txt
    form2a/
      ...
  val/
    ...
```

### 2. Create Annotations

```python
from dataset import create_annotation_file

create_annotation_file('data/train', 'data/train_annotations.json')
create_annotation_file('data/val', 'data/val_annotations.json')
```

### 3. Train Model

```bash
python train.py
```

Monitor metrics:
- Character Error Rate (CER)
- Word Error Rate (WER)  
- Training/Validation Loss

### 4. Evaluate

```python
from utils import calculate_cer, calculate_wer

predictions = [ocr.predict(img) for img in test_images]
cer = calculate_cer(predictions, ground_truths)
print(f"CER: {cer:.2f}%")
```

---

## 🌐 Web Application

### Start the Server

```bash
python web_app.py
```

### API Endpoints

**POST /api/ocr** - Process document
```bash
curl -X POST -F "file=@birth_cert.jpg" http://localhost:8000/api/ocr
```

**Response:**
```json
{
  "text": "Juan Dela Cruz\n01/15/1990\nTarlac City",
  "form_type": "form1a",
  "entities": {
    "persons": ["Juan Dela Cruz"],
    "dates": ["01/15/1990"],
    "locations": ["Tarlac City"]
  }
}
```

---

## 🎯 Expected Performance

Based on thesis objectives:

### CRNN+CTC Model:
- **Target CER:** < 5%
- **Target Accuracy:** > 95%
- Handles both printed and handwritten text

### Document Classifier (MNB):
- **Target Accuracy:** > 90%
- Fast classification (< 100ms)

### NER (spaCy):
- **F1 Score:** > 85%
- Extracts: Names, Dates, Places

---

## 🧪 Testing

### ISO 25010 Evaluation

**Usability Testing:**
```python
# Metrics to measure:
- Task completion rate
- Average time per task
- User satisfaction score (SUS)
```

**Reliability Testing:**
```python
# Metrics to measure:
- System uptime %
- Error rate
- Recovery time
```

### Confusion Matrix

```python
from sklearn.metrics import confusion_matrix
import seaborn as sns

cm = confusion_matrix(true_labels, predicted_labels)
sns.heatmap(cm, annot=True)
```

---

## 💾 Database Schema

### Birth Certificates Table
```sql
CREATE TABLE birth_certificates (
    id INT PRIMARY KEY AUTO_INCREMENT,
    child_name VARCHAR(255),
    date_of_birth DATE,
    place_of_birth VARCHAR(255),
    sex CHAR(1),
    father_name VARCHAR(255),
    mother_name VARCHAR(255),
    raw_text TEXT,
    form_image LONGBLOB,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

---

## 📈 System Requirements

### Minimum:
- CPU: Intel i5 or equivalent
- RAM: 8GB
- Storage: 10GB
- OS: Windows 10, Ubuntu 18.04, macOS 10.14

### Recommended:
- CPU: Intel i7 or equivalent
- GPU: NVIDIA GTX 1060 or better
- RAM: 16GB
- Storage: 50GB SSD

---

## 🔒 Data Privacy & Security

Following Philippine Data Privacy Act (RA 10173):

- ✅ Encrypted data transmission
- ✅ Access control and authentication
- ✅ Audit logging
- ✅ Regular security updates
- ✅ Data retention policies

---

## 📚 Key Algorithms

### 1. CRNN+CTC
**Purpose:** Text recognition from images  
**Strengths:** Handles variable-length sequences, no character segmentation needed  
**Reference:** Shi et al. (2016)

### 2. Multinomial Naive Bayes
**Purpose:** Document classification  
**Strengths:** Fast, efficient, works well with text data  
**Reference:** McCallum & Nigam (1998)

### 3. Named Entity Recognition
**Purpose:** Extract entities (names, dates, places)  
**Strengths:** Pre-trained, accurate, easy to use  
**Reference:** spaCy (Honnibal & Montani, 2017)

---

## 🛠️ Troubleshooting

### Low Accuracy?
1. Increase training data (target: 10,000+ samples)
2. Use data augmentation
3. Train longer (100+ epochs)
4. Clean your dataset

### Out of Memory?
1. Reduce batch size
2. Use smaller image dimensions
3. Use gradient accumulation
4. Enable mixed precision

### Slow Inference?
1. Use GPU if available
2. Batch process images
3. Optimize model (ONNX)
4. Cache frequent results

---

## 📖 Documentation

- **IMPLEMENTATION_GUIDE.md** - Complete step-by-step guide
- **API_DOCUMENTATION.md** - API reference (to be created)
- **USER_MANUAL.md** - End-user guide (to be created)

---

## 🎓 Academic References

### Key Papers:

1. **CRNN**  
   Shi, B., Bai, X., & Yao, C. (2016). An end-to-end trainable neural network for image-based sequence recognition and its application to scene text recognition. *IEEE TPAMI*.

2. **CTC Loss**  
   Graves, A., et al. (2006). Connectionist temporal classification: Labelling unsegmented sequence data with recurrent neural networks. *ICML*.

3. **Naive Bayes**  
   McCallum, A., & Nigam, K. (1998). A comparison of event models for naive bayes text classification. *AAAI Workshop*.

4. **spaCy**  
   Honnibal, M., & Montani, I. (2017). spaCy 2: Natural language understanding with Bloom embeddings, convolutional neural networks and incremental parsing.

---

## 👥 Contributors

**Researchers:**
- Shane Mark C. Blanco
- Princess A. Pasamonte
- Irish Faith G. Ramirez

**Advisers:**
- Mr. Rengel V. Corpuz (Technical Adviser)
- Mr. Joselito T. Tan (Subject Teacher)

**Institution:**  
Tarlac State University  
College of Computer Studies  
Bachelor of Science in Computer Science

---

## 📞 Support

For questions regarding this implementation:

1. Review IMPLEMENTATION_GUIDE.md
2. Check code documentation
3. Consult with thesis advisers

---

## 📄 License

This project is for academic purposes as part of a thesis requirement.

---

## ✅ Implementation Checklist

### Phase 1: Setup ✓
- [x] Install dependencies
- [x] Set up project structure
- [x] Prepare development environment

### Phase 2: Data Preparation
- [ ] Collect civil registry form images
- [ ] Create annotations
- [ ] Split into train/val/test sets

### Phase 3: Model Development
- [ ] Train CRNN+CTC model
- [ ] Train document classifier
- [ ] Integrate NER system

### Phase 4: Web Application
- [ ] Develop Flask/FastAPI backend
- [ ] Create frontend interface
- [ ] Implement database integration

### Phase 5: Testing
- [ ] Accuracy testing
- [ ] Black-box testing
- [ ] ISO 25010 evaluation
- [ ] User acceptance testing

### Phase 6: Deployment
- [ ] Optimize for production
- [ ] Set up server
- [ ] Deploy application
- [ ] Monitor performance

---

## 🎯 Success Metrics

Target metrics for thesis evaluation:

| Metric | Target | Status |
|--------|--------|--------|
| OCR Accuracy | > 95% | Pending |
| CER | < 5% | Pending |
| Classifier Accuracy | > 90% | Pending |
| NER F1 Score | > 85% | Pending |
| Response Time | < 2s | Pending |
| System Uptime | > 99% | Pending |

---

**Good luck with your thesis defense! 🎓✨**

For detailed implementation instructions, see **IMPLEMENTATION_GUIDE.md**