File size: 8,469 Bytes

960dd1b

---

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.