form-field-v1-nano

form-field-v1-nano — open-weight

A 0.90M-parameter form-field detector that punches far above its weight. Locates Text, Choice (checkbox/radio), and Signature widgets on document pages — on empty, filled, and handwritten forms — at 3.7 MB and ~90 pages/sec on a laptop CPU. Apache-2.0, downloadable, runs via ONNX Runtime with no custom code.

Part of the form-field-v1 family (-nano open · -small / -medium commercial, higher accuracy).

• 🎯 Try it: form-field-v1-demo
• 🏆 Leaderboard: form-field-v1-leaderboard
• 📊 Benchmark: form-field-v1-benchmark

Why it's notable

At 0.90M params it detects Text, Choice, and Signature across empty, filled, and handwritten forms — at 3.7 MB and ~90 pages/sec on a laptop CPU.

COCO mAP50-95, one shared pycocotools scorer across all models. On empty, per-class it reaches Text 0.472 / Choice 0.482 / Signature 0.179.

What's in this repo

Classes: 0 = Text, 1 = ChoiceButton, 2 = Signature.

Usage (torch)

The checkpoint is a YOLOX-Nano model (best_ckpt.pth + exp.py); run it with the yolox package.

import torch, numpy as np
from PIL import Image
from yolox.exp import get_exp
from yolox.utils import postprocess

exp = get_exp("exp.py"); model = exp.get_model().eval()
model.load_state_dict(torch.load("best_ckpt.pth", map_location="cpu")["model"])

S = 640
img = Image.open("page.png").convert("RGB")
r = min(S / img.width, S / img.height)                     # letterbox to SxS, pad 114, raw 0-255 (no normalize)
rs = img.resize((int(img.width * r), int(img.height * r)))
canvas = Image.new("RGB", (S, S), (114, 114, 114)); canvas.paste(rs, (0, 0))
x = torch.from_numpy(np.asarray(canvas, np.float32).transpose(2, 0, 1)[None])

with torch.no_grad():
    dets = postprocess(model(x), num_classes=3, conf_thre=0.3, nms_thre=0.6)[0]   # x1,y1,x2,y2,obj,cls_score,cls
# divide boxes by r to map back to page pixels; class 0=Text, 1=ChoiceButton, 2=Signature

Usage (ONNX Runtime)

import numpy as np, onnxruntime as ort
from PIL import Image

sess = ort.InferenceSession("model.onnx", providers=["CPUExecutionProvider"])
S = 640
img = Image.open("page.png").convert("RGB")
r = min(S / img.width, S / img.height)
rs = img.resize((int(img.width * r), int(img.height * r)))
canvas = Image.new("RGB", (S, S), (114, 114, 114)); canvas.paste(rs, (0, 0))
x = np.asarray(canvas, np.float32).transpose(2, 0, 1)[None]

out = sess.run(None, {sess.get_inputs()[0].name: x})[0]   # [1, 8400, 8] — already DECODED (boxes in 640px)
# rows: [cx, cy, w, h, obj, cls_Text, cls_Choice, cls_Signature].
score = out[0, :, 4:5] * out[0, :, 5:8]                   # obj * class prob; take argmax class, NMS per class,
# convert cx,cy,w,h -> x1,y1,x2,y2, then divide by r to map back to page pixels.

Verified: running this ONNX end-to-end on the full benchmark reproduces the torch model — fp32 mAP50-95 = 0.4792, fp16 (model_fp16.onnx) = 0.4776 (torch = 0.479). The ONNX is exported with decode baked in (tools/export_onnx.py --decode_in_inference), so no external grid-decode is needed.

Footprint: model_fp16.onnx (1.9 MB) halves the fp32 file with near-lossless accuracy (0.4776 vs 0.4792). fp16 is a size/GPU optimization — no CPU-speed change. For an even smaller bundle, INT8 shrinks further but its speed only materializes on an int8-optimized mobile backend (CoreML / NNAPI / TFLite-XNNPACK), not desktop ORT-CPU.

License & data

Apache-2.0. Trained on synthetic form renders (empty + filled + handwritten); no PII. Reproduction details in the project's docs/YOLOX.md.

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 - 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.