doclayout-yolov10-rukopys

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

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:

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)

Class distribution (gold stage, region counts)

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)

Per class

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

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.