BASALT · JOURNAL

Hidden layers in a PDF, and why switching one off is not removing it

2026-08-06 · pdf layers

PDF layers are not layers in the image editing sense. They are optional content groups: a visibility switch applied to marks that are already in the page's content stream. Turning a group off changes what a viewer draws and changes nothing about what the file contains.

That distinction is the whole problem. A document can look correct on screen, print correctly, and still hand over draft language or an earlier version of a figure to the first person who runs text extraction on it.

How optional content is structured

The document catalog carries an /OCProperties dictionary. It lists every optional content group under /OCGs and holds configuration dictionaries: a default configuration under /D and any alternates under /Configs. A configuration says which groups start on and which start off, using /ON and /OFF arrays plus a /BaseState.

Each group is an object with a /Name, which is what appears in a viewer's layers panel, and optional usage information describing intent, for example that a group should be visible on screen but not in print.

Membership works two ways. Content inside a page's stream can be bracketed by BDC and EMC marked content operators referencing the group, making those drawing operations conditional. Alternatively an entire XObject or annotation can carry an /OC entry naming the group. In both cases the operators and objects are unconditionally present in the file. Only the drawing is conditional.

Off means invisible, not absent

This is the point that matters more than anything else here.

An optional content group that is switched off renders nowhere. It does not appear on screen, it does not appear in print, it does not appear in a rendered image of the page, and it does not appear in a rendering-based visual comparison of two documents.

Its text still extracts. Copy and paste, pdftotext, an e-discovery processing pipeline, a search index, a screen reader: all of these read the content stream rather than the rendered output, and most do not evaluate optional content state at all. The words come out in reading order alongside the visible text. The same is true of an image assigned to a hidden group, which remains a stream in the file, extractable by any tool that walks objects.

So switching a layer off is a display setting, not a removal. It is the visual equivalent of drawing a black box over text, which also leaves the words in the file, except worse in one respect: a black box is at least visible to a reviewer looking at the page. A hidden layer is visible to nobody.

Where hidden layers come from

Nobody sets out to ship a document with a concealed layer. They arrive through normal production.

CAD and engineering exports carry the source drawing's layer structure, which routinely includes dimension sets, revision clouds, contractor notes, and superseded geometry, so a drawing exported for a client can contain the internal markup layer with its default state off. Design files behave the same way: a proof from a layout tool can carry alternate headlines, unapproved pricing, notes to the designer, and the figure that was replaced last week.

Template-driven documents use optional content to switch between variants: one jurisdiction's language and another's, a draft watermark turned off before sending. All variants remain in the file; only the switch changes. Some workflows even do this deliberately for redaction, putting the sensitive material on a layer and turning the layer off, which produces a document that looks redacted and is not.

Detecting layers in a file you received

A viewer with a layers panel will show you the groups a document declares, which is the fast check. It is not complete, because a configuration can be built so a group does not appear in the panel, and a viewer without a layers panel gives you nothing.

The direct check is to expand the document with qpdf --qdf --object-streams=disable and look for /OCProperties in the catalog, then read the /OCGs array and the /D configuration's /ON and /OFF entries. That tells you how many groups exist, what they are named, and which start off.

The useful follow-up is comparing what you can see against what extracts. Run pdftotext and read the output next to the rendered pages. Text that appears in the extraction but nowhere on the page is either in a switched-off group, drawn in rendering mode 3, or covered by an opaque graphic, and the technique is the one described in how to check whether a PDF was really redacted.

Removing a layer for real

Getting rid of a hidden layer means removing its content, not changing its state. There are two honest ways.

The first is to delete the marked content sections referencing the group, along with any XObjects and annotations carrying an /OC entry naming it, then remove the group from /OCProperties and rewrite the file so orphaned objects are dropped. Done correctly, nothing extracts because the operators are gone.

The second is to flatten the document to its visible state: resolve every group according to the current configuration, keep what is on, discard what is off, and remove /OCProperties entirely. You lose the ability to toggle anything, which is usually the point when a file is going out.

Either way the result has to be written as a single generation, because incremental updates append changes while leaving the original bytes in place, so a layer removal saved as an increment leaves the layer recoverable in the previous revision. And removing a layer touches nothing else: metadata, embedded files, OCR text, and bookmark titles are separate structures with separate removal steps. How to see everything a PDF is actually carrying covers the rest of that pass.