README.md

---
language:
- en
license: apache-2.0
base_model: facebook/detr-resnet-50
tags:
- object-detection
- detr
- vision
- doc-layout
- generated_from_trainer
library_name: transformers
datasets:
- biglam/loc_beyond_words
metrics:
- name: mean_average_precision (COCO 0.50:0.95)
  type: mean_average_precision
  value: 0.1658
---
# Control-R1: Doc-layout object detection (fine-tuned DETR)

This model is a fine-tuned **DETR (ResNet-50)** object-detection model for **document /
newspaper page-layout analysis**. It detects 7 region types in scanned historical
newspaper pages and was trained on the `biglam/loc_beyond_words` dataset.

## Base model & license

- **Base model**: [`facebook/detr-resnet-50`](https://huggingface.co/facebook/detr-resnet-50)
- **License**: Apache-2.0 (open license — free to share, modify and use commercially)
- The fine-tuned weights in this repository inherit the **Apache-2.0** license.

## Classes (7)

Photograph, Illustration, Map, Comics/Cartoon, Editorial Cartoon, Headline, Advertisement

## Training data

- **Dataset**: [biglam/loc_beyond_words](https://huggingface.co/datasets/biglam/loc_beyond_words)
- **Train**: 2846 images
- **Validation**: 712 images
- COCO-style annotations (xywh bounding boxes).

## Training details

- **Model**: `facebook/detr-resnet-50`, all parameters fine-tuned (backbone unfrozen)
- **Epochs**: 4
- **Batch size**: 4 (gradient accumulation = 2)
- **Optimizer**: AdamW (lr = 0.0001, weight decay on non-bias/LN params)
- **LR schedule**: linear warmup + cosine decay
- **Image preprocessing**: resize to shortest edge = 800px, longest = 1333px (aspect preserved), ImageNet normalization
- **Mixed precision**: bf16/fp16 autocast (GPU)
- **Hardware**: Hugging Face Jobs GPU

## Validation results (COCO eval on the 712-image validation split)

| Metric | Value |
|---|---|
| **mAP (IoU 0.50:0.95)** | 0.1658 |
| AP @ IoU 0.50 | 0.2761 |
| AP @ IoU 0.75 | 0.1802 |
| AR (max 100 dets) | 0.2908 |

Per-class AP (IoU 0.50:0.95):
- **Photograph**: 0.3484
- **Illustration**: 0.0000
- **Map**: 0.0000
- **Comics/Cartoon**: 0.0385
- **Editorial Cartoon**: 0.0000
- **Headline**: 0.4418
- **Advertisement**: 0.3321

## Quick usage

```python
from transformers import AutoModelForObjectDetection, AutoImageProcessor
from PIL import Image

model = AutoModelForObjectDetection.from_pretrained("harness-race/control-r1")
processor = AutoImageProcessor.from_pretrained("harness-race/control-r1")

image = Image.open("page.png").convert("RGB")
inputs = processor(images=image, return_tensors="pt")
outputs = model(**inputs)
results = processor.post_process_object_detection(outputs, target_sizes=[(image.height, image.width)], threshold=0.4)
for r in results[0]:
    print(model.config.id2label[int(r['labels'])], round(r['scores'].item(),3) if hasattr(r['scores'],'item') else r['scores'], [round(c,1) for c in r['boxes'].tolist()])
```

## Intended use & limitations

Trained for research on historical newspaper layout analysis. Best on page layouts similar
to the `loc_beyond_words` training distribution; large format/styled pages not seen in
training may be missed. Evaluation was done on the dataset's official 712-image validation
split; run at 2026-08-07 (UTC) on HF Jobs.

---
*Control-R1 — a layout-model entry. Trained on Hugging Face Jobs (< \$5 budget).*