How To Articlesby Thom Parker of WindJack Solutions.
Copyright © 2004 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.
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.
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.
The "Order" 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 Object copy.
Method #1, Explicit Indirect Reference Creation.
Method #2, Object Copy.
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.
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.
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 attributes.
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.
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.
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 firstname.lastname@example.org.