README.md

---
license: mit
library_name: ultralytics
pipeline_tag: object-detection
language:
- bo
tags:
- tibetan
- document-layout-analysis
- rt-detr
- rtdetr
- object-detection
- bounding-box
- BDRC
datasets:
- BDRC/TDLA-Training-Dataset-v2
metrics:
- name: canonical mean AP50 (test)
  type: mAP
  value: 0.981
model-index:
- name: Tibetan-Modern-Book-Layout-Detection
  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.976
    - type: mAP
      name: mAP@0.5:0.95 (native, test)
      value: 0.788
---

# Tibetan Modern Book Layout Detection (RT-DETR-l)

An **RT-DETR-l** 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 model supersedes the earlier YOLO26m
> [`BDRC/Tibetan_Modern_Book_Layout_Detection_Model`](https://huggingface.co/BDRC/Tibetan_Modern_Book_Layout_Detection_Model),
> which is retired. It is trained on a larger, re-reviewed, leakage-free dataset
> and evaluated on a held-out **test** split (not validation).

## Model description

This is the `tam2col` variant selected from a broader model bake-off (see the
[blog post](https://github.com/buda-base/tibetan-book-layout-analysis/blob/main/BLOGPOST.md)).
It is a 4-class RT-DETR-l that was trained with the **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).

| Property | Value |
| --- | --- |
| Architecture | RT-DETR-l (via Ultralytics) |
| Task | Object detection |
| Image size | 1024 × 1024 |
| Number of classes | 4 |
| Framework | `ultralytics` (`RTDETR`) |
| Weights file | `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

The detector is deliberately recall-happy, so **the best operating point differs
by class**. Using the Ultralytics default `conf=0.25` everywhere leaves
header/footer precision at only ≈0.83 and text-area at ≈0.955. Two cheap fixes,
both measured with a native per-class confidence sweep on the test set:

- Raise **header/footer to ≈0.60** → precision ≈0.83 → ≈0.95 (≈0.02 recall cost).
- Raise **text-area to ≈0.55** → precision ≈0.955 → ≈0.98 (≈0.002 recall cost).
- Leave **footnote at ≈0.25**, where recall is ≈1.0 (its few false positives are
  high-confidence and can't be thresholded away without losing real footnotes).

| class | recommended conf | P → P | R |
| --- | --- | --- | --- |
| header (0) | **0.60** | 0.83 → 0.96 | 0.95 |
| text-area (1) | **0.55** | 0.955 → 0.98 | 0.995 |
| footnote (2) | 0.25 | 0.918 | 1.00 |
| footer (3) | **0.60** | — → 0.94 | 0.95 |

If you need a single global threshold, **0.50** is the best compromise.

### Inference

```python
from ultralytics import RTDETR

model = RTDETR("tibetan_book_layout.pt")

# predict once at the lowest floor, then filter per class
CLASS_CONF = {0: 0.60, 1: 0.55, 2: 0.25, 3: 0.60}   # header, text-area, footnote, footer
results = model.predict("page.jpg", imgsz=1024, conf=min(CLASS_CONF.values()))

for r in results:
    for cls, conf, xywhn in zip(r.boxes.cls.tolist(),
                                r.boxes.conf.tolist(),
                                r.boxes.xywhn.tolist()):
        cls = int(cls)
        if conf < CLASS_CONF[cls]:
            continue
        print(model.names[cls], round(conf, 3), [round(v, 4) for v in xywhn])
```

A ready-made CLI (`infer.py`) with the thresholds baked in is in the
[GitHub repo](https://github.com/buda-base/tibetan-book-layout-analysis/blob/main/inference/infer.py).

### Downloading the weights

```python
from huggingface_hub import hf_hub_download
path = hf_hub_download("BDRC/Tibetan-Modern-Book-Layout-Detection",
                       "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.964 | 0.951 | 0.957 | 0.978 | 0.710 |
| text-area | 0.978 | 0.995 | 0.987 | 0.994 | 0.980 |
| footnote | 0.933 | 0.931 | 0.932 | 0.986 | 0.822 |
| footer | 0.913 | 0.952 | 0.932 | 0.947 | 0.642 |
| **overall** | **0.947** | **0.957** | **0.952** | **0.976** | **0.788** |

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
**maximum-F1 confidence** (the standard Ultralytics `val` operating point), *not*
at a fixed threshold. The per-class serving thresholds recommended above
(header/footer ≈ 0.60, text-area ≈ 0.55, footnote ≈ 0.25) are the practical
settings for `infer.py`; they land close to these max-F1 points.

### 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 layout variant was compared.

| class | AP@0.5 | AP@0.5:0.95 | best-F1 (@conf) |
| --- | --- | --- | --- |
| header-footer | 0.965 | 0.683 | 0.950 (@0.65) |
| text-area | 0.988 | 0.910 | 0.952 (@0.89) |
| footnote | 0.991 | 0.824 | 0.957 (@0.23) |
| **mean** | **0.981** | 0.806 | |

Against the other curricula in this canonical space, `tam2col` has the best mean
AP@0.5 and the best text-area / footnote localization, and it is the only variant
that handles two-column pages correctly (returning one box per column).

## Training details

| Parameter | Value |
| --- | --- |
| Base checkpoint | `rtdetr-l.pt` (Ultralytics) |
| Image size | 1024 |
| Epochs | 100 (early-stopped at 60, best at epoch 40) |
| Patience | 20 |
| Batch size | 8 |
| 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.
- The full recipe is [`training/recipes/run_v5_tam2col.sh`](https://github.com/buda-base/tibetan-book-layout-analysis/blob/main/training/recipes/run_v5_tam2col.sh).

## 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); recall is
  strong on the test set but the class remains the least-represented.
- Header/footer boxes are small and easy to over-predict — use the recommended
  ≈0.60 threshold for those two classes.

## License

The model weights are released under the **MIT License**, matching the training
code. 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_2026,
  title   = {Tibetan Modern Book Layout Detection (RT-DETR-l)},
  author  = {Buddhist Digital Resource Center (BDRC)},
  year    = {2026},
  url     = {https://huggingface.co/BDRC/Tibetan-Modern-Book-Layout-Detection}
}
```