wormclaude 1.0.74 → 1.0.76

package/skills/pdf/FORMS.md

@@ -0,0 +1,294 @@
+**CRITICAL: Work through these steps in the given order. Don't jump straight to writing code.**
+
+Before filling any PDF form, find out whether it already carries fillable form fields. From this file's directory, run:
+ `python scripts/check_fillable_fields <file.pdf>`, then branch to either the "Fillable fields" or "Non-fillable fields" section below based on what it reports.
+
+# Fillable fields
+When the PDF already has fillable form fields:
+- From this file's directory, run: `python scripts/extract_form_field_info.py <input.pdf> <field_info.json>`. This produces a JSON file listing the fields in the shape below:
+```
+[
+  {
+    "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
+    ],
+  }
+]
+```
+- Render the PDF to PNGs (one per page) using this script (run from this file's directory):
+`python scripts/convert_pdf_to_images.py <file.pdf> <output_directory>`
+Then study the images to work out what each form field is for (remember to translate the bounding-box PDF coordinates into image coordinates).
+- Build a `field_values.json` file in the shape below, holding the value to write into 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
+]
+```
+- Run `fill_fillable_fields.py` from this file's directory to produce the completed PDF:
+`python scripts/fill_fillable_fields.py <input pdf> <field_values.json> <output pdf>`
+The script validates the field IDs and values you supplied; if it reports errors, fix the flagged fields and run it again.
+
+# Non-fillable fields
+When the PDF has no fillable form fields, you'll overlay text annotations instead. Start by pulling coordinates from the PDF's structure (the more precise route), and only fall back to eyeballing positions if that fails.
+
+## Step 1: Try Structure Extraction First
+
+Run the script below to pull out text labels, lines, and checkboxes along with their exact PDF coordinates:
+`python scripts/extract_form_structure.py <input.pdf> form_structure.json`
+
+This writes a JSON file holding:
+- **labels**: Every text element with exact coordinates (x0, top, x1, bottom in PDF points)
+- **lines**: Horizontal lines that define row boundaries
+- **checkboxes**: Small square rectangles that are checkboxes (with center coordinates)
+- **row_boundaries**: Row top/bottom positions derived from the horizontal lines
+
+**Review the output**: If `form_structure.json` contains useful labels (text elements that map to form fields), go with **Approach A: Structure-Based Coordinates**. If the PDF is a scan or image with few or no labels, switch to **Approach B: Visual Estimation**.
+
+---
+
+## Approach A: Structure-Based Coordinates (Preferred)
+
+Pick this path when `extract_form_structure.py` did locate text labels in the PDF.
+
+### A.1: Analyze the Structure
+
+Open form_structure.json and pin down:
+
+1. **Label groups**: Neighboring text elements that together make one label (e.g., "Last" + "Name")
+2. **Row structure**: Labels sharing a similar `top` value belong to the same row
+3. **Field columns**: Entry areas begin where the label ends (x0 = label.x1 + gap)
+4. **Checkboxes**: Take the checkbox coordinates straight from the structure
+
+**Coordinate system**: PDF coordinates with y=0 at the TOP of the page and y growing downward.
+
+### A.2: Check for Missing Elements
+
+Structure extraction won't always catch every form element. Typical gaps:
+- **Circular checkboxes**: Only square rectangles register as checkboxes
+- **Complex graphics**: Decorative pieces or unusual form controls
+- **Faded or light-colored elements**: These may slip through
+
+If the PDF images show fields that never made it into form_structure.json, handle those particular fields with **visual analysis** (see "Hybrid Approach" below).
+
+### A.3: Create fields.json with PDF Coordinates
+
+For every field, work out the entry coordinates from the extracted structure:
+
+**Text fields:**
+- entry x0 = label x1 + 5 (leave a small gap past the label)
+- entry x1 = the next label's x0, or the row boundary
+- entry top = matches the label top
+- entry bottom = the row boundary line below, or label bottom + row_height
+
+**Checkboxes:**
+- Take the checkbox rectangle coordinates verbatim from form_structure.json
+- entry_bounding_box = [checkbox.x0, checkbox.top, checkbox.x1, checkbox.bottom]
+
+Write fields.json with `pdf_width` and `pdf_height` (which flags PDF coordinates):
+```json
+{
+  "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**: Stick to `pdf_width`/`pdf_height` and the coordinates pulled straight from form_structure.json.
+
+### A.4: Validate Bounding Boxes
+
+Before you fill anything, screen the bounding boxes for problems:
+`python scripts/check_bounding_boxes.py fields.json`
+
+This flags overlapping bounding boxes and entry boxes that are too cramped for the font size. Clear any reported errors before filling.
+
+---
+
+## Approach B: Visual Estimation (Fallback)
+
+Turn to this when the PDF is a scan or image and structure extraction turned up no usable text labels (for instance, every bit of text comes back as "(cid:X)" patterns).
+
+### B.1: Convert PDF to Images
+
+`python scripts/convert_pdf_to_images.py <input.pdf> <images_dir/>`
+
+### B.2: Initial Field Identification
+
+Look over each page image to map out the form's sections and get **rough estimates** of where fields sit:
+- Form field labels and roughly where they are
+- Entry areas (lines, boxes, or empty space meant for text)
+- Checkboxes and their rough locations
+
+For each field, jot down approximate pixel coordinates (precision can wait).
+
+### B.3: Zoom Refinement (CRITICAL for accuracy)
+
+For each field, crop a region around your estimate so you can dial in the coordinates exactly.
+
+**Make a zoomed crop with ImageMagick:**
+```bash
+magick <page_image> -crop <width>x<height>+<x>+<y> +repage <crop_output.png>
+```
+
+Where:
+- `<x>, <y>` = the crop region's top-left corner (your rough estimate, minus some padding)
+- `<width>, <height>` = the crop region's dimensions (the field area plus roughly 50px of padding on every side)
+
+**Example:** To tighten up a "Name" field estimated near (100, 150):
+```bash
+magick images_dir/page_1.png -crop 300x80+50+120 +repage crops/name_field.png
+```
+
+(Note: if `magick` isn't installed, run `convert` with the same arguments.)
+
+**Study the cropped image** to lock in precise coordinates:
+1. Find the exact pixel where the entry area starts (just past the label)
+2. Find where the entry area stops (before the next field or the page edge)
+3. Find the top and bottom of the entry line or box
+
+**Map crop coordinates back onto the full image:**
+- full_x = crop_x + crop_offset_x
+- full_y = crop_y + crop_offset_y
+
+Example: if the crop began at (50, 120) and the entry box starts at (52, 18) inside the crop:
+- entry_x0 = 52 + 50 = 102
+- entry_top = 18 + 120 = 138
+
+**Do this for every field**, bundling nearby fields into a single crop where you can.
+
+### B.4: Create fields.json with Refined Coordinates
+
+Write fields.json with `image_width` and `image_height` (which flags image coordinates):
+```json
+{
+  "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**: Stick to `image_width`/`image_height` together with the refined pixel coordinates from your zoom pass.
+
+### B.5: Validate Bounding Boxes
+
+Before filling, screen the bounding boxes for problems:
+`python scripts/check_bounding_boxes.py fields.json`
+
+This flags overlapping bounding boxes and entry boxes too cramped for the font size. Clear any reported errors before filling.
+
+---
+
+## Hybrid Approach: Structure + Visual
+
+Go this route when structure extraction nails most fields but skips a few elements (circular checkboxes, oddball form controls, and the like).
+
+1. **Apply Approach A** to the fields that showed up in form_structure.json
+2. **Render the PDF to images** so you can visually inspect the missing fields
+3. **Apply zoom refinement** (from Approach B) to those missing fields
+4. **Reconcile the coordinates**: keep `pdf_width`/`pdf_height` for the structure-extracted fields. For the visually estimated ones, convert image coordinates into PDF coordinates:
+   - pdf_x = image_x * (pdf_width / image_width)
+   - pdf_y = image_y * (pdf_height / image_height)
+5. **Settle on one coordinate system** in fields.json — convert everything to PDF coordinates with `pdf_width`/`pdf_height`
+
+---
+
+## Step 2: Validate Before Filling
+
+**Always screen the bounding boxes before filling:**
+`python scripts/check_bounding_boxes.py fields.json`
+
+This looks for:
+- Overlapping bounding boxes (which would smear text together)
+- Entry boxes too small for the chosen font size
+
+Clear any reported errors in fields.json before moving on.
+
+## Step 3: Fill the Form
+
+The fill script figures out the coordinate system on its own and handles the conversion:
+`python scripts/fill_pdf_form_with_annotations.py <input.pdf> fields.json <output.pdf>`
+
+## Step 4: Verify Output
+
+Render the filled PDF to images and confirm the text landed where it should:
+`python scripts/convert_pdf_to_images.py <output.pdf> <verify_images/>`
+
+If any text is out of place:
+- **Approach A**: Confirm you're using PDF coordinates from form_structure.json alongside `pdf_width`/`pdf_height`
+- **Approach B**: Confirm the image dimensions line up and the coordinates are accurate pixels
+- **Hybrid**: Confirm the coordinate conversions are right for the visually estimated fields