Print-Ready Page Sizing Standards for GIS Reports

pip install weasyprint==62.3 reportlab==4.2.5 pypdf==4.3.1 cairosvg==2.7.1

# page_config.py
from typing import Final

# All dimensions in millimetres
PAGE_SIZES: Final[dict[str, tuple[float, float]]] = {
    "A4":      (210.0,  297.0),
    "A3":      (297.0,  420.0),
    "Letter":  (215.9,  279.4),
    "Tabloid": (279.4,  431.8),
    # Large-format GIS atlases
    "12x18":   (304.8,  457.2),
    "18x24":   (457.2,  609.6),
}

BLEED_MM: Final[float] = 3.0
SAFE_ZONE_MM: Final[float] = 6.0   # inward from trim line
MIN_DPI: Final[int] = 300


def validate_page_config(
    size_name: str,
    dpi: int,
    orientation: str = "portrait",
) -> tuple[float, float]:
    """
    Return (width_mm, height_mm) for the named size, flipped if landscape.
    Raises ValueError for unrecognised sizes or sub-300 DPI.
    """
    if size_name not in PAGE_SIZES:
        raise ValueError(
            f"Unrecognised page size '{size_name}'. "
            f"Use one of: {list(PAGE_SIZES)}"
        )
    if dpi < MIN_DPI:
        raise ValueError(
            f"Raster DPI {dpi} is below the 300 DPI pre-press minimum."
        )
    w, h = PAGE_SIZES[size_name]
    return (h, w) if orientation == "landscape" else (w, h)

/* report-layout.css — WeasyPrint @page rules */
@page {
  size: A4 portrait;          /* or pass dynamically from Python */
  margin: 15mm 12mm 20mm 15mm; /* top right bottom left */

  @bottom-center {
    content: "Page " counter(page) " of " counter(pages);
    font-size: 8.5pt;
    color: #555;
  }

  @top-right {
    content: string(report-title);
    font-size: 8pt;
    color: #666;
  }
}

/* Map frames extend to the bleed edge; text stays in the safe zone */
.map-frame {
  /* extend 3 mm beyond content area to fill bleed on all sides */
  margin: -3mm;
  padding: 0;
}

.map-annotation,
.scale-bar,
.north-arrow {
  /* keep critical symbology 6 mm inward from trim */
  margin: 9mm;  /* 3 mm bleed + 6 mm safe zone */
}

import weasyprint
from pathlib import Path
from page_config import validate_page_config, BLEED_MM


def render_report(
    html_path: Path,
    output_path: Path,
    size_name: str = "A4",
    dpi: int = 300,
    orientation: str = "portrait",
) -> None:
    width_mm, height_mm = validate_page_config(size_name, dpi, orientation)

    # WeasyPrint reads bleed from the PDF metadata box; set via presentational hints
    doc = weasyprint.HTML(filename=str(html_path))
    pdf_bytes = doc.write_pdf(
        presentational_hints=True,
        # WeasyPrint 62+ exposes the media_type param for @page targeting
        uncompressed_pdf=False,
    )
    output_path.write_bytes(pdf_bytes)
    print(f"Rendered {output_path.name} at {width_mm}×{height_mm} mm, {dpi} DPI")

from PIL import Image
from pathlib import Path


def audit_raster_resolution(
    image_path: Path,
    target_print_width_mm: float,
    min_dpi: int = 300,
) -> None:
    """
    Confirm a raster tile is dense enough for the target print width.
    Raises ValueError if pixel density is below min_dpi at print size.
    """
    with Image.open(image_path) as img:
        pixel_width = img.width
        # Convert target print width from mm to inches, then compute effective DPI
        target_width_in = target_print_width_mm / 25.4
        effective_dpi = pixel_width / target_width_in

        if effective_dpi < min_dpi:
            raise ValueError(
                f"{image_path.name}: effective DPI {effective_dpi:.0f} at "
                f"{target_print_width_mm} mm print width is below {min_dpi} DPI. "
                "Re-export from GIS at native print resolution."
            )
        print(
            f"{image_path.name}: {effective_dpi:.0f} DPI at "
            f"{target_print_width_mm} mm — OK"
        )

/* Minimum sizes for spatial annotations at print */
.map-title       { font-size: 15pt; font-weight: 700; }
.section-heading { font-size: 12pt; font-weight: 600; }
.coordinate-label,
.axis-label      { font-size: 9.5pt; }
.legend-entry    { font-size: 8.5pt; }
.scale-text      { font-size: 8pt; }
.footnote        { font-size: 7.5pt; }  /* absolute floor */

