Flattening Transparency for PDF/X-4 Compliance

PDF/X-4 permits live transparency, so the correct default for print map exports is to keep transparency live and let the RIP composite it — flatten only when a specific downstream RIP rejects transparency groups, and when you do flatten, declare an explicit blend color space so live and flattened regions composite to the same color. This is the single most important difference from PDF/X-1a, which forbids transparency entirely and forces you to flatten every semi-transparent hillshade, glow, and layer blend before export.

Core Algorithm and Workflow

A cartographic PDF is rarely opaque. Terrain hillshades sit at partial alpha over landcover, water gets a soft multiply, and label halos rely on knockout groups. Under PDF/X-1a (ISO 15930-1) none of that survives: every transparent construct must collapse into opaque geometry before the file conforms. PDF/X-4 (ISO 15930-7) changes the rule — transparency groups, blend modes, and optional-content layers are all legal — so the decision is no longer “how do I flatten” but “should I flatten at all”.

The answer-first workflow is a decision, not a pipeline stage. Keep transparency live by default. Flatten only at a proven constraint. When you flatten, pin the blend color space so no color shift appears at the boundary between the flattened atoms and the rest of the page.

1. Prefer live transparency. Export the map with alpha and blend modes intact. A conformant PDF/X-4 file declares an OutputIntent (the target ICC profile) and may contain transparency groups; the RIP composites them at raster time against that profile.
2. Declare the blend color space. Every transparency group has a blend color space that governs the arithmetic of compositing. Set it explicitly to an ICC-based or DeviceN CMYK space that matches your OutputIntent. If you leave it unset it inherits the current device space, and semi-transparent RGB fills blended in the wrong space shift hue.
3. Flatten only at a proven constraint. Some legacy RIPs and older imagesetters cannot interpret transparency groups. Only then flatten — and flatten at the export DPI, holding the same blend space so the flattened atoms match the live regions they replace.
4. Preflight. Validate conformance with veraPDF’s PDF/X-4 profile and inspect the structure (OutputIntent, blend space, overprint keys) with Ghostscript before the file leaves your pipeline.

This decision sits on top of the vector export mechanics covered in High-Resolution Vector Export, and the blend space you choose must agree with the target profile discussed under Color Profile and CMYK Conversion.

Production-Ready Python Implementation

The script below drives the whole decision from Python. It shells out to Ghostscript for structural inspection and controlled flattening, and to veraPDF for conformance, because both are the reference implementations for their jobs. It never flattens unless require_opaque is set, honouring the answer-first default of keeping transparency live under PDF/X-4.

"""PDF/X-4 transparency handling and preflight.

Requires:
    Ghostscript >= 10.02   (gs on PATH)
    veraPDF      >= 1.26    (verapdf on PATH)
Both are external CLIs; this module orchestrates them.
"""
from __future__ import annotations

import json
import shutil
import subprocess
from pathlib import Path


class PreflightError(RuntimeError):
    """Raised when a required tool is missing or a PDF fails conformance."""


def _require(tool: str) -> str:
    path = shutil.which(tool)
    if path is None:
        raise PreflightError(f"{tool!r} not found on PATH")
    return path


def flatten_transparency(
    src: Path,
    dst: Path,
    dpi: int = 300,
    blend_icc: Path | None = None,
) -> Path:
    """Flatten transparency with Ghostscript at ``dpi``.

    Only call this when a downstream RIP rejects live transparency.
    ``blend_icc`` pins the transparency blend color space to the same
    ICC CMYK profile as the OutputIntent so no color shift appears at the
    flattened boundary. Omitting it lets Ghostscript fall back to the
    device space — the classic cause of hue drift in flattened maps.
    """
    gs = _require("gs")
    args = [
        gs,
        "-dBATCH",
        "-dNOPAUSE",
        "-dSAFER",
        "-sDEVICE=pdfwrite",
        "-dPDFX=true",
        "-dCompatibilityLevel=1.6",       # PDF/X-4 rides on PDF 1.6
        f"-r{dpi}",
        "-dHaveTransparency=false",       # force the flattener on
        f"-sOutputFile={dst}",
    ]
    if blend_icc is not None:
        # Composite in the OutputIntent space, not the device space.
        args.append(f"-sDefaultCMYKProfile={blend_icc}")
        args.append("-dOverrideICC=true")
    args.append(str(src))

    proc = subprocess.run(args, capture_output=True, text=True)
    if proc.returncode != 0 or not dst.exists():
        raise PreflightError(f"Ghostscript flatten failed:\n{proc.stderr}")
    return dst


