CommonForms

CommonForms can be installed either as a standalone CLI tool or as a library for use within an existing Python project.

As a CLI tool (Recommended): To avoid dependency conflicts with your existing environment, it is recommended to install CommonForms in an isolated environment using uv tool or pipx. This exposes only the commonforms command.

As a library: If you want to import CommonForms into your own Python code, install it using uv pip or pip.

⚠️ Warning: Because CommonForms has a large dependency footprint (including transformers, torch, rfdetr, and ultralytics) and pins specific versions, installing it into a shared or base environment may upgrade or change your existing packages like numpy, pillow, or transformers. It is highly recommended to use a dedicated virtualenv or conda environment.

# Install as an isolated CLI tool
uv tool install commonforms
# or
pipx install commonforms

# Install as a library in an existing project
uv pip install commonforms
# or
pip install commonforms

The following arguments are available for the commonforms command:

The PyPdfFormCreator class is the primary interface for adding interactive form elements (textboxes, checkboxes, and signatures) to an existing PDF file. It uses pypdf under the hood to manage annotations.

Workflow

1. Initialize: Create an instance by providing the path to an existing PDF.
2. Add Fields: Use methods like add_text_box, add_checkbox, or add_signature specifying the field name, the page index, and a BoundingBox defining the location.
3. Save: Call save(output_path) to write the new PDF to disk.
4. Cleanup: Call close() to release the file handles for the reader and writer.

from commonforms.form_creator import PyPdfFormCreator
from commonforms.utils import BoundingBox

# Initialize with an existing PDF
creator = PyPdfFormCreator("input.pdf")

# Define a location using BoundingBox (coordinates are normalized 0.0 to 1.0)
box = BoundingBox(x0=0.1, y0=0.1, x1=0.5, y1=0.2)

# Add a textbox on page 0
creator.add_text_box("user_name", page=0, bounding_box=box)

# Add a checkbox on page 0
creator.add_checkbox("agree_terms", page=0, bounding_box=box)

# Save the result
creator.save("output_form.pdf")
creator.close()

The FFDetrDetector class uses the RFDETR model to detect form widgets (TextBox, ChoiceButton, Signature) in PDF pages. It supports downloading weights automatically from the Hugging Face Hub if a valid model name like FFDETR is provided.

Key Methods:

• __init__(model_or_path: str, device: int | str = "cpu"):
  • model_or_path: Use "FFDETR" to download weights automatically, or provide a local path to a .pth file.
  • device: The device to run inference on (e.g., "cpu" or an integer for GPU).
• extract_widgets(pages: list[Page], confidence: float = 0.4, image_size: int = 1120, batch_size: int = 3) -> dict[int, list[Widget]]:
  • pages: A list of Page objects (obtained via render_pdf).
  • confidence: Detection threshold.
  • image_size: Target image size for processing.
  • batch_size: Number of pages to process in a single batch.

from commonforms.inference import FFDetrDetector
from commonforms.inference import render_pdf

# 1. Render PDF pages
pages = render_pdf("input.pdf")

# 2. Initialize detector
detector = FFDetrDetector(model_or_path="FFDETR", device="cpu")

# 3. Extract widgets
widgets_by_page = detector.extract_widgets(pages, confidence=0.5)

If you are integrating CommonForms into a Python application, you can call prepare_form directly from commonforms.inference.

Signature: prepare_form(input, output, model_or_path, keep_existing_fields, use_signature_fields, device, image_size, confidence, fast, multiline)

Parameters:

• input (Path): Path to the input PDF.
• output (Path): Path to save the output PDF.
• model_or_path (str): Model name (FFDNet-L/FFDNet-S) or path to a .pt model.
• keep_existing_fields (bool): Whether to keep existing form fields.
• use_signature_fields (bool): Whether to use signature fields for detected signatures.
• device (str): Inference device (e.g., cpu).
• image_size (int): Image size for inference.
• confidence (float): Confidence threshold for detection.
• fast (bool): Use fast mode for CPU speedup.
• multiline (bool): Enable multiline inputs for textboxes.

from commonforms.inference import prepare_form
from pathlib import Path

prepare_form(
    input=Path("input.pdf"),
    output=Path("output.pdf"),
    model_or_path="FFDNet-L",
    keep_existing_fields=True,
    use_signature_fields=False,
    device="cpu",
    image_size=1600,
    confidence=0.3,
    fast=True,
    multiline=True
)