saeid1999/fa-en-ar-handwritten-ocr-v1

Multi-script Synthetic Handwritten OCR — fa / ar / en

A large, clean, augmentation-rich synthetic handwriting dataset for training and benchmarking OCR / HTR models on Persian (fa), Arabic (ar) and English (en). Every line image ships with an exact Unicode transcription plus rich provenance metadata (writer style, font, ink, script direction, digit system). Page-level PAGE-XML and COCO ground truth support layout-aware training and evaluation out of the box.

• —1,000 rendered pages (A4/A5/A6, 1–2 columns, headers, page numbers)
• —24,030 line crops + 16,542 photometric/geometric augmented variants
• —177,270 word crops for word-level training
• —45 leakage-free writers — writer identity never crosses splits
• —Multi-format ground truth: IAM-TSV, JSONL, PAGE-XML 2019, COCO
• —Built-in benchmark suite (CER/WER) that reads all four formats

Why this dataset

Real Persian/Arabic handwriting corpora are scarce and license-restricted. This dataset is deterministically synthesized from licensed text corpora with per-page seeds, so every sample is exactly reproducible; realistic degradations (paper texture, illumination, stains, folds, skew, sensor noise, JPEG artifacts, pen-width dynamics, baseline wobble) make it hard enough to transfer to real scans. Content includes plain text lines, math formulas (rendered with correct semantics), hand-drawn tables and geometric figures — reflecting real document OCR workloads.

Splits

Writers (font+style personas) are disjoint across splits — no leakage.

Dataset structure

train/ validation/ test/     line crops + metadata.jsonl  (imagefolder)
  └── metadata.jsonl         {file_name, text, language, kind, page_id,
                              font, style, digit_system, mixed_with}
  note: train/ shards overflow files into train/x/ (Hub limit: 10k files
  per directory); metadata file_name values include the x/ prefix for
  those, so every path resolves exactly
augmented.zip                 augmented train variants + metadata.jsonl
words.zip                     word crops (unzip; paths in iam/words.txt)
pages/                        full-page JPEG (q88) for layout models
page_xml/                     PAGE-XML 2019-07-15 (regions/lines/polygons)
coco/                         coco_lines.json, coco_words.json
iam/                          lines.txt / words.txt + per-split TSVs
jsonl/                        full per-line records (fonts, seeds, bboxes)
meta/ pages.jsonl             page-level provenance
splits/ report/               page-id lists + statistics & charts
benchmark/                    multi-format CER/WER evaluation suite
train_code/                   TrOCR fine-tuning scripts + Colab job

Supported formats & loaders

1. HuggingFace `datasets` (imagefolder, recommended)

from datasets import load_dataset
ds = load_dataset("saeid1999/fa-en-ar-handwritten-ocr-v1")
ex = ds["train"][0]
ex["image"], ex["text"], ex["language"]

Zip members (augmented.zip, words.zip) are plain folders: unzip words.zip -d . restores words/.

2. IAM-style TSV (iam/train_lines.txt: path<TAB>text)

rows = [l.split("\t") for l in open("iam/train_lines.txt", encoding="utf-8")]

3. JSONL records (jsonl/lines.jsonl — full provenance per line)

4. PAGE-XML (page_xml/*.xml — layout + polygon coordinates)

5. COCO (coco/coco_lines.json — detection-style training)

Benchmarks

benchmark/ ships an evaluator that reads all four formats and reports micro/macro CER & WER, optionally per language:

# score a prediction file (JSONL with {key|image, text}) against any format
python benchmark/run_benchmark.py --gt iam/test_lines.txt \
    --pred preds/my_model.jsonl --by-language

# generate predictions with a CRNN checkpoint or a HF TrOCR model
python benchmark/predict.py --engine trocr --hf-model USER/MODEL \
    --gt iam/test_lines.txt --root . --out preds/trocr.jsonl

Baseline — CRNN+CTC (small model, trained on the earlier 150-page subset, evaluated zero-shot on this test split — deliberately weak; the fine-tuned TrOCR below shows what this data is worth):

Fine-tuned TrOCR (microsoft/trocr-base-handwritten + all train + augmented lines, trained on Colab T4): results land in train_code/ → see docs/hf_run/RESULTS.md in the pipeline repo after the remote run completes.

Training code

train_code/ contains the complete TrOCR fine-tuning recipe:

pip install "transformers>=4.43,<5" torch
python train_code/training/finetune_trocr.py \
    --dataset <downloaded-dataset-root> --labels-dir iam \
    --base-model microsoft/trocr-base-handwritten --epochs 8

Resume-safe: checkpoints land in output_dir/last each epoch; re-running the same command continues. The Colab one-click job (train_code/colab/trocr_remote_job.py) downloads this dataset from the Hub, merges augmented lines, trains on GPU, mirrors checkpoints to GitHub Releases against preemption, and pushes the fp16 model.

Augmentations used

Geometric: rotation ±1.4°, shear, light elastic warp. Photometric: brightness/contrast jitter, Gaussian blur, sensor noise, JPEG round-trips. Generation-time (page-level): paper texture, illumination gradients, stains, fold shadows, skew, pen-width dynamics, ink-flow variation, baseline wave. Test/val remain clean for fair scoring. Each train line has exactly one augmented sibling in augmented.zip (recorded in augmented/metadata.jsonl with the op list).

Provenance & license

Deterministic pipeline (per-page seeds from master seed 20260917); corpora are licensed text; fonts are OFL/Apache-licensed (see font.license fields in jsonl/lines.jsonl). Dataset content is released CC-BY-4.0.

یک خلاصهٔ فارسی

دیتاست سینتتیک دست‌نوشتهٔ سه‌زبانه (فارسی/عربی/انگلیسی) با ۱٬۰۰۰ صفحه، ۲۴٬۰۳۰ خط، ۱۶٬۵۴۲ نمونهٔ اگمنت‌شده، ۱۷۷٬۲۷۰ کلمه و ۴۵ نویسندهٔ بدون نشت بین اسپلیت‌ها. چهار فرمت برچسب (IAM/JSONL/PAGE-XML/COCO)، مجموعه‌بنچمارک CER/WER چندفرمته و کد کامل fine-tune مدل TrOCR همراه دیتاست منتشر می‌شود.