---
language:
- si
license: other
license_name: pending-upstream-checkpoint-license-clarification
library_name: transformers
pipeline_tag: image-to-text
tags:
- trocr
- ocr
- sinhala
- printed-text
- vision-encoder-decoder
base_model: Ransaka/TrOCR-Sinhala
datasets:
- Ransaka/sinhala_synthetic_ocr-large
- avishadilhara/sinhala-ocr-lk-acts-1010
metrics:
- cer
- wer
---

# TrOCR Sinhala Printed Lines

> Phase 0 research repository. No fine-tuned weights or final evaluation results have been released yet.

This project investigates whether fine-tuning `Ransaka/TrOCR-Sinhala` on synthetic Sinhala text-line images improves printed, line-level Sinhala OCR performance on real documents.

## Project status

| Workstream | Status |
|---|---|
| Research scope | Locked in `PROTOCOL.md` |
| Dataset license | Confirmed MIT |
| Intermediate checkpoint license | Clarification required |
| Training | Not started |
| Evaluation | Not started |
| Model weights | Not published |

The synthetic dataset contains an MIT `LICENSE` file. However, `Ransaka/TrOCR-Sinhala` does not currently declare a license. This repository therefore uses `license: other` as a temporary, conservative status. Do not publish or redistribute derived weights until the checkpoint author provides a clear license or the release basis is independently reviewed.

## Research question

Does synthetic-data fine-tuning of TrOCR improve printed, line-level Sinhala OCR on real documents?

## Scope

### In scope

- Printed Sinhala text
- Line-level text recognition
- Character Error Rate (CER)
- Word Error Rate (WER)
- Comparisons with the unmodified checkpoint and Tesseract 5.5
- Optional Surya comparison when its applicable terms are confirmed
- Period-stratified analysis where document-year metadata is available

### Out of scope

- Handwriting
- Full-page layout detection or reading order
- Production or high-stakes deployment
- Broad Sinhala-English code mixing
- Claims of parity with page-level commercial or large vision-language systems

## Data

### Training and validation

`Ransaka/sinhala_synthetic_ocr-large`

