| --- |
| license: apache-2.0 |
| pipeline_tag: image-classification |
| library_name: onnxruntime |
| language: [en] |
| tags: |
| - image-classification |
| - document-ai |
| - form-field-detection |
| - onnx |
| - open-weights |
| metrics: |
| - accuracy |
| --- |
| |
| # form-field-v1-state — open-weight |
|
|
| **A 96k-parameter filled/empty classifier for detected form fields.** Given a cropped field, it reads whether |
| the field is **filled** (filled / checked / signed) or **empty** (empty / unchecked / blank) — a single shared, |
| detector-agnostic model that supplies state for any of the `form-field-v1` detectors. ~0.4 MB, CPU-fast, |
| Apache-2.0, runs via ONNX Runtime with no custom code. |
|
|
| Part of the `form-field-v1` family — pair it with [`-nano`](https://huggingface.co/nutrientdocs/form-field-v1-nano) |
| (open) or [`-small`](https://huggingface.co/nutrientdocs/form-field-v1-small) / |
| [`-medium`](https://huggingface.co/nutrientdocs/form-field-v1-medium) (commercial). |
|
|
| - 🎯 **Try it:** [form-field-v1-demo](https://huggingface.co/spaces/nutrientdocs/form-field-v1-demo) |
| - 🏆 **Leaderboard:** [form-field-v1-leaderboard](https://huggingface.co/spaces/nutrientdocs/form-field-v1-leaderboard) |
| - 📊 **Benchmark:** [form-field-v1-benchmark](https://huggingface.co/datasets/nutrientdocs/form-field-v1-benchmark) |
|
|
| ## What it does |
|
|
| Field detectors locate `Text`, `Choice`, and `Signature` widgets; this model answers the follow-up question |
| **"is that field filled?"** on the detected crop. It takes a grayscale field crop, letterboxes it to **40×160** |
| (aspect-preserving — form fields are wide, median aspect ~3.3, so a square resize destroys thin printed text), |
| and outputs a binary **empty (0) / filled (1)** label. State is mapped per type: Text → filled/empty, |
| Choice → checked/unchecked, Signature → signed/blank. |
|
|
| ## Results |
|
|
| Binary field-state accuracy, one shared evaluation. |
|
|
| | | Accuracy | |
| |---|---| |
| | **form-field-v1-state** (this model) | **0.981** | |
| | Training-free ink heuristic | 0.915 | |
|
|
| On a held-out synthetic split it reaches **0.981** vs a training-free ink-presence heuristic's **0.915**. On a |
| real filled form (the ACME credit-card application, 25 fields) it matches the heuristic at **23/25**. |
|
|
| ## What's in this repo |
| | File | | |
| |---|---| |
| | `model.onnx` | ONNX graph, input `1×1×40×160` grayscale, output `logits [n,2]` | |
| | `state_cnn.pt` | PyTorch state dict (depthwise-separable CNN, 96k params) | |
|
|
| Classes: `0 = empty`, `1 = filled`. |
|
|
| ## Usage (ONNX Runtime) |
|
|
| ```python |
| import numpy as np, onnxruntime as ort |
| from PIL import Image |
| |
| sess = ort.InferenceSession("model.onnx", providers=["CPUExecutionProvider"]) |
| |
| def letterbox(crop, th=40, tw=160): # aspect-preserving, pad 255 (paper) |
| g = crop.convert("L"); w, h = g.size |
| s = min(tw / w, th / h); nw, nh = max(1, round(w * s)), max(1, round(h * s)) |
| out = Image.new("L", (tw, th), 255); out.paste(g.resize((nw, nh), Image.BILINEAR), ((tw - nw) // 2, (th - nh) // 2)) |
| return np.asarray(out, np.uint8) |
| |
| crop = Image.open("field_crop.png") # a detected field, cropped from the page |
| x = (((letterbox(crop).astype(np.float32) / 255) - 0.5) / 0.5)[None, None] # normalize, shape [1,1,40,160] |
| filled = int(sess.run(None, {sess.get_inputs()[0].name: x})[0].argmax(1)[0]) == 1 |
| ``` |
|
|
| ## License & data |
| Apache-2.0. Trained on synthetic form renders (empty + filled + handwritten field crops, with on-the-fly |
| augmentation for scan robustness); no PII. |
|
|
| ## About the author |
|
|
| <a href="https://nutrient.io/"> |
| <img src="https://avatars2.githubusercontent.com/u/1527679?v=3&s=200" height="80" /> |
| </a> |
|
|
| This project is maintained and funded by [Nutrient](https://nutrient.io/) - The deterministic document infrastructure enterprises run their highest-stakes workflows on: replayable output, clear exceptions, and full audit trails on the messy, regulated documents where AI alone breaks. |
|
|
