RaphaelBfr/morphology4metrology

Leveraging Morphology for Historical Script Metrological Analysis

Pretrained checkpoint for the architecture presented in Leveraging Morphology for Historical Script Metrological Analysis (ICDAR 2026).

Authors: Malamatenia Vlachou Efstathiou*, Raphaël Baena*, Dominique Stutzmann, Mathieu Aubry

Links

Paper (arXiv)	arxiv.org/abs/2606.09446
Project page	malamatenia.github.io/morphology4metrology-analysis
Code	github.com/raphael-baena/morphology4metrology
Metrological analysis	github.com/malamatenia/morphology4metrology-analysis
Paper dataset	Zenodo — BnF fr. 2813 (DOI: 10.5281/zenodo.18745702)

Description

This checkpoint is the pretrained detector used as starting weights for step 0 of the training pipeline described in the paper.

The architecture learns interpretable, learnable character prototypes along with precise, instance-level bounding boxes using only line-level transcription supervision.

Note: This Hugging Face repository hosts the pretrained weights only. Installation, training, and inference are handled in morphology4metrology. To perform the downstream metrological and paleographical analysis (and reproduce the visualizations reported in the paper), export the outputs from this pipeline and use morphology4metrology-analysis.

Files in this repository

File	Description
checkpoint.pth	Pretrained detector — use as --model_checkpoint_path in step 0 (with --init)
config/Latin_accent.py	Model config — use as --model_config_path

Download

pip install huggingface_hub
hf download RaphaelBfr/morphology4metrology checkpoint.pth --local-dir ./weights
hf download RaphaelBfr/morphology4metrology config/Latin_accent.py --local-dir ./weights/config

Or in Python:

from huggingface_hub import hf_hub_download

checkpoint = hf_hub_download("RaphaelBfr/morphology4metrology", "checkpoint.pth")
config = hf_hub_download("RaphaelBfr/morphology4metrology", "config/Latin_accent.py")

Quick start

1. Clone and install morphology4metrology.
2. Download the weights above into ./weights/.
3. Prepare a line dataset under datasets_path (see Input data format).
4. Run the 3-step training pipeline starting from this checkpoint.

You do not need to run synthetic pretraining — download this checkpoint and go directly to step 0.

Training pipeline

Step	Goal	Input	Output
0	Frozen boxes — learn prototypes + classifier	checkpoint.pth + --init	model.pth, reconstructor.pth
1	Full training — boxes + prototypes jointly	step 0 outputs	model.pth, reconstructor_unfrozen.pth
2	Per-document or per-script finetuning	step 1 outputs	one checkpoint folder per subset

Ready-made scripts for the paper dataset: scripts/btv1b84472995/.

Step 0 — frozen boxes, learn prototypes + classifier

python reconstruction.py \
  --dataset_file dataset \
  --data_folder btv1b84472995 \
  --space_index 0 \
  --model_config_path config/Latin_accent.py \
  --max_e 20 \
  --num_fine_classes 2 \
  --step 0 \
  --batch_size 16 \
  --sprite_size 32 \
  --line_resize_h_ref 90 \
  --line_resize_max_width 1400 \
  --init \
  --tag btv1b84472995_step_0 \
  --loss L1 \
  --model_checkpoint_path ./weights/checkpoint.pth

Argument	Role
--step 0	Freeze detector boxes; train reconstructor + classification head only
--init	Rebuild classifier for the dataset charset from the pretrained checkpoint
--model_checkpoint_path	This checkpoint (checkpoint.pth)
--tag	Run name; outputs go to logs_reconstruction/<tag>/

Outputs (logs_reconstruction/btv1b84472995_step_0/): model.pth, reconstructor.pth

Step 1 — full model

python reconstruction.py \
  --dataset_file dataset \
  --data_folder btv1b84472995 \
  --space_index 0 \
  --model_config_path config/Latin_accent.py \
  --max_e 100 \
  --num_fine_classes 2 \
  --step 1 \
  --batch_size 8 \
  --sprite_size 32 \
  --line_resize_h_ref 90 \
  --line_resize_max_width 1400 \
  --learning_rate 1e-4 \
  --weight_loss_reconstruction 3 \
  --tag btv1b84472995_step_1 \
  --loss L1 \
  --model_checkpoint_path logs_reconstruction/btv1b84472995_step_0/model.pth \
  --reconstructor_path logs_reconstruction/btv1b84472995_step_0/reconstructor.pth

Outputs (logs_reconstruction/btv1b84472995_step_1/): model.pth, reconstructor_unfrozen.pth, sprites/, transcribe.json

Step 2 — per-document finetuning

python reconstruction.py \
  --dataset_file dataset \
  --data_folder btv1b84472995 \
  --documents \
  --space_index 0 \
  --max_e 140 \
  --num_fine_classes 2 \
  --step 2 \
  --sprite_size 32 \
  --line_resize_h_ref 90 \
  --line_resize_max_width 1400 \
  --mask_sprite \
  --learning_rate 1e-2 \
  --learning_rate_background 1e-5 \
  --batch_size 8 \
  --tag btv1b84472995_finetune \
  --output_dir logs_reconstruction/ \
  --prototypes_only_path logs_reconstruction/btv1b84472995_step_1/reconstructor_unfrozen.pth \
  --model_checkpoint_path logs_reconstruction/btv1b84472995_step_1/model.pth \
  --annotation_file /path/to/datasets/btv1b84472995/annotation.json

Step 2 also supports --script <name> to finetune per hand/style label instead of --documents.

Input data format

<datasets_path>/<data_folder>/
├── annotation.json
├── images/
│   ├── <document_prefix>/
│   │   ├── <line_id>.png
│   │   └── ...
│   └── ...

{
  "IB15304245v_eSc_line_65f6c260.png": {
    "label": "sy enlas armas por bueno q̃ sea",
    "page": "IB15304245v.jpg",
    "split": "train",
    "script": "Southern_Textualis"
  }
}

Set the datasets root in datasets/config.json:

{
  "datasets_path": "/path/to/your/datasets"
}

Export paleography_input/

After step 1 and finetuning, export sprites and bbox JSONs for downstream analysis:

python export_paleography_input.py \
  --step1_dir logs_reconstruction/btv1b84472995_step_1 \
  --finetune_dir logs_reconstruction/btv1b84472995_finetune \
  --dataset_file dataset \
  --data_folder btv1b84472995 \
  --model_config_path config/Latin_accent.py \
  --line_resize_h_ref 90 \
  --line_resize_max_width 1400

Then use morphology4metrology-analysis on the exported paleography_input/ folder.

Paper dataset

Experiments use the Grandes Chroniques de France line dataset (Paris, BnF, fr. 2813), published on Zenodo. Download dataset.zip, extract under your datasets_path, and use --data_folder btv1b84472995.

Citation

@inproceedings{vlachou2026metrology,
  title     = {Leveraging Morphology for Historical Script Metrological Analysis},
  author    = {Vlachou-Efstathiou, Malamatenia and Baena, Raphael and
               Stutzmann, Dominique and Aubry, Mathieu},
  booktitle = {Document Analysis and Recognition -- ICDAR 2026},
  publisher = {Springer},
  year      = {2026}
}

Preprint: arXiv:2606.09446