• Create BookmarkCreate Bookmark
  • Create Note or TagCreate Note or Tag
  • PrintPrint
Share this Page URL
Help

Chapter 4. Graphics > Form XObjects

4.9. Form XObjects

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 PDF consumer application can optimize execution by caching the results of rendering the form XObject for repeated reuse.

Note

The term form also refers to a completely different kind of object, an interactive form (sometimes called an AcroForm), discussed in Section 8.6, “Interactive Forms.” Whereas the form XObjects described in this section 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 can serve as the template for an entire page. For 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, can be defined as a form XObject.

  • Certain document elements that are not part of a page's contents, such as annotation appearances (see Section 8.4.4, “Appearance Streams”), are 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 Section 4.9.2, “Group XObjects”). In particular, group XObjects are used to define transparency groups and soft masks for use in the transparent imaging model (see “Soft-Mask Dictionaries” on page 520 and Section 7.5.5, “Transparency Group XObjects”).

  • Another specialized type of form XObject, a reference XObject (PDF 1.4), can be used to import content from one PDF document into another (see Section 4.9.3, “Reference XObjects”).

The use of form XObjects requires two steps:

1.
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) contains descriptive information about the form XObject; the body of the stream describes the graphics objects that produce its appearance. The contents of the form dictionary are described in Section 4.9.1, “Form Dictionaries.”

