How To Articles
by Thom Parker of WindJack Solutions.
by WindJack Solutions
Creating OCG(Layers) with Acrobat
6.0 and PDFCanOpener
Acrobat has a tool that creates OCGs, but they don't make
it obvious. PDF
CanOpener can make these layers usable to you.
September 14th, 2004 - At the PDF Conference in Baltimore MD
Leonard Rosenthol gave a seminar on PDF's OCG(Optional Content
Group) feature, more commonly referred to as "Layers" because they are exposed to
the user in the Layers
Palette. Layers are a way of controlling the visibility of
elements on a page. Two classic examples given
in such seminars are a map where greater detail is displayed as
the zoom level increases, and a document where the text is
changed from English to French with a single click. Many applications
that create or convert to PDF output use this feature, yet Acrobat doesn't contain a single tool or command for
specifically creating Layers.
In this seminar Leonard showed that despite the fact that Adobe does not
advertise it, Acrobat 6.0 does in fact have a built-in tool that
creates layers to assist in its operation, but hides them from
the user. The Great Sage showed how PDF CanOpener
can modify a PDF Document to make this OCG visible on the Layers Palette
and therefore available for manipulation by the user.
How It's Done:
The tool in question is the Watermarks and Background tool
accessed from the "Documents" menu.
Selecting this menu item brings up the Watermarks and Background
dialog. This dialog will only accept a PDF file as input.
For testing purposes an easy place to find a good PDF is in the "Stamps" folder,
For this example we'll start with a blank single page
document (figure 1). Then add a Background (figure 2). The Cos Object Tree for the PDF file, as displayed by PDF CanOpener,
is shown below.
(figure 1: Blank 1 page PDF)
(figure 2: After Watermark Applied)
A new entry has been added to the Document catalog
that wasn't there before, "OCProperties". This dictionary
contains everything you need to know about an OCG Layer except
which visual elements it's applied to.
The OCG itself is intended only to calculate an
On or Off value that represents the OCG State. This value
can be calculated from a number of different parameters like
the document's zoom level, the current user, and whether the
document is being printed or displayed in the viewer.
Exactly which parameters are used to calculate a particular OCG
State are set within the OCG dictionary and the "D" entry of the
OCProperties. The OCG State can also be forced by the user from the Layers Palette
When Acrobat creates the background or watermark
it sets the OCG state to constant On or Off depending on how the
"Show when displaying on screen" and "Show when printing" check
boxes were set in the dialog box, and then deprives the user of
any control over these states. To find out how it does
this we need to examine the "OCProperties" dictionary.
The Object tree shown above the OCProperties
dictionary has 2 entries. The "OCGs" entry is an
array object. It lists all the OCGs defined for this document.
The "D" entry is a dictionary object. In the PDF Specification the "D" entry is called the
"Default Viewing Optional Content Configuration Dictionary."
Quite a mouthful. All the setup information on the OCGs is stored here.
Only a few of the possible
setup parameters are shown in figure 2.
For our purposes there are only two important
entries in "D", "Order" and "On". The "On"
entry is an array of OCG dictionaries. Each OCG placed in this
array will be set to the "On" state when the document is
loaded by Acrobat. Being listed here overrides any other
defaults that may have been set for the OCG.
array is also a list of OCG dictionaries. Each OCG placed
here is displayed in the Layers Palette. The order of entries in
the array matches the order of entries in the Layer Palette.
Our newly created OCG is listed in the "On"
array, but not in the "Order" Array. To make it visible in
the layers palette all we have to do is put it in the "Order"
Array. The OCG dictionary is an indirect object so we
won't be copying the entire object into this array, only a
reference to it. PDF CanOpener provides two methods to let
us do this: Explicit indirect reference creation, and
Method #1, Explicit Indirect Reference
- Select the OCG dictionary in the Object Tree Display (see
figure below). Note the Indirect Object Reference ID. In
the figure it's 20. We'll need this number for step 3.
(figure 3: PDF CanOpener Context Menu and Display)
Right click on the "Order" array and select
"Add..." from the context menu to bring up the "Add
Array Element" Dialog.
Select "Object Reference" from the
Type pull down, then enter the Object Reference ID from step 1 into
the "Object ID#" box.
(figure 4: Add New Element Dialog)
Click Ok and you're done.
Method #2, Object Copy.
Right click on the OCG Dictionary(see figure 1)
and select the "Copy CosObj" option. The OCG
Dictionary is now copied to the PDF CanOpener clipboard.
Right click on the "Order" array and select
"Paste CosObj". The Copy Options Dialog will
Indirect References Intact" and click OK.
(figure 5: CosObj Copy Dialog)
The Set Array Dialog will appear, just click OK.
(figure 6: Element Position Dialog)
Because we are changing a document level
property Acrobat needs to rescan the PDF. So save the
document, close it, then reopen it. Now you will be able
to see the "Background" layer on the Layers Palette.
"Background" is the name that Acrobat automatically gives this
Click on the layer name in the palette to toggle it on and off.
You should see the background image turn on and off as well.
Creating Multiple Backgrounds and Watermarks
Acrobat limits you to creating only one
Watermark or Background. If you use this tool a second
time, it overwrites the first one created. We've already seen how we can use
PDF CanOpener to wrest a bit of control away from Acrobat.
With a little more work we can remove control of this element
completely from the Background and Watermark Tool.
Once this is done you can use the tool to create a second
watermark or background that will not be overwritten, which also
means you can create multiple layers.
The first thing we need to do is change the name
of the OCG
from "Background", to something else. Since
Acrobat always uses the same names, we don't want there to be
conflicts with any new layers we create.
From the Layers Palette right click on the
"Background" layer and select "Properties..." to bring
up the properties dialog.
Change the "Layer Name".
The second thing we need to do is find the
actual graphical element on the page that is attached to this
layer and change some information on it. To do that we'll
use PDF CanOpener's Indirect Search capabilities.
Right click on the OCG dictionary in the Object
Tree and select the "Search for Indirect Object->Find" option.
The Indirect Object Search dialog will
automatically contain the ID of the object the mouse was
clicked on. "Unique Paths Only" should be checked.
(figure 7: Object Search Dialog)
Click OK and the Search Results dialog
will be displayed.
(figure 8: Search Results Dialog)
Seven results were returned, but only
one has a path that leads down to a specific page. It's the
first one in the list. We want
the one that leads to a page because this is where a graphical
page element is attached to the layer. Notice that our reference is inside an
XObject in the Pages Resource Dictionary. Select this
result and click on the "Find in Tree" button. Then close
The selected path is now expanded in
the Cos Object Tree display and our OCG Dictionary has the
(figure 9: Cos Object view of OCG placement in an
This XObject is a visual element on a page in
the PDF. It's literally the contents of the PDF page we
specified in the "Watermarks and Background" dialog. The "OC" entry attaches this XObject to an OCG.
When Acrobat attempts to draw this object on the page it first
checks for the "OC" entry. If it exists, as it does
here, Acrobat then checks the state of the OCG and draws the XObject only if
the state is "On". You can attach any XObject to
an OCG Layer just by adding an "OC"
entry containing a valid OCG object reference to the XObject's
The "OC" entry could contain
a single reference to the controlling OCG. The entry in
the above screenshot contains a reference to an OCMD, Optional
Content Membership Dictionary. The OCMD is a way of
grouping OCGs together to combine their states. In this case
there is only one OCG so the OCMD structure is unnecessary,
Acrobat just does things this way.
What we are really interested in is the
entry just below the "OC", the "PieceInfo" dictionary. The
PDF Specification indicates that this entry contains private
application data. The data in this entry is an Acrobat specific marker
indicating that this object is for use by the Watermarks and
Background Tool. If we delete this entry Acrobat will
not be able to detect that it has already created a Background and will allow us
to create a new Watermark or Background image without
overwriting the one we just created. Right click on the "PieceInfo"
node and select the "Delete" Option. Done.
Setting up the OCG for Automatic Control:
The PDF Specification defines 6 parameters that
can be used to automatically control the state of an OCG.
For the OCG we created in the first part of this article Acrobat set up 3 of these parameters, "Export", "Print", and "View".
The "Export" parameter is used when the PDF is exported to
another format, including an older version of PDF that doesn't
support OCGs. The "Print" parameter is used to determine
whether the layer should be printed and the "Vew" parameter is
used when the PDF is viewed on screen. All three of these
parameters can be controlled from the Layer Properties Dialog.
In order to use any of these parameters they have
to be listed at two different locations in the Cos Object Tree.
The first location is within the OCG dictionary itself.
(figure 10: OCG Usage Dictionary)
The "Usage" entry in the OCG is a
dictionary object that contains an entry for each parameter to
be used for
automatically calculating the OCG State. The actual parameter data
used in the calculation is contained within these
entries. For the parameters shown here, "Export", "Print",
and "View", this data is an "ON" or "OFF" indicator.
For some of the other possible usage parameters, like "Zoom",
this data is more complex.
To use one or more of these parameters, they have
to be referenced in an "Application Dictionary". The
Application Dictionaries are listed in the "AS" array of the "D"
dictionary (figure 11 below). The Application Dictionary
has an "Event" entry which indicates the situation
in which the Application Dictionary is to be used. This
entry can have one of the three possible values, Print, View, or
Export. This terminology is redundant but useful.
(figure 11: OCG Application Dictionary)
The Application Dictionary only applies to the OCGs contained in
its' "OCGs" array. The "Category" array is a list of
parameter names that are to be used in the OCG State calculation.
So here's how it works. We have two
things, 1) the Usage Dictionary in the OCG itself and 2) the
Application Dictionaries. The Usage Dictionary tells
Acrobat how to calculate the OCG State from different parameters
associated with what's happening to the PDF Document. The
Application Dictionary tells Acrobat which of these
parameters will actually be used in the state calculation for
each OCG and during a particular event (print, view, or export).
For example, if the PDF in the screenshot above is being viewed on the screen, the Application
Dictionary that has an "Event" value of "View"
will be selected to
determine the state calculation. All other Application
Dictionaries are ignored. A parameter is used in the
state calculation only if it is listed in both the OCG's Usage Dictionary
and in the "Category"
array of the Application Dictionary.
In figure 11 above, the "Category" array for the first Application
Dictionary contains only one entry, "View". So the "View"
entry in our OCG's Usage Dictionary is the only thing that is
used to calculate the OCG State when the PDF is being viewed on the
screen. The data for the OCG's "View" parameter
is a single value, "ViewState=ON" (figure 10), which means that this OCG is
always "ON" when the PDF is viewed on screen.
The whole Optional Content setup is fairly
complex but very flexible. Hopefully Adobe or 3rd party vendors
will be creating more tools to create and manipulate layers, but
in the absence of such software you can always use PDF CanOpener
to fix things up the way you want.
We hope this material was helpful to you.
If you have any questions or comments for us or want more info
on PDF CanOpener, please send email to