Update README.md

README.md

@@ -1,94 +1,231 @@
 ---
+language:
+- vi
 license: apache-2.0
+library_name: rfdetr
+pipeline_tag: object-detection
 tags:
+- rf-detr
 - object-detection
-- vision
-datasets:
-- coco
-pipeline_tag: object-detection
-library_name: transformers
+- document-layout
+- textbook
+- fine-tuned
+
 ---
 
-# RF-DETR (Large)
+<div align="center">
 
-RF-DETR is a real-time detection transformer family introduced in [RF-DETR: Neural Architecture Search for Real-Time Detection Transformers](https://huggingface.co/papers/2511.09554) by Robinson et al. and integrated in 🤗 Transformers via [PR #36895](https://github.com/huggingface/transformers/pull/36895).
+# 🔍 VT-DETR — Textbook Layout Detection
 
-## Model description
+**RF-DETR Large fine-tuned for Vietnamese textbook document layout analysis**
 
-RF-DETR is an end-to-end object detection model that combines ideas from LW-DETR and Deformable DETR: a DINOv2-with-registers style ViT backbone (with an RF-DETR windowing pattern for efficient attention), a multi-scale projector between encoder and decoder, and a multi-scale deformable DETR decoder for fast convergence and strong accuracy–latency tradeoffs.
+[![license](https://img.shields.io/badge/license-Apache%202.0-green.svg)](https://github.com/roboflow/rf-detr/blob/develop/LICENSE)
+[![mAP50:95](https://img.shields.io/badge/mAP@50%3A95-83.0%25-blue)](.)
+[![mAP50](https://img.shields.io/badge/mAP@50-92.2%25-blue)](.)
+[![F1](https://img.shields.io/badge/F1-88.8%25-blue)](.)
+[![Python](https://img.shields.io/badge/python-3.8%2B-blue)](.)
 
-Key Architectural Details:
-- **Backbone:** DINOv2-with-registers style ViT with RF-DETR **windowed / full** attention alternation (instead of a purely convolutional encoder).
-- **Multi-scale fusion:** **RF-DETR multi-scale projector** (C2f-style blocks in the LW-DETR lineage) to aggregate multi-level backbone features before the decoder.
-- **Decoder:** **Deformable DETR**-style decoder with multi-scale deformable cross-attention; depth and input resolution vary by checkpoint (NAS frontier).
-- **Queries:** DETR-style object queries with bipartite matching and auxiliary decoder losses for training stability.
+</div>
+
+---
 
-Training Details:
-- **Detection losses:** classification plus bounding-box L1 and GIoU, with auxiliary losses on intermediate decoder layers.
-- **Group DETR:** parallel decoder copies during training for faster convergence (same high-level idea as LW-DETR's Group DETR).
-- **NAS (family-level):** the RF-DETR paper uses weight-sharing neural architecture search over practical accuracy–latency knobs after adapting a shared backbone on the target dataset, so many checkpoints correspond to different subnets without full independent retrains for every point on the frontier.
+## Overview
+
+**VT-DETR** stands for **Vietnamese Textbook Detection Transformer** — a fine-tuned variant of **RF-DETR Large** targeting automated detection of structural elements in Vietnamese textbook pages. It identifies four layout classes with high accuracy, enabling downstream document parsing, indexing, and educational content extraction pipelines.
+
+| Property | Value |
+|---|---|
+| Base model | RF-DETR Large (pretrained) |
+| Task | Object Detection |
+| Domain | Document Layout / Textbook Pages |
+| Language | Vietnamese |
+| Input resolution | 640 × 640 |
+
+---
+
+## Classes
+
+| ID | Label | Description |
+|:---:|---|---|
+| 0 | `Object-detection` | Generic detectable region |
+| 1 | `Figure` | Diagrams, illustrations, charts |
+| 2 | `Icon` | Small symbolic graphics |
+| 3 | `Table` | Tabular data structures |
+
+---
+
+## Demo
+
+| Input | Inference Output |
+|:---:|:---:|
+| ![Input sample](./page077.png) | ![Inference result](./inference.webp) |
+
+---
 
-### How to use
+## Benchmark
 
-You can use the raw model for object detection. See the [model hub](https://huggingface.co/models?search=stevenbucaille/rf-detr) to look for all available RF-DETR models.
+### ✅ Best validation metrics
 
-Here is how to use this model:
+| Metric | Value |
+|---|---:|
+| mAP @ \[0.50 : 0.95\] | **0.8304** |
+| mAP @ 0.50 | **0.9216** |
+| mAP @ 0.75 | **0.8992** |
+| Precision | **0.9471** |
+| Recall | **0.8997** |
+| F1 | **0.8875** |
+
+### 📉 Last epoch metrics
+
+| Metric | Value |
+|---|---:|
+| mAP @ \[0.50 : 0.95\] | 0.8161 |
+| mAP @ 0.50 | 0.9074 |
+| mAP @ 0.75 | 0.8811 |
+| Precision | 0.9184 |
+| Recall | 0.8272 |
+| F1 | 0.8694 |
+
+> Metrics sourced from `outputs/rfdetr_textbook/metrics.csv` (full training run). A separate single-image eval run in `outputs/exp_rfdetr_textbook/eval/metrics.json` (`num_images=1`) is not representative and excluded from this report.
+
+---
+
+## Training Configuration
+
+```yaml
+model:
+  size: large
+
+training:
+  epochs: 20
+  batch_size: 4
+  grad_accum_steps: 8
+  resolution: 640
+  device: cuda
+
+augmentation:
+  mosaic: true
+  mixup: 0.1
+
+early_stopping:
+  enabled: true
+  monitor: mAP50:95
+  patience_logs: 4
+  min_delta: 0.005
+```
+
+### Dataset split (COCO format)
+
+```
+data_resplit/
+├── train/
+│   └── _annotations.coco.json
+├── valid/
+│   └── _annotations.coco.json
+└── test/
+    └── _annotations.coco.json
+```
+
+---
+
+## Usage
+
+### Install
+
+```bash
+pip install "rfdetr[train,loggers]"
+```
+
+### Inference
 
 ```python
-from transformers import AutoImageProcessor, RfDetrForObjectDetection
-import torch
+from rfdetr import RFDETRLarge
 from PIL import Image
-import requests
 
-url = "http://images.cocodataset.org/val2017/000000039769.jpg"
-image = Image.open(requests.get(url, stream=True).raw)
+model = RFDETRLarge(pretrain_weights="checkpoint_best_total.pth")
+image = Image.open("page077.png")
+detections = model.predict(image, threshold=0.5)
+print(detections)
+```
 
-processor = AutoImageProcessor.from_pretrained("stevenbucaille/rf-detr-large")
-model = RfDetrForObjectDetection.from_pretrained("stevenbucaille/rf-detr-large")
+### Train
 
-inputs = processor(images=image, return_tensors="pt")
-outputs = model(**inputs)
+```bash
+python -m rfdetr_finetune.train
+```
 
-# convert outputs (bounding boxes and class logits) to COCO API
-# let's only keep detections with score > 0.35
-target_sizes = torch.tensor([image.size[::-1]])
-results = processor.post_process_object_detection(outputs, target_sizes=target_sizes, threshold=0.35)[0]
+### Evaluate
 
-for score, label, box in list(zip(results["scores"], results["labels"], results["boxes"]))[:8]:
-    box = [round(i, 2) for i in box.tolist()]
-    print(
-            f"Detected {model.config.id2label[label.item()]} with confidence "
-            f"{round(score.item(), 3)} at location {box}"
-    )
+```bash
+python -m rfdetr_finetune.evaluate
 ```
-This should output:
+
+---
+
+## Repository Structure
+
 ```
-Detected remote with confidence 0.99 at location [40.68, 73.34, 175.62, 118.01]
-Detected cat with confidence 0.986 at location [348.33, 24.59, 640.12, 373.98]
-Detected cat with confidence 0.986 at location [13.36, 54.71, 316.59, 473.24]
-Detected remote with confidence 0.947 at location [334.29, 76.64, 370.47, 187.34]
-Detected couch with confidence 0.549 at location [1.67, 0.92, 639.56, 474.81]
-Detected remote with confidence 0.135 at location [338.6, 76.26, 369.93, 130.59]
-Detected remote with confidence 0.268 at location [258.99, 54.31, 291.03, 78.72]
-Detected remote with confidence 0.119 at location [335.04, 150.52, 352.63, 186.95]
+huggingface/
+├── README.md                    # Model card
+├── checkpoint_best_total.pth    # Best checkpoint (by mAP50:95)
+├── inference.webp               # Demo output
+└── page077.png                  # Demo input
 ```
 
-## Training data
+---
+
+## Limitations
+
+- Trained and evaluated on Vietnamese textbook domain; generalization to other document types is not guaranteed.
+- Test set benchmark not yet finalized — reported metrics are from the validation split.
+- Robustness may be improved with additional data augmentation, larger datasets, or LR schedule tuning.
+
+---
+
+## License
+
+This model is released under the **Apache License 2.0**, inherited from the base RF-DETR Large model by Roboflow.
+
+> Copyright 2025 Roboflow, Inc.  
+> Licensed under the Apache License, Version 2.0. See [LICENSE](https://github.com/roboflow/rf-detr/blob/develop/LICENSE) for details.
+
+Fine-tuned weights and additional code in this repository are also distributed under Apache 2.0.
+
+---
+
+## Citation
 
-These checkpoints are trained on the standard [COCO 2017 object detection dataset](https://cocodataset.org/#home) label space (80 categories) as reflected in `config.id2label`.
+If you use this model or the RF-DETR framework, please cite:
 
-### BibTeX entry and citation info
+**Base model (RF-DETR Large):**
 
 ```bibtex
-@misc{robinson2026rfdetrneuralarchitecturesearch,
-      title={RF-DETR: Neural Architecture Search for Real-Time Detection Transformers},
-      author={Isaac Robinson and Peter Robicheaux and Matvei Popov and Deva Ramanan and Neehar Peri},
-      year={2026},
-      eprint={2511.09554},
-      archivePrefix={arXiv},
-      primaryClass={cs.CV},
-      url={https://huggingface.co/papers/2511.09554},
+@misc{rf-detr,
+  title        = {RF-DETR: Neural Architecture Search for Real-Time Detection Transformers},
+  author       = {Isaac Robinson and Peter Robicheaux and Matvei Popov and Deva Ramanan and Neehar Peri},
+  year         = {2025},
+  eprint       = {2511.09554},
+  archivePrefix= {arXiv},
+  primaryClass = {cs.CV},
+  url          = {https://arxiv.org/abs/2511.09554}
 }
 ```
 
-This model was originally contributed by stevenbucaille in 🤗 transformers.
+> Base weights: [Roboflow/rf-detr-large](https://huggingface.co/Roboflow/rf-detr-large) — Apache 2.0
+
+**This fine-tuned model (VT-DETR):**
+
+```bibtex
+@misc{vtdetr2025,
+  title        = {VT-DETR: RF-DETR Large Fine-tuned for Textbook Layout Detection},
+  author       = {hieptran318204},
+  year         = {2025},
+  howpublished = {\url{https://huggingface.co/hieptran318204/vt-detr}}
+}
+```
+
+---
+
+<div align="center">
+<sub>Fine-tuned with ❤️ for Vietnamese educational document processing</sub>
+</div>