def validate_pdfx4(pdf: Path) -> dict:
    """Validate against the PDF/X-4 profile with veraPDF.

    Returns the parsed JSON report. Raises PreflightError on non-conformance
    so the call can gate a CI build.
    """
    verapdf = _require("verapdf")
    proc = subprocess.run(
        [verapdf, "--flavour", "4", "--format", "json", str(pdf)],
        capture_output=True,
        text=True,
    )
    # veraPDF exits non-zero on invalid PDFs; parse the report regardless.
    try:
        report = json.loads(proc.stdout)
    except json.JSONDecodeError as exc:
        raise PreflightError(f"veraPDF produced no JSON:\n{proc.stderr}") from exc

    jobs = report["report"]["jobs"]
    compliant = all(
        j["validationResult"][0]["compliant"]
        for j in jobs
        if j.get("validationResult")
    )
    if not compliant:
        raise PreflightError(f"{pdf.name} is not PDF/X-4 conformant")
    return report


def inspect_structure(pdf: Path) -> str:
    """Dump OutputIntent, transparency, and overprint keys via Ghostscript.

    A cheap structural read that answers 'is transparency still live?' and
    'is an OutputIntent present?' without a full render.
    """
    gs = _require("gs")
    proc = subprocess.run(
        [
            gs, "-dBATCH", "-dNOPAUSE", "-dSAFER",
            "-sDEVICE=inkcov",            # per-page ink coverage = separations sanity check
            "-o", "-",
            str(pdf),
        ],
        capture_output=True,
        text=True,
    )
    return proc.stdout


def prepare_for_press(
    src: Path,
    out_dir: Path,
    require_opaque: bool = False,
    dpi: int = 300,
    blend_icc: Path | None = None,
) -> Path:
    """End-to-end: keep transparency live unless a RIP needs it flattened,
    then preflight. Returns the path to the validated, press-ready PDF.
    """
    out_dir.mkdir(parents=True, exist_ok=True)

    if require_opaque:
        target = out_dir / f"{src.stem}_flat.pdf"
        flatten_transparency(src, target, dpi=dpi, blend_icc=blend_icc)
    else:
        # Default X-4 path: transparency stays live, file is copied as-is.
        target = out_dir / src.name
        target.write_bytes(src.read_bytes())

    validate_pdfx4(target)              # gate: raises on non-conformance
    print(inspect_structure(target))    # human-readable separations check
    return target


# ---------------------------------------------------------------------------
# Example usage
# ---------------------------------------------------------------------------
# ready = prepare_for_press(
#     src=Path("exports/atlas_sheet_07.pdf"),
#     out_dir=Path("press"),
#     require_opaque=False,               # keep transparency live (X-4 default)
#     dpi=300,
#     blend_icc=Path("profiles/FOGRA39.icc"),
# )
# print("Press-ready:", ready)

Performance Tuning and Cartographic Best Practices

