failed09/bashkir-trocr-base

BashkirTrOCR

Optical Character Recognition for printed Bashkir books and documents, shipped as standalone ONNX models (FP16 CUDA GPU & dynamic INT8 CPU) with a local browser review studio.

Overview

This model transcribes printed Bashkir text lines and full document pages. It supports the complete 42-letter Bashkir Cyrillic alphabet, including all 9 specific letters (ә, ө, ү, ғ, ҡ, ң, һ, ҫ, ҙ), mixed Russian-Bashkir lines, punctuation, and dialogue formatting.

The release bundles a complete zero-PyTorch ONNX Runtime pipeline: PP-OCRv3 (DBNet) text-line detection, wide-line splitting, ViT-Base + TrOCR recognition in both mixed FP16 (for NVIDIA CUDA GPUs) and dynamic INT8 (for CPUs), a CLI runner, and Bashkir OCR Studio — a local web interface with two review modes (line-by-line crop comparison and side-by-side full page + full text).

At a glance
Task	Page & line-level Optical Character Recognition (image-to-text)
Default artifact	models/fp16/ (CUDA GPU) / models/int8/ (CPU)
Architecture	Vision-Encoder-Decoder (ViT-Base + TrOCR Causal LM) + PP-OCRv3 detector
Version / license	v3.0-onnx-runtime.1 / Apache-2.0

Contents

Files and Configurations

File / Directory	Purpose	Size
models/fp16/encoder.onnx (recommended for GPU)	Mixed FP16 ViT encoder for NVIDIA CUDA	172.3 MB
models/fp16/decoder.onnx (recommended for GPU)	Mixed FP16 TrOCR decoder for NVIDIA CUDA	598.1 MB
models/int8/encoder.onnx (recommended for CPU)	Dynamic INT8 ViT encoder for CPU	89.8 MB
models/int8/decoder.onnx (recommended for CPU)	Dynamic INT8 TrOCR decoder for CPU	300.4 MB
models/dbnet.onnx	PP-OCRv3 text-line detector graph	2.4 MB
tokenizer.json, tokenizer_config.json	Tokenizer vocabulary (50,283 tokens) and settings	1.8 MB
config.json, preprocessor_config.json	Runtime contract, generation limits and image normalization	—
start_ocr.bat, studio.py, run.py, runtime/	One-click Windows launcher, local browser studio and CLI	—
requirements-cpu.txt, requirements-gpu.txt	Isolated dependency manifests for CPU and CUDA runtimes	—
QUICKSTART_RU.md	Quickstart guide and troubleshooting in Russian	—
META.json	Release passport and artifact hashes	—
LICENSE, NOTICE, licenses/	Full Apache-2.0 license text and upstream attributions	—
SHA256SUMS	Checksums of the public files	—

Raw training corpora, rendered synthetic image archives and full PyTorch checkpoints are not included.

Model Architecture

Property	Value
Base architecture	Vision-Encoder-Decoder (VisionEncoderDecoderModel)
Encoder	Vision Transformer (ViT-Base, 12 layers, 12 attention heads, hidden size 768)
Decoder	TrOCR Autoregressive Transformer Decoder (12 layers, 16 heads, hidden size 1024)
Line detector	PP-OCRv3 (DBNet) polygon detector + horizontal line merger
Parameters	~334M
Vocabulary	50,283 tokens
Image resolution	384 × 384 RGB

Examples

Side-by-side line recognition in Bashkir OCR Studio (cropped book lines on the left, recognized text on the right):

Method

BashkirTrOCR v3 pipeline
  ├── 1. page text-line detection (PP-OCRv3 / DBNet) & horizontal box merging
  ├── 2. wide-line splitting at whitespace valleys (aspect ratio > 20:1)
  ├── 3. ViT-Base visual encoding (384 × 384 RGB) & autoregressive TrOCR decoding
  └── 4. interactive browser review (line-by-line crops or full-page side-by-side)

The recognizer was adapted from microsoft/trocr-base-stage1 with full Bashkir Cyrillic vocabulary coverage and fine-tuned on a multi-domain collection of printed text lines (books, vintage scans, and digital typography). The trained v3 checkpoint was exported to ONNX and converted into two deployment variants:

• Mixed FP16 (models/fp16/) for NVIDIA CUDA GPUs, keeping graph inputs/outputs and numerically sensitive reductions in FP32 for exact parity with the PyTorch v3 checkpoint.
• Dynamic INT8 (models/int8/) for standalone CPU execution without a dedicated GPU.

Benchmark

