PDF Form Engine

PDF Form Engine is a cross-platform command-line tool that converts existing PDFs into fillable AcroForm templates and generates filled PDFs using structured JSON data.

It is designed to be used as:

• A native engine behind desktop form editors (e.g. Flutter, Electron)
• A backend utility for generating PDFs from user input
• A standalone PDF form processing tool

The tool uses PyMuPDF (MuPDF) for reliable and standards-compliant PDF manipulation.

---

Features

• Create fillable PDF forms (AcroForms) from existing PDFs
• Define form fields using a JSON schema
• Support for text fields, checkboxes, radio buttons, and dropdowns
• Fill PDF forms programmatically using JSON input
• Optional flattening of filled PDFs
• Works without Adobe Acrobat
• Cross-platform (Linux, macOS, Windows)
• Can be distributed as a single standalone binary

---

Requirements

• Python 3.8+ (not required when using the compiled binary)
• PyMuPDF
• Click

---

Installation

Option 1: Install from source (development)

pip install -e .

---

Option 2: Run without installation

python -m pdf_form_engine --help

---

Option 3: Standalone binary (recommended for desktop apps)

Build the binary:

pyinstaller \
  --onefile \
  --name pdf-form-engine \
  --collect-all pymupdf \
  pdf_form_engine/__main__.py

---

The binary will be available at:

dist/pdf-form-engine

---

Usage

Create a Fillable PDF

pdf-form-engine apply \
  --input original.pdf \
  --schema schema.json \
  --output fillable.pdf

Fill a PDF with User Data

pdf-form-engine fill \
  --input fillable.pdf \
  --data data.json \
  --output filled.pdf

Flatten a PDF

pdf-form-engine fill \
  --input fillable.pdf \
  --data data.json \
  --output final.pdf \
  --flatten

Flattening removes form fields and produces a final, non-editable PDF.

Schema Format

Form fields are defined using a JSON schema.

Example:

{
  "fields": [
    {
      "name": "customer_name",
      "type": "text",
      "page": 0,
      "x": 120,
      "y": 540,
      "width": 220,
      "height": 22,
      "required": true
    },
    {
      "name": "agree_terms",
      "type": "checkbox",
      "page": 1,
      "x": 90,
      "y": 410,
      "width": 15,
      "height": 15
    }
  ]
}

Notes:

• Page numbers are 0-based
• Coordinates are in PDF points
• Field names must be unique

Data Format (Filling PDFs)

{
  "customer_name": "Ali Yar Khan",
  "agree_terms": true
}

Typical Use Cases

• PDF form builders and editors
• Contract and agreement generation
• Invoice and bill generation
• Government and compliance forms
• Desktop applications requiring local PDF processing
• Backend PDF automation pipelines

Limitations

• Does not support XFA forms
• Scanned PDFs require OCR before processing
• Appearance styling is minimal by default

Roadmap

• OCR support for scanned PDFs
• Field appearance customization
• Auto field detection
• Schema validation
• Logging and error reporting

License

MIT License

Acknowledgements

• PyMuPDF (MuPDF)
• MuPDF Project