Setting the file. One moment.
Subchapter 10.9
forms.mdMarkdown12 KBView on GitHub
CRITICAL: You MUST complete these steps in order. Do not skip ahead to writing code.
If you need to fill out a PDF form, first check to see if the PDF has fillable form fields. Run this script from this file’s directory:
python scripts/check_fillable_fields <file.pdf>, and depending on the result go to either the “Fillable fields” or “Non-fillable fields” and follow those instructions.
If the PDF has fillable form fields:
python scripts/extract_form_field_info.py <input.pdf> <field_info.json>. It will create a JSON file with a list of fields in this format:[
{
"field_id": (unique ID for the field),
"page": (page number, 1-based),
"rect": ([left, bottom, right, top] bounding box in PDF coordinates, y=0 is the bottom of the page),
"type": ("text", "checkbox", "radio_group", or "choice"),
},
// Checkboxes have "checked_value" and "unchecked_value" properties:
{
"field_id": (unique ID for the field),
"page": (page number, 1-based),
"type": "checkbox",
"checked_value": (Set the field to this value to check the checkbox),
"unchecked_value": (Set the field to this value to uncheck the checkbox),
},
// Radio groups have a "radio_options" list with the possible choices.
{
"field_id": (unique ID for the field),
"page": (page number, 1-based),
"type": "radio_group",
"radio_options": [
{
"value": (set the field to this value to select this radio option),
"rect": (bounding box for the radio button for this option)
},
// Other radio options
]
},
// Multiple choice fields have a "choice_options" list with the possible choices:
{
"field_id": (unique ID for the field),
"page": (page number, 1-based),
"type": "choice",
"choice_options": [
{
"value": (set the field to this value to select this option),
"text": (display text of the option)
},
// Other choice options
],
}
]python scripts/convert_pdf_to_images.py <file.pdf> <output_directory>
Then analyze the images to determine the purpose of each form field (make sure to convert the bounding box PDF coordinates to image coordinates).field_values.json file in this format with the values to be entered for each field:[
{
"field_id": "last_name", // Must match the field_id from `extract_form_field_info.py`
"description": "The user's last name",
"page": 1, // Must match the "page" value in field_info.json
"value": "Simpson"
},
{
"field_id": "Checkbox12",
"description": "Checkbox to be checked if the user is 18 or over",
"page": 1,
"value": "/On" // If this is a checkbox, use its "checked_value" value to check it. If it's a radio button group, use one of the "value" values in "radio_options".
},
// more fields
]fill_fillable_fields.py script from this file’s directory to create a filled-in PDF:
python scripts/fill_fillable_fields.py <input pdf> <field_values.json> <output pdf>
This script will verify that the field IDs and values you provide are valid; if it prints error messages, correct the appropriate fields and try again.If the PDF doesn’t have fillable form fields, you’ll add text annotations. First try to extract coordinates from the PDF structure (more accurate), then fall back to visual estimation if needed.
Run this script to extract text labels, lines, and checkboxes with their exact PDF coordinates:
python scripts/extract_form_structure.py <input.pdf> form_structure.json
This creates a JSON file containing:
Check the results: If form_structure.json has meaningful labels (text elements that correspond to form fields), use Approach A: Structure-Based Coordinates. If the PDF is scanned/image-based and has few or no labels, use Approach B: Visual Estimation.
Use this when extract_form_structure.py found text labels in the PDF.
Read form_structure.json and identify:
top values are in the same rowCoordinate system: PDF coordinates where y=0 is at TOP of page, y increases downward.
The structure extraction may not detect all form elements. Common cases:
If you see form fields in the PDF images that aren’t in form_structure.json, you’ll need to use visual analysis for those specific fields (see “Hybrid Approach” below).
For each field, calculate entry coordinates from the extracted structure:
Text fields:
Checkboxes:
Create fields.json using pdf_width and pdf_height (signals PDF coordinates):
{
"pages": [
{"page_number": 1, "pdf_width": 612, "pdf_height": 792}
],
"form_fields": [
{
"page_number": 1,
"description": "Last name entry field",
"field_label": "Last Name",
"label_bounding_box": [43, 63, 87, 73],
"entry_bounding_box": [92, 63, 260, 79],
"entry_text": {"text": "Smith", "font_size": 10}
},
{
"page_number": 1,
"description": "US Citizen Yes checkbox",
"field_label": "Yes",
"label_bounding_box": [260, 200, 280, 210],
"entry_bounding_box": [285, 197, 292, 205],
"entry_text": {"text": "X"}
}
]
}Important: Use pdf_width/pdf_height and coordinates directly from form_structure.json.
Before filling, check your bounding boxes for errors:
python scripts/check_bounding_boxes.py fields.json
This checks for intersecting bounding boxes and entry boxes that are too small for the font size. Fix any reported errors before filling.
Use this when the PDF is scanned/image-based and structure extraction found no usable text labels (e.g., all text shows as “(cid:X)” patterns).
python scripts/convert_pdf_to_images.py <input.pdf> <images_dir/>
Examine each page image to identify form sections and get rough estimates of field locations:
For each field, note approximate pixel coordinates (they don’t need to be precise yet).
For each field, crop a region around the estimated position to refine coordinates precisely.
Create a zoomed crop using ImageMagick:
magick <page_image> -crop <width>x<height>+<x>+<y> +repage <crop_output.png>Where:
<x>, <y> = top-left corner of crop region (use your rough estimate minus padding)<width>, <height> = size of crop region (field area plus ~50px padding on each side)Example: To refine a “Name” field estimated around (100, 150):
magick images_dir/page_1.png -crop 300x80+50+120 +repage crops/name_field.png(Note: if the magick command isn’t available, try convert with the same arguments).
Examine the cropped image to determine precise coordinates:
Convert crop coordinates back to full image coordinates:
Example: If the crop started at (50, 120) and the entry box starts at (52, 18) within the crop:
Repeat for each field, grouping nearby fields into single crops when possible.
Create fields.json using image_width and image_height (signals image coordinates):
{
"pages": [
{"page_number": 1, "image_width": 1700, "image_height": 2200}
],
"form_fields": [
{
"page_number": 1,
"description": "Last name entry field",
"field_label": "Last Name",
"label_bounding_box": [120, 175, 242, 198],
"entry_bounding_box": [255, 175, 720, 218],
"entry_text": {"text": "Smith", "font_size": 10}
}
]
}Important: Use image_width/image_height and the refined pixel coordinates from the zoom analysis.
Before filling, check your bounding boxes for errors:
python scripts/check_bounding_boxes.py fields.json
This checks for intersecting bounding boxes and entry boxes that are too small for the font size. Fix any reported errors before filling.
Use this when structure extraction works for most fields but misses some elements (e.g., circular checkboxes, unusual form controls).
pdf_width/pdf_height. For visually-estimated fields, you must convert image coordinates to PDF coordinates:
pdf_width/pdf_heightAlways validate bounding boxes before filling:
python scripts/check_bounding_boxes.py fields.json
This checks for:
Fix any reported errors in fields.json before proceeding.
The fill script auto-detects the coordinate system and handles conversion:
python scripts/fill_pdf_form_with_annotations.py <input.pdf> fields.json <output.pdf>
Convert the filled PDF to images and verify text placement:
python scripts/convert_pdf_to_images.py <output.pdf> <verify_images/>
If text is mispositioned:
pdf_width/pdf_height