CalliScript

AI-Powered Arabic Calligraphy Style Detector

CalliScript is a web application that identifies the style of Arabic calligraphy from an uploaded image. Using a custom convolutional neural network trained from scratch, it classifies calligraphy into three classical styles — Diwani, Naskh, and Thuluth — and returns a confidence breakdown across all three.

---

Overview

Arabic calligraphy is one of the most refined artistic traditions in the world, with each script carrying its own history, geometry, and rhythm. Distinguishing between styles typically requires trained expertise. CalliScript makes this knowledge accessible by automating style recognition through deep learning.

---

Features

• Drag-and-drop image upload with instant preview
• Real-time style classification via REST API
• Confidence percentage for the predicted style
• Full probability breakdown across all three styles
• Animated result visualisation
• Responsive, dark-themed interface

---

Architecture

CalliScript follows a three-tier architecture:

User → Frontend → Flask Backend → Custom CNN → JSON Response → Frontend Display

Flow:

1. The user uploads a calligraphy image through the browser interface
2. The image is sent to the Flask backend via POST /predict
3. The backend converts the image to RGB and applies the same resize-and-normalise transform used during evaluation
4. The preprocessed tensor [1, 3, 224, 224] is passed through the trained model
5. Raw logits are converted to probabilities using softmax
6. The backend returns the predicted style, its confidence, and the full percentage breakdown as JSON
7. The frontend renders the result with animated confidence bars

---

Model

A custom CNN trained from scratch in PyTorch.

Component	Details
Input	224 × 224 RGB
Conv Block 1	3 → 32 channels
Conv Block 2	32 → 64 channels
Conv Block 3	64 → 128 channels
Conv Block 4	128 → 256 channels
Pooling	Global Average Pooling
Classifier	256 → 128 → 3
Output	Diwani, Naskh, Thuluth

Each convolutional block contains two Conv2d → BatchNorm → ReLU layers followed by max pooling.

Training configuration:

• Optimiser: AdamW (lr = 3e-4, weight decay = 5e-2)
• Loss: Cross-entropy with class weighting and label smoothing (0.1)
• Scheduler: Cosine annealing
• Augmentation: Random rotation, colour jitter, affine transforms, random erasing
• Class balancing: Weighted random sampler with sqrt-inverse frequency weights
• Split: 70% train / 15% validation / 15% test (stratified)
• Early stopping on validation accuracy

---

Tech Stack

Frontend

• HTML5, CSS3, Vanilla JavaScript

Backend

• Python, Flask, Flask-CORS

Machine Learning

• PyTorch, TorchVision, Pillow

---

Project Structure

CalliScript/
├── backend/
│   ├── app.py                 # Flask REST API
│   ├── model_arch.py          # CNN architecture definition
│   ├── custom_cnn_model.pt    # Trained model weights
│   ├── requirements.txt
│   └── Procfile
├── frontend/
│   ├── index.html
│   ├── style.css
│   ├── script.js
│   └── images/
└── README.md

---

Getting Started

Prerequisites

• Python 3.9 or higher
• pip

Installation

Clone the repository:

git clone https://github.com/yourusername/calliscript.git
cd calliscript/backend

Install dependencies:

pip install -r requirements.txt

Run the backend:

python app.py

The server will start at http://127.0.0.1:5000

Launch the Frontend

Open frontend/index.html in your browser.

---

API Reference

GET /health

Health check endpoint.

Response:

{
  "status": "Server is running!",
  "classes": ["Diwani", "Naskh", "Thuluth"]
}

POST /predict

Classify a calligraphy image.

Request: multipart/form-data with field image

Response:

{
  "style": "Diwani",
  "confidence": 92.45,
  "all_probabilities": {
    "Diwani": 92.45,
    "Naskh": 5.30,
    "Thuluth": 2.25
  }
}

---

Styles Detected

Style	Arabic	Description
Diwani	ديواني	An ornate cursive script developed in the Ottoman court, known for its flowing, interwoven letterforms
Naskh	نسخ	A clear, rounded script widely used for printed Arabic text, valued for its legibility
Thuluth	ثلث	A majestic, elegant script often used for architectural inscriptions and decorative titles

---

License

This project is released under the MIT License.

---

Acknowledgements

Built as a semester project exploring the intersection of computer vision and Islamic art.