Polish Metrical HTR — experimental
A fine-tuned line recognizer for nineteenth-century Polish Roman-Catholic metrical registers (baptisms, marriages, deaths — names, dates, places, and record prose, principally 1800–1865). It reads one polygon-masked line crop at a time and returns its transcription. It is a recognizer only: it does not segment pages, find lines, or assign table cells.
Where to plug it in
This model shares the exact input contract of its base,
Kansallisarkisto/multicentury-htr-model,
so it is a drop-in replacement for the recognizer stage of the Finnish
National Archives pipeline. Run it inside the
Multicentury HTR Demo,
which handles page layout and line segmentation, and swap the recognizer for
this checkpoint to read Polish metrical hands.
Input contract
- take the line polygon in native image coordinates;
- crop its bounding box, keep pixels inside the polygon, fill the outside white;
- resize the RGB crop to 192×1024;
- decode greedily with
interpolate_pos_encoding=True.
How it was trained
Sequence-level knowledge distillation: an automatic archival HTR teacher
provided pseudo-labels for archive-page line polygons, and the student learned
(masked crop → transcription) pairs, initialized from the base multicentury
model. The split unit is the whole EAIS book, so training, development, and the
sealed test share no book. Training used 64,250 line exposures across 178 books;
crops are forced to 192×1024 (warp), 4 epochs, batch 12, lr 1e-5 cosine,
bfloat16, greedy decoding.
Evaluation
These numbers measure agreement with automatic teacher-generated text, i.e. teacher fidelity — not absolute accuracy against human transcription. There is no human ground truth for this material, so no human CER/WER is claimed.
| split | CER | WER |
|---|---|---|
| book-exclusive development (4 frozen books, 2,590 lines) | 0.315 | 0.731 |
| frozen random test (18 sealed books, 1,972 lines) | 0.385 | 0.809 |
The permitted use is experimental shadow OCR and fuzzy candidate generation with source-image linkage, raw-output provenance, and abstention — not authoritative transcription and not evidence for a genealogical fact.
Usage
pip install torch transformers pillow
python inference.py masked_line_crop.png --device cuda
inference.py is a self-contained implementation: it loads the
bundled processor, fixes the size to 192×1024, and passes
interpolate_pos_encoding=True during generation.
Batch inference
import torch
from PIL import Image
from transformers import TrOCRProcessor, VisionEncoderDecoderModel
model_id = "meldynamics/polish-metrical-htr-experimental"
processor = TrOCRProcessor.from_pretrained(
model_id, size={"height": 192, "width": 1024}
)
model = VisionEncoderDecoderModel.from_pretrained(model_id).cuda().eval()
images = [Image.open(path).convert("RGB") for path in line_crop_paths]
pixels = processor(images=images, return_tensors="pt").pixel_values.cuda()
with torch.inference_mode():
ids = model.generate(
pixels, max_new_tokens=96, num_beams=1, interpolate_pos_encoding=True
)
texts = processor.batch_decode(ids, skip_special_tokens=True)
Keep greedy decoding and the exact resize/interpolation contract; changing them is a different inference configuration.
Technical details
| item | value |
|---|---|
| architecture | TrOCR VisionEncoderDecoderModel (ViT encoder + autoregressive decoder) |
| required input | RGB polygon-masked line crop, 192×1024 |
| required generation flag | interpolate_pos_encoding=True |
| model parameters | 609,697,792 |
| weight format | SafeTensors, ~2.4 GB |
| weight SHA-256 | 34b651452fc0f015b6b03a2faee50fb1b6d2c6595e5c542066fc3c7d6dd8ac01 |
| tested stack | PyTorch CUDA; Transformers 5.2.x |
Limitations
- Teacher errors are inherited through distillation; teacher-relative CER is not human accuracy.
- Short fragments, compact cells, and bad line polygons are much harder than ordinary horizontal body lines.
- Recognition only — it does not assign cells, group records, or validate facts.
Licensing and provenance
Released under Apache License 2.0, matching the immediate base model
Kansallisarkisto/multicentury-htr-model; the repository includes the license
and identifies the direct parent.
Upstream caveat for commercial users: the base model lists
microsoft/trocr-large-handwritten as an ancestor, which was fine-tuned on IAM
data (research/non-commercial terms). This project follows the direct-parent
Apache-2.0 license but does not represent the entire ancestry as cleared for
every commercial use; obtain legal review where required. Source-image and
archive rights are separate and are not conveyed here.
Citation
@misc{meldynamics2026polishmetricalhtr,
author = {MelDynamics},
title = {Polish Metrical HTR -- experimental},
year = {2026},
publisher = {Hugging Face},
howpublished = {\url{https://huggingface.co/meldynamics/polish-metrical-htr-experimental}},
note = {Distilled fine-tune of Kansallisarkisto/multicentury-htr-model}
}
Also cite the base model and TrOCR work when appropriate.