Upload folder using huggingface_hub

README.md

@@ -1,59 +1,208 @@
 ---
+language:
+- vi
 license: apache-2.0
+library_name: d-fine
+pipeline_tag: object-detection
 tags:
-- object-detection
-- computer-vision
 - d-fine
-- document-layout-analysis
-metrics:
-- map
+- object-detection
+- document-layout
+- fine-tuned
+- hgnetv2
+
 ---
 
-# D-FINE Layout Detection Model (HGNetv2-X)
+<div align="center">
 
-## Model Details
-Đây là mô hình nhận diện các phần tử trong tài liệu (Document Layout Analysis) được huấn luyện dựa trên kiến trúc **D-FINE** tiên tiến (phiên bản cấu hình X cỡ lớn sử dụng backbone **HGNetv2-B5**).
+# 🔍 D-FINE X — Object Detection for Document Layout
 
-- **Task:** Object Detection (Phát hiện vật thể)
-- **Architecture:** D-FINE (HGNetv2-X)
-- **Epochs Trained:** 80 Epochs (Gồm 72 epochs Stage 1 và 8 epochs Stage 2 tinh chỉnh)
+**D-FINE HGNetv2-X fine-tuned for document layout analysis**
 
-## Dataset
-Mô hình được huấn luyện trên tập dữ liệu tùy chỉnh bao gồm các lớp đối tượng (classes) thường gặp trong bố cục tài liệu:
-0. `Object-detection` (Lớp bao trùm)
-1. `Figure` (Hình ảnh/Hình vẽ)
-2. `Icon` (Biểu tượng)
-3. `Table` (Bảng biểu)
+[![license](https://img.shields.io/badge/license-Apache%202.0-green.svg)](https://github.com/Peterande/D-FINE/blob/master/LICENSE)
+[![mAP50:95](https://img.shields.io/badge/mAP@50%3A95-83.75%25-blue)]()
+[![mAP50](https://img.shields.io/badge/mAP@50-91.82%25-blue)]()
+[![Python](https://img.shields.io/badge/python-3.8%2B-blue)]()
 
-## Evaluation Results
-Kết quả đạt được trên tập Validation sau khi kết thúc Stage 2 (tinh chỉnh tọa độ mịn):
-- **mAP @ [0.50:0.95]:** 83.75%
-- **mAP @ 0.50:** 91.82%
-- **mAP @ 0.75:** 89.66%
-- **AP (Medium Objects):** 87.03%
-- **AP (Large Objects):** 83.84%
-- **Recall (AR @ 100):** 93.48%
+</div>
+
+---
 
-## How to Use
-Để sử dụng mô hình này, bạn cần tải xuống mã nguồn của [D-FINE](https://github.com/Peterande/D-FINE).
+## Overview
+
+Mô hình **D-FINE HGNetv2-X** được fine-tune cho bài toán nhận diện bố cục tài liệu (Document Layout Analysis). Mô hình sử dụng kiến trúc D-FINE tiên tiến với cơ chế Fine-grained Distribution Refinement (FDR) để tinh chỉnh bounding box, kết hợp backbone HGNetv2-B5 mạnh mẽ.
+
+| Property | Value |
+|---|---|
+| Base model | D-FINE (HGNetv2-X) |
+| Task | Object Detection |
+| Domain | Document Layout |
+| Input resolution | 640 × 640 |
+| Training | 80 epochs (72 Stage 1 + 8 Stage 2) |
+
+---
+
+## 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 |
+
+---
+
+## Benchmark
+
+### ✅ Best validation metrics (Stage 2)
+
+| Metric | Value |
+|---|---:|
+| mAP @ \[0.50 : 0.95\] | **0.8375** |
+| mAP @ 0.50 | **0.9182** |
+| mAP @ 0.75 | **0.8966** |
+| AP (Medium) | **0.8703** |
+| AP (Large) | **0.8384** |
+| AR @ 100 | **0.9348** |
+
+---
+
+## Usage
+
+### Option 1 — HuggingFace Transformers (recommended)
 
-**Bước 1: Clone D-FINE repository**
 ```bash
+pip install transformers torch torchvision
+# Clone D-FINE source code (bắt buộc)
 git clone https://github.com/Peterande/D-FINE.git
 cd D-FINE
 pip install -r requirements.txt
 ```
 
-**Bước 2: Tải file cấu hình & trọng số**
-Tải file `model.pth`, `dfine_hgnetv2_x_custom.yml`, và `custom_detection.yml` từ kho lưu trữ (repository) này và đặt vào các thư mục tương ứng trong dự án của bạn.
+```python
+from transformers import AutoModel, AutoImageProcessor
+from PIL import Image
+
+processor = AutoImageProcessor.from_pretrained(
+    "ducnhan0804/dfine-x-obj-detection",
+    trust_remote_code=True
+)
+model = AutoModel.from_pretrained(
+    "ducnhan0804/dfine-x-obj-detection",
+    trust_remote_code=True
+)
+
+image = Image.open("path/to/your/document.png")
+inputs = processor.preprocess(image)
+outputs = model(inputs["images"], threshold=0.4)
+results = processor.post_process_object_detection(outputs, threshold=0.4)
+
+# results[0]["boxes"]  → xyxy coordinates (tensor)
+# results[0]["scores"] → confidence scores (tensor)
+# results[0]["labels"] → class ids (tensor)
+print(results)
+```
+
+> **Note:** `trust_remote_code=True` is required because this model uses custom `modeling_dfine.py`. The checkpoint (~1GB) is downloaded automatically to `~/.cache/huggingface/` on first run.
+
+> **Important:** You must run this code from the D-FINE root directory so that the source code (`src/`) can be imported.
+
+### Option 2 — D-FINE directly
 
-**Bước 3: Chạy Suy luận (Inference)**
-Sử dụng script có sẵn của D-FINE để chạy nhận diện trên một tài liệu, hình ảnh hoặc video:
 ```bash
-python tools/inference/torch_inf.py \
-    -c configs/dfine/custom/dfine_hgnetv2_x_custom.yml \
-    -r model.pth \
-    -i path/to/your/document_image.jpg \
-    -d cuda:0
+git clone https://github.com/Peterande/D-FINE.git
+cd D-FINE
+pip install -r requirements.txt
+```
+
+```python
+# Download checkpoint from HuggingFace
+from huggingface_hub import hf_hub_download
+
+weights = hf_hub_download(
+    repo_id="ducnhan0804/dfine-x-obj-detection",
+    filename="best_stg2.pth"
+)
+
+# Run inference using D-FINE's built-in script
+# python tools/inference/torch_inf.py -c configs/dfine/custom/dfine_hgnetv2_x_custom.yml -r <weights_path> -i <image_path> -d cuda:0
+```
+
+---
+
+## Training Configuration
+
+```yaml
+model:
+  architecture: D-FINE (HGNetv2-X)
+  backbone: HGNetv2-B5
+
+training:
+  total_epochs: 80
+  stage1_epochs: 72 (heavy augmentation)
+  stage2_epochs: 8 (fine-tuning, no heavy augmentation)
+  resolution: 640
+  device: cuda
+
+optimizer:
+  type: AdamW
+  lr: 0.00025
+  backbone_lr: 0.0000025
+```
+
+### Dataset split (COCO format)
+
+```
+datasets/
+├── train/
+│   ├── _annotations.coco.json
+│   └── *.jpg
+└── valid/
+    ├── _annotations.coco.json
+    └── *.jpg
+```
+
+---
+
+## Repository Structure
+
+```
+ducnhan0804/dfine-x-obj-detection
+├── README.md                        # Model card
+├── config.json                      # HuggingFace model config
+├── preprocessor_config.json         # Image processor config
+├── modeling_dfine.py                # Custom modeling code (trust_remote_code)
+├── best_stg2.pth                    # Best checkpoint (Stage 2)
+├── dfine_hgnetv2_x_custom.yml      # D-FINE training config
+└── custom_detection.yml             # Dataset config
+```
+
+---
+
+## Limitations
+
+- Trained on a specific document layout dataset; generalization to other document types is not guaranteed.
+- Requires D-FINE source code to be cloned and available locally for inference.
+- The checkpoint file is ~1GB in size.
+
+---
+
+## License
+
+This model is released under the **Apache License 2.0**, inherited from the D-FINE base model.
+
+---
+
+## Citation
+
+**Base model (D-FINE):**
+
+```bibtex
+@article{peng2024d,
+  title={D-FINE: Redefine Regression Task in DETRs as Fine-grained Distribution Refinement},
+  author={Peng, Yansong and Songtao, Liu and others},
+  journal={arXiv preprint arXiv:2407.06537},
+  year={2024}
+}
 ```
-Kết quả nhận diện sẽ được lưu thành tệp `torch_results.jpg`.

best_stg2.pth

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:133b1d98baabec1490f8b181eacb2d79673bced3ee988f8cf27fb2269b743736
+size 1003102397

config.json

@@ -0,0 +1,25 @@
+{
+  "model_type": "dfine",
+  "architectures": ["DFINEModel"],
+  "auto_map": {
+    "AutoConfig": "modeling_dfine.DFINEConfig",
+    "AutoModel": "modeling_dfine.DFINEModel"
+  },
+  "num_classes": 4,
+  "id2label": {
+    "0": "Object-detection",
+    "1": "Figure",
+    "2": "Icon",
+    "3": "Table"
+  },
+  "label2id": {
+    "Object-detection": 0,
+    "Figure": 1,
+    "Icon": 2,
+    "Table": 3
+  },
+  "resolution": 640,
+  "checkpoint": "best_stg2.pth",
+  "config_file": "dfine_hgnetv2_x_custom.yml",
+  "backbone": "HGNetv2-B5"
+}

modeling_dfine.py

@@ -0,0 +1,229 @@
+"""
+D-FINE HuggingFace Wrapper
+Cho phép load model D-FINE thông qua transformers AutoModel.
+Yêu cầu: Người dùng phải clone repo D-FINE và chạy code từ thư mục gốc của nó.
+"""
+
+import os
+import sys
+import torch
+import torch.nn as nn
+import torchvision.transforms as T
+from PIL import Image
+from transformers import PretrainedConfig, PreTrainedModel, BaseImageProcessor
+
+
+class DFINEConfig(PretrainedConfig):
+    """Config class cho D-FINE model trên HuggingFace."""
+    model_type = "dfine"
+
+    def __init__(
+        self,
+        num_classes=4,
+        resolution=640,
+        checkpoint="best_stg2.pth",
+        config_file="dfine_hgnetv2_x_custom.yml",
+        **kwargs,
+    ):
+        self.num_classes = num_classes
+        self.resolution = resolution
+        self.checkpoint = checkpoint
+        self.config_file = config_file
+        super().__init__(**kwargs)
+
+
+class DFINEImageProcessor(BaseImageProcessor):
+    """Image processor: resize ảnh về kích thước chuẩn 640x640 và chuyển thành tensor."""
+
+    def __init__(self, size=None, **kwargs):
+        super().__init__(**kwargs)
+        self.size = size or {"height": 640, "width": 640}
+
+    def preprocess(self, images, **kwargs):
+        if not isinstance(images, list):
+            images = [images]
+        processed = []
+        for img in images:
+            if not isinstance(img, Image.Image):
+                img = Image.fromarray(img)
+            img = img.convert("RGB")
+            processed.append(img)
+        return {"images": processed}
+
+    def post_process_object_detection(self, outputs, threshold=0.5, target_sizes=None):
+        """Lọc kết quả dự đoán theo ngưỡng confidence."""
+        results = []
+        for i, (boxes, scores, labels) in enumerate(
+            zip(outputs["boxes"], outputs["scores"], outputs["labels"])
+        ):
+            keep = scores > threshold
+            result = {
+                "boxes": boxes[keep],
+                "scores": scores[keep],
+                "labels": labels[keep],
+            }
+            results.append(result)
+        return results
+
+
+class DFINEModel(PreTrainedModel):
+    """
+    HuggingFace wrapper cho D-FINE object detection model.
+
+    Cách hoạt động:
+    1. Tự động tải file checkpoint (.pth) từ HuggingFace Hub.
+    2. Sử dụng source code D-FINE có sẵn trên máy để khởi tạo kiến trúc mạng.
+    3. Load trọng số vào mạng và chạy inference.
+
+    Yêu cầu: Người dùng phải clone repo D-FINE và chạy từ thư mục gốc.
+    """
+
+    config_class = DFINEConfig
+
+    def __init__(self, config):
+        super().__init__(config)
+        self._model = None
+        self._weights_path = None
+        self._config_path = None
+
+    @classmethod
+    def from_pretrained(cls, pretrained_model_name_or_path, *args, **kwargs):
+        kwargs.pop("ignore_mismatched_sizes", None)
+        config = kwargs.pop("config", None)
+        if config is None:
+            config = DFINEConfig.from_pretrained(
+                pretrained_model_name_or_path,
+                **{
+                    k: v
+                    for k, v in kwargs.items()
+                    if k in ("trust_remote_code", "cache_dir", "revision", "token")
+                },
+            )
+        model = cls(config)
+
+        # Tải file checkpoint và config YAML từ HuggingFace Hub
+        weights_file = config.checkpoint
+        config_file = config.config_file
+
+        local_weights = os.path.join(pretrained_model_name_or_path, weights_file)
+        local_config = os.path.join(pretrained_model_name_or_path, config_file)
+
+        if os.path.exists(local_weights):
+            model._weights_path = local_weights
+        else:
+            from huggingface_hub import hf_hub_download
+
+            model._weights_path = hf_hub_download(
+                repo_id=pretrained_model_name_or_path, filename=weights_file
+            )
+
+        if os.path.exists(local_config):
+            model._config_path = local_config
+        else:
+            from huggingface_hub import hf_hub_download
+
+            model._config_path = hf_hub_download(
+                repo_id=pretrained_model_name_or_path, filename=config_file
+            )
+
+        return model
+
+    def _load_dfine(self, device=None):
+        """Lazy load: Chỉ khởi tạo model khi thực sự cần chạy inference."""
+        if self._model is not None:
+            return
+
+        # Thêm đường dẫn D-FINE vào sys.path để import được source code
+        dfine_root = os.getcwd()
+        if dfine_root not in sys.path:
+            sys.path.insert(0, dfine_root)
+
+        try:
+            from src.core import YAMLConfig
+        except ImportError:
+            raise ImportError(
+                "Không tìm thấy source code D-FINE! "
+                "Hãy đảm bảo bạn đã clone repo D-FINE "
+                "(git clone https://github.com/Peterande/D-FINE.git) "
+                "và đang chạy code từ thư mục gốc của nó."
+            )
+
+        # Khởi tạo model từ YAML config
+        cfg = YAMLConfig(self._config_path, resume=self._weights_path)
+
+        if "HGNetv2" in cfg.yaml_cfg:
+            cfg.yaml_cfg["HGNetv2"]["pretrained"] = False
+
+        # Load trọng số
+        checkpoint = torch.load(self._weights_path, map_location="cpu")
+        if "ema" in checkpoint:
+            state = checkpoint["ema"]["module"]
+        else:
+            state = checkpoint["model"]
+
+        cfg.model.load_state_dict(state)
+
+        # Chuyển sang deploy mode (loại bỏ các thành phần training)
+        deploy_model = cfg.model.deploy()
+        postprocessor = cfg.postprocessor.deploy()
+
+        class _DeployModel(nn.Module):
+            def __init__(self, model, postprocessor):
+                super().__init__()
+                self.model = model
+                self.postprocessor = postprocessor
+
+            def forward(self, images, orig_target_sizes):
+                outputs = self.model(images)
+                outputs = self.postprocessor(outputs, orig_target_sizes)
+                return outputs
+
+        if device is None:
+            device = "cuda" if torch.cuda.is_available() else "cpu"
+
+        self._model = _DeployModel(deploy_model, postprocessor).to(device)
+        self._model.eval()
+
+    def forward(self, images, threshold=0.4):
+        """
+        Chạy inference trên danh sách ảnh PIL.
+
+        Args:
+            images: list[PIL.Image] hoặc một PIL.Image đơn lẻ.
+            threshold: Ngưỡng confidence tối thiểu (mặc định 0.4).
+
+        Returns:
+            dict với keys: "boxes", "scores", "labels" (mỗi key là list of tensors).
+        """
+        device = "cuda" if torch.cuda.is_available() else "cpu"
+        self._load_dfine(device=device)
+
+        if not isinstance(images, list):
+            images = [images]
+
+        transforms = T.Compose([T.Resize((640, 640)), T.ToTensor()])
+
+        boxes_list, scores_list, labels_list = [], [], []
+        for img in images:
+            if not isinstance(img, Image.Image):
+                img = Image.fromarray(img)
+            img = img.convert("RGB")
+            w, h = img.size
+            orig_size = torch.tensor([[w, h]]).to(device)
+            im_data = transforms(img).unsqueeze(0).to(device)
+
+            with torch.no_grad():
+                labels, boxes, scores = self._model(im_data, orig_size)
+
+            boxes_list.append(boxes[0])
+            scores_list.append(scores[0])
+            labels_list.append(labels[0])
+
+        return {"boxes": boxes_list, "scores": scores_list, "labels": labels_list}
+
+
+# Đăng ký với HuggingFace AutoModel / AutoConfig
+from transformers import AutoConfig, AutoModel
+
+AutoConfig.register("dfine", DFINEConfig)
+AutoModel.register(DFINEConfig, DFINEModel)

preprocessor_config.json

@@ -0,0 +1,11 @@
+{
+  "image_processor_type": "DFINEImageProcessor",
+  "auto_map": {
+    "AutoImageProcessor": "modeling_dfine.DFINEImageProcessor"
+  },
+  "size": {"height": 640, "width": 640},
+  "do_resize": true,
+  "do_normalize": true,
+  "image_mean": [0.485, 0.456, 0.406],
+  "image_std": [0.229, 0.224, 0.225]
+}