Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,81 @@
+---
+language:
+- en
+license: mit
+library_name: ultralytics
+tags:
+- yolo11
+- object-detection
+- document-ai
+- form-understanding
+- vision
+pipeline_tag: object-detection
+---
+
+# YOLO11m Document Widget Detector
+
+This is a fine-tuned YOLO11m model for detecting interactive form widgets (text inputs, checkboxes/radio buttons, and signatures) in document images and PDFs.
+
+It was trained on the [CommonForms](https://huggingface.co/datasets/jbarrow/CommonForms) dataset (100,000 document images) and achieves high accuracy across diverse document layouts.
+
+## Model Details
+- **Architecture:** YOLO11m
+- **Task:** Object Detection (Document Widgets)
+- **Classes:** 
+  - `0`: `text_input`
+  - `1`: `choice_button` (checkboxes & radio buttons)
+  - `2`: `signature`
+- **Input Size:** 1024x1024
+
+## Performance (mAP@50)
+- **text_input:** 0.814
+- **choice_button:** 0.709
+- **signature:** 0.838
+- **Overall mAP@50:** 0.787
+
+## Usage
+
+### Using the Python Package
+
+You can install the official inference package to automatically download this model and process PDFs or images.
+
+```bash
+pip install widget-detector
+```
+
+```python
+from widget_detector import WidgetDetector
+
+# Initialize without a path to auto-download from Hugging Face
+detector = WidgetDetector()
+
+# Run inference on a PDF (auto-renders pages to images)
+result = detector.detect_path("sample_form.pdf")
+
+# Print results
+for page in result.pages:
+    print(f"Page {page.page}: Found {len(page.widgets)} widgets")
+    for w in page.widgets:
+        print(f" - {w.class_name} ({w.confidence:.2f}) at {w.bbox.x1:.1f}, {w.bbox.y1:.1f}")
+
+# Save to JSON
+result.save("output.json")
+```
+
+### Using Ultralytics Directly
+
+If you prefer to use the raw Ultralytics library:
+
+```python
+from ultralytics import YOLO
+from huggingface_hub import hf_hub_download
+
+# Download the model weights
+model_path = hf_hub_download(repo_id="PSynx/widget-detector-yolo", filename="best.pt")
+
+# Load the model
+model = YOLO(model_path)
+
+# Run inference
+results = model("document_image.png", imgsz=1024, conf=0.25)
+```