Widget Detector

End-to-end document form widget detection using YOLO11m, automatically downloading fine-tuned weights from Hugging Face.

Detects 3 classes of form fields from scanned PDFs and document images:

Installation

You can install the package directly from PyPI:

pip install psynx-widget-detector

Requires Python 3.11+

Quickstart

The package will automatically download the fine-tuned YOLO11m weights from Hugging Face (PSynx/widget-detector-yolo) the first time you run it.

from widget_detector import WidgetDetector

# 1. Initialize the detector (downloads weights automatically if not found)
detector = WidgetDetector()

# 2. Run inference on a PDF (auto-renders pages to images)
result = detector.detect_path("sample_form.pdf")

# 3. Print the results
print(f"Detected {result.total_widgets} widgets across {result.total_pages} pages.")

for page in result.pages:
    print(f"\nPage {page.page}:")
    for widget in page.widgets:
        print(f" - {widget.class_name} ({widget.confidence:.2f}) at "
              f"[{widget.bbox.x1:.1f}, {widget.bbox.y1:.1f}, {widget.bbox.x2:.1f}, {widget.bbox.y2:.1f}]")

# 4. Save results to JSON
result.save("output.json")

Output Format

The detector returns a structured Pydantic object that cleanly serializes to JSON:

{
  "source": "form.pdf",
  "total_pages": 3,
  "total_widgets": 24,
  "pages": [
    {
      "source": "form.pdf",
      "page": 1,
      "image_width": 1654,
      "image_height": 2339,
      "processing_time_ms": 142.3,
      "widgets": [
        {
          "class_id": 0,
          "class_name": "text_input",
          "confidence": 0.913,
          "bbox": {
            "x1": 120.0, "y1": 340.0, "x2": 480.0, "y2": 380.0,
            "x1_norm": 0.073, "y1_norm": 0.145,
            "x2_norm": 0.290, "y2_norm": 0.163
          },
          "page": 1
        }
      ]
    }
  ]
}

Notes

• CommonForms choice_button includes both checkboxes and radio buttons as one class (the dataset does not distinguish them).
• Inference Speed: If you have a CUDA-enabled GPU, the WidgetDetector will automatically use it for highly accelerated inference.