Distribute form XObjects on layers

Form XObjects in a PDF are used to encapsulate page content. That is useful e.g. to import new content such as a stamp that is placed on a page, in imposition when pages are placed on a sheet, to group objects together for transparency or to reuse the same content several times. The last  use case has a lot to do with variable data print: If static (reused) content is in a form XObject that is referenced whenever used the output engine (RIP, DFE) can process it once and reuse it for rendering (caching) which means that it will run much faster. If that is, however, not the case that can slow down the output significantly. If caching works smoothly the first instance of a page needs as long as it needs to process it, corresponding later pages are processed much faster. However, even if reused content is in a form XObject it may not be possible to cache it, e.g. when it interacts with other content via transparency.

In order to analyze whether a VDP PDF may have caching issues a tool that allows you to visualize the form XObject structure in a PDF would be helpful and it would be even better if it would be possible to modify it.

Distribute form XObjects on layers

In pdfToolbox you can use layers to visualize the form XObject structure in a PDF. There are three ways to access this feature:

Layer Explorer


The Layer Explorer an be found in the Tools menu. If a PDF is opened that does not already have layers it shows an item "Enumerate XObjects" that then opens the:

Enumerate XObjects action in the Switchboard (group Layers)


If you click on "Execute" the form XObjects of the current PDF are distributed onto new layers and the Layer Explorer is opened.

"Distribute form XObjects on layers" Quick Fix

If you want to distribute form XObjects onto layers with pdfToolbox CLI, SDK or server you can use the Quick Fix with this name.

Investigate a form XObject structure in Layer Explorer

Let us use an example PDF with 10 pages. This PDF has been derived from the PDF/VT sample files.

After you have distributed the form XObjects in this PDF on layers the Layer Explorer will look like this:


The layer structure visualizes the form XObject structure

The PDF has now 8 new layers.

In the PDF red rectangles indicate the position of the form XObjects. These red indicators all belong to the new layer "Form XObject BBoxes". A red rectangle is only visible if this layer is visible and the respective form XObject that it belongs to is visible too.

The other new layers tell you something via their names: The name starts with an index number. It also indicates on how many pages it is (re)used and if it has child layers how many that are.

Form XObject can contain other form XObjects thereby creating a hierarchy and the layers are created in a structure that corresponds to that hierarchy.

A child layer is only visible if all of its parent layers are visible.


If you switch the layer "01-formX on 10 pages, children:1" off you see that there is an additional, little smaller layout completely covered by the visible objects. Apparently a left over from the designer?


The output RIP will still have to process it which will slow down rendering. In our not very complex 10 page PDF that is not a big deal, but that may be different in a PDF with ten thousand pages and if they e.g. use transparency.

In any case would it be good to remove or disable the hidden content.

Optimizing a PDF for rendering in the RIP

You could now remove the hidden XObject by selecting it in the Layer Explorer and clicking  on the red "-" symbol.


You will see a dialogue that allows you to remove it with its content.

This approach works fine, but would in a "real" VDP file with thousands of references to this form XObject have an important downside: All content streams that reference it will have to be modified and that may take very long.

A smarter way is to make this hidden layer initially invisible which means that a RIP will (normally) ignore it. You can modify the initial visibility by switching all layers off that should be invisible and then use the "Save visibility" button at the bottom of the Layer Explorer.


This will just bring up an additional, explanatory dialogue (that you may disable for the future once understood) and you can then save the modified result. Since only parameter has to be modified for the layer that will be a very quick operation.