Add core weights as safetensors (recognizer + line detector, 71.2M params)

51b8c31 verified about 14 hours ago

6.38 kB

---
language:
- fa
license: other
license_name: bina-0.4-rizeh
pipeline_tag: image-to-text
tags:
- bina
- ocr
- persian
- farsi
- handwriting
- printed-text
- ctc
- document-understanding
datasets:
- Reza2kn/persian-handwriting-pages-3.69m
- Reza2kn/persian-printed-ocr-3.5m
---
# Bina 0.4 Rizeh

Bina 0.4 Rizeh is the small, fast member of the Bina 0.4 Persian OCR family. It reads whole pages (printed text, handwriting, forms, screenshots, letters, newspapers and simple math). Its core is about 71M parameters: a 38.5M line detector (fine-tuned Surya text detector) and a 32.8M CTC line recognizer distilled from [Bina 0.4 Koochik](https://huggingface.co/Reza2kn/Bina-0.4-Koochik). They run inside a page pipeline:

1. **Layout**: Surya layout (`datalab-to/surya_layout2`, pinned revision, downloaded on first run).
2. **Lines**: fine-tuned Surya-architecture line detectors (body text, printed layer, handwriting page path).
3. **Reading**: the 95k-step Indra CTC student for body text, plus specialist readers with the same architecture: printed/form labels, short form cells, numeric and math, and degraded scans.
4. **Assembly**: row consolidation, column and table ordering, printed-label admission and page-level ordering.

This repository is the complete production pipeline exactly as it scored below, not just a checkpoint: all weights, calibrations and code are bundled.

## Quick run

```bash
hf download Reza2kn/Bina-0.4-Rizeh --local-dir Bina-0.4-Rizeh
cd Bina-0.4-Rizeh
pip install -r requirements.txt          # Python 3.10, NVIDIA GPU recommended
python rizeh.py examples/demo.png --out results
python rizeh.py scan1.jpg scan2.png document.pdf --out results
```

The first run binds the bundled paths to your checkout (it edits the bundled text files in place, and reruns automatically if you move the folder) and downloads the pinned Surya layout model. For each page you get `<name>.txt` with the page text in reading order, and `<name>.json` with every line's text, box, layer (`printed` / handwriting / body) and confidence. PDFs are rendered at 200 dpi.

From Python:

```python
from PIL import Image
from rizeh import Rizeh
ocr = Rizeh("cuda")
result = ocr(Image.open("page.jpg").convert("RGB"))
print(result["text"])
```

## Scores

Character error rate (CER, %) on the internal gates this release was frozen on. Lower is better.

| Gate | CER |
|---|---:|
| 193 cropped regions, overall | 9.39 |
| · forms | 3.80 |
| · screenshots | 4.65 |
| · prose | 9.15 |
| · math | 12.09 |
| · newspaper | 13.49 |
| · tables | 19.63 |
| 50 handwriting pages, handwritten body only | 3.97 |
| 50 handwriting pages, full page incl. printed form text | 10.89 |
| 338 printed lines | 1.76 |
| 7 real scanned documents (printed regions) | 10.61 |
| Scanned official letter | 2.12 |

[Persian OCR Triple Threat](https://huggingface.co/spaces/Reza2kn/PersianOCR-TripleThreat), same 95k recognizer, measured 2026-11-03 before the final assembly fixes (lower is better):

| Split | Rows | WER | CER | S³ | Triple Threat |
|---|---:|---:|---:|---:|---:|
| Printed | 6,669 | 4.70 | 1.37 | 5.88 | 4.74 |
| Handwriting | 6,669 | 18.48 | 13.01 | 15.19 | 15.41 |
| Equal-split overall | 13,338 | 11.59 | 7.19 | 10.54 | **10.08** |

## Limitations

- **Historical manuscripts do not work.** On HPHD (historical nastaliq and shekasteh manuscripts) the recognizer is at 67% CER even on oracle line crops, and full pages come out as fluent-looking nonsense. Do not use it for manuscripts.
- **Tables are weak** (about 20% CER), especially dense or low-resolution tables with handwriting over the cells.
- **Reading order** on busy layouts (multi-column newspapers, exam sheets with many labels) is the largest remaining error source; the characters are usually right but lines can come out in a different order.
- **Faint or coloured printed labels** (light-blue Nastaliq on forms) are often missed.
- The pipeline has many stages tuned together. Swapping one component (for example a newer recognizer) without retuning the stages after it makes results worse; this was measured, not assumed.
- Persian-first. Latin text and digits are read, but other languages were not a goal.
- Confidences are model scores, not calibrated probabilities.

## Training and provenance

- Recognizer: Indra CTC, 32,796,250 parameters, 20 blocks, 1,617-symbol vocabulary; 95,000 training steps, distilled from Bina 0.4 Koochik checkpoint 18,404.
- Specialist readers (printed labels, form cells, numeric/math, degraded scans) are 32.8M fine-tunes of the same recognizer; the two line detectors are 38.5M fine-tunes of Surya's text detector, and the printed-text head adds 0.39M.
- Checkpoint selection used internal development sets only; the gates above were never used to pick weights.
- `model.safetensors` holds the two core networks (`recognizer.*`, 32.8M, and `line_detector.*`, 38.5M) in safetensors form for reuse and fine-tuning. `rizeh.py` runs from the original files under `stallion/`, which contain the same weights.
- `MANIFEST.json` lists every bundled file with its original location and size. Under `stallion/` the files are organized by experiment directory exactly as they ran in production; `rizeh.py` is the entry point.

## License

Bina recognizer weights and code: CC BY-NC 4.0, matching the non-commercial training data. Line-detector weights are fine-tunes of Surya (datalab) detection weights, and the Surya layout model is downloaded from datalab; both stay under [Surya's model license](https://github.com/datalab-to/surya), which limits commercial use.

## فارسی

بینا ۰٫۴ ریزه عضو کوچک و سریع خانواده OCR فارسی بینا ۰٫۴ است. یک مدل CTC با ۳۲٫۸ میلیون پارامتر که از بینا ۰٫۴ کوچیک تقطیر شده، درون یک خط‌لوله کامل صفحه کار می‌کند: چیدمان صفحه، تشخیص خط، خواندن متن چاپی و دست‌نویس، فرم‌ها، اعداد و چیدن متن به ترتیب خواندن.

```bash
pip install -r requirements.txt
python rizeh.py page.jpg --out results
```

محدودیت مهم: روی نسخه‌های خطی تاریخی (نستعلیق و شکسته قدیمی) قابل استفاده نیست، و جدول‌ها و ترتیب خواندن صفحه‌های شلوغ هنوز ضعیف‌اند.

	---
	language:
	- fa
	license: other
	license_name: bina-0.4-rizeh
	pipeline_tag: image-to-text
	tags:
	- bina
	- ocr
	- persian
	- farsi
	- handwriting
	- printed-text
	- ctc
	- document-understanding
	datasets:
	- Reza2kn/persian-handwriting-pages-3.69m
	- Reza2kn/persian-printed-ocr-3.5m
	---

	# Bina 0.4 Rizeh

	Bina 0.4 Rizeh is the small, fast member of the Bina 0.4 Persian OCR family. It reads whole pages (printed text, handwriting, forms, screenshots, letters, newspapers and simple math). Its core is about 71M parameters: a 38.5M line detector (fine-tuned Surya text detector) and a 32.8M CTC line recognizer distilled from [Bina 0.4 Koochik](https://huggingface.co/Reza2kn/Bina-0.4-Koochik). They run inside a page pipeline:

	1. Layout: Surya layout (`datalab-to/surya_layout2`, pinned revision, downloaded on first run).
	2. Lines: fine-tuned Surya-architecture line detectors (body text, printed layer, handwriting page path).
	3. Reading: the 95k-step Indra CTC student for body text, plus specialist readers with the same architecture: printed/form labels, short form cells, numeric and math, and degraded scans.
	4. Assembly: row consolidation, column and table ordering, printed-label admission and page-level ordering.

	This repository is the complete production pipeline exactly as it scored below, not just a checkpoint: all weights, calibrations and code are bundled.

	## Quick run

	```bash
	hf download Reza2kn/Bina-0.4-Rizeh --local-dir Bina-0.4-Rizeh
	cd Bina-0.4-Rizeh
	pip install -r requirements.txt # Python 3.10, NVIDIA GPU recommended
	python rizeh.py examples/demo.png --out results
	python rizeh.py scan1.jpg scan2.png document.pdf --out results
	```

	The first run binds the bundled paths to your checkout (it edits the bundled text files in place, and reruns automatically if you move the folder) and downloads the pinned Surya layout model. For each page you get `<name>.txt` with the page text in reading order, and `<name>.json` with every line's text, box, layer (`printed` / handwriting / body) and confidence. PDFs are rendered at 200 dpi.

	From Python:

	```python
	from PIL import Image
	from rizeh import Rizeh
	ocr = Rizeh("cuda")
	result = ocr(Image.open("page.jpg").convert("RGB"))
	print(result["text"])
	```

	## Scores

	Character error rate (CER, %) on the internal gates this release was frozen on. Lower is better.

	\| Gate \| CER \|
	\|---\|---:\|
	\| 193 cropped regions, overall \| 9.39 \|
	\| · forms \| 3.80 \|
	\| · screenshots \| 4.65 \|
	\| · prose \| 9.15 \|
	\| · math \| 12.09 \|
	\| · newspaper \| 13.49 \|
	\| · tables \| 19.63 \|
	\| 50 handwriting pages, handwritten body only \| 3.97 \|
	\| 50 handwriting pages, full page incl. printed form text \| 10.89 \|
	\| 338 printed lines \| 1.76 \|
	\| 7 real scanned documents (printed regions) \| 10.61 \|
	\| Scanned official letter \| 2.12 \|

	[Persian OCR Triple Threat](https://huggingface.co/spaces/Reza2kn/PersianOCR-TripleThreat), same 95k recognizer, measured 2026-11-03 before the final assembly fixes (lower is better):

	\| Split \| Rows \| WER \| CER \| S³ \| Triple Threat \|
	\|---\|---:\|---:\|---:\|---:\|---:\|
	\| Printed \| 6,669 \| 4.70 \| 1.37 \| 5.88 \| 4.74 \|
	\| Handwriting \| 6,669 \| 18.48 \| 13.01 \| 15.19 \| 15.41 \|
	\| Equal-split overall \| 13,338 \| 11.59 \| 7.19 \| 10.54 \| 10.08 \|

	## Limitations

	- Historical manuscripts do not work. On HPHD (historical nastaliq and shekasteh manuscripts) the recognizer is at 67% CER even on oracle line crops, and full pages come out as fluent-looking nonsense. Do not use it for manuscripts.
	- Tables are weak (about 20% CER), especially dense or low-resolution tables with handwriting over the cells.
	- Reading order on busy layouts (multi-column newspapers, exam sheets with many labels) is the largest remaining error source; the characters are usually right but lines can come out in a different order.
	- Faint or coloured printed labels (light-blue Nastaliq on forms) are often missed.
	- The pipeline has many stages tuned together. Swapping one component (for example a newer recognizer) without retuning the stages after it makes results worse; this was measured, not assumed.
	- Persian-first. Latin text and digits are read, but other languages were not a goal.
	- Confidences are model scores, not calibrated probabilities.

	## Training and provenance

	- Recognizer: Indra CTC, 32,796,250 parameters, 20 blocks, 1,617-symbol vocabulary; 95,000 training steps, distilled from Bina 0.4 Koochik checkpoint 18,404.
	- Specialist readers (printed labels, form cells, numeric/math, degraded scans) are 32.8M fine-tunes of the same recognizer; the two line detectors are 38.5M fine-tunes of Surya's text detector, and the printed-text head adds 0.39M.
	- Checkpoint selection used internal development sets only; the gates above were never used to pick weights.
	- `model.safetensors` holds the two core networks (`recognizer.`, 32.8M, and `line_detector.`, 38.5M) in safetensors form for reuse and fine-tuning. `rizeh.py` runs from the original files under `stallion/`, which contain the same weights.
	- `MANIFEST.json` lists every bundled file with its original location and size. Under `stallion/` the files are organized by experiment directory exactly as they ran in production; `rizeh.py` is the entry point.

	## License

	Bina recognizer weights and code: CC BY-NC 4.0, matching the non-commercial training data. Line-detector weights are fine-tunes of Surya (datalab) detection weights, and the Surya layout model is downloaded from datalab; both stay under [Surya's model license](https://github.com/datalab-to/surya), which limits commercial use.

	## فارسی

	بینا ۰٫۴ ریزه عضو کوچک و سریع خانواده OCR فارسی بینا ۰٫۴ است. یک مدل CTC با ۳۲٫۸ میلیون پارامتر که از بینا ۰٫۴ کوچیک تقطیر شده، درون یک خط‌لوله کامل صفحه کار می‌کند: چیدمان صفحه، تشخیص خط، خواندن متن چاپی و دست‌نویس، فرم‌ها، اعداد و چیدن متن به ترتیب خواندن.

	```bash
	pip install -r requirements.txt
	python rizeh.py page.jpg --out results
	```

	محدودیت مهم: روی نسخه‌های خطی تاریخی (نستعلیق و شکسته قدیمی) قابل استفاده نیست، و جدول‌ها و ترتیب خواندن صفحه‌های شلوغ هنوز ضعیف‌اند.