• Keep transparency live unless you have a rejection in hand. Live transparency renders sharper (the RIP composites at device resolution) and produces smaller files than a flattener, which fractures overlapping regions into many small opaque atoms. Do not pre-flatten “to be safe” — under PDF/X-4 that is a regression, not a precaution.
• Match the blend color space to the OutputIntent. The transparency group blend space and the file’s OutputIntent ICC profile should be the same CMYK space (for example FOGRA39 or GRACoL). When they disagree, semi-transparent hillshades composite in one space and are proofed in another, and the map darkens or shifts hue exactly along the transparent edges. This is the same profile discipline described in Color Profile and CMYK Conversion.
• Resolve overprint before flattening, not after. Overprint and transparency are composited together. A flattener bakes overprinting objects into opaque atoms, which can silently defeat an intended knockout or lock in an overprint that was only a preview. Run a separations preview first, decide the overprint behaviour, then flatten.
• Flatten at the export DPI, never below it. The flattener rasterises the parts of the page it cannot keep as vectors. If Ghostscript’s -r is lower than your target device resolution, those rasterised atoms are visibly soft against the still-vector geometry around them. Align the flatten resolution with the strategy in DPI and Resolution Management.
• Gate the build on veraPDF, inspect with Ghostscript. Treat veraPDF’s PDF/X-4 profile as a pass/fail CI gate and Ghostscript’s inkcov / structural output as the diagnostic you read when the gate fails. One answers “is it conformant”, the other answers “why not”.

Integration and Next Steps

prepare_for_press is renderer-agnostic: it accepts any PDF your export stage produces — a Matplotlib savefig to PDF, a QGIS layout export, or a Cairo surface — and applies the transparency decision plus preflight uniformly.

• Batch pipelines. Call prepare_for_press per map sheet inside your generation loop; because it flattens only on demand, most sheets pass straight through to the veraPDF gate with transparency live.
• CI enforcement. Because validate_pdfx4 raises on non-conformance, drop it into a pytest check or a pre-publish step so a non-conformant sheet fails the build rather than reaching the press.
• Web-facing variants. When the same map also ships as a lightweight vector for the browser, the transparency and atom-count trade-offs shift entirely — that path is covered in Optimizing SVG File Size for Web Map Delivery.

Store the validated PDFs and the veraPDF JSON reports as build artefacts so any press query can be answered from the conformance record rather than re-run by hand.

Frequently Asked Questions

Does PDF/X-4 require me to flatten transparency?

No. PDF/X-4 (ISO 15930-7) is the first PDF/X part that permits live transparency, blend modes, and optional-content layers. PDF/X-1a (ISO 15930-1) forbids them and forces flattening. Under X-4 the correct default is to keep transparency live and flatten only when a specific downstream RIP cannot process transparency groups.

Why do my transparent map layers shift color when flattened?

Compositing is performed in the transparency group’s blend color space. If you never declared one, the compositor uses the current device space, and blending semi-transparent RGB fills in an unexpected space produces a hue shift along the flattened boundaries. Declare an explicit ICC-based or DeviceN CMYK blend space that matches your OutputIntent so live and flattened regions composite identically.

How does overprint interact with transparency during flattening?

They are resolved together during composition. A flattener converts overprinting objects into opaque atoms, which can defeat an intended knockout or bake in an overprint that was only meant as a screen preview. Decide overprint behaviour and confirm it with a separations preview before flattening, so the resulting atoms match press behaviour.

Which tools validate PDF/X-4 conformance automatically?

veraPDF ships a PDF/X-4 validation profile and returns machine-readable JSON suitable for CI gating. Ghostscript complements it — it reports the OutputIntent and ink coverage, renders separations, and performs the flattening itself when a RIP requires it. Use veraPDF for conformance and Ghostscript for structural inspection and controlled flattening.

Related

• High-Resolution Vector Export — the parent overview covering vector export mechanics that this transparency decision sits on top of.
• Optimizing SVG File Size for Web Map Delivery — the web-facing counterpart where transparency and atom-count trade-offs run the opposite direction.
• Color Profile and CMYK Conversion — the ICC profile discipline that your transparency blend color space must agree with.

Back to High-Resolution Vector Export