| --- |
| license: mit |
| language: |
| - ar |
| - aeb |
| pipeline_tag: image-to-text |
| base_model: microsoft/trocr-base-handwritten |
| tags: |
| - image-to-text |
| - ocr |
| - handwriting-recognition |
| - htr |
| - arabic |
| - tunisian |
| - trocr |
| - vision-encoder-decoder |
| - offline |
| --- |
| |
| # trocr-tunisian-arabic — handwritten Tunisian Arabic recognition |
|
|
| A TrOCR vision-encoder/decoder fine-tuned for **handwritten Tunisian Arabic**, with a 30k-token Arabic-native vocabulary. |
|
|
| ## Why this exists |
|
|
| Cloud OCR services handle printed Arabic reasonably and handwritten dialectal Arabic poorly. For the use case this was built for, they were not an option at all: Tunisian legal documents contain privileged client data that cannot leave the premises under the country's data-protection regime. That ruled out every managed service and required a model that runs fully offline. |
|
|
| ## Intended use |
|
|
| Offline extraction of handwritten Arabic from structured forms. |
|
|
| Built for and deployed in [Wathiqa](https://github.com/GhwazouaniWala/Wathiqa), which turns handwritten Tunisian legal forms into structured, searchable client records without any cloud dependency. |
|
|
| **This is a word-level model.** In Wathiqa it sits behind a segmentation stage: the ink mask is dilated horizontally by a kernel scaled to text height — Arabic joins letters within a word but not between words, so inter-word gaps are the reliable separator — and the resulting components are read right to left. Feeding a full unsegmented line will not work well. |
|
|
| ## Usage |
|
|
| <!-- Paste the VisionEncoderDecoderModel loading and generation code you have |
| actually run, including the processor and any generation config used. --> |
| |
| ## Where it sits in a real pipeline |
|
|
| Wathiqa routes each field type to a purpose-built engine rather than asking one model to cover everything: |
|
|
| | Field type | Engine | |
| |---|---| |
| | Arabic text, names, notes | **This model** | |
| | CIN, passport, number, phone, date | Dedicated digit recogniser with a constrained alphabet and shape validation | |
| | Printed captions | EasyOCR (Arabic + Latin) | |
| | Checkboxes | Fill-ratio detector | |
| | Signatures | Ink-presence detector | |
|
|
| That routing exists because these are genuinely different problems, and the limitations below are the reason. |
|
|
| ## Limitations |
|
|
| - **Trained on isolated words**, not lines or sentences. Word segmentation is the caller's responsibility. |
| - **Not for digits.** Numeric fields need a separate path — a word model asked for a digit string produces confident nonsense. Wathiqa isolates characters, constrains the alphabet to `0-9` and separators, then validates the assembled value against the field's expected shape. |
| - **Not for printed text.** Printed captions are a different problem and route elsewhere. |
| - **A blank crop returns confident nonsense rather than silence.** Empty-field detection must happen before the model is called; Wathiqa reports fields with no ink as empty and never sends them to a model. |
| - Trained on Tunisian handwriting. Performance on other regional Arabic hands is untested. |
|
|
| ## Training |
|
|
| Fine-tuned from [`microsoft/trocr-base-handwritten`](https://huggingface.co/microsoft/trocr-base-handwritten) on handwritten Tunisian Arabic, with the decoder vocabulary replaced by a 30k-token Arabic-native vocabulary. |
|
|
| <!-- Optional but worth adding: number of training samples, how the corpus was |
| collected and labelled, image preprocessing, and CER/WER on a held-out set. --> |
| |
| ## Related work |
|
|
| | Model | Purpose | |
| |---|---| |
| | [`Ghazouaniwala/emotions_speech`](https://huggingface.co/Ghazouaniwala/emotions_speech) | Speaker-independent speech emotion recognition | |
| | [`Ghazouaniwala/silma-tts-derja`](https://huggingface.co/Ghazouaniwala/silma-tts-derja) | Tunisian Derja speech synthesis | |
|
|
| ## Citation |
|
|
| ```bibtex |
| @misc{ghazouani2025trocrtunisian, |
| author = {Ghazouani, Wala Eddine}, |
| title = {trocr-tunisian-arabic: handwritten Tunisian Arabic recognition}, |
| year = {2025}, |
| url = {https://huggingface.co/Ghazouaniwala/trocr-tunisian-arabic} |
| } |
| ``` |
|
|
| --- |
|
|
| Built by [Wala Eddine Ghazouani](https://www.walaghazouani.com) · [GitHub](https://github.com/GhwazouaniWala) · [LinkedIn](https://www.linkedin.com/in/ghazouani-wala-eddine) |
