Most creative applications have a “layer” notion. Usually, it’s represented in the user interface in a way similar to what is shown below.

Here we have a number of layers, and each layer has one object on it: three text lines, and 2 vector elements (rectangles) in total. Typically, these layers can now be switched on or off in the user interface, which makes the objects on them visible or invisible. In the screenshot above, everything is visible.

Layers and z-order

In most creative applications, the concept of layers is intimately tied to what is called “Z-order” or “painting order”, which is the order in which objects are painted on the canvas. So lower layers are painted first, higher layers are painted over lower layers. Moving all rectangle layers down, changes the design.

The rectangles are now at the bottom of the z-order, and the text is painted over them. The screenshots above are from Affinity Publisher, but the concept is the same in Adobe Photoshop, Adobe Illustrator, Adobe InDesign, QuarkXPress… you name it.

Layers in callas pdfToolbox

pdfToolbox also has something called layers:

There is a “Layer Explorer” window, that lets you see what layers came in from creative applications, and what layers were created in the PDF itself. Unfortunately, and the screenshot above already shows this, these are not really layers as you know them…

OCG

No, it’s not a curse, an “OCG” is an “Optional Content Group”. The PDF file format doesn’t really have the concept of a “layer” as such, it has an optional content group concept instead. OCGs are completely optional, your PDF files don’t need them at all. But they can be present to group certain elements on the page, and control their visibility.

What pdfToolbox calls “Layers” are really “Optional Content Groups” found in the PDF file. Why are they called layers? Well, it’s a familiar term first of all, and certainly easier than “optional content groups” or “OCGs” and secondly, most creative applications have an option to translate layers into OCGs when exporting PDF. So from a continuity and simplicity point of view, it kind of makes sense to call them layers in pdfToolbox.

Kind of. There be dragons!

OCGs and the “z-order”

The danger is that OCGs are radically different than layers in important ways. Most importantly, optional content groups have nothing to do with the “z-order”. In fact, the example screenshot from pdfToolbox above does something that isn’t possible in creative applications. It contains two ‘layers’:

• All text objects
• All vector objects

The “All text objects” layer contains all text objects and switching it off, hides all text objects from the PDF file. This isn’t possible in creative applications because these text objects aren’t together in the z-order!

Also, changing the “order” of these two layers in the PDF document (moving the “All vector objects” layer to the top, for example), does not affect how the PDF page is painted at all. Again, optional content groups in PDF are completely not linked to the z-order of the objects they contain.

Z-order in PDF

Is there no z-order concept in PDF? Of course, there is: objects on a page are drawn in a particular, well-defined order (in fact, the same order they are defined in the page description for a page). You can also move objects in the z-order in PDF. In pdfToolbox, you have the “Bring to front” fixup, for example:

This takes the specified objects and brings them to the front of the painting order (to the top of the z-order). The “Send to back” fixup does the inverse and moves them to the back.

These fixups are also very useful, as they allow, for example, to ensure that a cut contour (dieline) is drawn on top of all other objects in the file.

Conclusion

While pdfToolbox has a “Layer Explorer” and people often talk about layers in PDF documents, you should be very careful with that. PDF documents don’t really have a layer concept as you know it from your creative applications, and it’s dangerous to think about them like that.

Instead, PDF has the “Optional Content Group” or “OCG” concept that can be used to affect the visibility of page elements. While this is similar to what you can do in creative applications, the two concepts are still fundamentally different!

Oh, using OCGs, the PDF specification than also defines things such as “OCCD” and “OCMD” which allow even more complicated functionality. But that’s a story for another day!