URDU-OCR-CNN

A full-stack web application for recognizing handwritten Urdu characters using Convolutional Neural Networks (CNN).

🔗 Quick Links

• 📖 Documentation
• 🐛 Report Bug
• 💡 Request Feature
• 🤝 Contributing Guide

---

📑 Table of Contents

• 📝 Description
• ✨ Features
• 🔤 Supported Characters
• 🛠️ Tech Stack
• 📦 Dependencies & Packages
• 📁 Project Structure
• 🚀 Getting Started
• 📊 Training the Model
• 📚 Datasets
• 🔌 API Endpoints
• 🧪 Testing
• 📖 Documentation
• 🤝 Contributing
• 📄 License
• 🛡 Security
• 📏 Code of Conduct
• 🙏 Acknowledgments

---

📝 Description

This application uses deep learning to recognize handwritten Urdu alphabets and digits. Users can either upload images of handwritten characters or draw them directly on a canvas. The CNN model analyzes the input and provides predictions with confidence scores.

✨ Features

• 🖼️ Image Upload: Drag and drop or click to upload images
• ✏️ Drawing Canvas: Draw characters directly in the browser
• 🧠 AI-Powered: CNN model for accurate character recognition
• ⚡ Fast Predictions: Results in milliseconds
• 📊 Top-5 Predictions: View confidence scores for top predictions
• 🌐 RESTful API: Well-documented API endpoints
• 📱 Responsive Design: Works on desktop and mobile
• 🎨 Modern UI: Built with custom CSS styling

🔤 Supported Characters

Urdu Alphabets (36)

ا ب پ ت ٹ ث ج چ ح خ د ڈ ذ ر ڑ ز ژ س ش ص ض ط ظ ع غ ف ق ک گ ل م ن و ہ ی ے

Urdu Digits (10)

۰ ۱ ۲ ۳ ۴ ۵ ۶ ۷ ۸ ۹

🛠️ Tech Stack

Languages

Frameworks & Libraries

Backend:

Frontend:

DevOps / CI / Tools

Testing

---

📦 Dependencies & Packages

Backend Runtime Dependencies

Web Framework & Server

Machine Learning & Data Science

Image Processing

Configuration & Validation

Testing

Frontend Dependencies

Runtime Dependencies

Dev Dependencies

📁 Project Structure

urdu-character-recognition/
│
├── README.md
├── .gitignore
├── docker-compose.yml
│
├── backend/
│   ├── app/
│   │   ├── main.py                 # FastAPI entry point
│   │   ├── config.py               # Configuration
│   │   ├── logger.py               # Custom logger
│   │   ├── api/
│   │   │   ├── dependencies.py
│   │   │   └── routes/
│   │   │       ├── prediction.py
│   │   │       └── health.py
│   │   ├── models/
│   │   │   ├── cnn_model.py
│   │   │   └── schemas.py
│   │   ├── services/
│   │   │   ├── model_service.py
│   │   │   └── image_service.py
│   │   ├── utils/
│   │   │   └── helpers.py
│   │   └── core/
│   │       └── exceptions.py
│   ├── ml/
│   │   ├── train.py
│   │   ├── evaluate.py
│   │   ├── preprocess.py
│   │   ├── augmentation.py
│   │   └── verify_dataset.py
│   ├── data/
│   │   ├── raw/
│   │   │   ├── characters_train_set/
│   │   │   ├── characters_test_set/
│   │   │   ├── digits_train_set/
│   │   │   └── digits_test_set/
│   │   └── processed/
│   ├── saved_models/
│   ├── logs/
│   ├── tests/
│   ├── requirements.txt
│   └── Dockerfile
│
├── frontend/
│   ├── src/
│   │   ├── components/
│   │   │   ├── ImageUploader.tsx
│   │   │   ├── DrawingCanvas.tsx
│   │   │   ├── PredictionResult.tsx
│   │   │   ├── Header.tsx
│   │   │   ├── Footer.tsx
│   │   │   └── LoadingSpinner.tsx
│   │   ├── pages/
│   │   │   ├── HomePage.tsx
│   │   │   ├── AboutPage.tsx
│   │   │   └── HowItWorksPage.tsx
│   │   ├── services/
│   │   │   └── api.ts
│   │   ├── hooks/
│   │   │   └── usePrediction.ts
│   │   ├── types/
│   │   │   └── index.ts
│   │   └── utils/
│   │       └── imageUtils.ts
│   ├── package.json
│   ├── vite.config.ts
│   ├── tailwind.config.js
│   └── Dockerfile
│
└── docs/
    ├── API.md
    ├── MODEL.md
    └── SETUP.md

🚀 Getting Started

Prerequisites

• Python 3.10+
• Node.js 18+
• npm or yarn

Installation

Backend Setup

cd backend

# Create virtual environment
python -m venv venv

# Activate virtual environment
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Copy environment file
cp .env.example .env

Frontend Setup

cd frontend

# Install dependencies
npm install

# Copy environment file
cp .env.example .env

Running the Application

Development Mode

Backend:

cd backend
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Frontend:

cd frontend
npm run dev

Access:

• Frontend: http://localhost:5173
• Backend API: http://localhost:8000
• API Docs: http://localhost:8000/docs

Using Docker

# Build and run
docker-compose up --build

# Run in background
docker-compose up -d

📊 Training the Model

1. Prepare Dataset

