File size: 3,885 Bytes
62b1049 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 | ---
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.
|