---
license: cc-by-nc-4.0
language:
  - ckb
  - ar
tags:
  - handwritten-text-recognition
  - paragraph-recognition
  - kurdish
  - arabic
  - densenet
  - transformer
  - pytorch
  - safetensors
pipeline_tag: image-to-text
---
# ETE-KHPR: End-to-End Kurdish Handwritten Paragraph Recognition
### A DenseNet121-Transformer Architecture with Synthetic Paragraph Generation

This repository contains the source code, trained models, and vocabularies for end-to-end Kurdish handwritten paragraph recognition without explicit line segmentation, with cross-script evaluation on Arabic (KHATT) and cross-dataset transfer to an external Kurdish dataset (DASNUS).

---

## Repository Structure

```
KHPR/
├── DASTNUS-Kurdish-ParagraphHTR/   # Best Kurdish paragraph model
│   ├── model.safetensors           # Model weights
│   ├── config.json                 # Architecture configuration
│   ├── vocab.json                  # Character vocabulary (char → index)
│   ├── idx_to_char.json            # Reverse vocabulary (index → char)
│   └── README.md                   # Model card
│
├── DASNUS-Kurdish-ParagraphHTR/    # Model fine-tuned on external Kurdish dataset
│   ├── model.safetensors
│   ├── config.json
│   ├── vocab.json
│   ├── idx_to_char.json
│   └── README.md
│
├── KHATT-Arabic-ParagraphHTR/      # Model fine-tuned on KHATT Arabic dataset
│   ├── model.safetensors
│   ├── config.json
│   ├── vocab.json                  # KHATT Arabic vocabulary (143 tokens)
│   ├── idx_to_char.json
│   └── README.md
│
├── Scripts/
│   ├── pretrain.py                 # Pre-training on synthetic paragraphs
│   ├── finetune.py                 # Fine-tuning on real handwritten paragraphs
│   ├── inference.py                # Single image and batch inference
│   └── generate_paragraphs.py     # Synthetic paragraph generation
│
├── Sample/
│   ├── sample_paragraph.tif        # Example Kurdish handwritten paragraph
│   └── sample_paragraph.txt        # Corresponding ground truth
│
├── requirements.txt
└── README.md
```

---

## Architecture

| Component | Details |
|-----------|---------|
| CNN Backbone | DenseNet-121 (ImageNet pre-trained) |
| Encoder | 3 Transformer encoder layers |
| Decoder | 6 Transformer decoder layers |
| Attention Heads | 8 |
| Hidden Size | 256 |
| Feed-Forward Dim | 2048 |
| Positional Encoding | 2D sinusoidal (encoder) + 1D sinusoidal (decoder) |
| Total Parameters | 22.7M |

The model processes full paragraph images end-to-end and outputs the complete multi-line text, including line break positions, without any explicit line segmentation.

---

## Performance

### Kurdish — DASTNUS Unique Handwritten Paragraphs

| Decoding Strategy | CER | WER | CRR (%) | WRR (%) |
|---|---|---|---|---|
| Greedy | 0.0721 | 0.3624 | 92.79 | 63.76 |
| Beam-10 | 0.0706 | 0.3580 | 92.94 | 64.20 |
| Beam-10 + 8-gram LM (w=0.6) | 0.0676 | 0.3422 | 93.24 | 65.78 |
| Beam-10 + RoBERTa (w=0.1) | 0.0680 | 0.3484 | 93.20 | 65.16 |

### Cross-Script Evaluation — KHATT Arabic Handwritten Paragraphs

| Model | CER | WER | CRR (%) |
|---|---|---|---|
| Proposed | 0.1394 | 0.5075 | 86.06 |
| MSdocTr-Lite (reimplemented, same conditions) | 0.1622 | 0.5227 | 83.78 |

### Cross-Dataset Transfer — DASNUS External Kurdish Dataset

| Setting | Training Samples | CER | WER | CRR (%) |
|---|---|---|---|---|
| Zero-shot | 0 | 0.2257 | 0.6206 | 77.43 |
| Few-shot 10% | 184 | 0.1535 | 0.4757 | 84.65 |
| Few-shot 50% | 922 | 0.1034 | 0.3609 | 89.66 |
| Full fine-tune | 1,843 | 0.0856 | 0.3148 | 91.44 |

---

## Installation

```bash
git clone https://huggingface.co/karez/KHPR
cd KHPR
pip install -r requirements.txt
```

---

## Quick Start

### Inference

