Karez commited on
Commit
a165b9a
Β·
verified Β·
1 Parent(s): dbd3549

Upload README.md with huggingface_hub

Browse files
Files changed (1) hide show
  1. README.md +143 -0
README.md ADDED
@@ -0,0 +1,143 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # KHLR: Kurdish Handwritten Line Recognition
2
+
3
+ **A DenseNet121-Transformer Architecture with Constrained Synthetic Line Generation**
4
+
5
+ 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.
6
+
7
+ ---
8
+
9
+ ## Repository Structure
10
+
11
+ ```
12
+ KHLR/
13
+ β”œβ”€β”€ Kurdish-HLR-Model/ # Best Kurdish model (safetensors + config)
14
+ β”œβ”€β”€ Arabic-HLR-Model/ # Fine-tuned on KHATT Arabic dataset
15
+ β”œβ”€β”€ Urdu-HLR-Model/ # Fine-tuned on PUCIT Urdu dataset
16
+ β”œβ”€β”€ Scripts/
17
+ β”‚ β”œβ”€β”€ train.py # Main training script
18
+ β”‚ β”œβ”€β”€ synthetic_line_generator.py # Recipe-based synthetic line generation
19
+ β”‚ └── inference.py # Single image / batch inference
20
+ β”œβ”€β”€ Sample/
21
+ β”‚ β”œβ”€β”€ sample_image.tif # Example handwritten line image
22
+ β”‚ └── sample_image.txt # Corresponding ground truth
23
+ β”œβ”€β”€ requirements.txt
24
+ └── README.md
25
+ ```
26
+
27
+ ## Architecture
28
+
29
+ | Component | Details |
30
+ |-----------|---------|
31
+ | CNN Backbone | DenseNet-121 (ImageNet pre-trained) |
32
+ | Encoder | 3 Transformer encoder layers |
33
+ | Decoder | 3 Transformer decoder layers |
34
+ | Attention Heads | 8 |
35
+ | Hidden Size | 256 |
36
+ | Feed-Forward Dim | 1024 |
37
+ | Total Parameters | ~12.8M |
38
+
39
+ ## Performance
40
+
41
+ ### Kurdish (DASTNUS)
42
+
43
+ | Configuration | CER | WER | CRR (%) |
44
+ |--------------|-----|-----|---------|
45
+ | +AA+SKHL+FHL-50 | 0.0593 | 0.3083 | 94.07 |
46
+ | +AA+SKHL+FHL-50 + 8-gram LM | 0.0534 | 0.2746 | 94.66 |
47
+
48
+ ### Cross-Dataset Generalization
49
+
50
+ | Dataset | Language | CER | WER | CRR (%) |
51
+ |---------|----------|-----|-----|---------|
52
+ | KHATT | Arabic | 0.1135 | 0.4156 | 88.65 |
53
+ | PUCIT | Urdu | 0.0932 | 0.2799 | 90.68 |
54
+
55
+ ## Installation
56
+
57
+ ```bash
58
+ git clone https://huggingface.co/karez/KHLR
59
+ cd KHLR
60
+ pip install -r requirements.txt
61
+ ```
62
+
63
+ ## Quick Start
64
+
65
+ ### Inference
66
+
67
+ ```bash
68
+ # Single image (using .pth checkpoint)
69
+ python Scripts/inference.py \
70
+ --image Sample/sample_image.tif \
71
+ --model_path Kurdish-HLR-Model/model.safetensors \
72
+ --vocab_path Kurdish-HLR-Model/vocab.json
73
+
74
+ # Directory of images
75
+ python Scripts/inference.py \
76
+ --image_dir ./test_images \
77
+ --model_path Kurdish-HLR-Model/model.safetensors \
78
+ --vocab_path Kurdish-HLR-Model/vocab.json
79
+ ```
80
+
81
+ ### Training
82
+
83
+ ```bash
84
+ # Basic training (unique handwritten lines only)
85
+ python Scripts/train.py \
86
+ --data_dir ./data/DASTNUS \
87
+ --vocab_path Kurdish-HLR-Model/vocab.json
88
+
89
+ # Full training with synthetic lines + writer mixing (best configuration)
90
+ python Scripts/train.py \
91
+ --data_dir ./data/DASTNUS \
92
+ --vocab_path Kurdish-HLR-Model/vocab.json \
93
+ --use_synthetic \
94
+ --synthetic_dir ./data/Synthetic-Lines \
95
+ --use_writer_mixing \
96
+ --fixed_lines_dir ./data/Fixed-Lines \
97
+ --num_writers 50
98
+ ```
99
+
100
+ ### Synthetic Line Generation
101
+
102
+ ```bash
103
+ python Scripts/synthetic_line_generator.py \
104
+ --unique_words_dir ./data/Unique-Words \
105
+ --person_names_dir ./data/Person-Names \
106
+ --output_dir ./data/Synthetic-Lines \
107
+ --training_writers ./writers/Training.txt \
108
+ --validation_writers ./writers/Validation.txt \
109
+ --testing_writers ./writers/Testing.txt
110
+ ```
111
+
112
+ ## Models
113
+
114
+ | Model | Language | Vocabulary | Format |
115
+ |-------|----------|-----------|--------|
116
+ | Kurdish-HLR-Model | Kurdish (Sorani) | 114 tokens | safetensors |
117
+ | Arabic-KHATT-Model | Arabic | 192 tokens (unified) | safetensors |
118
+ | Urdu-PUCIT-Model | Urdu | 192 tokens (unified) | safetensors |
119
+
120
+ The Arabic and Urdu models use a triple unified vocabulary (Kurdish + Arabic + Urdu) enabling cross-script transfer learning.
121
+
122
+ ## Dataset
123
+
124
+ The models were trained using the following subsets of the **DASTNUS** Kurdish handwritten dataset:
125
+
126
+ | Data Source | Training | Validation | Testing |
127
+ |-------------|----------|------------|---------|
128
+ | Unique handwritten lines | 3,575 | 655 | 649 |
129
+ | Synthetic handwritten lines | 3,762 | 614 | 596 |
130
+ | Fixed-content lines (50 writers) | 512 | - | - |
131
+ | **Total** | **7,849** | **1,269** | **1,245** |
132
+
133
+ The data used in this research is available upon request for non-commercial scientific research purposes only.
134
+
135
+ ## Citation
136
+
137
+ ```bibtex
138
+ []
139
+ ```
140
+
141
+ ## License
142
+
143
+ This repository is released for **non-commercial scientific research purposes only**.