| ---
|
| language:
|
| - ckb
|
| - ar
|
| - ur
|
| license: cc-by-nc-4.0
|
| tags:
|
| - handwritten-text-recognition
|
| - kurdish
|
| - arabic
|
| - urdu
|
| - densenet
|
| - transformer
|
| - pytorch
|
| - safetensors
|
| datasets:
|
| - DASTNUS
|
| - KHATT
|
| - PUCIT
|
| metrics:
|
| - cer
|
| - wer
|
| pipeline_tag: image-to-text
|
| ---
|
|
|
| # KHLR: Kurdish Handwritten Line Recognition
|
|
|
| **A DenseNet121-Transformer Architecture with Constrained Synthetic Line Generation**
|
|
|
| This repository contains the source code, trained models, and vocabularies for Kurdish handwritten line recognition, with cross-dataset generalization to Arabic (KHATT) and Urdu (PUCIT) handwritten datasets.
|
|
|
| ---
|
|
|
| ## Repository Structure
|
|
|
| ```
|
| KHLR/
|
| ├── Kurdish-HLR-Model/ # Best Kurdish model (safetensors + config)
|
| ├── Arabic-HLR-Model/ # Fine-tuned on KHATT Arabic dataset
|
| ├── Urdu-HLR-Model/ # Fine-tuned on PUCIT Urdu dataset
|
| ├── Scripts/
|
| │ ├── train.py # Main training script
|
| │ ├── synthetic_line_generator.py # Recipe-based synthetic line generation
|
| │ └── inference.py # Single image / batch inference
|
| ├── Sample/
|
| │ ├── sample_image.tif # Example handwritten line image
|
| │ └── sample_image.txt # Corresponding ground truth
|
| ├── requirements.txt
|
| └── README.md
|
| ```
|
|
|
| ## Architecture
|
|
|
| | Component | Details |
|
| |-----------|---------|
|
| | CNN Backbone | DenseNet-121 (ImageNet pre-trained) |
|
| | Encoder | 3 Transformer encoder layers |
|
| | Decoder | 3 Transformer decoder layers |
|
| | Attention Heads | 8 |
|
| | Hidden Size | 256 |
|
| | Feed-Forward Dim | 1024 |
|
| | Total Parameters | ~12.8M |
|
|
|
| ## Performance
|
|
|
| ### Kurdish (DASTNUS)
|
|
|
| | Configuration | CER | WER | CRR (%) |
|
| |--------------|-----|-----|---------|
|
| | +AA+SKHL+FHL-50 | 0.0593 | 0.3083 | 94.07 |
|
| | +AA+SKHL+FHL-50 + 8-gram LM | 0.0534 | 0.2746 | 94.66 |
|
|
|
| ### Cross-Dataset Generalization
|
|
|
| | Dataset | Language | CER | WER | CRR (%) |
|
| |---------|----------|-----|-----|---------|
|
| | KHATT | Arabic | 0.1135 | 0.4156 | 88.65 |
|
| | PUCIT | Urdu | 0.0932 | 0.2799 | 90.68 |
|
|
|
| ## Installation
|
|
|
| ```bash
|
| git clone https://huggingface.co/karez/KHLR
|
| cd KHLR
|
| pip install -r requirements.txt
|
| ```
|
|
|
| ## Quick Start
|
|
|
| ### Inference
|
|
|
| ```bash
|
| # Single image (using .pth checkpoint)
|
| python Scripts/inference.py \
|
| --image Sample/sample_image.tif \
|
| --model_path Kurdish-HLR-Model/model.safetensors \
|
| --vocab_path Kurdish-HLR-Model/vocab.json
|
|
|
| # Directory of images
|
| python Scripts/inference.py \
|
| --image_dir ./test_images \
|
| --model_path Kurdish-HLR-Model/model.safetensors \
|
| --vocab_path Kurdish-HLR-Model/vocab.json
|
| ```
|
|
|
| ### Training
|
|
|
| ```bash
|
| # Basic training (unique handwritten lines only)
|
| python Scripts/train.py \
|
| --data_dir ./data/DASTNUS \
|
| --vocab_path Kurdish-HLR-Model/vocab.json
|
|
|
| # Full training with synthetic lines + writer mixing (best configuration)
|
| python Scripts/train.py \
|
| --data_dir ./data/DASTNUS \
|
| --vocab_path Kurdish-HLR-Model/vocab.json \
|
| --use_synthetic \
|
| --synthetic_dir ./data/Synthetic-Lines \
|
| --use_writer_mixing \
|
| --fixed_lines_dir ./data/Fixed-Lines \
|
| --num_writers 50
|
| ```
|
|
|
| ### Synthetic Line Generation
|
|
|
| ```bash
|
| python Scripts/synthetic_line_generator.py \
|
| --unique_words_dir ./data/Unique-Words \
|
| --person_names_dir ./data/Person-Names \
|
| --output_dir ./data/Synthetic-Lines \
|
| --training_writers ./writers/Training.txt \
|
| --validation_writers ./writers/Validation.txt \
|
| --testing_writers ./writers/Testing.txt
|
| ```
|
|
|
| ## Models
|
|
|
| | Model | Language | Vocabulary | Format |
|
| |-------|----------|-----------|--------|
|
| | Kurdish-HLR-Model | Kurdish (Sorani) | 114 tokens | safetensors |
|
| | Arabic-HLR-Model | Arabic | 192 tokens (unified) | safetensors |
|
| | Urdu-HLR-Model | Urdu | 192 tokens (unified) | safetensors |
|
|
|
| The Arabic and Urdu models use a triple unified vocabulary (Kurdish + Arabic + Urdu) enabling cross-script transfer learning.
|
|
|
| ## Dataset
|
|
|
| The models were trained using the following subsets of the **DASTNUS** Kurdish handwritten dataset:
|
|
|
| | Data Source | Training | Validation | Testing |
|
| |-------------|----------|------------|---------|
|
| | Unique handwritten lines | 3,575 | 655 | 649 |
|
| | Synthetic handwritten lines | 3,762 | - | - |
|
| | Fixed-content lines (50 writers) | 512 | - | - |
|
| | **Total** | **7,849** | **655** | **649** |
|
|
|
| The data used in this research is available upon request for non-commercial scientific research purposes only.
|
|
|
| ## Citation
|
|
|
| ```bibtex
|
| []
|
| ```
|
|
|
| ## License
|
|
|
| This repository is released for **non-commercial scientific research purposes only**. |
