checkbox-extractor

Finds ticked checkboxes and radio buttons in scanned or photographed forms and returns JSON. No template is needed: boxes are found from their outline, grouped into questions, and each group gets its header text from Tesseract OCR plus the positions of the ticked boxes.

Install

pip install .                      # or: pip install -e . while developing
sudo apt install tesseract-ocr poppler-utils   # OCR, and PDF support

Command line

checkbox-extract form.jpg
checkbox-extract form.pdf -o result.json --debug-dir debug/
checkbox-extract scans_folder/ --threshold 0.12 --lang eng+hin

python -m checkbox_extractor works the same way.

Output (one page):

{
  "source": "form.jpg",
  "page": 1,
  "checkbox_count": 5,
  "ticked_count": 2,
  "groups": [
    {"header": "Gender", "total": 2, "ticked": [1], "ticked_labels": ["Male"]},
    {"header": "Smoker?", "total": 3, "ticked": [2], "ticked_labels": ["No"]}
  ]
}

ticked holds 1-based positions. Add --full to also get every box's label, shape, fill ratio and bounding box (useful when tuning --threshold).

Python

from checkbox_extractor import extract

result = extract("form.jpg")
for group in result["groups"]:
    print(group["header"], group["ticked"])

result = extract("form.jpg", full=True)   # detailed output

# an image already in memory (BGR numpy array, e.g. from cv2.imread)
result = extract(image, threshold=0.12)

A PDF or a folder returns a list with one result per page.

Tests

bash test_forms/run_tests.sh       # fixed sample forms
python3 test_forms/fuzz_forms.py   # random generated forms