README.md

---
license: agpl-3.0
library_name: doclayout-yolo
pipeline_tag: object-detection
language:
- bo
tags:
- tibetan
- document-layout-analysis
- doclayout-yolo
- yolov10
- object-detection
- bounding-box
- BDRC
datasets:
- BDRC/TDLA-Training-Dataset-v2
metrics:
- name: canonical mean F1 (test)
  type: F1
  value: 0.947
model-index:
- name: Tibetan-Modern-Book-Layout-Detection-DocLayout-YOLO
  results:
  - task:
      type: object-detection
    dataset:
      name: TDLA-Training-Dataset-v2 (test)
      type: BDRC/TDLA-Training-Dataset-v2
    metrics:
    - type: mAP
      name: mAP@0.5 (native, test)
      value: 0.963
    - type: mAP
      name: mAP@0.5:0.95 (native, test)
      value: 0.775
---

# Tibetan Modern Book Layout Detection (DocLayout-YOLO)

A **DocLayout-YOLO** ([OpenDataLab](https://github.com/opendatalab/DocLayout-YOLO),
YOLOv10-based) object detector that locates the four structural regions of a
**modern Tibetan book** page — **header**, **text-area**, **footnote**,
**footer** — as a preprocessing step for OCR and etext production.

- **Training code, recipes & write-up:** [buda-base/tibetan-book-layout-analysis](https://github.com/buda-base/tibetan-book-layout-analysis)
- **Dataset:** [BDRC/TDLA-Training-Dataset-v2](https://huggingface.co/datasets/BDRC/TDLA-Training-Dataset-v2) (gated, fair-use)

> This is one of several architectures BDRC fine-tuned on the same labels and
> recipe to test how much the choice of architecture matters (see the
> [blog post](https://github.com/buda-base/tibetan-book-layout-analysis/blob/main/BLOGPOST.md)).
> The primary, production release is the RT-DETR-l fine-tune at
> [BDRC/Tibetan-Modern-Book-Layout-Detection-RTDETR](https://huggingface.co/BDRC/Tibetan-Modern-Book-Layout-Detection-RTDETR)
> (MIT-licensed). **This checkpoint is licensed AGPL-3.0**, not MIT, because
> DocLayout-YOLO's own codebase (and the Ultralytics YOLO it builds on) is
> AGPL-3.0 — see [License](#license) below before using it in a closed-source
> product.

## Model description

This is a DocLayout-YOLO detector fine-tuned with the **`tam2col`** labelling
scheme: text-area boxes merged into one envelope per page, except on genuine
two-column pages, where it keeps one box per column. Header and footer are
kept as separate classes (they can be combined losslessly downstream). Unlike
the off-the-shelf DocStructBench checkpoint (which uses a 10-class generic
document schema), this model was fine-tuned directly on BDRC's 4-class
schema, so its output classes need no remapping.

| Property | Value |
| --- | --- |
| Architecture | DocLayout-YOLO (YOLOv10-based, via [`doclayout_yolo`](https://github.com/opendatalab/DocLayout-YOLO)) |
| Task | Object detection |
| Base checkpoint | DocStructBench pretrained (OpenDataLab) |
| Image size | 1024 × 1024 |
| Number of classes | 4 |
| Framework | `doclayout_yolo` (`YOLOv10`) |
| Weights file | `doclayout_yolo_tibetan_book_layout.pt` |

## Classes

| ID | Class | Description |
| -- | --------- | --------------------- |
| 0 | header | running title / marginal text at top or side |
| 1 | text-area | main body text (one box per column) |
| 2 | footnote | notes below the text area |
| 3 | footer | folio numbers / marginal text at bottom or side |

## Recommended usage — per-class confidence thresholds

Like the primary RT-DETR-l release, this detector is recall-happy, so the best
operating point differs by class. These are each class's own max-F1 confidence
from a native per-class sweep on the test set:

| class | recommended conf |
| --- | --- |
| header (0) | **0.42** |
| text-area (1) | **0.66** |
| footnote (2) | **0.27** |
| footer (3) | **0.48** |

If you need a single global threshold, **0.30** is the best compromise (it is
also the operating point used for the cross-architecture comparison in the
blog post).

### Inference

```python
from doclayout_yolo import YOLOv10

model = YOLOv10("doclayout_yolo_tibetan_book_layout.pt")
CLASS_CONF = {0: 0.42, 1: 0.66, 2: 0.27, 3: 0.48}  # header, text-area, footnote, footer
names = {0: "header", 1: "text-area", 2: "footnote", 3: "footer"}

results = model.predict("page.jpg", imgsz=1024, conf=min(CLASS_CONF.values()))
for r in results:
    for b, cf, cl in zip(r.boxes.xyxy.tolist(), r.boxes.conf.tolist(), r.boxes.cls.tolist()):
        cls = int(cl)
        if cf < CLASS_CONF[cls]:
            continue
        print(names[cls], round(cf, 3), b)
```

A ready-made CLI (`infer.py`) with the thresholds baked in is included in this
repo.

### Downloading the weights

```python
from huggingface_hub import hf_hub_download
path = hf_hub_download("BDRC/Tibetan-Modern-Book-Layout-Detection-DocLayout-YOLO",
                       "doclayout_yolo_tibetan_book_layout.pt")
```

## Performance

Evaluated on the **held-out test split** (860 images) of
`BDRC/TDLA-Training-Dataset-v2`.

### Native 4-class metrics

| class | P | R | F1 | mAP@0.5 | mAP@0.5:0.95 |
| --- | --- | --- | --- | --- | --- |
| header | 0.959 | 0.948 | 0.954 | 0.965 | 0.716 |
| text-area | 0.983 | 0.981 | 0.982 | 0.995 | 0.976 |
| footnote | 0.930 | 0.889 | 0.909 | 0.929 | 0.725 |
| footer | 0.963 | 0.957 | 0.960 | 0.961 | 0.684 |
| **overall** | — | — | **0.951** | **0.963** | **0.775** |

The **mAP** columns are threshold-independent — they integrate over the full
precision/recall curve (every confidence), so they do not depend on any
operating threshold. The **P / R / F1** columns are reported at each class's
own **max-F1 confidence** (see the per-class thresholds above), *not* at a
fixed threshold.

### Canonical 3-class metrics

Header + footer are combined into one `header-footer` class (matched
individually), text-area is compared as one merged envelope, and footnote is
left as-is — a fair space in which every fine-tuned architecture in the blog
post was compared.

| class | best-F1 |
| --- | --- |
| header-footer | 0.948 |
| text-area | 0.996 |
| footnote | 0.897 |
| **mean F1** | **0.947** (@ conf 0.30) |

This lands slightly below BDRC's primary RT-DETR-l fine-tune (mean F1 0.960),
mainly on the footnote class.

### Contamination (the metric that actually matters for OCR)

Of the ground-truth headers/footers and footnotes this model *misses*, the
share that get folded into its predicted text-area box (silently corrupting
downstream OCR) rather than dropped cleanly:

| region | detected | folded into text-area |
| --- | --- | --- |
| header/footer | 96% | 0.1% |
| footnote | 87% | 0% |

For comparison, off-the-shelf systems in the same evaluation ranged from 1.2%
to 56% on header/footer contamination alone — see the
[blog post](https://github.com/buda-base/tibetan-book-layout-analysis/blob/main/BLOGPOST.md)
for the full picture.

## Training details

| Parameter | Value |
| --- | --- |
| Base checkpoint | DocStructBench pretrained (OpenDataLab) |
| Image size | 1024 |
| Epochs | 100 planned, early-stopped at epoch 61 (best @ epoch 41) |
| GPU | single NVIDIA A10G (24 GB) |

- **Dataset:** [BDRC/TDLA-Training-Dataset-v2](https://huggingface.co/datasets/BDRC/TDLA-Training-Dataset-v2) — 8,325 images (6,751 train / 714 val / 860 test), volume-level leakage-free splits, augmented images confined to train.
- **Label variant (`tam2col`):** text-area boxes merged per page except on two-column pages; built with `data/build_curricula.py` in the GitHub repo.

## Intended use

Automatic layout detection of **modern Tibetan book** pages, as a
preprocessing step for OCR pipelines, document digitization, structured text
extraction, and digital-library indexing.

## Limitations

- Trained on **modern Tibetan books**; performance on traditional pecha,
  manuscripts, or woodblock prints is not characterized and may be poor.
- Optimized for 1024 px input; very high-resolution scans may benefit from a
  higher `imgsz`.
- The footnote class is rare in the source material (≈1.4% of boxes); this is
  this checkpoint's weakest class (F1 0.909, mAP@0.5:0.95 0.725), somewhat
  below BDRC's primary RT-DETR-l fine-tune.
- Header/footer boxes are small and easy to over-predict — use the
  recommended per-class thresholds above.

## License

**The model weights are released under the GNU Affero General Public License
v3.0 (AGPL-3.0)**, not the permissive MIT license used for BDRC's primary
RT-DETR-l release. This is because DocLayout-YOLO's training code (and the
Ultralytics YOLO codebase it is built on) is itself AGPL-3.0-licensed, and
these weights are a derivative work produced by fine-tuning it. If you use
this checkpoint (or a model derived from it) as part of a network service, the
AGPL-3.0 requires you to make the complete corresponding source available to
users of that service. If that doesn't work for your use case, use BDRC's
MIT-licensed RT-DETR-l release or the Apache-2.0-licensed RF-DETR-L release
instead — both score comparably on this benchmark. This is not legal advice;
consult your own counsel for how AGPL-3.0 applies to your use case.

The **page images used for training are not covered by any content license**
— they are BDRC library scans distributed on a fair-use basis. You are solely
responsible for your own copyright / rights analysis before use; BDRC accepts
no liability for misuse. See the
[dataset card](https://huggingface.co/datasets/BDRC/TDLA-Training-Dataset-v2)
for the full notice.

## Acknowledgements

Developed by the [Buddhist Digital Resource Center (BDRC)](https://www.bdrc.io)
for the BDRC Etext Corpus, with annotations produced and consolidated on the
Ultralytics platform.

## Citation

```bibtex
@software{bdrc_tibetan_book_layout_doclayoutyolo_2026,
  title   = {Tibetan Modern Book Layout Detection (DocLayout-YOLO)},
  author  = {Buddhist Digital Resource Center (BDRC)},
  year    = {2026},
  url     = {https://huggingface.co/BDRC/Tibetan-Modern-Book-Layout-Detection-DocLayout-YOLO}
}
```