KHPR-ETE

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

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

Cross-Script Evaluation — KHATT Arabic Handwritten Paragraphs

Cross-Dataset Transfer — DASNUS External Kurdish Dataset

---

Installation

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

---

Quick Start

Inference

# 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

# 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

# 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

# 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

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

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

[]

---

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.