# preflight.py — run in CI after each render batch
import subprocess
import sys
from pathlib import Path


def run_verapdf_check(pdf_path: Path, flavour: str = "2b") -> bool:
    """
    Validate PDF/A conformance via veraPDF.
    Returns True if conformant, False otherwise.
    PDF/X-4 requires a commercial preflight tool (e.g. Callas pdfToolbox).
    """
    result = subprocess.run(
        ["verapdf", f"--flavour", flavour, "--format", "text", str(pdf_path)],
        capture_output=True,
        text=True,
    )
    passed = "PASS" in result.stdout
    if not passed:
        print(f"FAIL  {pdf_path.name}\n{result.stdout}", file=sys.stderr)
    return passed


def audit_embedded_fonts(pdf_path: Path) -> list[str]:
    """Return names of any non-embedded fonts (must be empty for print delivery)."""
    from pypdf import PdfReader

    reader = PdfReader(str(pdf_path))
    unembedded: list[str] = []
    for page in reader.pages:
        resources = page.get("/Resources", {})
        fonts = resources.get("/Font", {})
        for font_ref in fonts.values():
            font_obj = font_ref.get_object()
            descriptor = font_obj.get("/FontDescriptor")
            if descriptor:
                fd = descriptor.get_object()
                if not (fd.get("/FontFile") or fd.get("/FontFile2") or fd.get("/FontFile3")):
                    unembedded.append(font_obj.get("/BaseFont", "unknown"))
    return unembedded

#!/usr/bin/env python3
"""
generate_print_pdf.py — production batch renderer for GIS reports.

Usage:
    python generate_print_pdf.py --html report.html --out report.pdf \
        --size A4 --dpi 300 --orientation portrait
"""
import argparse
import logging
import sys
from pathlib import Path

import weasyprint

from page_config import validate_page_config
from preflight import audit_embedded_fonts, run_verapdf_check

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s  %(levelname)-7s  %(message)s",
    datefmt="%H:%M:%S",
)
log = logging.getLogger(__name__)


def build_pdf(
    html_path: Path,
    output_path: Path,
    size_name: str,
    dpi: int,
    orientation: str,
) -> int:
    """Return 0 on success, 1 on any validation failure."""
    # 1. Validate dimensions before any I/O
    try:
        w_mm, h_mm = validate_page_config(size_name, dpi, orientation)
    except ValueError as exc:
        log.error("Dimension validation failed: %s", exc)
        return 1

    log.info("Rendering %s → %s  (%g×%g mm, %s, %d DPI)",
             html_path.name, output_path.name, w_mm, h_mm, orientation, dpi)

    # 2. Render
    try:
        doc = weasyprint.HTML(filename=str(html_path))
        doc.write_pdf(target=str(output_path), presentational_hints=True)
    except Exception as exc:
        log.error("Render failed: %s", exc)
        return 1

    # 3. Preflight: font embedding
    unembedded = audit_embedded_fonts(output_path)
    if unembedded:
        log.error("Non-embedded fonts detected: %s", unembedded)
        return 1

    # 4. Preflight: PDF/A conformance (PDF/X-4 requires Callas or similar)
    if not run_verapdf_check(output_path):
        log.error("PDF/A conformance check failed — see stderr above.")
        return 1

    log.info("Preflight passed. Output: %s", output_path)
    return 0


if __name__ == "__main__":
    parser = argparse.ArgumentParser(description="Render a print-ready GIS report PDF.")
    parser.add_argument("--html", required=True, type=Path)
    parser.add_argument("--out", required=True, type=Path)
    parser.add_argument("--size", default="A4", choices=["A4", "A3", "Letter", "Tabloid", "12x18", "18x24"])
    parser.add_argument("--dpi", type=int, default=300)
    parser.add_argument("--orientation", default="portrait", choices=["portrait", "landscape"])
    args = parser.parse_args()

    sys.exit(build_pdf(args.html, args.out, args.size, args.dpi, args.orientation))

@page portrait-page  { size: A4 portrait;  margin: 15mm; }
@page landscape-page { size: A4 landscape; margin: 12mm; }

.portrait-section  { page: portrait-page; }
.landscape-section { page: landscape-page; }

FROM python:3.12-slim
RUN apt-get update && apt-get install -y \
    libcairo2 libpango-1.0-0 libpangocairo-1.0-0 \
    libgdk-pixbuf-2.0-0 libffi-dev shared-mime-info \
    && rm -rf /var/lib/apt/lists/*