Repository navigation
PDF Spec 08 Images
Part of: PDF-Spec-08-Graphics
Navigation: PDF-Spec-08-XObjects | PDF-Spec-Index | Next →
The reference XObject in the containing document shall be a form XObject containing the Ref entry in its form dictionary, as described below. This form XObject shall serve as a proxy that shall be displayed or printed by a conforming reader in place of the imported content.
NOTE 3 The proxy might consist of a low-resolution image of the imported content, a piece of descriptive text referring to it, a gray box to be displayed in its place, or any other similar placeholder.
Conforming readers that do not recognize the Ref entry shall simply display or print the proxy as an ordinary form XObject. Those readers that do implement reference XObjects shall use the proxy in place of the imported content if the latter is unavailable. A conforming reader may also provide a user interface to allow editing and updating of imported content links.
The imported content shall consist of a single, complete PDF page in the target document. It shall be designated by a reference dictionary , which in turn shall be the value of the Ref entry in the reference XObject's form dictionary (see 8.10.2, "Form Dictionaries"). The presence of the Ref entry shall distinguish reference XObjects from other types of form XObjects. Table 97 shows the contents of the reference dictionary.
Table 97 - Entries in a Reference Dictionary
| Key | Type | Value |
|---|---|---|
| F | file specification | (Required) The file containing the target document. |
| Page | integer or text string | (Required) A page index or page label (see 12.4.2, "Page Labels") identifying the page of the target document containing the content to be imported. This reference is a weak one and may be inadvertently invalidated if the referenced page is changed or replaced in the target document after the reference is created. |
| ID | array | (Optional) An array of two byte strings constituting a file identifier (see 14.4, "File Identifiers") for the file containing the target document. The use of this entry improves an reader's chances of finding the intended file and allows it to warn the user if the file has changed since the reference was created. |
When the imported content replaces the proxy, it shall be transformed according to the proxy object's transformation matrix and clipped to the boundaries of its bounding box, as specified by the Matrix and BBox entries in the proxy's form dictionary (see 8.10.2, "Form Dictionaries"). The combination of the proxy object's matrix and bounding box thus implicitly defines the bounding box of the imported page. This bounding box typically coincides with the imported page's crop box or art box (see 14.11.2, "Page Boundaries"), but may not correspond to any of the defined page boundaries. If the proxy object's form dictionary contains a Group entry, the specified group attributes shall apply to the imported page as well, which allows the imported page to be treated as a group without further modification.
When printing a page containing reference XObjects, an application may emit any of the following items, depending on the capabilities of the conforming reader, the user's preferences, and the nature of the print job:
- The imported content designated by the reference XObject
- The reference XObject as a proxy for the imported content
- An OPI proxy or substitute image taken from the reference XObject's OPI dictionary, if any (see 14.11.7, "Open Prepress Interface (OPI)")
The imported content or the reference XObject may also be emitted, by a conforming reader, in place of an OPI proxy when generating OPI comments in a PostScript output stream.
Certain special considerations arise when reference XObjects interact with other PDF features:
- When the page imported by a reference XObject contains annotations (see 12.5, "Annotations"), all annotations that contain a printable, unhidden, visible appearance stream (12.5.5, "Appearance Streams") shall be included in the rendering of the imported page. If the proxy is a snapshot image of the imported page, it shall also include the annotation appearances. These appearances shall therefore be converted into part of the proxy's content stream, either as subsidiary form XObjects or by flattening them directly into the content stream.
- Logical structure information associated with a page (see 14.7, "Logical Structure") may be ignored when importing the page into another document with a reference XObject. In a target document with multiple
pages, structure elements occurring on the imported page are typically part of a larger structure pertaining to the document as a whole; such elements cannot meaningfully be incorporated into the structure of the containing document. In a one-page target document or one made up of independent, structurally unrelated pages, the logical structure for the imported page may be wholly self-contained; in this case, it may be possible to incorporate this structure information into that of the containing document. However, PDF provides no mechanism for the logical structure hierarchy of one document to refer indirectly to that of another.
Optional content (PDF 1.5) refers to sub-clauses of content in a PDF document that can be selectively viewed or hidden by document authors or consumers. This capability is useful in items such as CAD drawings, layered artwork, maps, and multi-language documents.
NOTE The following sub-clauses describe the PDF structures used to implement optional content:
8.11.2, "Optional Content Groups", describes the primary structures used to control the visibility of content.
8.11.3, "Making Graphical Content Optional", describes how individual pieces of content in a document may declare themselves as belonging to one or more optional content groups.
8.11.4, "Configuring Optional Content", describes how the states of optional content groups are set.
An optional content group is a dictionary representing a collection of graphics that can be made visible or invisible dynamically by users of conforming readers. The graphics belonging to such a group may reside anywhere in the document: they need not be consecutive in drawing order, nor even belong to the same content stream. Table 98 shows the entries in an optional content group dictionary.
Table 98 - Entries in an Optional Content Group Dictionary
| Key | Type | Value |
|---|---|---|
| Type | name | (Required) The type of PDF object that this dictionary describes; shall be OCG for an optional content group dictionary. |
| Name | text string | (Required) The name of the optional content group, suitable for presentation in a reader's user interface. |
| Intent | name or array | (Optional) A single intent name or an array containing any combination of names. PDF defines two names, View and Design , that may indicate the intended use of the graphics in the group. A conforming reader may choose to use only groups that have a specific intent and ignore others. Default value: View . See 8.11.2.3, "Intent" for more information. |
| Usage | dictionary | (Optional) A usage dictionary describing the nature of the content controlled by the group. It may be used by features that automatically control the state of the group based on outside factors. See 8.11.4.4, "Usage and Usage Application Dictionaries" for more information. |
In its simplest form, each dictionary shall contain a Type entry and a Name for presentation in a user interface. It may also have an Intent entry that may describe its intended use (see 8.11.2.3, "Intent") and a Usage entry that shall describe the nature of its content (see 8.11.4.4, "Usage and Usage Application Dictionaries").
Individual content elements in a document may specify the optional content group or groups that affect their visibility (see 8.11.3, "Making Graphical Content Optional"). Any content whose visibility shall be affected by a given optional content group is said to belong to that group.
A group shall be assigned a state, which is either ON or OFF . States themselves are not part of the PDF document but may be set programmatically or through the reader's user interface to change the visibility of content. When a document is first opened by a conforming reader, the groups' states shall be initialized based on the document's default configuration dictionary (see 8.11.4.3, "Optional Content Configuration Dictionaries").
Content belonging to a group shall be visible when the group is ON and invisible when it is OFF . Content may belong to multiple groups, which may have conflicting states. These cases shall be described by the use of optional content membership dictionaries, described in the next sub-clause.
As mentioned above, content may belong to a single optional content group and shall be visible when the group is ON and invisible when it is OFF . To express more complex visibility policies, content shall not declare itself to belong directly to an optional content group but rather to an optional content membership dictionary , whose entries are shown in Table 99.
NOTE 1 8.11.3, "Making Graphical Content Optional" describes how content declares its membership in a group or membership dictionary.
Table 99 - Entries in an Optional Content Membership Dictionary
| Key | Type | Value |
|---|---|---|
| Type | name | (Required) The type of PDF object that this dictionary describes; shall be OCMD for an optional content membership dictionary. |
| OCGs | dictionary or array | (Optional) A dictionary or array of dictionaries specifying the optional content groups whose states shall determine the visibility of content controlled by this membership dictionary. Null values or references to deleted objects shall be ignored. If this entry is not present, is an empty array, or contains references only to null or deleted objects, the membership dictionary shall have no effect on the visibility of any content. |
| P | name | (Optional) A name specifying the visibility policy for content belonging to this membership dictionary. Valid values shall be: AllOn visible only if all of the entries in OCGs are ON AnyOn visible if any of the entries in OCGs are ON AnyOff visible if any of the entries in OCGs are OFF AllOff visible only if all of the entries in OCGs are OFF Default value: AnyOn |
| VE | array | (Optional; PDF 1.6) An array specifying a visibility expression , used to compute visibility of content based on a set of optional content groups; see discussion below. |
An optional content membership dictionary may express its visibility policy in two ways:
-
The P entry may specify a simple boolean expression indicating how the optional content groups specified by the OCGs entry determine the visibility of content controlled by the membership dictionary.
-
PDF 1.6 introduced the VE entry, which is a visibility expression that may be used to specify an arbitrary boolean expression for computing the visibility of content from the states of optional content groups.
-
NOTE 2 Since the VE entry is more general, if it is present and supported by the conforming reader software, it should be used in preference to OCGs and P . However, for compatibility purposes, conforming writers should use OCGs and P entries where possible. When the use of VE is necessary to express the intended behaviour, OCGs and P entries should also be provided to approximate the behaviour in non-conforming reader software.
A visibility expression is an array with the following characteristics:
- Its first element shall be a name representing a boolean operator ( And , Or , or Not ).
- Subsequent elements shall be either optional content groups or other visibility expressions.
- If the first element is Not , it shall have only one subsequent element. If the first element is And or Or , it shall have one or more subsequent elements.
- In evaluating a visibility expression, the ON state of an optional content group shall be equated to the boolean value true ; OFF shall be equated to false .
Membership dictionaries are useful in cases such as these:
- Some content may choose to be invisible when a group is ON and visible when it is OFF . In this case, the content would belong to a membership dictionary whose OCGs entry consists of a single optional content group and whose P entry is AnyOff or AllOff .
NOTE 3 It is legal to have an OCGs entry consisting of a single group and a P entry that is AnyOn or AllOn . However, in this case it is preferable to use an optional content group directly because it uses fewer objects.
- Some content may belong to more than one group and needs to specify its policy when the groups are in conflicting states. In this case, the content would belong to a membership dictionary whose OCGs entry consists of an array of optional content groups and whose P entry specifies the visibility policy, as illustrated in EXAMPLE 1 in this sub-clause. EXAMPLE 2 in this sub-clause shows the equivalent policy using visibility expressions.
EXAMPLE 1 This example shows content belonging to a membership dictionary whose OCGs entry consists of an array of optional content groups and whose P entry specifies the visibility policy.
<< /Type /OCMD % Content belonging to this optional content % membership dictionary is controlled by the states /OCGs [12 0 R 13 0 R 14 0 R] % of three optional content groups. /P /AllOn % Content is visible only if the state of all three >> % groups is ON; otherwise it's hidden.
- EXAMPLE 2 This example shows a visibility expression equivalent to EXAMPLE 1 in this sub-clause
- EXAMPLE 3 This example shows a more complicated visibility expression based on five optional content groups, represented by objects 1 through 5. It is equivalent to
<< /Type /OCMD /VE [/And 12 0 R 13 0 R 14 0 R] % Visibility expression equivalent to EXAMPLE 1. >>
'OCG 1' OR (NOT 'OCG 2') OR ('OCG 3' AND 'OCG 4' AND 'OCG 5')
<< /Type /OCMD /VE [/Or % Visibility expression: OR 1 0 R % OCG 1 [/Not 2 0 R] % NOT OCG 2 [/And 3 0 R 4 0 R 5 0 R] % OCG 3 AND OCG 4 AND OCG 5 ] >>
PDF defines two intents: Design , which may be used to represent a document designer's structural organization of artwork, and View , which may be used for interactive use by document consumers. A conforming writer shall not use a value other than Design or View .
- NOTE The Intent entry in Table 98 provides a way to distinguish between different intended uses of optional content. For example, many document design applications, such as CAD packages, offer layering features for collecting groups of graphics together and selectively hiding or viewing them for the convenience of the author. However, this layering may be different (at a finer granularity, for example) than would be useful to consumers of the document. Therefore, it is possible to specify different intents for optional content groups within a single document. A conforming reader may decide to use only groups that are of a specific intent.
Configuration dictionaries (see 8.11.4.3, "Optional Content Configuration Dictionaries") may also contain an Intent entry. If one or more of a group's intents is contained in the current configuration's set of intents, the group shall be used in determining visibility. If there is no match, the group shall have no effect on visibility.
If the configuration's Intent is an empty array, no groups shall be used in determining visibility; therefore, all content shall be considered visible.
Graphical content in a PDF file may be made optional by specifying membership in an optional content group or optional content membership dictionary. Two primary mechanisms exist for defining membership:
- Sections of content streams delimited by marked-content operators may be made optional, as described in 8.11.3.2, "Optional Content in Content Streams".
- Form and image XObjects and annotations may be made optional in their entirety by means of a dictionary entry, as described in 8.11.3.3, "Optional Content in XObjects and Annotations".
When a piece of optional content in a PDF file is determined that it shall be hidden, the following occurs:
- The content shall not be drawn.
- Graphics state operations, such as setting the colour, transformation matrix, and clipping, shall still be applied. In addition, graphics state side effects that arise from drawing operators shall be applied; in particular, the current text position shall be updated even for text wrapped in optional content. In other words, graphics state parameters that persist past the end of a marked-content section shall be the same whether the optional content is visible or not.
Hiding a section of optional content shall not change the colour of objects that do not belong to the same optional content group.
- This rule shall also apply to operators that set state that is not strictly graphics state; for example, BX and EX .
- Objects such as form XObjects and annotations that have been made optional may be skipped entirely, because their contents are encapsulated such that no changes to the graphics state (or other state) persist beyond the processing of their content stream.
Other features in conforming readers, such as searching and editing, may be affected by the ability to selectively show or hide content. A conforming reader may choose whether to use the document's current state of optional content groups (and, correspondingly, the document's visible graphics) or to supply their own states of optional content groups to control the graphics they process.
- NOTE 4 Tools to select and move annotations should honour the current on-screen visibility of annotations when performing cursor tracking and mouse-click processing. A full text search engine, however, may need to
process all content in a document, regardless of its current visibility on-screen. Export filters might choose the current on-screen visibility, the full content, or present the user with a selection of OCGs to control visibility.
- NOTE 5 A non-conforming reader that does not support optional content, such as one that only supports PDF 1.4 functionality, will draw and process all content in a document.
Sections of content in a content stream (including a page's Contents stream, a form or pattern's content stream, glyph descriptions a Type 3 font as specified by its CharProcs entry, or an annotation's appearance) may be made optional by enclosing them between the marked-content operators BDC and EMC (see 14.6, "Marked Content") with a marked-content tag of OC. In addition, a DP marked-content operator may be placed in a page's content stream to force a reference to an optional content group or groups on the page, even when the page has no current content in that layer.
The property list associated with the marked content shall specify either an optional content group or optional content membership dictionary to which the content belongs. Because a group shall be an indirect object and a membership dictionary contains references to indirect objects, the property list shall be a named resource listed in the Properties subdictionary of the current resource dictionary (see 14.6.2, "Property Lists"), as shown in EXAMPLE 1 and EXAMPLE 2 in this sub-clause.
Although the marked-content tag shall be OC , other applications of marked content are not precluded from using OC as a tag. The marked content shall be considered to be for optional content only if the tag is OC and the dictionary operand is a valid optional content group or optional content membership dictionary.
- NOTE 1 To avoid conflict with other features that used marked content (such as logical structure; see 14.7, "Logical Structure"), the following strategy is recommended:
Where content is to be tagged with optional content markers as well as other markers, the optional content markers should be nested inside the other marked content.
Where optional content and the other markers would overlap but there is not strict containment, the optional content should be broken up into two or more BDC/EMC sections, nesting the optional content sections inside the others as necessary. Breaking up optional content spans does not damage the nature of the visibility of the content, whereas the same guarantee cannot be made for all other uses of marked content.
- NOTE 2 Any marked content tagged for optional content that is nested inside other marked content tagged for optional content is visible only if all the levels indicate visibility. In other words, if the settings that apply to the outer level indicate that the content should be hidden, the inner level is hidden regardless of its settings.
In the following example, the state of the Show Greeting optional content group directly controls the visibility of the text string 'Hello' on the page. When the group is ON , the text shall be visible; when the group is OFF , the text shall be hidden.
EXAMPLE 1 % Within a content stream ... /OC /oc1 BDC % Optional content follows BT /F1 1 Tf 12 0 0 12 100 600 Tm (Hello) Tj ET EMC % End of optional content ... << % In the resources dictionary /Properties << /oc1 5 0 R >> % This dictionary maps the name oc1 to an ... % optional content group (object 5) >> 5 0 obj % The OCG controlling the visibility
<< % of the text. /Name (Show Greeting)
/Type /OCG >> endobj
The example above shows one piece of content associated with one optional content group. There are other possibilities:
- More than one section of content may refer to the same group or membership dictionary, in which case the visibility of both sections is always the same.
- Equivalently, although less space-efficient, different sections may have separate membership dictionaries with the same OCGs and P entries. The sections shall have identical visibility behaviour.
- Two sections of content may belong to membership dictionaries that refer to the same group(s) but with different P settings. For example, if one section has no P entry, and the other has a P entry of AllOff , the visibility of the two sections of content shall be opposite. That is, the first section shall be visible when the second is hidden, and vice versa.
The following example demonstrates both the direct use of optional content groups and the indirect use of groups through a membership dictionary. The content (a black rectangle frame) is drawn if either of the images controlled by the groups named Image A or Image B is shown. If both groups are hidden, the rectangle frame shall be hidden.
EXAMPLE 2 % Within a content stream ... /OC /OC2 BDC % Draws a black rectangle frame 0 g 4 w 100 100 412 592 re s EMC /OC /OC3 BDC % Draws an image XObject q 412 0 0 592 100 100 cm /Im3 Do Q EMC /OC /OC4 BDC % Draws an image XObject q 412 0 0 592 100 100 cm /Im4 Do Q EMC ... << % The resource dictionary /Properties << /OC2 20 0 R /OC3 30 0 R /OC4 40 0 R >> /XObject << /lm3 50 0 R /lm4 /60 0 R >> >> 20 0 obj << % Optional content membership dictionary /Type /OCMD /OCGs [30 0 R 40 0 R] /P /AnyOn >> endobj 30 0 obj % Optional content group 'Image A' << /Type /OCG /Name (Image A)
PDF 32000-1:2008
>> % Optional content group 'Image B' /Name (Image B)
endobj 40 0 obj << /Type /OCG >> endobj
In addition to marked content within content streams, form XObjects and image XObjects (see 8.8, "External Objects") and annotations (see 12.5, "Annotations") may contain an OC entry, which shall be an optional content group or an optional content membership dictionary.
A form or image XObject's visibility shall be determined by the state of the group or those of the groups referenced by the membership dictionary in conjunction with its P (or VE ) entry, along with the current visibility state in the context in which the XObject is invoked (that is, whether objects are visible in the contents stream at the place where the Do operation occurred).
Annotations have various flags controlling on-screen and print visibility (see 12.5.3, "Annotation Flags"). If an annotation contains an OC entry, it shall be visible for screen or print only if the flags have the appropriate settings and the group or membership dictionary indicates it shall be visible.
A PDF document containing optional content may specify the default states for the optional content groups in the document and indicate which external factors shall be used to alter the states.
NOTE The following sub-clauses describe the PDF structures that are used to specify this information.
8.11.4.2, "Optional Content Properties Dictionary" describes the structure that lists all the optional content groups in the document and their possible configurations.
8.11.4.3, "Optional Content Configuration Dictionaries" describes the structures that specify initial state settings and other information about the groups in the document.
8.11.4.4, "Usage and Usage Application Dictionaries" and 8.11.4.5, "Determining the State of Optional Content Groups" describe how the states of groups can be affected based on external factors.
The optional OCProperties entry in the document catalog (see 7.7.2, "Document Catalog") shall contain, when present, the optional content properties dictionary , which contains a list of all the optional content groups in the document, as well as information about the default and alternate configurations for optional content. This dictionary shall be present if the file contains any optional content; if it is missing, a conforming reader shall ignore any optional content structures in the document.
This dictionary contains the following entries:
Table 100 - Entries in the Optional Content Properties Dictionary
| Key | Type | Value |
|---|---|---|
| OCGs | array | (Required) An array of indirect references to all the optional content groups in the document (see 8.11.2, "Optional Content Groups"), in any order. Every optional content group shall be included in this array. |
Table 100 - Entries in the Optional Content Properties Dictionary (continued)
| Key | Type | Value |
|---|---|---|
| D | dictionary | (Required) The default viewing optional content configuration dictionary (see 8.11.4.3, "Optional Content Configuration Dictionaries"). |
| Configs | array | (Optional) An array of alternate optional content configuration dictionaries (see 8.11.4.3, "Optional Content Configuration Dictionaries"). |
The D and Configs entries in Table 100 are configuration dictionaries , which represent different presentations of a document's optional content groups for use by conforming readers. The D configuration dictionary shall be used to specify the initial state of the optional content groups when a document is first opened. Configs lists other configurations that may be used under particular circumstances. The entries in a configuration dictionary are shown in Table 101.
Table 101 - Entries in an Optional Content Configuration Dictionary
| Key | Type | Value |
|---|---|---|
| Name | text string | (Optional) A name for the configuration, suitable for presentation in a user interface. |
| Creator | text string | (Optional) Name of the application or feature that created this configuration dictionary. |
| BaseState | name | (Optional) Used to initialize the states of all the optional content groups in a document when this configuration is applied. The value of this entry shall be one of the following names: ON The states of all groups shall be turned ON . OFF The states of all groups shall be turned OFF . Unchanged The states of all groups shall be left unchanged. After this initialization, the contents of the ON and OFF arrays shall be processed, overriding the state of the groups included in the arrays. Default value: ON . If BaseState is present in the document's default configuration dictionary, its value shall be ON . |
| ON | array | (Optional) An array of optional content groups whose state shall be set to ON when this configuration is applied. If the BaseState entry is ON , this entry is redundant. |
| OFF | array | (Optional) An array of optional content groups whose state shall be set to OFF when this configuration is applied. If the BaseState entry is OFF , this entry is redundant. |
| Intent | name or array | (Optional) A single intent name or an array containing any combination of names. it shall be used to determine which optional content groups' states to consider and which to ignore in calculating the visibility of content (see 8.11.2.3, "Intent"). PDF defines two intent names, View and Design . In addition, the name All shall indicate the set of all intents, including those not yet defined. Default value: View . The value shall be View for the document's default configuration. |
Table 101 - Entries in an Optional Content Configuration Dictionary (continued)
| Key | Type | Value |
|---|---|---|
| AS | array | (Optional) An array of usage application dictionaries (see Table 103) specifying which usage dictionary categories (see Table 102) shall be consulted by conforming readers to automatically set the states of optional content groups based on external factors, such as the current system language or viewing magnification, and when they shall be applied. |
| Order | array | (Optional) An array specifying the order for presentation of optional content groups in a conforming reader's user interface. The array elements may include the following objects: Optional content group dictionaries, whose Name entry shall be displayed in the user interface by the conforming reader. Arrays of optional content groups which may be displayed by a conforming reader in a tree or outline structure. Each nested array may optionally have as its first element a text string to be used as a non-selectable label in a conforming reader's user interface. Text labels in nested arrays shall be used to present collections of related optional content groups, and not to communicate actual nesting of content inside multiple layers of groups (see EXAMPLE 1 in 8.11.4.3, "Optional Content Configuration Dictionaries"). To reflect actual nesting of groups in the content, such as for layers with sublayers, nested arrays of groups without a text label shall be used (see EXAMPLE 2 in 8.11.4.3, "Optional Content Configuration Dictionaries"). An empty array [] explicitly specifies that no groups shall be presented. In the default configuration dictionary, the default value shall be an empty array; in other configuration dictionaries, the default shall be the Order value from the default configuration dictionary. Any groups not listed in this array shall not be presented in any user |
| ListMode | name | (Optional) A name specifying which optional content groups in the Order array shall be displayed to the user. Valid values shall be: AllPages Display all groups in the Order array. VisiblePages Display only those groups in the Order array that are referenced by one or more visible pages. |
| RBGroups | array | (Optional) An array consisting of one or more arrays, each of which represents a collection of optional content groups whose states shall be intended to follow a radio button paradigm. That is, the state of at most one optional content group in each array shall be ON at a time. If one group is turned ON , all others shall be turned OFF . However, turning a group from ON to OFF does not force any other group to be turned ON . An empty array [] explicitly indicates that no such collections exist. In the default configuration dictionary, the default value shall be an empty array; in other configuration dictionaries, the default is the RBGroups value from the default configuration dictionary. |
Table 101 - Entries in an Optional Content Configuration Dictionary (continued)
| Key | Type | Value |
|---|---|---|
| Locked | array | (Optional; PDF 1.6) An array of optional content groups that shall be locked when this configuration is applied. The state of a locked group cannot be changed through the user interface of a conforming reader. Conforming writer s can use this entry to prevent the visibility of content that depends on these groups from being changed by users. Default value: an empty array. A conforming reader may allow the states of optional content groups from being changed by means other than the user interface, such as JavaScript or items in the AS entry of a configuration dictionary. |
NOTE EXAMPLE 1 and EXAMPLE 2 in this sub-clause illustrate the use of the Order entry to control the display of groups in a user interface.
1 0 obj <</Type /OCG /Name (Skin)>> endobj % Optional content groups 2 0 obj <</Type /OCG /Name (Bones)>> endobj 3 0 obj <</Type /OCG /Name (Bark)>> endobj 4 0 obj <</Type /OCG /Name (Wood)>> endobj 5 0 obj % Configuration dictionary << /Order [[(Frog Anatomy) 1 0 R 2 0 R] [(Tree Anatomy) 3 0 R 4 0 R] ] >> A conforming reader should display the optional content groups as follows: Frog Anatomy Skin Bones Tree Anatomy Bark Wood EXAMPLE 2 Given the following PDF objects: % Page contents /OC /L1 BDC % Layer 1 /OC /L1a BDC % Sublayer A of layer 1 0 0 100 100 re f EMC /OC /L1b BDC % Sublayer B of layer 1 0 100 100 100 re f EMC EMC ... << /L1 1 0 R % Resource names /L1a 2 0 R /L1b 3 0 R >> ... %Optional content groups 1 0 obj <</Type /OCG /Name (Layer 1)>> endobj 2 0 obj <</Type /OCG /Name (Sublayer A)>> endobj 3 0 obj <</Type /OCG /Name (Sublayer B)>> endobj ... 4 0 obj % Configuration dictionary << /Order [1 0 R [2 0 R 3 0 R]] >> A conforming reader should display the OCGs as follows: Layer 1 Sublayer A Sublayer B
The AS entry is an auto state array consisting of one or more usage application dictionaries that specify how conforming readers shall automatically set the state of optional content groups based on external factors, as discussed in the following sub-clause.
Optional content groups are typically constructed to control the visibility of graphic objects that are related in some way. Objects can be related in several ways; for example, a group may contain content in a particular language or content suitable for viewing at a particular magnification.
An optional content group's usage dictionary (the value of the Usage entry in an optional content group dictionary; see Table 98) shall contain information describing the nature of the content controlled by the group. This dictionary can contain any combination of the entries shown in Table 102.
Table 102 - Entries in an Optional Content Usage Dictionary
| Key | Type | Value |
|---|---|---|
| CreatorInfo | dictionary | (Optional) A dictionary used by the creating application to store application-specific data associated with this optional content group. It shall contain two required entries: Creator A text string specifying the application that created the group. Subtype A name defining the type of content controlled by the group. Suggested values include but shall not be limited to Artwork , for graphic-design or publishing applications, and Technical , for technical designs such as building plans or schematics. Additional entries may be included to present information relevant to the creating application or related applications. Groups whose Intent entry contains Design typically include a CreatorInfo entry. |
| Language | dictionary | (Optional) A dictionary specifying the language of the content controlled by this optional content group. It may contain the following two entries: Lang (required) A text string that specifies a language and possibly a locale (see 14.9.2, "Natural Language Specification"). For example, es-MX represents Mexican Spanish. Preferred (optional) A name whose values shall be either ON or OFF . Default value: OFF . it shall be used by conforming readers when there is a partial match but no exact match between the system language and the language strings in all usage dictionaries. See 8.11.4.4, "Usage and Usage Application Dictionaries" for more information. |
| Export | dictionary | (Optional) A dictionary containing one entry, ExportState , a name whose value shall be either ON or OFF . This value shall indicate the recommended state for content in this group when the document (or part of it) is saved by a conforming reader to a format that does not support optional content (for example, a raster image format). |
| Zoom | dictionary | (Optional) A dictionary specifying a range of magnifications at which the content in this optional content group is best viewed. It shall contain one or both of the following entries: min The minimum recommended magnification factor at which the group shall be ON . Default value: 0. max The magnification factor below which the group shall be ON . Default value: infinity. |
Table 102 - Entries in an Optional Content Usage Dictionary (continued)
| Key | Type | Value |
|---|---|---|
| dictionary | (Optional) A dictionary specifying that the content in this group is shall be used when printing. It may contain the following optional entries: Subtype A name object specifying the kind of content controlled by the group; for example, Trapping , PrintersMarks and Watermark . PrintState A name that shall be either ON or OFF , indicating that the group shall be set to that state when the document is printed from a conforming reader. | |
| View | dictionary | (Optional) A dictionary that shall have a single entry, ViewState , a name that shall have a value of either ON or OFF , indicating that the group shall be set to that state when the document is opened in a conforming reader. |
| User | dictionary | (Optional) A dictionary specifying one or more users for whom this optional content group is primarily intended. Each dictionary shall have two required entries: Type A name object that shall be either Ind (individual), Ttl (title), or Org (organization). Name A text string or array of text strings representing the name(s) |
| PageElement | dictionary | (Optional) A dictionary declaring that the group contains a pagination artifact. It shall contain one entry, Subtype , whose value shall be a name that is either HF (header/footer), FG (foreground image or graphic), BG (background image or graphic), or L (logo). |
While the data in the usage dictionary serves as information for a document user to examine, it may also be used by conforming readers to automatically manipulate the state of optional content groups based on external factors such as current system language settings or zoom level. Document authors may use usage application dictionaries to specify which entries in the usage dictionary shall be consulted to automatically set the state of optional content groups based on such factors. Usage application dictionaries shall be listed in the AS entry in an optional content configuration dictionary (see Table 101). If no AS entry is present, states shall not be automatically adjusted based on usage information.
A usage application dictionary specifies the rules for which usage entries shall be used by conforming readers to automatically manipulate the state of optional content groups, which groups shall be affected, and under which circumstances. Table 103 shows the entries in a usage application dictionary.
Usage application dictionaries shall only be used by interactive conforming readers, and shall not be used by applications that use PDF as final form output (see 8.11.4.5, "Determining the State of Optional Content Groups" for more information).
Table 103 - Entries in a Usage Application Dictionary
| Key | Type | Value |
|---|---|---|
| Event | name | (Required) A name defining the situation in which this usage application dictionary should be used. Shall be one of View , Print , or Export . |
| OCGs | array | (Optional) An array listing the optional content groups that shall have their states automatically managed based on information in their usage dictionary (see 8.11.4.4, "Usage and Usage Application Dictionaries"). Default value: an empty array, indicating that no groups shall be affected. |
| Category | array | (Required) An array of names, each of which corresponds to a usage dictionary entry (see Table 102). When managing the states of the optional content groups in the OCGs array, each of the corresponding categories in the group's usage dictionary shall be considered. |
The Event entry specifies whether the usage settings shall be applied during viewing, printing, or exporting the document. The OCGs entry specifies the set of optional content groups to which usage settings shall be applied. For each of the groups in OCGs , the entries in its usage dictionary (see Table 102) specified by Category shall be examined to yield a recommended state for the group. If all the entries yield a recommended state of ON , the group's state shall be set to ON ; otherwise, its state shall be set to OFF .
The entries in the usage dictionary shall be used as follows:
- View : The state shall be the value of the ViewState entry. This entry allows a document to contain content that is relevant only when the document is viewed interactively, such as instructions for how to interact with the document.
- Print : The state shall be the value of the PrintState entry. If PrintState is not present, the state of the optional content group shall be left unchanged.
- Export : The state shall be the value of the ExportState entry.
- Zoom : If the current magnification level of the document is greater than or equal to min and less than max , the ON state shall be used; otherwise, OFF shall be used.
- User : The Name entry shall specify a name or names to match with the user's identification. The Type entry determines how the Name entry shall be interpreted (name, title, or organization). If there is an exact match, the ON state shall be used; otherwise OFF shall be used.
- Language : This category shall allow the selection of content based on the language and locale of the application. If an exact match to the language and locale is found among the Lang entries of the optional content groups in the usage application dictionary's OCGs list, all groups that have exact matches shall receive an ON recommendation. If no exact match is found, but a partial match is found (that is, the language matches but not the locale), all partially matching groups that have Preferred entries with a value of ON shall receive an ON recommendation. All other groups shall receive an OFF recommendation.
There shall be no restriction on multiple entries with the same value of Event , in order to allow documents with incompatible usage application dictionaries to be combined into larger documents and have their behaviour preserved. If a given optional content group appears in more than one OCGs array, its state shall be ON only if all categories in all the usage application dictionaries it appears in shall have a state of ON .
EXAMPLE
This example shows the use of an auto state array with usage application dictionaries. The AS entry in the default configuration dictionary is an array of three usage application dictionaries, one for each of the Event values View , Print , and Export .
/OCProperties % OCProperties dictionary in document catalog << /OCGs [1 0 R 2 0 R 3 0 R 4 0 R] /D << /BaseState /OFF % The default configuration /ON [1 0 R] /AS [ % Auto state array of usage application dictionaries << /Event /View /Category [/Zoom] /OCGs [1 0 R 2 0 R 3 0 R 4 0 R] >> << /Event /Print /Category [/Print] /OCGs [4 0 R] >> << /Event /Export /Category [/Export] /OCGs [3 0 R 4 0 R] >> ] >> >> ... 1 0 obj << /Type /OCG /Name (20000 foot view) /Usage << /Zoom << /max 1.0 >> >> >> endobj 2 0 obj << /Type /OCG
/Name (10000 foot view) /Usage << /Zoom << /min 1.0 /max 2.0 >> >> >> endobj 3 0 obj << /Type /OCG /Name (1000 foot view) /Usage << /Zoom << /min 2.0 /max 20.0 >> /Export << /ExportState /OFF >> >> >> endobj 4 0 obj << /Type /OCG /Name (Copyright notice) /Usage << /Print << /PrintState /ON >> /Export << /ExportState /ON>> >> >> endobj
In the example, the usage application dictionary with event type View specifies that all optional content groups shall have their states managed based on zoom level when viewing. Three groups (objects 1, 2, and 3) contain Zoom usage information. Object 4 has none; therefore, it shall not be affected by zoom level changes. Object 3 shall receive an OFF recommendation when exporting. When printing or exporting, object 4 shall receive an ON recommendation.
This sub-clause summarizes the rules by which conforming readers make use of the configuration and usage application dictionaries to set the state of optional content groups. For purposes of this discussion, it is useful to distinguish the following types of conforming readers:
- Viewer applications which allow users to interact with the document in various ways.
- Design applications, which offer layering features for collecting groups of graphics together and selectively hiding or viewing them.
NOTE 1 The following rules are not meant to apply to design applications; they may manage their states in an entirely different manner if they choose.
- Aggregating applications, which import PDF files as graphics.
- Printing applications, which print PDF files.
When a document is first opened, its optional content groups shall be assigned a state based on the D (default) configuration dictionary in the OCProperties dictionary:
- a) The value of BaseState shall be applied to all the groups.
- b) The groups listed in either the ON or OFF array (depending on which one is opposite to BaseState ) shall have their states adjusted.
This state shall be the state used by printing and aggregating application. Such applications shall not apply the changes based on usage application dictionaries described below. However, for more advanced functionality, they may provide user control for manipulating the individual states of optional content groups.
NOTE 2 Viewer applications may also provide users with an option to view documents in this state (that is, to disable the automatic adjustments discussed below). This option permits an accurate preview of the content as it will appear when placed into an aggregating application or sent to a stand-alone printing system.
The remaining discussion in this sub-clause applies only to viewer applications. Such applications shall examine the AS array for usage application dictionaries that have an Event of type View . For each one found,
the groups listed in its OCGs array shall be adjusted as described in 8.11.4.4, "Usage and Usage Application Dictionaries".
Subsequently, the document is ready for interactive viewing by a user. Whenever there is a change to a factor that the usage application dictionaries with event type View depend on (such as zoom level), the corresponding dictionaries shall be reapplied.
The user may manipulate optional content group states manually or by triggering SetOCGState actions (see 12.6.4.12, "Set-OCG-State Actions") by, for example, clicking links or bookmarks. Manual changes shall override the states that were set automatically. The states of these groups remain overridden and shall not be readjusted based on usage application dictionaries with event type View as long as the document is open (or until the user reverts the document to its original state).
Navigation: PDF-Spec-08-XObjects | PDF-Spec-Index | Next →