meldynamics/polish-metrical-htr-experimental

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

1. take the line polygon in native image coordinates;
2. crop its bounding box, keep pixels inside the polygon, fill the outside white;
3. resize the RGB crop to 192×1024;
4. 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.