README.md

---
pipeline_tag: object-detection
tags:
- form-field-detection
- documents
- commonforms
library_name: commonforms
datasets:
  - jbarrow/CommonForms
---

🪄 Automatically convert a PDF into a fillable form.

[💻 Hosted Models (detect.semanticdocs.org)](https://detect.semanticdocs.org) | [📄 CommonForms Paper](https://arxiv.org/abs/2509.16506) | [🤗 Dataset](https://huggingface.co/datasets/jbarrow/CommonForms) | [🦾 Models](https://github.com/jbarrow/commonforms/tree/main/commonforms/models)

![Pipeline](https://raw.githubusercontent.com/jbarrow/commonforms/main/assets/pipeline.png)

# FFDNet-S

FFDNet-S is the 6 million parameter object detector trained on the dataset from the paper [CommonForms: A Large, Diverse Dataset for Form Field Detection](https://arxiv.org/abs/2509.16506).
The model detects widgets from among three classes: TextBoxes, ChoiceButtons (checkboxes), and Signature fields.

## Results

| Model | Text | Choice | Signature | AP (↑) |
|-------|------|--------|-----------|--------|
| FFDNet-S (1216px) | 61.5 | 71.3 | 84.2 | 72.3 |
| FFDNet-L (1216px) | 71.4 | 78.1 | 93.5 | 81.0 |


## Installation

The `commonforms` package can be installed with either `uv` or `pip`, feel free to choose your package manager flavor.
The `uv` command:

```sh
uv pip install commonforms
```

The `pip` command:

```
pip install commonforms
```

Once it's installed, you should be able to run the CLI command on ~any PDF.
Refer to [the `commonforms` documentation](https://github.com/jbarrow/commonforms) for the latest information.

## CLI

The simplest usage will run inference on your CPU using the default suggested settings:

```
commonforms <input.pdf> <output.pdf>
```

| Input | Output |
|-------|--------|
| ![Input PDF](https://raw.githubusercontent.com/jbarrow/commonforms/main/assets/input.png) | ![Output PDF](https://raw.githubusercontent.com/jbarrow/commonforms/main/assets/output.png) |

### Command Line Arguments

| Argument | Type | Default | Description |
|----------|------|---------|-------------|
| `input` | Path | Required | Path to the input PDF file |
| `output` | Path | Required | Path to save the output PDF file |
| `--model` | str | `FFDNet-L` | Model name (FFDNet-L/FFDNet-S) or path to custom .pt file |
| `--keep-existing-fields` | flag | `False` | Keep existing form fields in the PDF |
| `--use-signature-fields` | flag | `False` | Use signature fields instead of text fields for detected signatures |
| `--device` | str | `cpu` | Device for inference (e.g., `cpu`, `cuda`, `0`) |
| `--image-size` | int | `1600` | Image size for inference |
| `--confidence` | float | `0.3` | Confidence threshold for detection |
| `--fast` | flag | `False` | If running on a CPU, you can trade off accuracy for speed and run in about half the time |

## CommonForms API

In addition to the CLI, you can use

```py
from commonforms import prepare_form

prepare_form(
    "path/to/input.pdf",
    "path/to/output.pdf"
)
```

All of the above arguments are keyword arguments to the `prepare_form` function.
E.g. if you want to prepare a with signature fields and keep existing fields at 1216 resolution, you would run:

```
from commonforms import prepare_form

prepare_form(
    "path/to/input.pdf",
    "path/to/output.pdf",
    keep_existing_fields=True,
    use_signature_fields=True,
    image_size=1216
)
```

## References

* [CommonForms: A Large, Diverse Dataset for Form Field Detection](https://arxiv.org/abs/2509.16506)