Flatten PDF

What gets burned in, and what is spared on purpose

Every annotation in a PDF already carries a picture of itself — its appearance stream — which is what a reader draws. Flattening takes that picture, draws it into the page's own content, and then removes the annotation, so the mark stops being a thing sitting on the page and becomes part of the page. The placement is the fiddly part and it is done by the specification's own rule: the appearance box is put through the stream's matrix, the transformed corners are fitted to the annotation rectangle, and the result is scaled to match. Skipping that step is why naive flattening puts signatures at the wrong size and stamps slightly off where they were — it is the single most common bug in this operation.

Three kinds of annotation are deliberately spared. Links are kept as links, because they have no appearance to burn and turning a working table of contents into inert ink while "flattening comments" would be vandalism rather than a feature. Anything flagged hidden or no-view is skipped entirely, since burning it in would make content appear that the author chose to conceal. And an annotation with no stored appearance at all is left alone, because there is nothing to draw — a reader generates those on the fly, and inventing one here would mean guessing at a font and a border the author never specified.

A checkbox or radio button stores several appearances and a note of which state is current, so the one actually in use is the one burned in — a ticked box stays ticked, an unticked one leaves nothing behind. Form fields go through the form machinery rather than this path, and a malformed form dictionary is caught and skipped rather than being allowed to lose the comment flattening as well. The saved file uses object streams, so it is usually a little smaller than the one you started with even though content has been added to it.

When you want something else

A cryptographically signed document must not be flattened here, and not because of a shortcoming: rewriting page content is precisely what a digital signature exists to detect, so the result will correctly report as tampered. If a signed file needs its fields locked, that is a different operation — setting the field flags read-only rather than burning them in — and qpdf --json-input or a small pikepdf script does it without touching a single content stream.

For flattening at volume, or for forms whose appearances were never generated because the document asked the reader to do it, pdftk in.pdf output out.pdf flatten and Ghostscript's gs -dPreserveAnnots=false -sDEVICE=pdfwrite -o out.pdf in.pdf both render through a full interpreter that will generate a missing appearance instead of leaving the field alone. Ghostscript flattens links along with everything else, which is a trade rather than an improvement.