- 6,969 synthetic Sinhala image-text pairs
- One published `train` split
- Five reported font families
- Dataset DOI: [10.57967/hf/1809](https://doi.org/10.57967/hf/1809)
- Repository `LICENSE`: MIT
- Fixed project split: 90% train and 10% validation using seed 42

The exact generated indices and dataset revision must be written to the experiment manifest before training.

### Real-document evaluation

`avishadilhara/sinhala-ocr-lk-acts-1010`

- 1,010 page images from Sri Lankan legislative acts
- Published splits: train 707, test 202, evaluation 101
- License: CC BY 4.0
- Paper: [arXiv:2606.29378](https://arxiv.org/abs/2606.29378)

TrOCR is a line-recognition model. The page dataset must therefore be converted into a documented, deterministic line-level benchmark before direct evaluation. Page-level benchmark figures are contextual references and must not be presented as directly comparable line-level results.

## Pre-registered experiment

The hypotheses, fixed splits, seeds, metrics, normalization, hyperparameters, decision rules, and reporting requirements are defined in [`PROTOCOL.md`](PROTOCOL.md). Material deviations must be documented before results are interpreted.

## Planned baselines

| System | Role | Primary comparison |
|---|---|---|
| `Ransaka/TrOCR-Sinhala` | Starting checkpoint | Measures improvement from additional fine-tuning |
| Tesseract 5.5 | Permissive classical baseline | CER and WER on the same line images |
| Surya OCR | Optional research baseline | CER and WER on the same evaluation unit |

Published page-level results are contextual targets only:

| System | CER | WER | Evaluation unit |
|---|---:|---:|---|
| Tesseract v5 | 10.69% | Not reported | Real pages |
| Surya OCR | 8.84% | 26.64% | Real pages |
| Google Document AI | 2.06% | Not reported | Real pages |
| Fine-tuned LightOnOCR-2-1B | 1.05% | 5.63% | Real pages |

These figures come from a June 2026 preprint and are not direct line-level acceptance thresholds.

## Planned training configuration

| Parameter | Pre-registered value |
|---|---|
| Optimizer | AdamW |
| Learning rate | 4e-5 |
| Epochs | 10 |
| Effective batch size | 8 |
| Precision | FP16 when supported |
| Seed | 42 |
| Evaluation beams | 4 |
| Runs | 3 independent runs |

The machine-readable configuration is in [`configs/phase0.yaml`](configs/phase0.yaml).

## Evaluation and reporting

CER is the primary metric and WER is secondary. Report:

- Results for every seed, plus mean and standard deviation
- Exact dataset revisions and split-index checksum
- Raw and normalized metrics
- 95% paired bootstrap confidence intervals for model differences
- Error examples grouped by degradation type
- Results by document period where supported
- Runtime and hardware details

Final results belong in `results/metrics.json` and the table below. Do not add zero-value placeholders to Hugging Face `model-index` metadata because they can be mistaken for real results.

| System | Dataset/slice | CER mean ± SD | WER mean ± SD | Status |
|---|---|---:|---:|---|
| Starting checkpoint | Real Sinhala line benchmark | TBD | TBD | Not run |
| Fine-tuned model | Real Sinhala line benchmark | TBD | TBD | Not run |
| Tesseract 5.5 | Real Sinhala line benchmark | TBD | TBD | Not run |
| Surya OCR | Real Sinhala line benchmark | TBD | TBD | Optional |

## Intended use

The eventual model is intended for research and prototyping involving printed Sinhala text lines, including OCR experiments, document digitization research, and accessibility prototypes. Human review is required for consequential use.

## Limitations

- Synthetic training data may not represent real scanning noise, skew, bleed-through, compression, damaged print, or historical typography.
- Training fonts cover only a limited part of Sinhala typography.
- Accuracy may degrade on older documents, handwriting, mixed-language text, unusual symbols, curved lines, and full pages.
- Line segmentation quality can dominate end-to-end page performance.
- Results from legislative acts may not generalize to receipts, books, forms, signs, or contemporary digital screenshots.

## Bias and responsible use

The training domain may overrepresent clean, computer-generated Sinhala and underrepresent historical fonts and real capture conditions. Evaluate new domains before use. Do not use unreviewed OCR output as authoritative evidence in legal, medical, financial, identity, or public-administration decisions.

Public legislative documents can contain names. Preserve source attribution, minimize unnecessary retention, and review extracted text before redistribution.

## Planned inference

The final release will support the standard Transformers interface:

```python
from PIL import Image
from transformers import TrOCRProcessor, VisionEncoderDecoderModel

repo_id = "kaan84/sinhala-print-trocr"
processor = TrOCRProcessor.from_pretrained(repo_id)
model = VisionEncoderDecoderModel.from_pretrained(repo_id)

image = Image.open("sinhala-line.png").convert("RGB")
pixel_values = processor(images=image, return_tensors="pt").pixel_values
generated_ids = model.generate(pixel_values, num_beams=4)
text = processor.batch_decode(generated_ids, skip_special_tokens=True)[0]
print(text)
```

This snippet will work only after weights and processor assets are published.

## Repository structure

```text
.
├── README.md
├── PROTOCOL.md
├── RISK_REGISTER.md
├── ATTRIBUTION_AND_LICENSING.md
├── REPRODUCIBILITY_CHECKLIST.md
├── requirements.txt
├── configs/
│   └── phase0.yaml
├── scripts/
│   └── README.md
├── assets/
│   └── README.md
├── runs/
│   └── README.md
└── results/
    ├── README.md
    └── metrics.template.json
```

## Release gates

1. Obtain and archive explicit licensing clarification for `Ransaka/TrOCR-Sinhala`.
2. Record immutable dataset and model revisions.
3. Commit split indices and their checksum.
4. Complete three seeded runs.
5. Run every baseline on identical evaluation units.
6. Populate real metrics and add `model-index` metadata.
7. Complete the reproducibility checklist.
8. Publish model weights only after the licensing gate passes.

## Citation

If this research is published, add its final citation here. Upstream citations and licensing notes are maintained in [`ATTRIBUTION_AND_LICENSING.md`](ATTRIBUTION_AND_LICENSING.md).