Module: app.pdf_fill

Overlay-based TRAQ PDF rendering utilities.

Authors:

Roger Erismann (https://hammerdirt.solutions), OpenAI Codex

Purpose:

Render TRAQ form values into the PDF template using visual overlay geometry (traq_full_map.json) rather than AcroForm field names.

Backstory / rationale:

The available TRAQ template has incomplete/inconsistent AcroForm metadata. Runtime filling therefore uses explicit box coordinates from the overlay mapping pipeline (app/traq_2_schema/*) to ensure every visual field can be addressed deterministically.

Coordinate system contract:

  • Mapping stores template-space pixels: bbox_px = [x0, y0, x1, y1]

  • Origin is top-left of the rendered overlay template

  • This module scales/transforms those coordinates into PDF page points before drawing text/check marks.

References

  • app/traq_2_schema/traq_full_map.json

  • app/traq_2_schema/build_traq_full_map.py

  • references/overlay_readme.md

app.pdf_fill.extract_pdf_field_values(pdf_path)[source]

Extract AcroForm values from a PDF for diagnostics/testing.

This is a helper for inspection only. Runtime filling is overlay-based.

Parameters:

pdf_path (Path)

Return type:

dict[str, str]

app.pdf_fill.generate_traq_pdf(*, form_data, output_path, template_path=None, flatten=False)[source]

Generate filled TRAQ PDF using overlay mapping for all pages.

Parameters:

  • form_data (dict[str, Any]) – Final/draft form payload. Supports top-level data or wrapped {“data”: …} payload shape.

  • output_path (Path) – Output PDF path.

  • template_path (Path | None) – Optional TRAQ template path override.

  • flatten (bool) – Reserved compatibility parameter (current path is overlay-only).

Return type:

None