@ngockhoale/ukit 1.1.6

package/templates/.claude/skills/pdf/scripts/fill_pdf_form_with_annotations.py

@@ -0,0 +1,108 @@
+import json
+import sys
+
+from pypdf import PdfReader, PdfWriter
+from pypdf.annotations import FreeText
+
+
+# Fills a PDF by adding text annotations defined in `fields.json`. See forms.md.
+
+
+def transform_coordinates(bbox, image_width, image_height, pdf_width, pdf_height):
+    """Transform bounding box from image coordinates to PDF coordinates"""
+    # Image coordinates: origin at top-left, y increases downward
+    # PDF coordinates: origin at bottom-left, y increases upward
+    x_scale = pdf_width / image_width
+    y_scale = pdf_height / image_height
+    
+    left = bbox[0] * x_scale
+    right = bbox[2] * x_scale
+    
+    # Flip Y coordinates for PDF
+    top = pdf_height - (bbox[1] * y_scale)
+    bottom = pdf_height - (bbox[3] * y_scale)
+    
+    return left, bottom, right, top
+
+
+def fill_pdf_form(input_pdf_path, fields_json_path, output_pdf_path):
+    """Fill the PDF form with data from fields.json"""
+    
+    # `fields.json` format described in forms.md.
+    with open(fields_json_path, "r") as f:
+        fields_data = json.load(f)
+    
+    # Open the PDF
+    reader = PdfReader(input_pdf_path)
+    writer = PdfWriter()
+    
+    # Copy all pages to writer
+    writer.append(reader)
+    
+    # Get PDF dimensions for each page
+    pdf_dimensions = {}
+    for i, page in enumerate(reader.pages):
+        mediabox = page.mediabox
+        pdf_dimensions[i + 1] = [mediabox.width, mediabox.height]
+    
+    # Process each form field
+    annotations = []
+    for field in fields_data["form_fields"]:
+        page_num = field["page_number"]
+        
+        # Get page dimensions and transform coordinates.
+        page_info = next(p for p in fields_data["pages"] if p["page_number"] == page_num)
+        image_width = page_info["image_width"]
+        image_height = page_info["image_height"]
+        pdf_width, pdf_height = pdf_dimensions[page_num]
+        
+        transformed_entry_box = transform_coordinates(
+            field["entry_bounding_box"],
+            image_width, image_height,
+            pdf_width, pdf_height
+        )
+        
+        # Skip empty fields
+        if "entry_text" not in field or "text" not in field["entry_text"]:
+            continue
+        entry_text = field["entry_text"]
+        text = entry_text["text"]
+        if not text:
+            continue
+        
+        font_name = entry_text.get("font", "Arial")
+        font_size = str(entry_text.get("font_size", 14)) + "pt"
+        font_color = entry_text.get("font_color", "000000")
+
+        # Font size/color seems to not work reliably across viewers:
+        # https://github.com/py-pdf/pypdf/issues/2084
+        annotation = FreeText(
+            text=text,
+            rect=transformed_entry_box,
+            font=font_name,
+            font_size=font_size,
+            font_color=font_color,
+            border_color=None,
+            background_color=None,
+        )
+        annotations.append(annotation)
+        # page_number is 0-based for pypdf
+        writer.add_annotation(page_number=page_num - 1, annotation=annotation)
+        
+    # Save the filled PDF
+    with open(output_pdf_path, "wb") as output:
+        writer.write(output)
+    
+    print(f"Successfully filled PDF form and saved to {output_pdf_path}")
+    print(f"Added {len(annotations)} text annotations")
+
+
+if __name__ == "__main__":
+    if len(sys.argv) != 4:
+        print("Usage: fill_pdf_form_with_annotations.py [input pdf] [fields.json] [output pdf]")
+        sys.exit(1)
+    input_pdf = sys.argv[1]
+    fields_json = sys.argv[2]
+    output_pdf = sys.argv[3]
+    
+    fill_pdf_form(input_pdf, fields_json, output_pdf)

package/templates/.claude/skills/pdf-processing/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: pdf-processing
+description: Production-ready PDF processing toolkit with forms, tables, OCR, validation, and batch operations. Supports extracting text/tables, creating/modifying PDFs, and handling complex forms.
+enabledByDefault: false
+---
+
+# PDF Processing
+
+Comprehensive PDF toolkit combining basic manipulation (merge/split/rotate) with advanced processing (forms, OCR, tables).
+
+## Quick Start
+
+### Basic Operations (pypdf)
+
+```python
+from pypdf import PdfReader, PdfWriter
+
+# Read & Extract Text
+reader = PdfReader("doc.pdf")
+text = reader.pages[0].extract_text()
+
+# Merge PDFs
+writer = PdfWriter()
+for path in ["a.pdf", "b.pdf"]:
+    reader = PdfReader(path)
+    for page in reader.pages:
+        writer.add_page(page)
+with open("merged.pdf", "wb") as f:
+    writer.write(f)
+```
+
+### Advanced Processing (Included Scripts)
+
+This skill includes production-ready scripts in `scripts/`:
+
+```bash
+# Analyze PDF form fields
+python scripts/analyze_form.py input.pdf --output fields.json
+
+# Fill PDF form with validation
+python scripts/fill_form.py input.pdf data.json output.pdf
+
+# Extract tables to CSV
+python scripts/extract_tables.py report.pdf --output tables.csv
+```
+
+## Features
+
+- **Forms:** Complete form processing (analyze, fill, validate)
+- **Tables:** Advanced extraction (multi-page, merged cells)
+- **OCR:** Process scanned documents (via Tesseract)
+- **Manipulation:** Merge, split, rotate, watermark, encrypt
+- **Validation:** Pre/post-processing checks
+
+## Tools & Libraries
+
+| Task | Recommended Tool |
+|------|------------------|
+| **Basic manipulation** | `pypdf` (Python) or `qpdf` (CLI) |
+| **Text/Table extraction** | `pdfplumber` |
+| **Form filling** | `pypdf` or included `fill_form.py` |
+| **OCR** | `pytesseract` + `pdf2image` |
+| **Generation** | `reportlab` |
+
+## Common Workflows
+
+### 1. Process Form Submissions
+```bash
+# 1. Analyze structure
+python scripts/analyze_form.py template.pdf --output schema.json
+
+# 2. Fill with data
+python scripts/fill_form.py template.pdf submission.json completed.pdf
+```
+
+### 2. Extract Data from Reports
+```bash
+# Extract tables to CSV
+python scripts/extract_tables.py monthly_report.pdf --output data.csv
+```
+
+### 3. OCR Scanned Documents
+```python
+import pytesseract
+from pdf2image import convert_from_path
+
+images = convert_from_path('scanned.pdf')
+text = pytesseract.image_to_string(images[0])
+```
+
+## Included Scripts
+
+- `analyze_form.py`: Extract form field info
+- `fill_form.py`: Fill forms with validation
+- `extract_tables.py`: Export tables to CSV/Excel
+- `extract_text.py`: Extract text preserving layout
+- `merge_pdfs.py`: Merge multiple files
+- `split_pdf.py`: Split into pages
+- `validate_pdf.py`: Check file integrity
+
+## Dependencies
+
+```bash
+pip install pdfplumber pypdf pillow pytesseract pandas reportlab
+```
+
+For OCR, install system tesseract (e.g., `brew install tesseract` or `apt-get install tesseract-ocr`).