Download an Urdu handwritten character dataset and place it in backend/data/raw/.

Recommended Structure (Split Train/Test)

The recommended structure uses separate train and test directories:

backend/data/raw/
├── characters_train_set/
│   ├── alif/
│   │   ├── img001.png
│   │   └── ...
│   ├── alif mad aa/
│   ├── ayn/
│   ├── baa/
│   ├── bari yaa/
│   ├── cheey/
│   ├── choti yaa/
│   ├── daal/
│   ├── dhaal/
│   ├── faa/
│   ├── gaaf/
│   ├── ghain/
│   ├── haa1/
│   ├── haa2/
│   ├── haa3/
│   ├── hamza/
│   ├── jeem/
│   ├── kaaf/
│   ├── khaa/
│   ├── laam/
│   ├── meem/
│   ├── noon/
│   ├── noonghunna/
│   ├── paa/
│   ├── qaaf/
│   ├── raa/
│   ├── rhraa/
│   ├── seen/
│   ├── seey/
│   ├── sheen/
│   ├── swaad/
│   ├── taa/
│   ├── ttaa/
│   ├── twa/
│   ├── waw/
│   ├── zaaa/
│   ├── zaal/
│   ├── zhaa/
│   ├── zwaa/
│   └── zwaad/
├── characters_test_set/
│   └── (same structure as train set)
├── digits_train_set/
│   ├── 0/
│   ├── 1/
│   ├── 2/
│   ├── 3/
│   ├── 4/
│   ├── 5/
│   ├── 6/
│   ├── 7/
│   ├── 8/
│   └── 9/
└── digits_test_set/
    └── (same structure as train set)

Legacy Structure (Single Directory)

You can also use a single directory with all classes:

backend/data/raw/
├── alif/
│   ├── img001.png
│   └── ...
├── bay/
│   ├── img001.png
│   └── ...
└── ...

2. Verify Dataset

Before training, verify your dataset structure:

cd backend
python -m ml.verify_dataset --data-dir data/raw

To also test data loading:

python -m ml.verify_dataset --data-dir data/raw --test-load

3. Train

Train Character Model (Recommended)

cd backend
python -m ml.train --dataset-type characters

Train Digit Model

cd backend
python -m ml.train --dataset-type digits --model-path saved_models/urdu_digits_model.h5 --labels-path saved_models/digit_labels.json

Training Options

python -m ml.train --help

Options:
  --data-dir          Base directory for raw data (default: data/raw)
  --processed-dir     Directory for processed data (default: data/processed)
  --model-path        Path to save the model (default: saved_models/urdu_cnn_model.h5)
  --labels-path       Path to save class labels (default: saved_models/class_labels.json)
  --dataset-type      Dataset type: 'characters' or 'digits' (default: characters)
  --image-size        Image size (default: 64)
  --batch-size        Batch size (default: 32)
  --epochs            Number of epochs (default: 100)
  --lr                Learning rate (default: 0.001)
  --no-augmentation   Disable data augmentation
  --use-processed     Use pre-processed data if available
  --no-split-dirs     Use legacy single directory mode

4. Evaluate

python -m ml.evaluate

📚 Datasets

Recommended Datasets

1. Urdu Handwritten Dataset

   • URL: https://www.kaggle.com/datasets/surindersinghkhurana/handwritten-urdu-characters-dataset
   • Contains: Urdu characters script

2. Urdu Nastalique Dataset

   • URL: https://www.kaggle.com/datasets/saqibraza21/printed-urdu-character-nastalique-font
   • Research paper: Search for "UCOM Urdu Character Dataset"

3. Urdu-Handwritten-Characters Dataset (Kaggle)

   • URL: https://www.kaggle.com/datasets/hazrat/uhat-urdu-handwritten-text-dataset
   • Contains: 38 classes of Urdu characters

4. CALAM Dataset

   • URL: Contact researchers at FAST-NUCES Pakistan
   • Contains: Comprehensive Urdu handwriting samples

🔌 API Endpoints

Method	Endpoint	Description
GET	/health	Health check
GET	/	Welcome message
POST	/api/v1/predict	Predict from image upload
POST	/api/v1/predict/canvas	Predict from canvas drawing
GET	/api/v1/classes	Get supported characters

Example API Call

curl -X POST "http://localhost:8000/api/v1/predict" \
  -F "file=@path/to/image.png"

🧪 Testing

Backend Tests

cd backend
pytest tests/ -v

Frontend Tests

cd frontend
npm run test

📖 Documentation

• API Documentation
• Model Architecture
• Setup Instructions

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details on:

• How to fork and clone the repository
• Code style and linting rules
• Submitting bug reports and feature requests
• Creating pull requests
• Testing and documentation requirements

📄 License

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

🛡 Security

Security is a priority for this project. If you discover a security vulnerability, please review our Security Policy for information on how to report it responsibly.

📏 Code of Conduct

We are committed to providing a welcoming and inclusive environment. Please read our Code of Conduct to understand our community guidelines and expectations.

🙏 Acknowledgments

• TensorFlow/Keras team for the deep learning framework
• FastAPI team for the excellent web framework
• React team for the frontend library
• All contributors to the Urdu handwritten character datasets
• The open-source community for their invaluable tools and libraries

📧 Contact

For questions or feedback, please open an issue on GitHub or reach out through our Discussions.

---

Made with ❤️ by H0NEYP0T-466