```bash
# Single paragraph image (with config auto-load)
python Scripts/inference.py \
    --image Sample/sample_paragraph.tif \
    --model_path DASTNUS-Kurdish-ParagraphHTR/model.safetensors \
    --vocab_path DASTNUS-Kurdish-ParagraphHTR/vocab.json \
    --config_path DASTNUS-Kurdish-ParagraphHTR/config.json

# Directory of images with timing
python Scripts/inference.py \
    --image_dir ./test_paragraphs \
    --model_path DASTNUS-Kurdish-ParagraphHTR/model.safetensors \
    --vocab_path DASTNUS-Kurdish-ParagraphHTR/vocab.json \
    --config_path DASTNUS-Kurdish-ParagraphHTR/config.json \
    --show_timing \
    --output_file predictions.txt

# Arabic model (KHATT)
python Scripts/inference.py \
    --image Sample/arabic_paragraph.tif \
    --model_path KHATT-Arabic-ParagraphHTR/model.safetensors \
    --vocab_path KHATT-Arabic-ParagraphHTR/vocab.json \
    --config_path KHATT-Arabic-ParagraphHTR/config.json
```

### Synthetic Paragraph Generation

```bash
# Full three-source generation (best configuration)
python Scripts/generate_paragraphs.py \
    --unique_train_dir ./data/UniqueLines/Training \
    --fixed_train_dir ./data/FixedLines/Training \
    --synthetic_train_dir ./data/SyntheticLines/Training \
    --unique_val_dir ./data/UniqueLines/Validation \
    --fixed_val_dir ./data/FixedLines/Validation \
    --synthetic_val_dir ./data/SyntheticLines/Validation \
    --output_dir ./SyntheticParagraphs_12000 \
    --dataset_size 12000
```

### Pre-training

```bash
# Pre-train on synthetic paragraphs (Kurdish, default settings)
python Scripts/pretrain.py \
    --data_dir ./SyntheticParagraphs_12000 \
    --vocab_path DASTNUS-Kurdish-ParagraphHTR/vocab.json \
    --output_dir ./output \
    --model_name pretrained_kurdish

# Pre-train without curriculum learning
python Scripts/pretrain.py \
    --data_dir ./SyntheticParagraphs_12000 \
    --vocab_path DASTNUS-Kurdish-ParagraphHTR/vocab.json \
    --no_curriculum
```

### Fine-tuning

```bash
# Fine-tune on DASTNUS unique handwritten paragraphs
python Scripts/finetune.py \
    --data_dir ./data/UniqueHandwrittenParagraphs \
    --vocab_path DASTNUS-Kurdish-ParagraphHTR/vocab.json \
    --pretrained_path ./output/pretrained_kurdish.pth \
    --output_dir ./output \
    --model_name finetuned_dastnus

# Fine-tune on DASNUS external Kurdish dataset
python Scripts/finetune.py \
    --data_dir ./data/DASNUS-Paragraphs \
    --vocab_path DASTNUS-Kurdish-ParagraphHTR/vocab.json \
    --pretrained_path ./output/pretrained_kurdish.pth \
    --output_dir ./output \
    --model_name finetuned_dasnus

# Fine-tune on KHATT Arabic dataset
python Scripts/finetune.py \
    --data_dir ./data/KHATT-Paragraphs \
    --vocab_path KHATT-Arabic-ParagraphHTR/vocab.json \
    --pretrained_path ./output/pretrained_khatt.pth \
    --output_dir ./output \
    --model_name finetuned_khatt
```
---

## Training Data

### DASTNUS and DASNUS Models

| Data Source | Training | Validation | Testing |
|---|---|---|---|
| Unique handwritten paragraphs | 710 | 144 | 144 |
| Synthetic paragraphs (pre-training) | 10,200 | 1,800 | — |

Synthetic paragraphs were generated from DASTNUS line sources using the `generate_paragraphs.py` script, combining unique handwritten lines, Fixed handwrwritten lines and recipe-based synthetic handwritten lines with single-writer consistency, zero duplicate text orderings, and source-level isolation between splits.

### KHATT Model

| Data Source | Training | Validation | Testing |
|---|---|---|---|
| Reconstructed KHATT paragraphs | 1,193 | 144 | 150 |
| Synthetic paragraphs (pre-training) | 10,201 | 1,199 | — |

Synthetic paragraphs for KHATT pre-training were generated by combining KHATT handwritten lines with Kurdish line sources from DASTNUS to provide richer visual diversity across handwriting styles within the same Arabic script family.

---

## Hardware

Experiments were conducted on a workstation equipped with an Intel Core i9-14900K processor, 128 GB RAM, and an NVIDIA GeForce RTX 5090 GPU with 32 GB VRAM.

---

## Citation

```bibtex
[]
```

---

## License

This repository is released for non-commercial scientific research purposes only under the CC-BY-NC-4.0 license. The data used in this research is available upon request for non-commercial scientific research purposes only.