ukr-htr-convtext

<div align="center"> # 🇺🇦 Ukrainian OCR / ICR (HTR-ConvText)

Handwritten & printed text recognition for Ukrainian

Upload an image → Get recognized text

English · Українська

</div> <div align="left" style="line-height: 1.6">

📋 Table of Contents

• ✨ Highlights
• 🚀 Quickstart
• 📖 Model Description
• 🖼️ Recognition Examples
• 🛠️ Tools & Scripts
• 📊 Evaluation
• 🙏 Attribution & Citation

✨ Highlights

🚀 Quickstart

from transformers import AutoModel, AutoProcessor

processor = AutoProcessor.from_pretrained("Valerii02/ukr-htr-convtext", trust_remote_code=True)
model = AutoModel.from_pretrained("Valerii02/ukr-htr-convtext", trust_remote_code=True)

inputs = processor(images="sample.png", return_tensors="pt")
logits = model(**inputs).logits
text = processor.batch_decode(logits)[0]
print(text)

💡 Try it now: Open the Gradio demo — no code required!

📖 Model Description

This repository packages a Ukrainian OCR/ICR model for handwritten and partially printed text with a Hugging Face–native API (AutoModel + AutoProcessor).

Architecture

• Backbone: ResNet-18 + MobileViT (MVP), hierarchical ConvText encoder (U-Net-like down/upsampling)
• Decoding: CTC greedy
• Vocabulary: 151 characters (Ukrainian + symbols)

Training Data

Training

• 500k iterations, batch 16 + grad accum 4
• SAM optimizer, EMA (decay 0.9999), TCM warmup 40k iters
• Scan simulation & detector-error augmentations
• Hardware: NVIDIA B200 (180GB VRAM)

🖼️ Recognition Examples

Real-world inference on scanned Ukrainian documents. GT = ground truth.

🛠️ Tools & Scripts

Conversion

python prepare_hf_artifacts.py \
  --checkpoint-path /path/to/best_CER.pth \
  --alphabet-path /path/to/alphabet.json \
  --output-dir ./release

ONNX Export

python export_onnx.py --hf-model-dir ./release --output-dir ./onnx

📊 Evaluation

Micro-averaging, format_string_for_wer normalization.

Comparison with other systems

On the same 124 real-world samples, the finetuned Ukrainian HTR-ConvText model (ukr-htr-convtext) was compared against several vision–language and HTR baselines.

Across this evaluation set, the proposed ukr-htr-convtext model more than halves the character error rate relative to the next best system (mamay) and strongly outperforms generic and domain-adapted VLM/HTR baselines.

⚠️ Limitations

• Sensitive to severe blur, low contrast, non-standard page artifacts
• Performance may drop on long lines far from training distribution
• CTC decoding can fail on highly ambiguous character boundaries

🙏 Attribution & Citation

This implementation adapts ideas from DAIR-Group/HTR-ConvText. See NOTICE and CITATION.cff for details. Upstream (HTR-ConvText):

@misc{truc2025htrconvtext,
  title={HTR-ConvText: Leveraging Convolution and Textual Information for Handwritten Text Recognition},
  author={Pham Thach Thanh Truc and Dang Hoai Nam and Huynh Tong Dang Khoa and Vo Nguyen Le Duy},
  year={2025},
  eprint={2512.05021},
  archivePrefix={arXiv},
  primaryClass={cs.CV},
  url={https://arxiv.org/abs/2512.05021},
}

This model: See CITATION.cff for full attribution.

📄 License

Apache-2.0. See LICENSE.

</div> <div align="left"> ⭐ Star this repo if you find it useful! · <a href="https://huggingface.co/Valerii02/ukr-htr-convtext/discussions">Report issues</a> · <a href="https://huggingface.co/Valerii02/ukr-htr-convtext">Contributions welcome</a> </div>