OCR-AJAMI-Hausa V11
OCR-AJAMI-Hausa V11
OCR-AJAMI-Hausa V11 is an experimental handwritten text recognition model for Hausa manuscripts written in Ajami script.
The model performs direct transcription from an Ajami manuscript image into Latin-script Hausa.
It does not require an intermediate Arabic-character recognition stage or a manually defined Arabic-letter dictionary.
The general objective is:
text Ajami manuscript image ↓ visual representation ↓ CNN feature extraction ↓ Bidirectional LSTM ↓ CTC ↓ Latin-script transcription
The longer-term research goal is to develop a visual manuscript recognition methodology that can later be adapted to Ajami manuscripts written in other languages.
Model version
text Model : OCR-AJAMI-Hausa V11 Framework : PyTorch Architecture : CRNN + BiLSTM + CTC Input channels : 2
V11 introduces a second visual input channel compared with V10.
The two channels are:
text Channel 0 : normalized grayscale image Channel 1 : local ink map
The purpose of the second channel is to help the convolutional network distinguish manuscript ink from variations in paper and background appearance.
Architecture
The model consists of:
grayscale manuscript preprocessing;
local ink-map generation;
convolutional visual feature extraction;
a two-layer bidirectional LSTM;
a linear classifier;
CTC decoding.
The processing pipeline is:
text Ajami manuscript image | v Convert to grayscale | v Resize to height = 96 px | v Horizontal RTL mirroring | +------------------------+ | | v v Grayscale channel Local ink-map | | +------------+-----------+ | v 2-channel CNN | v Visual features | v 2-layer Bidirectional LSTM hidden size 256 | v Linear classifier | v CTC | v Latin-script transcription
Input representation Channel 0 — Grayscale The original image is converted to grayscale. Pixel values are normalized before being passed to the CNN. The grayscale channel preserves the complete visual information of the manuscript.
Channel 1 — Local ink map V11 introduces an additional representation intended to emphasize manuscript strokes relative to the local paper background. A blurred version of the image is used to estimate the local background. Conceptually:
background = GaussianBlur(grayscale)
ink_map = background - grayscale
Negative values are removed.
The remaining ink response is amplified and normalized.
The configuration used for V11 is:
text Background blur radius : 5.0 Ink gain : 1.6
No hard binary threshold is applied.
This is intentional.
Hard binarization may remove faint manuscript details such as:
dots;
diacritics;
thin strokes;
partially erased ink;
weak character components.
The continuous ink map preserves more of this information.
CNN
The CNN receives two input channels:
python nn.Conv2d( 2, 64, kernel_size=3, padding=1 )
The convolutional frontend progressively extracts visual features while reducing image height.
The horizontal dimension is largely preserved so that it can be interpreted as a sequence by the recurrent network.
Sequence model
The sequence component is a two-layer bidirectional LSTM:
python nn.LSTM( input_size=384, hidden_size=256, num_layers=2, bidirectional=True, batch_first=True, dropout=0.2 )
The bidirectional LSTM receives the visual sequence produced by the CNN.
Its output is passed to a linear classifier and optimized using CTC.
CTC
Connectionist Temporal Classification is used to learn alignment between manuscript image features and the Latin transcription.
No explicit character-level alignment between the Ajami source image and the Latin transcription is required.
This is particularly useful for this project because the training data contains:
text Ajami image + Latin transcription
rather than:
text Ajami image + Arabic Unicode transcription + Latin transcription
RTL handling
Ajami is written from right to left.
The CTC sequence is processed from left to right.
Before entering the CNN, the manuscript image is therefore horizontally mirrored.
Conceptually:
text Original Ajami image RTL ↓ horizontal mirror ↓ visual reading sequence aligned with CTC LTR sequence processing
This transformation produced a substantial improvement during the experimental development of the model.
Image size
Images are resized while preserving their aspect ratio.
The fixed image height is:
text 96 pixels
Image width remains variable.
Images in the same batch are padded to the maximum width of the batch.
Training dataset The experiment used the following split: Split Percentage Number of images Train 92% 2,942 Validation 3% 96 Test 5% 160 The split is fixed for evaluation. Validation and test images are never augmented.
Fixed visual augmentation Each real training image is represented by eight deterministic views. Therefore:
Real training images : 2,942
Views per image : 8
Virtual train size per epoch:
2,942 × 8 = 23,536
The eight views are: View Transformation 0 Original image 1 Brightness and contrast variation 2 Ink thickness variation 3 Scanner / resolution degradation 4 Mild Gaussian blur 5 Small rotation 6 Mild geometric scaling 7 Moderate combined document degradation These transformations are deterministic. A given training image / variant pair therefore remains reproducible across epochs.
View 0 — Original The original manuscript image is preserved without visual augmentation. This ensures that the model continues to see real, unmodified training data.
View 1 — Brightness and contrast This view simulates variation caused by: different scanning conditions; paper brightness; illumination; faded manuscripts; different digitization settings.
View 2 — Ink thickness A mild morphological transformation changes apparent stroke thickness. This is intended to improve robustness to differences in: pen pressure; ink diffusion; scan resolution; manuscript degradation. The transformation is intentionally limited because small Ajami dots and signs contain important information.
View 3 — Scanner degradation The image is temporarily downsampled and reconstructed. This simulates loss of detail caused by lower quality acquisition.
View 4 — Mild blur A low-radius Gaussian blur simulates optical or scanning blur.
View 5 — Rotation The manuscript line is rotated slightly. This simulates small page or crop alignment errors. The transformation uses image expansion to avoid cutting characters at the borders.
View 6 — Geometric variation Width and height are modified slightly. This encourages the model not to associate a transcription with one exact spatial scale.
View 7 — Combined document degradation This view combines mild changes in: brightness; contrast; blur; rotation. The transformation remains deliberately conservative. The objective is to simulate plausible manuscript digitization variation without altering the linguistic content.
Training configuration The main V11 training parameters were:
Image height : 96
Batch size : 24
Optimizer : AdamW
Initial learning rate: 0.001
Weight decay : 0.0001
Loss : CTC
Gradient clipping : 5.0
LSTM layers : 2
LSTM hidden size : 256
Bidirectional : yes
LSTM dropout : 0.2
Dynamic augmentation: disabled
Fixed augmentation : enabled
Views per image : 8
The learning rate was controlled with ReduceLROnPlateau.
The model checkpoint with the lowest validation Character Error Rate was retained.
Best checkpoint
The best V11 checkpoint was obtained at:
text Epoch 17
Validation results Metric Result CER 0.2377
Test results
Metric Result
CER 0.2374
WER 0.6920
Exact-line rate 0.2750
The validation and test CER are very close:
text Validation CER : 0.2377 Test CER : 0.2374
This indicates that the selected validation checkpoint generalized similarly on the held-out test set for this experiment.
Comparison with V10
V10 used the same general OCR architecture and training methodology but only one grayscale input channel.
V11 adds the local ink-map channel.
Metric V10 V11
Test CER 0.2550 0.2374
Test WER 0.6963 0.6920
Exact-line rate 0.2750 0.2750
The Character Error Rate decreased from:
text 0.2550
to:
text 0.2374
This corresponds to approximately:
text 6.9% relative CER reduction
The WER improvement is smaller.
This suggests that the ink-map mainly helped reduce local character-level recognition errors.
Observed behavior V11 generally produces errors at the local character level rather than completely unrelated sequences. Typical remaining errors include: character substitutions; missing characters; additional characters; incorrect spaces; errors involving diacritics; confusion between visually similar manuscript patterns.
Intended use This model is intended for research involving: Hausa Ajami OCR; handwritten text recognition; historical manuscript transcription; direct Ajami-to-Latin transcription; CRNN / CTC manuscript recognition; visual ink/background separation; language-independent manuscript OCR research.
Language-independent research objective
The longer-term objective is not to require a manually defined Arabic-letter dictionary.
The intended approach is:
text manuscript image ↓ visual patterns ↓ sequence representation ↓ target-language transcription
Instead of:
text manuscript image ↓ Arabic character recognition ↓ Arabic dictionary ↓ transliteration rules ↓ target transcription
This should make it easier to experiment with Ajami manuscripts written in other languages.
Future versions may investigate visual pattern representations that capture recurring groups of strokes or glyph structures without requiring explicit Arabic-character labels.
Limitations This model remains experimental. Important limitations include: the amount of real transcribed data remains limited; WER remains significantly higher than CER; the model may produce plausible but incorrect Latin strings; the current evaluation is specific to the fixed 92/3/5 split; robustness to completely unseen scribes is not fully established; robustness to very degraded manuscript pages is not fully established; performance on other Ajami languages has not yet been measured; the model should not be considered a universal Arabic-script OCR system.
Files
The model repository contains:
text README.md best_cer_v11.pt hausa_ctc_vocab_nouveau.json train_hausa_ctc_v11_inkmap_92_3_5.py
Checkpoint
The main checkpoint is:
text best_cer_v11.pt
The checkpoint contains the PyTorch state dictionary and training metadata.
Vocabulary
The CTC vocabulary is distributed as:
text hausa_ctc_vocab_nouveau.json
The vocabulary includes the Latin characters and diacritics present in the transcription corpus.
Loading V11 uses a custom PyTorch architecture. It is not a standard Hugging Face Transformers model. The architecture must therefore be instantiated before loading the state dictionary. Example:
import torch
checkpoint = torch.load(
"best_cer_v11.pt",
map_location="cpu",
weights_only=False
)
model.load_state_dict(
checkpoint["model_state_dict"]
)
model.eval()
The complete V11 model architecture and preprocessing pipeline are available in:
text train_hausa_ctc_v11_inkmap_92_3_5.py
Hardware used during development The model was developed and tested on a consumer NVIDIA GPU with approximately 6 GB VRAM. The experimental setup used a GTX 1060-class GPU. This demonstrates that the architecture can be trained on relatively modest GPU hardware.
Future work Planned research directions include: deeper convolutional networks; residual CNN blocks; multi-scale visual features; visual pattern grouping; local glyph-pattern representations; improved word-boundary modeling; larger transcribed datasets; combined fixed and dynamic augmentation; attention mechanisms; lightweight Transformer sequence models; transfer learning across Ajami languages; manuscript-style adaptation; self-supervised visual pretraining.
Source project Development repository: https://github.com/IX-World/OCR-AJAMI-Hausa
Citation If you use this model in academic or research work, please cite the associated project repository until a formal publication citation becomes available. Project:
OCR-AJAMI-Hausa
IX-World