Module: app.traq_2_schema.build_traq_full_map

Build the canonical TRAQ overlay mapping used at runtime.

Authors:

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

Purpose:

Compiles the page-level visual overlay templates and the human-curated mapping specs (mapone.md, maptwo.md) into one canonical traq_full_map.json used by app/pdf_fill.py.

Backstory / design rationale:

The TRAQ PDF copy used in this project has incomplete/inconsistent AcroForm fields. To avoid silent placement gaps, the runtime fill path is based on visual overlay boxes (pixel coordinates) rather than AcroForm names. This builder is the bridge from: - visual geometry (overlay JSONs with box IDs + bounding boxes), and - semantic mapping (markdown files mapping box IDs to JSON paths/types) into a single runtime map.

Coordinate system:

  • bbox_px values are template-render pixel coordinates from overlay JSON.

  • Origin is top-left of the rendered template page.

  • Values are stored as [x0, y0, x1, y1] in that same pixel space.

  • Downstream rendering (pdf_fill.py) scales these into PDF points per page.

References

  • references/overlay_readme.md

  • references/docs/IMPLEMENTATION_PLAN_2026-02-11.md

  • app/traq_2_schema/overlay_page1.json

  • app/traq_2_schema/overlay_page2.json

  • app/traq_2_schema/mapone.md

  • app/traq_2_schema/maptwo.md

app.traq_2_schema.build_traq_full_map.main()[source]

Build and write the canonical merged TRAQ overlay map.

Flow:

  1. Read page overlay geometry JSON files.

  2. Parse semantic mappings from mapone.md and maptwo.md.

  3. Join rows by box_id to attach bbox_px.

  4. Emit merged payload with page metadata and missing-ID diagnostics.

Return type:

None