Resources

by Thom Parker of WindJack Solutions.
Copyright © 2004 by WindJack Solutions
 

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, typically at:
            "C:\Program Files\Adobe\Acrobat 6.0\Acrobat\plug_ins\Annotations\Stamps"

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 or with a JavaScript. 

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.

1. 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)
    

2. Right click on the "Order" array and select "Add..." from the context menu to bring up the "Add Array Element" Dialog.

3. 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)
    

4. Click Ok and you're done.

Method #2, Object Copy.

1. 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.

2. Right click on the "Order" array and select "Paste CosObj".  The Copy Options Dialog will appear.

3. Select "Leave Indirect References Intact" and click OK.
   
   
   (figure 5:  CosObj Copy Dialog)
    

4. The Set Array Dialog will appear, just click OK.
   
   
   (figure 6:  Element Position Dialog)
    

5. Done.

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 layer.  This is the same name to use if you want to control this layer from JavaScript. 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. 

1. From the Layers Palette right click on the "Background" layer and select "Properties..." to bring up the properties dialog. 

2. Change the "Layer Name".

3. Select OK.

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.

1. Right click on the OCG dictionary in the Object Tree and select the "Search for Indirect Object->Find" option.

2. 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)
    

3. Click OK and the Search Results dialog will be displayed.
   
   
   (figure 8:  Search Results Dialog)
    

4. 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 dialog.

5. The selected path is now expanded in the Cos Object Tree display and our OCG Dictionary has the focus.
   
   (figure 9:  Cos Object view of OCG placement in an XObject)
    

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. 

(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 info@windjack.com.