Runtime parity and speed comparison between the bundled ONNX variants on the 133-line multi-page diagnostic suite (NVIDIA RTX 4060 vs CPU):

Runtime variant	Precision	Lines tested	Exact match vs PyTorch v3	Full poem page latency	133-line suite total time
NVIDIA CUDA GPU	Mixed FP16	133	133 / 133 (100%)	8.8 s	66.9 s
CPU	Dynamic INT8	133	114 / 133 (85.7%)	49.7 s	392.4 s

Differences between INT8 CPU and FP16 GPU outputs consist primarily of dash variants (— vs –) and minor punctuation on degraded scans.

Quality and Use

Use this release for assisted digitization of printed Bashkir books, articles, and dictionary pages. The bundled Bashkir OCR Studio (studio.py / start_ocr.bat) serves as a ready-to-run reference application for single-page interactive review with two view modes:

• Line-by-line review — inspect each detected line crop alongside its editable transcription.
• Full page & text — view the full page scan on the left and edit the complete page text as a single block on the right, with one-click clipboard copy and UTF-8 text export.

For large-scale book digitization, the standalone OCR engine (runtime/engine.py) or the raw ONNX graphs can be directly integrated into custom batch, PDF, or multi-page processing pipelines.

Limitations

• Tiny superscript footnote digits can be confused with punctuation (e.g. 1 → !), and visually similar glyphs (1, I, l, 7) require attention.
• Multi-column layouts, heavy page skew, decorative dividers, and low-contrast scans can affect reading order or line boundaries.
• Wide-line splitting may introduce spaces or split hyphenated words across chunk boundaries.
• Designed for printed Cyrillic Bashkir text; not intended for handwriting or historical Arabic-script manuscripts.

Related Resources

• Bashkir Diacritics Restorer — character-level restorer for Bashkir-specific letters (ә, ө, ү, ғ, ҡ, ң, һ, ҫ, ҙ), useful for post-correcting characters confused on degraded scans.
• BashkirRoBERTa — pretrained Bashkir masked language model suitable for scoring OCR hypotheses and reconstructing damaged words or broken line fragments.

Usage

Note: The bundled Bashkir OCR Studio web interface is provided as an interactive single-page usage example. For automated multi-page or full-book processing, import runtime.engine.OCR (or run the ONNX sessions directly) in your own batch pipeline.

1. Local Browser Studio (Windows One-Click Example)

Download the repository and double-click start_ocr.bat. By default ([3] Auto), the launcher automatically detects an NVIDIA GPU via nvidia-smi, creates an isolated .venv-gpu environment (or .venv-cpu on CPU-only machines), installs dependencies, and opens Bashkir OCR Studio at http://127.0.0.1:8001:

pip install huggingface_hub
hf download failed09/bashkir-trocr-base --local-dir bashkir-ocr

2. Command-Line & Custom Pipeline API

cd bashkir-ocr
python -m venv .venv-gpu
.venv-gpu\Scripts\python -m pip install -r requirements-gpu.txt

# Transcribe a page image from CLI (use --backend auto, gpu, or cpu)
.venv-gpu\Scripts\python run.py page.png --backend auto --output result.txt

# Launch the web studio manually
.venv-gpu\Scripts\python studio.py --backend auto

from PIL import Image
from runtime.engine import OCR

ocr = OCR(".", backend="auto")  # selects CUDA FP16 if available, else CPU INT8
result = ocr.recognize(Image.open("page.png"))
print(result["full_text"])

License

The model weights, ONNX graphs and runtime code are distributed under Apache-2.0. Upstream attributions for TrOCR (MIT) and RapidOCR (Apache-2.0) are recorded in NOTICE. Rights in original source publications remain with their respective owners; raw book scans and training texts are not redistributed.

Citation

@software{failed09_bashkir_trocr_2026,
  title = {BashkirTrOCR: Printed Bashkir OCR with ONNX Runtime (FP16 CUDA & INT8 CPU)},
  author = {failed09},
  year = {2026},
  publisher = {Hugging Face},
  url = {https://huggingface.co/failed09/bashkir-trocr-base},
  note = {Optical Character Recognition model and local review studio for Bashkir}
}

Open Bashkir Data and Sources 🐝

This release is part of an open-source effort to support the development, preservation and practical use of the Bashkir language. Other related models, datasets and tools are available on the author's Hugging Face profile.

The author does not claim ownership or authorship of the source texts or other materials used to derive this release; rights and licensing remain with the original authors, publishers and dataset providers. Source texts are not redistributed in this repository, so users should follow the licenses and attribution requirements of the relevant upstream resources.