2.
Paint the form XObject. The Do operator (see Section 4.7, “External Objects”) paints a form XObject whose name is supplied as an operand. (The name is 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 is expressed in form space, as are any coordinates used in the form XObject's content stream, such as path coordinates. The Matrix entry in the form dictionary specifies the mapping from form space to the current user space. Each time the form XObject is painted by the Do operator, this matrix is concatenated with the current transformation matrix to define the mapping from form space to device space. (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.)

When the Do operator is applied to a form XObject, it does the following tasks:

1.
Saves the current graphics state, as if by invoking the q operator (see Section 4.3.3, “Graphics State Operators”)

2.
Concatenates the matrix from the form dictionary's Matrix entry with the current transformation matrix (CTM)

3.
Clips according to the form dictionary's BBox entry

4.
Paints the graphics objects specified in the form's content stream

5.
Restores the saved graphics state, as if by invoking the Q operator (see Section 4.3.3, “Graphics State Operators”)

Except as described above, the initial graphics state for the form is inherited from the graphics state that is in effect at the time Do is invoked.

4.9.1. Form Dictionaries

Every form XObject has a form type, which determines the format and meaning of the entries in its form dictionary. At the time of publication, only one form type, type 1, has been defined. Form XObject dictionaries may contain the entries shown in Table 4.45, in addition to the usual entries common to all streams (see Table 3.4 on page 38).

Table 4.45. Additional entries specific to a type 1 form dictionary
KEYTYPEVALUE
TYPEname(Optional) The type of PDF object that this dictionary describes; if present, must be XObject for a form XObject.
Subtypename(Required) The type of XObject that this dictionary describes; must be Form for a form XObject.
FormTypeinteger(Optional) A code identifying the type of form XObject that this dictionary describes. The only valid value defined at the time of publication is 1. Default value: 1.
BBoxrectangle(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 are used to clip the form XObject and to determine its size for caching.
Matrixarray(Optional) An array of six numbers specifying the form matrix, which maps form space into user space (see Section 4.2.3, “Transformation Matrices”). Default value: the identity matrix [100 100].
Resourcesdictionary(Optional but strongly recommended; PDF 1.2) A dictionary specifying any resources (such as fonts and images) required by the form XObject (see Section 3.7, “Content Streams and Resources”).

In PDF 1.1 and earlier, all named resources used in the form XObject must 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. It can be useful to specify these resources 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 should have the same name in both locations.

In PDF 1.2 and later versions, form XObjects can be independent of the content 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 contains all named resources used by the form XObject. These resources are not promoted to the outer content stream's resource dictionary, although that stream's resource dictionary refers to the form XObject.
Groupdictionary(Optional; PDF 1.4) A group attributes dictionary indicating that the contents of the form XObject are to be treated as a group and specifying the attributes of that group (see Section 4.9.2, “Group XObjects”).

Note

If a Ref entry (see below) is present, the group attributes 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.

Refdictionary(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 Section 4.9.3, “Reference XObjects”).
Metadatastream(Optional; PDF 1.4) A metadata stream containing metadata for the form XObject (see Section 10.2.2, “Metadata Streams”).
PieceInfodictionary(Optional; PDF 1.3) A page-piece dictionary associated with the form XObject (see Section 10.4, “Page-Piece Dictionaries”).
LastModifieddate(Required if PieceInfo is present; optional otherwise; PDF 1.3) The date and time (see Section 3.8.3, “Dates”) when the form XObject's contents were most recently modified. If a page-piece dictionary (PieceInfo) is present, the modification date is used to ascertain which of the application data dictionaries it contains correspond to the current content of the form (see Section 10.4, “Page-Piece Dictionaries”).
StructParentinteger(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 “Finding Structure Elements from Content Items” on page 797).
StructParentsinteger(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 “Finding Structure Elements from Content Items” on page 797).

Note

At most one of the entries StructParent or StructParents may be present. A form XObject can be either a content item in its entirety or a container for marked-content sequences that are content items, but not both.

OPIdictionary(Optional; PDF 1.2) An OPI version dictionary for the form XObject (see Section 10.10.6, “Open Prepress Interface (OPI)”).
OCdictionary(Optional; PDF 1.5) An optional content group or optional content membership dictionary (see Section 4.10, “Optional Content”) specifying the optional content properties for the form XObject. Before the form is processed, its visibility is determined based on this entry. If it is determined to be invisible, the entire form is skipped, as if there were no Do operator to invoke it.
Namename(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 Section 3.7.2, “Resource Dictionaries”).

Note

This entry is obsolescent and its use is no longer recommended. (See implementation note 54 in Appendix H.)


Example 4.31 shows a simple form XObject that paints a filled square 1000 units on each side.

Example 4.31.

6 0 obj                              % Form XObject
   << /Type/XObject
      /Subtype/Form
      /FormType1
      /BBox[0 0 1000 1000]
      /Matrix[1 0 0 1 0 0]
      /Resources<</ProcSet[/PDF]>>
      /Length58
  >>
stream
    0 0m
    0 1000 l
    1000 1000 l
    1000 0 l
    f
endstream
endobj

4.9.2. 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 is distinguished by the presence of the optional Group entry in the form dictionary (see Section 4.9.1, “Form Dictionaries”). The value of this entry is a subsidiary group attributes dictionary describing the properties of the group.

As shown in Table 4.46, every group XObject has 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. Only one such subtype is currently defined, a transparency group XObject (subtype Transparency) representing a transparency group for use in the transparent imaging model (see Section 7.3, “Transparency Groups”). The remaining contents of this type of dictionary are described in Section 7.5.5, “Transparency Group XObjects.”

Table 4.46. Entries common to all group attributes dictionaries
KEYTYPEVALUE
TYPEname(Optional) The type of PDF object that this dictionary describes; if present, must be Group for a group attributes dictionary.
Sname(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 in PDF 1.4 is Transparency; see Section 7.5.5, “Transparency Group XObjects,” for the remaining contents of this type of dictionary. Other group subtypes may be added in the future.


4.9.3. Reference XObjects

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 Section 3.10.3, “Embedded File Streams”).

The reference XObject in the containing document is a form XObject containing the optional Ref entry in its form dictionary, as described below. This form XObject serves as a proxy that can be displayed or printed in place of the imported content. 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. PDF consumers that do not recognize the Ref entry simply display or print the proxy as an ordinary form XObject (see implementation note 55 in Appendix H). Those that do implement reference XObjects can use the proxy in place of the imported content if the latter is unavailable. An application may also provide a user interface to allow editing and updating of imported content links.

The imported content consists of a single, complete PDF page in the target document. It is designated by a reference dictionary, which in turn is the value of the Ref entry in the reference XObject's form dictionary (see Section 4.9.1, “Form Dictionaries”). The presence of the Ref entry distinguishes reference XObjects from other types of form XObjects. Table 4.47 shows the contents of the reference dictionary.

Table 4.47. Entries in a reference dictionary
KEYTYPEVALUE
Ffile specification(Required) The file containing the target document.
Pageinteger or text string(Required) A page index or page label (see Section 8.3.1, “Page Labels”) identifying the page of the target document containing the content to be imported. Note that the reference is a weak one and can be inadvertently invalidated if the referenced page is changed or replaced in the target document after the reference is created.
IDarray(Optional) An array of two strings constituting a file identifier (see Section 10.3, “File Identifiers”) for the file containing the target document. The use of this entry improves an application'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 is 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 Section 4.9.1, “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 Section 10.10.1, “Page Boundaries”), but it is not required to correspond to any of the defined page boundaries. If the proxy object's form dictionary contains a Group entry, the specified group attributes apply to the imported page as well, which allows the imported page to be treated as a group without further modification.

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 application, 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 Section 10.10.6, “Open Prepress Interface (OPI)”)

The imported content or the reference XObject may also be emitted in place of an OPI proxy when generating OPI comments in a PostScript output stream.

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 Section 8.4, “Annotations”), all annotations that contain a printable, unhidden, visible appearance stream (Section 8.4.4, “Appearance Streams”) must be included in the rendering of the imported page. If the proxy is a snapshot image of the imported page, it must also include the annotation appearances. These appearances must 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 Section 10.6, “Logical Structure”) should normally 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.

  • Creative Edge
  • Create BookmarkCreate Bookmark
  • Create Note or TagCreate Note or Tag
  • PrintPrint