Metadata-Version: 2.4
Name: checkbox-extractor
Version: 0.1.0
Summary: Find ticked checkboxes and radio buttons in scanned or photographed forms, no template needed
Author: Gopal R S
License-Expression: MIT
Keywords: checkbox,omr,form,ocr,opencv,document,scan
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Classifier: Topic :: Text Processing
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: opencv-python-headless>=4.8
Requires-Dist: numpy
Dynamic: license-file

# 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

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

## Command line

```bash
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):

```json
{
  "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

```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
bash test_forms/run_tests.sh       # fixed sample forms
python3 test_forms/fuzz_forms.py   # random generated forms
```
