57
©
Adobe Systems Incorporated 2008 – All rights reserved
217
PDF 32000-1:2008
8.10 Form XObjects
8.10.1
General
A form XObject is a PDF content stream that is a self-contained description of any sequence of graphics
objects (including path objects, text objects, and sampled images). A form XObject may be painted multiple
times—either on several pages or at several locations on the same page—and produces the same results each
time, subject only to the graphics state at the time it is invoked. Not only is this shared definition economical to
represent in the PDF file, but under suitable circumstances the conforming reader can optimize execution by
caching the results of rendering the form XObject for repeated reuse.
NOTE 1
The term form also refers to a completely different kind of object, an interactive form (sometimes called an
AcroForm), discussed in 12.7, "Interactive Forms". Whereas the form XObjects described in this sub-clause
correspond to the notion of forms in the PostScript language, interactive forms are the PDF equivalent of the
familiar paper instrument. Any unqualified use of the word form is understood to refer to an interactive form; the
type of form described here is always referred to explicitly as a form XObject.
Form XObjects have various uses:
•
As its name suggests, a form XObject may serve as the template for an entire page.
EXAMPLE
A program that prints filled-in tax forms can first paint the fixed template as a form XObject and then paint
the variable information on top of it.
•
Any graphical element that is to be used repeatedly, such as a company logo or a standard component in
the output from a computer-aided design system, may be defined as a form XObject.
•
Certain document elements that are not part of a page’s contents, such as annotation appearances (see
12.5.5, "Appearance Streams"), shall be represented as form XObjects.
•
A specialized type of form XObject, called a group XObject (PDF 1.4), can be used to group graphical
elements together as a unit for various purposes (see 8.10.3, "Group XObjects"). In particular, group
XObjects shall be used to define transparency groups and soft masks for use in the transparent imaging
model (see 11.6.5.2, "Soft-Mask Dictionaries" and 11.6.6, "Transparency Group XObjects").
•
Another specialized type of form XObject, a reference XObject (PDF 1.4), may be used to import content
from one PDF document into another (see 8.10.4, "Reference XObjects").
A writer shall perform the following two specific operations in order to use a form XObject:
a) Define the appearance of the form XObject. A form XObject is a PDF content stream. The dictionary portion of the
stream (called the form dictionary ) shall contain descriptive information about the form XObject; the body of the stream
shall describe the graphics objects that produce its appearance. The contents of the form dictionary are described in
8.10.2, "Form Dictionaries".
b) Paint the form XObject. The Do operator (see 8.8, "External Objects") shall paint a form XObject whose name is
supplied as an operand. The name shall be defined in the XObject subdictionary of the current resource dictionary.
Before invoking this operator, the content stream in which it appears should set appropriate parameters in the graphics
state. In particular, it should alter the current transformation matrix to control the position, size, and orientation of the
form XObject in user space.
Each form XObject is defined in its own coordinate system, called form space . The BBox entry in the form
dictionary shall be expressed in form space, as shall be any coordinates used in the form XObject’s content
stream, such as path coordinates. The Matrix entry in the form dictionary shall specify the mapping from form
space to the current user space. Each time the form XObject is painted by the Do operator, this matrix shall be
concatenated with the current transformation matrix to define the mapping from form space to device space.
NOTE 2
This differs from the Matrix entry in a pattern dictionary, which maps pattern space to the initial user space of
the content stream in which the pattern is used.
VB.NET Image: Image Scaling SDK to Scale Picture / Photo this VB.NET image scaling control add-on, we API, developer can only scale one image / picture / photo at com is professional provider of document, content and
adding image to pdf file; how to add an image to a pdf in preview
68
PDF 32000-1:2008
218
©
Adobe Systems Incorporated 2008 – All rights reserved
When the Do operator is applied to a form XObject, a conforming reader shall perform the following tasks:
a) Saves the current graphics state, as if by invoking the q operator (see 8.4.4, "Graphics State Operators")
b) Concatenates the matrix from the form dictionary’s Matrix entry with the current transformation matrix (CTM)
c) Clips according to the form dictionary’s BBox entry
d) Paints the graphics objects specified in the form’s content stream
e) Restores the saved graphics state, as if by invoking the Q operator (see 8.4.4, "Graphics State Operators")
Except as described above, the initial graphics state for the form shall be inherited from the graphics state that
is in effect at the time Do is invoked.
8.10.2
Form Dictionaries
Every form XObject shall have a form type , which determines the format and meaning of the entries in its form
dictionary. This specification only defines one form type, Type 1. Form XObject dictionaries may contain the
entries shown in Table 95, in addition to the usual entries common to all streams (see Table 5).
Table 95 – Additional Entries Specific to a Type 1 Form Dictionary
Key
Type
Value
Type
name
(Optional) The type of PDF object that this dictionary describes; if
present, shall be XObject for a form XObject.
Subtype
name
(Required) The type of XObject that this dictionary describes; shall be
Form for a form XObject.
FormType
integer
(Optional) A code identifying the type of form XObject that this
dictionary describes. The only valid value is 1. Default value: 1.
BBox
rectangle
(Required) An array of four numbers in the form coordinate system
(see above), giving the coordinates of the left, bottom, right, and top
edges, respectively, of the form XObject’s bounding box. These
boundaries shall be used to clip the form XObject and to determine its
size for caching.
Matrix
array
(Optional) An array of six numbers specifying the form matrix, which
maps form space into user space (see 8.3.4, "Transformation
Matrices"). Default value: the identity matrix [ 1 0 0 1 0 0 ].
Resources
dictionary
(Optional but strongly recommended; PDF 1.2) A dictionary specifying
any resources (such as fonts and images) required by the form
XObject (see 7.8, "Content Streams and Resources").
In a PDF whose version is 1.1 and earlier, all named resources used in
the form XObject sh
all be included in the resource dictionary of each
page object on which the form XObject appears, regardless of whether
they also appear in the resource dictionary of the form XObject. These
resources should also be specified in the form XObject’s resource
dictionary as well, to determine which resources are used inside the
form XObject. If a resource is included in both dictionaries, it shall
have the same name in both locations.
In PDF 1.2 and later versions, form XObjects may be independent of
the con
tent streams in which they appear, and this is strongly
recommended although not required. In an independent form XObject,
the resource dictionary of the form XObject is required and shall
contain all named resources used by the form XObject. These
resources shall not be promoted to the outer content stream’s
resource dictionary, although that stream’s resource dictionary refers
to the form XObject.
84
©
Adobe Systems Incorporated 2008 – All rights reserved
219
PDF 32000-1:2008
EXAMPLE
The following shows a simple form XObject that paints a filled square 1000 units on each side.
6 0 obj
% Form XObject
<< /Type /XObject
/Subtype /Form
/FormType 1
/BBox [ 0 0 1000 1000 ]
/Matrix [ 1 0 0 1 0 0 ]
/Resources << /ProcSet [ /PDF ] >>
Group
dictionary
(Optional; PDF 1.4) A group attributes dictionary indicating that the
contents of the form XObject shall be treated as a group and
specifying the attributes of that group (see 8.10.3, "Group XObjects").
If a Ref entry (see below) is present, the group attributes shall also
apply to the external page imported by that entry, which allows such an
imported page to be treated as a group without further modification.
Ref
dictionary
(Optional; PDF 1.4) A reference dictionary identifying a page to be
imported from another PDF file, and for which the form XObject serves
as a proxy (see 8.10.4, "Reference XObjects").
Metadata
stream
(Optional; PDF 1.4) A metadata stream containing metadata for the
form XObject (see 14.3.2, "Metadata Streams").
PieceInfo
dictionary
(Optional; PDF 1.3) A page-piece dictionary associated with the form
XObject (see 14.5, "Page-Piece Dictionaries").
LastModified
date
(Required if PieceInfo is present; optional otherwise; PDF 1.3) The
date and time (see 7.9.4, "Dates") when the form XObject’s contents
were most recently modified. If a page-piece dictionary (PieceInfo) is
present, the modification date shall be used to ascertain which of the
application data dictionaries it contains correspond to the current
content of the form (see 14.5, "Page-Piece Dictionaries").
StructParent
integer
(Required if the form XObject is a structural content item; PDF 1.3)
The integer key of the form XObject’s entry in the structural parent tree
(see 14.7.4.4, "Finding Structure Elements from Content Items").
StructParents
integer
(Required if the form XObject contains marked-content sequences that
are structural content items; PDF 1.3) The integer key of the form
XObject’s entry in the structural parent tree (see 14.7.4.4, "Finding
Structure Elements from Content Items").
At most one of the entries StructParent or StructParents shall be
present. A form XObject shall be either a content item in its entirety or
a container for marked-content sequences that are content items, but
not both.
OPI
dictionary
(Optional; PDF 1.2) An OPI version dictionary for the form XObject
(see 14.11.7, "Open Prepress Interface (OPI)").
OC
dictionary
(Optional; PDF 1.5) An optional content group or optional content
membership dictionary (see 8.11, "Optional Content") specifying the
optional content properties for the form XObject. Before the form is
processed, its visibility shall be determined based on this entry. If it is
determined to be invisible, the entire form shall be skipped, as if there
were no Do operator to invoke it.
Name
name
(Required in PDF 1.0; optional otherwise)
The name by which this
form XObject is referenced in the XObject subdictionary of the current
resource dictionary (see 7.8.3, "Resource Dictionaries").
NOTE
This entry is obsolescent and its use is no longer
re
commended.
Table 95 – Additional Entries Specific to a Type 1 Form Dictionary (continued)
Key
Type
Value
57
PDF 32000-1:2008
220
©
Adobe Systems Incorporated 2008 – All rights reserved
/Length 58
>>
stream
0 0 m
0 1000 l
1000 1000 l
1000 0 l
f
endstream
endobj
8.10.3
Group XObjects
A group XObject (PDF 1.4) is a special type of form XObject that can be used to group graphical elements
together as a unit for various purposes. It shall be distinguished by the presence of the optional Group entry in
the form dictionary (see 8.10.2, "Form Dictionaries"). The value of this entry shall be a subsidiary group
attributes dictionary describing the properties of the group.
As shown in Table 96, every group XObject shall have a group subtype (specified by the S entry in the group
attributes dictionary) that determines the format and meaning of the dictionary’s remaining entries. This
specification only defines one subtype, a transparency group XObject (subtype Transparency) representing a
transparency group for use in the transparent imaging model (see 11.4, "Transparency Groups"). The
remaining contents of this type of dictionary are described in 11.6.6, "Transparency Group XObjects".
8.10.4
Reference XObjects
8.10.4.1 General
Reference XObjects (PDF 1.4) enable one PDF document to import content from another. The document in
which the reference occurs is called the containing document; the one whose content is being imported is the
target document. The target document may reside in a file external to the containing document or may be
included within it as an embedded file stream (see 7.11.4, "Embedded File Streams").
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.
Table 96 – Entries Common to all Group Attributes Dictionaries
Key
Type
Value
Type
name
(Optional) The type of PDF object that this dictionary describes; if
present, shall be Group for a group attributes dictionary.
S
name
(Required) The group subtype, which identifies the type of group whose
attributes this dictionary describes and determines the format and
meaning of the dictionary’s remaining entries. The only group subtype
defined is Transparency; see 11.6.6, "Transparency Group XObjects",
for the remaining contents of this type of dictionary.
62
©
Adobe Systems Incorporated 2008 – All rights reserved
221
PDF 32000-1:2008
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.
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.
8.10.4.2 Printing Reference XObjects
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.
8.10.4.3 Special Considerations
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
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.
61
PDF 32000-1:2008
222
©
Adobe Systems Incorporated 2008 – All rights reserved
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.
8.11 Optional Content
8.11.1
General
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.
8.11.2
Optional Content Groups
8.11.2.1 General
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.
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").
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: Vi
ew. 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.
Documents you may be interested
Documents you may be interested