meldynamics/polish-metrical-htr-experimental

Polish Metrical HTR — experimental (strict teacher-data v2)

Experimental release, updated 2026-08-19. This is a fine-tuned line recognizer for nineteenth-century Polish Roman-Catholic metrical registers. It is intended for a geometry-aware, polygon-masked line-crop pipeline; it is not a whole-page OCR or layout model.

This revision replaces the original P5 checkpoint with the strict-v2 candidate selected on book-exclusive development data. The original public checkpoint is preserved as Hub tag p5-20260816.

Intended scope

• Polish-script metrical books, principally 1800–1865.
• Handwritten record prose, names, dates, places, and limited printed form text.
• RGB line/cell crops resized to 192×1024.
• ViT inference with interpolate_pos_encoding=True.

Do not use this model for Cyrillic/Russian registers, Latin-heavy registers, or as a substitute for page segmentation, table/cell assignment, or reading order. Route Ecclesiastical Latin and mixed Latin/Lithuanian pages to a suitable multilingual model instead.

Base model and training method

The lineage is:

1. Kansallisarkisto/multicentury-htr-model,
2. the original P5 Polish checkpoint, then
3. this strict-v2 low-learning-rate encoder-unfrozen continuation.

Training is sequence-level knowledge distillation: Transkribus HTR model 464825 generated pseudo-labels for archive-page line polygons, and the student learned (masked crop → pseudo-transcription) pairs. This is not logit distillation and not a claim that the labels are human ground truth.

The private training corpus is not published here. No archive images, line crops, or Transkribus transcriptions are included in this repository.

Input contract

The tested production path is:

1. obtain the PAGE line/cell polygon in native image coordinates;
2. take its bounding box;
3. copy pixels inside the polygon and fill everything outside it with white;
4. rotate explicitly classified vertical text when required;
5. pass the RGB crop through the bundled processor at 192×1024; and
6. decode greedily while preserving upstream reading order.

A plain bbox crop includes neighboring handwriting and is a different input distribution. Full-page images must be segmented before recognition.

Strict-v2 data policy

The split unit is the complete EAIS inventory/book, never a random line. Books are mutually exclusive across optimizer input, broad development, historical compatibility, and the frozen test.

training component	exposures	policy
original handwritten P5 rows	11,267	retained base handwriting
unique new P6 teacher rows	9,056	geometry/plausibility/novelty/form selection
bounded active-learning repeats	1,811	maximum 2×; plausible moderate disagreements only
synthetic period-style print	1,165	controlled to 5% of exposures
total	23,299	67 positive-ID training books

An additional 15,663 P6 rows were capped or quarantined rather than blindly trained. High student/teacher disagreement alone is not sufficient evidence of a useful label: it can indicate a teacher error, fragment, vertical annotation, or incorrect crop. Four P6 books unseen by P5 (2,590 real-pipeline line crops) were development-only and were excluded even from the training lexicon used by soft label-quality gates.

Training settings for this revision:

item	setting
initialization	original P5 checkpoint
epochs	4; best selected by book-exclusive dev CER
batch	12; no gradient accumulation
learning rate	1e-5, cosine decay, 5% warm-up
encoder	unfrozen
precision	bfloat16
label max length	96 tokens
validation decoding	greedy, 80 generated tokens

Evaluation

All numbers below measure agreement with automatic Transkribus 464825 text, not absolute OCR accuracy against human transcription.

Book-exclusive broad development

Four books and 2,590 line crops, unseen during P5 and strict-v2 training:

model	CER	WER
original P5	0.4038	0.8150
strict-v2 (this revision)	0.3516	0.7732

Frozen random P7 test through the production crop pipeline

P7 contains 1,972 aligned lines from 18 independently random, previously unseen books (one page per book). Both checkpoints used identical saved PAGE polygons, legacy-A4-to-native coordinate scaling, polygon-mask/bbox-fill crops, 192×1024 input, and greedy decoding.

model	micro CER	micro WER	book-macro CER	exact-line rate
original P5	0.4860	0.8803	0.6279	1.37%
strict-v2 (this revision)	0.4266	0.8454	0.5530	1.52%

The paired whole-book bootstrap candidate-minus-baseline delta is −0.0593 CER (95% CI −0.0690 to −0.0500) and −0.0349 WER (95% CI −0.0449 to −0.0246). Every tested form and crop-geometry stratum improved. On normal horizontal body lines, CER changed from 0.4617 to 0.4021.

Historical compatibility

On the original narrow 1,679-line handwritten split, CER changed from 0.3359 to 0.2951. This cohort is retained for historical compatibility, not model selection or production-accuracy estimation.

Human-ground-truth status

A frozen review queue exists with 240 uniformly sampled representative P7 lines and a separate 60-line high-disagreement challenge set. At publication time it is 0/240 reviewed, so no human CER/WER is reported. Do not quote the teacher-relative values above as human transcription accuracy.

Usage

pip install torch transformers pillow
python inference.py masked_line_crop.png --device cuda

inference.py is a self-contained wide-line implementation. It loads the bundled processor, fixes the processor 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)

Start at 8–16 crops per GPU batch and increase only while memory permits. Keep greedy decoding and the exact resize/interpolation contract for comparisons; changing them creates 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, approximately 2.4 GB
strict-v2 weight SHA-256	5c4abb0e9d68d416bc95692a9d2d4634afb10fe0068b644ada60cd9816f917e8
tested stack	PyTorch CUDA; Transformers 5.2.x

CPU inference works but is substantially slower.

Limitations

• Teacher errors are inherited by sequence-level distillation.
• The frozen random test remains difficult (teacher-relative CER 0.4266).
• Short fragments, compact/vertical annotations, and bad line polygons remain much harder than ordinary horizontal body lines.
• The model performs recognition only: it does not assign cells, group records, infer people/events, or validate historical facts.
• Polish names appearing inside Latin or Cyrillic records do not make the whole page an appropriate input for this model.

Licensing and provenance

This derivative is released under Apache License 2.0, matching its immediate base model, Kansallisarkisto/multicentury-htr-model. The repository includes the Apache-2.0 license and identifies the modification and direct parent.

Upstream caveat for commercial users: the base model identifies microsoft/trocr-large-handwritten as an ancestor; that checkpoint was fine-tuned on IAM data. IAM's database terms are research/non-commercial. The Microsoft checkpoint itself declares no Hub weight license, while the related UniLM/TrOCR source code is MIT-licensed. Kansallisarkisto released its direct derivative under Apache-2.0. This project follows the direct-parent license but does not represent the entire ancestry as independently cleared for every commercial use. Obtain legal review where required.

Transkribus terms grant users broad rights to use, modify, and create derivative works from recognition results; source-image and archive rights remain 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 = {Strict teacher-data v2 fine-tune of Kansallisarkisto/multicentury-htr-model}
}

Also cite the upstream base model and TrOCR work when appropriate.