README.md · failed09/bashkir-trocr-base at main

File size: 9,944 Bytes

c8cdee4

---
language:
- ba
license: apache-2.0
pretty_name: BashkirTrOCR
library_name: onnxruntime
pipeline_tag: image-to-text
tags:
- bashkir
- trocr
- ocr
- optical-character-recognition
- vision-encoder-decoder
- text-recognition
- onnx
- onnxruntime
- int8
- fp16
- low-resource
- experimental
---

# 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):

![Bashkir OCR Studio line recognition comparison](examples/line_comparison.png)

## Method

```text
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`](https://huggingface.co/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](https://huggingface.co/failed09/bashkir-diacritics-restorer) — character-level restorer for Bashkir-specific letters (`ә, ө, ү, ғ, ҡ, ң, һ, ҫ, ҙ`), useful for post-correcting characters confused on degraded scans.
- [BashkirRoBERTa](https://huggingface.co/failed09/bashkir-roberta) — 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`:

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

### 2. Command-Line & Custom Pipeline API

```bash
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
```

```python
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](https://huggingface.co/failed09/bashkir-trocr-base/blob/main/LICENSE). Upstream attributions for TrOCR (`MIT`) and RapidOCR (`Apache-2.0`) are recorded in [NOTICE](https://huggingface.co/failed09/bashkir-trocr-base/blob/main/NOTICE). Rights in original source publications remain with their respective owners; raw book scans and training texts are not redistributed.

## Citation

```bibtex
@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.