doclayout-yolov10-rukopys

A DocLayout-YOLO (YOLOv10m-doclayout) document-layout detector for handwritten Ukrainian pages, fine-tuned on the Rukopys dataset with a 7-class head: 0 handwritten · 1 printed · 2 formula · 3 table · 4 annotation · 5 image · 6 graph.

TL;DR

	value
Architecture	DocLayout-YOLO, YOLOv10m-doclayout variant, 7-class head
Init from	juliozhao/DocLayout-YOLO-DocStructBench (10-class document-structure checkpoint)
Classes	handwritten, printed, formula, table, annotation, image, graph
Trained on	Rukopys, silver→gold two-stage curriculum
Gold-val mAP@50 / mAP@50-95	0.8263 / 0.5547 (macro over 7 classes)
Input	a document page image, 1024×1024
Output	class-labeled region bounding boxes

Intended use

Detecting and classifying page regions on handwritten Ukrainian documents, upstream of region recognizers (e.g. Hukyl/trocr-large-rukopys for text, Hukyl/trocr-base-rukopys-formula for formulas).

How to use

from huggingface_hub import hf_hub_download
from doclayout_yolo import YOLOv10

path = hf_hub_download("Hukyl/doclayout-yolov10-rukopys", "weights/best.pt")
model = YOLOv10(path)

# conf ~0.25-0.28 is the balanced (max-F1) operating point;
# lower it to trade precision for recall.
results = model.predict("page.jpg", imgsz=1024, conf=0.25)
for r in results:
    for box, cls, conf in zip(r.boxes.xyxy, r.boxes.cls, r.boxes.conf):
        print(model.names[int(cls)], conf.item(), box.tolist())

Files

weights/best.pt   gold-stage fitness checkpoint (epoch 3) — use this
weights/last.pt   final-epoch (60) checkpoint
metrics.json      val metrics: aggregate + per-class + a scan of the periodic
                  epoch checkpoints (each with its max-F1 confidence; the
                  intermediate checkpoints themselves are not uploaded)
args.yaml         exact gold-stage training configuration
results.csv       per-epoch metric/loss curves

Head transplant

The base 10-class DocStructBench checkpoint is adapted before training: the backbone, neck, and bbox-regression branch are loaded as-is, and the classification head is re-initialised with each of the 7 classes seeded from the semantically closest DocStructBench class:

class	DocStructBench source
handwritten	plain text
printed	plain text
formula	isolate_formula
table	table
annotation	plain text
image	figure
graph	figure

Training

Two-stage silver→gold curriculum; both stages are a full fine-tune (no frozen layers) of the transplanted checkpoint.

1. Silver pretrain: the auto-labeled Rukopys silver split — 8,202 pages / 160,942 regions, carrying ~63× more printed and ~8× more annotation than gold. 30-epoch budget, batch 16; the best checkpoint (epoch 20) warm-starts stage 2.
2. Gold fine-tune (the published weights): the human-labeled Rukopys train split, 60 epochs run in full.

Hyperparameters (gold stage, as launched)

hyperparameter	value
epochs	60 (early stopping disabled, patience=0)
batch / image size	20 / 1024
optimizer	AdamW, lr0 9.09e-4, lrf 0.01, momentum 0.937, weight decay 5e-4
warmup	3 epochs, bias lr 0
LR schedule	linear (cos_lr=false)
loss gains (box / cls / dfl)	7.5 / 0.5 / 1.5
augmentation	HSV 0.015/0.7/0.4, translate 0.1, scale 0.5, randaugment, erasing 0.4; mosaic/mixup/flips/rotation off
AMP	on
checkpoint	best.pt by fitness = 0.1·mAP@50 + 0.9·mAP@50–95 (epoch 3), saves every 3 epochs
seed	0 (training); data split seed 42

Class distribution (gold stage, region counts)

class	train	val
handwritten	19,420	2,157
printed	266	42
formula	2,545	347
table	128	14
annotation	494	60
image	115	4
graph	54	5
total	23,022	2,629

Results

Held-out val split of the Rukopys train data: 133 pages / 2,629 regions (stratified holdout, seed 42), evaluated on weights/best.pt. Box matching at IoU 0.50 (mAP@50–95 averages IoU 0.50:0.95), NMS at IoU 0.70. Precision and recall are reported at the max-F1 confidence operating point (0.284), not at a fixed threshold.

Aggregate (macro over 7 classes)

metric	value
mAP@50	0.8263
mAP@50-95	0.5547
precision	0.8101
recall	0.7635
max-F1 confidence	0.284

Per class

class	n	P	R	mAP@50	mAP@50-95
handwritten	2,157	0.9187	0.9342	0.9551	0.6264
printed	42	0.8714	0.8065	0.8950	0.5583
formula	347	0.9070	0.8415	0.9218	0.6321
table	14	0.8432	0.9286	0.9358	0.5237
annotation	60	0.7731	0.2839	0.4310	0.2008
image	4	0.3624	0.7500	0.7835	0.7057
graph	5	0.9951	0.8000	0.8617	0.6361

We also acknowledge that printed/table/annotation/image/graph n is quite small, so measuring detection metrics against them is quite noisy.

Limitations

• annotation recall is weak (0.28); margin notes are frequently missed.
• The detector tends to segment handwritten text finer than the dataset's annotators — long lines sometimes come out as word- or sub-line boxes, and these splits are high-confidence, so raising the threshold does not remove them. Downstream consumers that need annotator-granularity lines should merge boxes geometrically.
• Precision/recall are reported at the max-F1 confidence; calibrate the inference threshold against your own target metric.
• Handwritten Ukrainian school/archival-style pages only; behaviour on other document types is untested.
• Single seed and validation split — no across-run variance estimate.

Training data & attribution

dataset	source	license	role
Rukopys	UkrainianCatholicUniversity/rukopys	CC BY 4.0	silver pretrain (auto-labeled) + gold fine-tune

License & lineage

Model weights are AGPL-3.0, inherited from DocLayout-YOLO / Ultralytics YOLOv10. The base checkpoint juliozhao/DocLayout-YOLO-DocStructBench is DocLayout-YOLO trained on the DocStructBench document corpus.