PDF Reference sixth edition, Adobe Portable Document Format Version 1.7 (book 1) — page 9
331
SECTION 4.6
Patterns
Gouraud-Shaded Triangle Meshes)” on page 314 for further details on the format
of the data.
TABLE 4.36 Data values in a tensor-product patch mesh
EDGE FLAG
NEXT SET OF DATA VALUES
f = 0
x00 y00 x01 y01 x02 y02 x03 y03
x
y13 x23 y23 x33 y33 x32
y
13
32
x31 y31 x30 y30 x20 y20 x10 y10
x
y11 x12 y12 x22 y22 x21
y
11
21
c
c03 c33 c30
00
New patch; no implicit values
f = 1
x13 y13 x23 y23 x33 y33 x32 y32
x
y31 x30 y30
31
x20 y20 x10 y10 x11 y11 x12 y12
x
y22 x21 y21
22
c
c30
33
Implicit values:
(x00 , y00 ) = (x03 , y03 ) previous
c00 = c03 previous
(x01 , y01 ) = (x13 , y13 ) previous
c03 = c33 previous
(x02 , y02 ) = (x23 , y23 ) previous
(x03 , y03 ) = (x33 , y33 ) previous
f = 2
x13 y13 x23 y23 x33 y33 x32 y32
x
y31 x30 y30
31
x20 y20 x10 y10 x11 y11 x12 y12
x
y22 x21 y21
22
c
c30
33
Implicit values:
(x00 , y00 ) = (x33 , y33 ) previous
c00 = c33 previous
(x01 , y01 ) = (x32 , y32 ) previous
c03 = c30 previous
(x02 , y02 ) = (x31 , y31 ) previous
(x03 , y03 ) = (x30 , y30 ) previous
f = 3
x13 y13 x23 y23 x33 y33 x32 y32
x
y31 x30 y30
31
x20 y20 x10 y10 x11 y11 x12 y12
x
y22 x21 y21
22
c
c30
33
Implicit values:
(x00 , y00 ) = (x30 , y30 ) previous
c00 = c30 previous
(x01 , y01 ) = (x20 , y20 ) previous
c03 = c00 previous
(x02 , y02 ) = (x10 , y10 ) previous
(x03 , y03 ) = (x00 , y00 ) previous
332
CHAPTER 4
Graphics
4.7
External Objects
An external object (commonly called an XObject) is a graphics object whose con-
tents are defined by a self-contained content stream, separate from the content
stream in which it is used. There are three types of external objects:
• An image XObject (Section 4.8.4, “Image Dictionaries”) represents a sampled
visual image such as a photograph.
• A form XObject (Section 4.9, “Form XObjects”) is a self-contained description
of an arbitrary sequence of graphics objects.
• A PostScript XObject (Section 4.7.1, “PostScript XObjects”) contains a fragment
of code expressed in the PostScript page description language. PostScript XOb-
jects are no longer recommended to be used.
Two further categories of external objects, group XObjects and reference XObjects
(both PDF 1.4), are actually specialized types of form XObjects with additional
properties. See Sections 4.9.2, “Group XObjects,” and 4.9.3, “Reference XObjects,”
for additional information.
Any XObject can be painted as part of another content stream by means of the Do
operator (see Table 4.37). This operator applies to any type of XObject—image,
form, or PostScript. The syntax is the same in all cases, although details of the
operator’s behavior differ depending on the type. (See implementation note 51 in
Appendix H.)
TABLE 4.37 XObject operator
OPERANDS
OPERATOR
DESCRIPTION
name
Do
Paint the specified XObject. The operand name must appear as a key in the
XObject subdictionary of the current resource dictionary (see Section 3.7.2, “Re-
source Dictionaries”). The associated value must be a stream whose Type entry,
if present, is XObject. The effect of Do depends on the value of the XObject’s
Subtype entry, which may be Image (see Section 4.8.4, “Image Dictionaries”),
Form (Section 4.9, “Form XObjects”), or PS (Section 4.7.1, “PostScript XOb-
jects”).
333
SECTION 4.7
External Objects
4.7.1
PostScript XObjects
Beginning with PDF 1.1, a content stream can include PostScript language frag-
ments. These fragments are used only when printing to a PostScript output de-
vice; they have no effect either when viewing the document on-screen or when
printing it to a non-PostScript device. In addition, applications that understand
PDF are unlikely to be able to interpret the PostScript fragments. Hence, this ca-
pability should be used with extreme caution and only if there is no other way to
achieve the same result. Inappropriate use of PostScript XObjects can cause PDF
files to print incorrectly.
Note: Since PDF 1.4 encompasses all of the Adobe imaging model features of the
PostScript language, there is no longer any reason to use PostScript XObjects. This
feature is likely to be removed from PDF in a future version.
A PostScript XObject is an XObject stream whose Subtype entry has the value PS.
A PostScript XObject dictionary can contain the entries shown in Table 4.38 in
addition to the usual entries common to all streams (see Table 3.4 on page 62).
TABLE 4.38 Additional entries specific to a PostScript XObject dictionary
KEY
TYPE
VALUE
Type
name
(Optional) The type of PDF object that this dictionary describes; if present, must be
XObject for a PostScript XObject.
Subtype
name
(Required) The type of XObject that this dictionary describes; must be PS for a Post-
Script XObject.
Note: Alternatively, the value of this entry may be Form, with an additional Subtype2
entry whose value is PS.
Level1
stream
(Optional) A stream whose contents are to be used in place of the PostScript
XObject’s stream when the target PostScript interpreter is known to support only
LanguageLevel 1.
When a PDF content stream is translated into the PostScript language, any Do
operation that references a PostScript XObject is replaced by the contents of the
XObject stream itself. The stream is copied without interpretation. The PostScript
fragment may use Type 1 and TrueType fonts listed in the Font subdictionary of
the current resource dictionary (see Section 3.7.2, “Resource Dictionaries”), ac-
cessing them by their BaseFont names using the PostScript findfont operator. The
fragment may not use other types of fonts listed in the Font subdictionary. It
334
CHAPTER 4
Graphics
should not reference the PostScript definitions corresponding to PDF procedure
sets (see Section 10.1, “Procedure Sets”), which are subject to change.
4.8
Images
PDF’s painting operators include general facilities for dealing with sampled im-
ages. A sampled image (or just image for short) is a rectangular array of sample
values, each representing a color. The image may approximate the appearance of
some natural scene obtained through an input scanner or a video camera, or it
may be generated synthetically.
FIGURE 4.25 Typical sampled image
An image is defined by a sequence of samples obtained by scanning the image
array in row or column order. Each sample in the array consists of as many color
components as are needed for the color space in which they are specified—for
example, one component for DeviceGray, three for DeviceRGB, four for
DeviceCMYK, or whatever number is required by a particular DeviceN space.
Each component is a 1-, 2-, 4-, 8-, or (in PDF 1.5) 16-bit integer, permitting the
representation of 2, 4, 16, 256, or (in PDF 1.5) 65536 distinct values for each com-
ponent. (Other component sizes can be accommodated when a JPXDecode filter
is used; see Section 3.3.8, “JPXDecode Filter.)
335
SECTION 4.8
Images
PDF provides two means for specifying images:
• An image XObject (described in Section 4.8.4, “Image Dictionaries”) is a
stream object whose dictionary specifies attributes of the image and whose
data contains the image samples. Like all external objects, it is painted on the
page by invoking the Do operator in a content stream (see Section 4.7, “Exter-
nal Objects”). Image XObjects have other uses as well, such as for alternate im-
ages
(see
“Alternate Images” on page
347), image masks
(Section
4.8.5,
“Masked Images”), and thumbnail images
(Section
8.2.3,
“Thumbnail
Images”).
• An inline image is a small image that is completely defined—both attributes
and data—directly inline within a content stream. The kinds of images that can
be represented in this way are limited; see Section 4.8.6, “Inline Images,” for
details.
4.8.1
Image Parameters
The properties of an image—resolution, orientation, scanning order, and so
forth—are entirely independent of the characteristics of the raster output device
on which the image is to be rendered. A PDF consumer application usually ren-
ders images by a sampling technique that attempts to approximate the color val-
ues of the source as accurately as possible. The actual accuracy achieved depends
on the resolution and other properties of the output device.
To paint an image, four interrelated items must be specified:
• The format of the image: number of columns (width), number of rows (height),
number of color components per sample, and number of bits per color compo-
nent
• The sample data constituting the image’s visual content
• The correspondence between coordinates in user space and those in the image’s
own internal coordinate space, defining the region of user space that will re-
ceive the image
• The mapping from color component values in the image data to component
values in the image’s color space
All of these items are specified explicitly or implicitly by an image XObject or an
inline image.
336
CHAPTER 4
Graphics
Note: For convenience, the following sections refer consistently to the object defining
an image as an image dictionary. Although this term properly refers only to the
dictionary portion of the stream object representing an image XObject, it should be
understood to apply equally to the stream’s data portion or to the parameters and
data of an inline image.
4.8.2
Sample Representation
The source format for an image can be described by four parameters:
• The width of the image in samples
• The height of the image in samples
• The number of color components per sample
• The number of bits per color component
The image dictionary specifies the width, height, and number of bits per compo-
nent explicitly. The number of color components can be inferred from the color
space specified in the dictionary.
Note: For images using the JPXDecode filter (see Section 3.3.8, “JPXDecode Filter”),
the number of bits per component is determined from the image data and not speci-
fied in the image dictionary. The color space may or may not be specified in the dic-
tionary.
Sample data is represented as a stream of bytes, interpreted as 8-bit unsigned
integers in the range 0 to 255. The bytes constitute a continuous bit stream, with
the high-order bit of each byte first. This bit stream, in turn, is divided into units
of n bits each, where n is the number of bits per component. Each unit encodes a
color component value, given with high-order bit first; units of 16 bits are given
with the most significant byte first. Byte boundaries are ignored, except that each
row of sample data must begin on a byte boundary. If the number of data bits per
row is not a multiple of 8, the end of the row is padded with extra bits to fill out
the last byte. A PDF consumer application ignores these padding bits.
Each n-bit unit within the bit stream is interpreted as an unsigned integer in the
range 0 to 2n − 1, with the high-order bit first. The image dictionary’s Decode
entry maps this integer to a color component value, equivalent to what could be
used with color operators such as sc or g. Color components are interleaved sam-
337
SECTION 4.8
Images
ple by sample; for example, in a three-component RGB image, the red, green, and
blue components for one sample are followed by the red, green, and blue compo-
nents for the next.
Normally, the color samples in an image are interpreted according to the color
space specified in the image dictionary (see Section 4.5, “Color Spaces”), without
reference to the color parameters in the graphics state. However, if the image dic-
tionary’s ImageMask entry is true, the sample data is interpreted as a stencil mask
for applying the graphics state’s nonstroking color parameters (see “Stencil Mask-
ing” on page 350).
4.8.3
Image Coordinate System
Each image has its own internal coordinate system, or image space. The image oc-
cupies a rectangle in image space w units wide and h units high, where w and h
are the width and height of the image in samples. Each sample occupies one
square unit. The coordinate origin (0, 0) is at the upper-left corner of the image,
with coordinates ranging from 0 to w horizontally and 0 to h vertically.
The image’s sample data is ordered by row, with the horizontal coordinate varying
most rapidly. This is shown in Figure 4.26, where the numbers inside the squares
indicate the order of the samples, counting from 0. The upper-left corner of the
first sample is at coordinates (0, 0), the second at (1, 0), and so on through the last
sample of the first row, whose upper-left corner is at (w − 1, 0) and whose upper-
right corner is at (w, 0). The next samples after that are at coordinates (0, 1),
(1, 1), and so on to the final sample of the image, whose upper-left corner is at
(w − 1, h − 1) and whose lower-right corner is at (w, h).
Note: The image coordinate system and scanning order imposed by PDF do not pre-
clude using different conventions in the actual image. Coordinate transformations
can be used to map from other conventions to the PDF convention.
The correspondence between image space and user space is constant: the unit
square of user space, bounded by user coordinates (0, 0) and (1, 1), corresponds
to the boundary of the image in image space (see Figure 4.27). Following the
normal convention for user space, the coordinate (0, 0) is at the lower-left corner
of this square, corresponding to coordinates (0, h) in image space. The transfor-
mation from image space to user space could be described by the matrix
[ 1 ⁄ w
0 0 −1 ⁄ h 0 1 ].
338
CHAPTER 4
Graphics
0
1
2
w-1
w
0
0
1
w-1
1
w
w+1
2w-1
2
h-1
(h-1)w
(h-1)w+1
hw-1
h
FIGURE 4.26 Source image coordinate system
0
w
0
(0, 1)
(1, 1)
CTM
h
(0, 0)
(1, 0)
Unit square
Source image
in user space
Current page
FIGURE 4.27 Mapping the source image
An image can be placed on the output page in any position, orientation, and size
by using the cm operator to modify the current transformation matrix (CTM) so
as to map the unit square of user space to the rectangle or parallelogram in which
the image is to be painted. Typically, this is done within a pair of q and Q opera-
tors to isolate the effect of the transformation, which can include translation, ro-
339
SECTION 4.8
Images
tation, reflection, and skew (see Section 4.2, “Coordinate Systems”). For example,
if the XObject subdictionary of the current resource dictionary defines the name
Image1 to denote an image XObject, the code shown in Example 4.27 paints the
image in a rectangle whose lower-left corner is at coordinates (100, 200), that is
rotated 45 degrees counterclockwise, and that is 150 units wide and 80 units high.
Example 4.27
q
% Save graphics state
1 0 0 1 100 200 cm
% Translate
0. 7071 0. 7071 −0. 7071 0. 7071 0 0 cm
% Rotate
150 0 0 80 0 0 cm
% Scale
/Image1 Do
% Paint image
Q
% Restore graphics state
(As discussed in Section 4.2.3, “Transformation Matrices,” these three transfor-
mations could be combined into one.) Of course, if the aspect ratio (width to
height) of the original image in this example is different from 150:80, the result
will be distorted.
4.8.4
Image Dictionaries
An image dictionary—that is, the dictionary portion of a stream representing an
image XObject—can contain the entries listed in Table 4.39 in addition to the
usual entries common to all streams (see Table 3.4 on page 62). There are many
relationships among these entries, and the current color space may limit the
choices for some of them. Attempting to use an image dictionary whose entries
are inconsistent with each other or with the current color space causes an error.
Note: The entries described here are appropriate for a base image—one that is in-
voked directly with the Do operator. Some of the entries are not relevant for images
used in other ways, such as for alternate images (see “Alternate Images” on page
347), image masks (Section 4.8.5, “Masked Images”), or thumbnail images (Section
8.2.3, “Thumbnail Images”). Except as noted, such irrelevant entries are simply ig-
nored.
340
CHAPTER 4
Graphics
TABLE 4.39 Additional entries specific to an image dictionary
KEY
TYPE
VALUE
Type
name
(Optional) The type of PDF object that this dictionary describes; if
present, must be XObject for an image XObject.
Subtype
name
(Required) The type of XObject that this dictionary describes; must be
Image for an image XObject.
Width
integer
(Required) The width of the image, in samples.
Height
integer
(Required) The height of the image, in samples.
ColorSpace
name or
(Required for images, except those that use the JPXDecode filter; not allowed
array
for image masks) The color space in which image samples are specified; it
can be any type of color space except Pattern.
If the image uses the JPXDecode filter, this entry is optional:
• If ColorSpace is present, any color space specifications in the JPEG2000
data are ignored.
• If ColorSpace is absent, the color space specifications in the JPEG2000
data are used. The Decode array is also ignored unless ImageMask is
true.
BitsPerComponent
integer
(Required except for image masks and images that use the JPXDecode filter)
The number of bits used to represent each color component. Only a single
value may be specified; the number of bits is the same for all color compo-
nents. Valid values are 1, 2, 4, 8, and (in PDF 1.5) 16. If ImageMask is true,
this entry is optional, and if specified, its value must be 1.
If the image stream uses a filter, the value of BitsPerComponent must be
consistent with the size of the data samples that the filter delivers. In par-
ticular, a CCITTFaxDecode or JBIG2Decode filter always delivers 1-bit sam-
ples, a RunLengthDecode or DCTDecode filter delivers 8-bit samples, and
an LZWDecode or FlateDecode filter delivers samples of a specified size if
a predictor function is used.
If the image stream uses the JPXDecode filter, this entry is optional and ig-
nored if present. The bit depth is determined in the process of decoding
the JPEG2000 image.
Intent
name
(Optional; PDF 1.1) The name of a color rendering intent to be used in
rendering the image (see “Rendering Intents” on page 260). Default value:
the current rendering intent in the graphics state.
341
SECTION 4.8
Images
KEY
TYPE
VALUE
ImageMask
boolean
(Optional) A flag indicating whether the image is to be treated as an image
mask (see Section 4.8.5, “Masked Images”). If this flag is true, the value of
BitsPerComponent must be 1 and Mask and ColorSpace should not be
specified; unmasked areas are painted using the current nonstroking col-
or. Default value: false.
Mask
stream
(Optional except for image masks; not allowed for image masks; PDF 1.3)
or array
An image XObject defining an image mask to be applied to this image (see
“Explicit Masking” on page 351), or an array specifying a range of colors
to be applied to it as a color key mask (see “Color Key Masking” on page
351). If ImageMask is true, this entry must not be present.
(See
implementation note 52 in Appendix H.)
Decode
array
(Optional) An array of numbers describing how to map image samples
into the range of values appropriate for the image’s color space (see
“Decode Arrays” on page 344). If ImageMask is true, the array must be
either [ 0 1 ] or [ 1 0 ]; otherwise, its length must be twice the number of
color components required by ColorSpace. If the image uses the
JPXDecode filter and ImageMask is false, Decode is ignored.
Default value: see “Decode Arrays” on page 344.
Interpolate
boolean
(Optional) A flag indicating whether image interpolation is to be per-
formed (see “Image Interpolation” on page 346). Default value: false.
Alternates
array
(Optional; PDF 1.3) An array of alternate image dictionaries for this image
(see “Alternate Images” on page 347). The order of elements within the
array has no significance. This entry may not be present in an image XOb-
ject that is itself an alternate image.
SMask
stream
(Optional; PDF 1.4) A subsidiary image XObject defining a soft-mask
image (see “Soft-Mask Images” on page 553) to be used as a source of
mask shape or mask opacity values in the transparent imaging model. The
alpha source parameter in the graphics state determines whether the mask
values are interpreted as shape or opacity.
If present, this entry overrides the current soft mask in the graphics state,
as well as the image’s Mask entry, if any. (However, the other transparency-
related graphics state parameters—blend mode and alpha constant—
remain in effect.) If SMask is absent, the image has no associated soft
mask (although the current soft mask in the graphics state may still ap-
ply).
342
CHAPTER 4
Graphics
KEY
TYPE
VALUE
SMaskInData
integer
(Optional for images that use the JPXDecode filter, meaningless otherwise;
PDF 1.5) A code specifying how soft-mask information (see “Soft-Mask
Images” on page 553) encoded with image samples should be used:
0
If present, encoded soft-mask image information should be ig-
nored.
1
The image’s data stream includes encoded soft-mask values. An
application can create a soft-mask image from the information to
be used as a source of mask shape or mask opacity in the transpar-
ency imaging model.
2
The image’s data stream includes color channels that have been
preblended with a background; the image data also includes an
opacity channel. An application can create a soft-mask image with
a Matte entry from the opacity channel information to be used as
a source of mask shape or mask opacity in the transparency mod-
el.
If this entry has a nonzero value, SMask should not be specified. See also
Section 3.3.8, “JPXDecode Filter.”
Default value: 0.
Name
name
(Required in PDF 1.0; optional otherwise) The name by which this image
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 53 in Appendix H.)
StructParent
integer
(Required if the image is a structural content item; PDF 1.3) The integer key
of the image’s entry in the structural parent tree (see “Finding Structure
Elements from Content Items” on page 868).
ID
byte string
(Optional; PDF 1.3; indirect reference preferred) The digital identifier of
the image’s parent Web Capture content set (see Section 10.9.5, “Object
Attributes Related to Web Capture”).
OPI
dictionary
(Optional; PDF 1.2) An OPI version dictionary for the image (see Section
10.10.6, “Open Prepress Interface (OPI)”). If ImageMask is true, this entry
is ignored.
Metadata
stream
(Optional; PDF 1.4) A metadata stream containing metadata for the image
(see Section 10.2.2, “Metadata Streams”).
343
SECTION 4.8
Images
KEY
TYPE
VALUE
OC
dictionary
(Optional; PDF 1.5) An optional content group or optional content mem-
bership dictionary (see Section 4.10, “Optional Content”), specifying the
optional content properties for this image XObject. Before the image is
processed, its visibility is determined based on this entry. If it is deter-
mined to be invisible, the entire image is skipped, as if there were no Do
operator to invoke it.
Example 4.28 defines an image 256 samples wide by 256 high, with 8 bits per
sample in the DeviceGray color space. It paints the image on a page with its lower-
left corner positioned at coordinates (45, 140) in current user space and scaled to
a width and height of 132 user space units.
Example 4.28
20 0 obj
% Page object
<< /Type /Page
/Parent 1 0 R
/Resources 21 0 R
/MediaBox [ 0 0 612 792 ]
/Contents 23 0 R
>>
endobj
21 0 obj
% Resource dictionary for page
<< /ProcSet [ /PDF /ImageB ]
/XObject << /Im1 22 0 R >>
>>
endobj
22 0 obj
% Image XObject
<< /Type /XObject
/Subtype /Image
/Width 256
/Height 256
/ColorSpace /DeviceGray
/BitsPerComponent 8
/Length 83183
/Filter
/ASCII85Decode
>>
344
CHAPTER 4
Graphics
stream
9LhZI9h\GY9i+bb;,p:e;G9SP92/)X9MJ>^:f14d;,U(X8P;cO;G9e];c$=k9Mn\]
… Image data representing 65,536 samples…
8P;cO;G9e];c$=k9Mn\]~>
endstream
endobj
23 0 obj
% Contents of page
<< /Length 56 >>
stream
q
% Save graphics state
132 0 0 132 45 140 cm
% Translate to (45,140) and scale by 132
/Im1 Do
% Paint image
Q
% Restore graphics state
endstream
endobj
Decode Arrays
An image’s data stream is initially decomposed into integers in the domain 0 to
2n − 1, where n is the value of the image dictionary’s BitsPerComponent entry.
The image’s Decode array specifies a linear mapping of each integer component
value to a number that would be appropriate as a component value in the image’s
color space.
Each pair of numbers in a Decode array specifies the lower and upper values to
which the domain of sample values in the image is mapped. A Decode array con-
tains one pair of numbers for each component in the color space specified by the
image’s ColorSpace entry. The mapping for each color component is a linear
transformation; that is, it uses the following formula for linear interpolation:
y = Interpolate(x,xmin, xmax, ymin, ymax)
⎛
ymax – ymin⎞
=
ymin
+
⎜(
x xmin
)
× ----------------------------
⎟
x
⎝
max – xmin⎠
Generally, this formula is used to convert a value x between xmin and xmax to a
corresponding value y between ymin and ymax , projecting along the line defined
by the points (xmin , ymin ) and (xmax , ymax ). While this formula applies to values
outside the domain xmin to xmax and does not require that xmin < xmax , note that
interpolation used for color conversion, such as the Decode array, does require
345
SECTION 4.8
Images
that xmin < xmax and clips x values to this domain so that y = ymin for all x ≤ xmin ,
and y = ymax for all x ≥ xmax .
For a Decode array of the form [ Dmin Dmax ], this can be written as
y
=
Interpolate (x, 0, 2n
-
1,
,
)
Dmin
Dmax
⎛
-
⎞
Dmax
Dmin
=
+
⎜x
×
⎟
Dmin
⎝
2n
-
1
⎠
where
n is the value of BitsPerComponent
x is the input value, in the domain 0 to 2n − 1
Dmin and Dmax are the values specified in the Decode array
y is the output value, to be interpreted in the image’s color space
Samples with a value of 0 are mapped to Dmin , those with a value of 2n − 1 are
mapped to Dmax , and those with intermediate values are mapped linearly be-
tween Dmin and Dmax . Table 4.40 lists the default Decode arrays for use with the
various color spaces. For most color spaces, the Decode arrays listed in the table
map into the full range of allowed component values. For an Indexed color space,
the default Decode array ensures that component values that index a color table
are passed through unchanged.
TABLE 4.40 Default Decode arrays
COLOR SPACE
Decode ARRAY
DeviceGray
[ 0.0 1.0 ]
DeviceRGB
[ 0.0 1.0
0.0
1.0
0.0 1.0 ]
DeviceCMYK
[ 0.0 1.0
0.0
1.0
0.0
1.0
0.0 1.0 ]
CalGray
[ 0.0 1.0 ]
CalRGB
[ 0.0 1.0
0.0
1.0
0.0 1.0 ]
Lab
[ 0 100 amin amax bmin bmax ] where amin , amax , bmin , and bmax
correspond to the values in the Range array of the image’s color
space
346
CHAPTER 4
Graphics
COLOR SPACE
Decode ARRAY
ICCBased
Same as the value of Range in the ICC profile of the image’s color
space
Indexed
[ 0 N ], where N = 2n − 1
Pattern
(Not permitted with images)
Separation
[ 0.0 1.0 ]
DeviceN
[ 0.0 1.0
0.0
1.0
… 0.0 1.0 ] (one pair of elements for each color
component)
It is possible to specify a mapping that inverts sample color intensities by specify-
ing a Dmin value greater than Dmax . For example, if the image’s color space is
DeviceGray and the Decode array is [ 1.0 0.0 ], an input value of 0 is mapped to 1.0
(white); an input value of 2n − 1 is mapped to 0.0 (black).
The Dmin and Dmax parameters for a color component are not required to fall
within the range of values allowed for that component. For instance, if an applica-
tion uses 6-bit numbers as its native image sample format, it can represent those
samples in PDF in 8-bit form, setting the two unused high-order bits of each
sample to 0. The image dictionary should then specify a Decode array of
[ 0.00000 4.04762 ], which maps input values from 0 to 63 into the range 0.0 to 1.0
(4.04762 being approximately equal to 255 ÷ 63). If an output value falls outside
the range allowed for a component, it is automatically adjusted to the nearest al-
lowed value.
Image Interpolation
When the resolution of a source image is significantly lower than that of the out-
put device, each source sample covers many device pixels. As a result, images can
appear jaggy or blocky. These visual artifacts can be reduced by applying an im-
age interpolation algorithm during rendering. Instead of painting all pixels cov-
ered by a source sample with the same color, image interpolation attempts to
produce a smooth transition between adjacent sample values. Image interpola-
tion is enabled by setting the Interpolate entry in the image dictionary to true. It
is disabled by default because it may increase the time required to render the im-
age.
347
SECTION 4.8
Images
Note: The interpolation algorithm is implementation-dependent and is not specified
by PDF. Image interpolation may not always be performed for some classes of imag-
es or on some output devices.
Alternate Images
Alternate images (PDF 1.3) provide a straightforward and backward-compatible
way to include multiple versions of an image in a PDF file for different purposes.
These variant representations of the image may differ, for example, in resolution
or in color space. The primary goal is to reduce the need to maintain separate
versions of a PDF document for low-resolution on-screen viewing and high-
resolution printing.
In PDF 1.3, a base image (that is, the image XObject referred to in a resource
dictionary) can contain an Alternates entry. The value of this entry is an array of
alternate image dictionaries specifying variant representations of the base image.
Each alternate image dictionary contains an image XObject for one variant and
specifies its properties. Table 4.41 shows the contents of an alternate image dictio-
nary.
TABLE 4.41 Entries in an alternate image dictionary
KEY
TYPE
VALUE
Image
stream
(Required) The image XObject for the alternate image.
DefaultForPrinting boolean
(Optional) A flag indicating whether this alternate image is the default ver-
sion to be used for printing. At most one alternate for a given base image may
be so designated. If no alternate has this entry set to true, the base image is
used for printing.
OC
dictionary
(Optional; PDF 1.5) An optional content group (see Section 4.10.1, “Optional
Content Groups”) or optional content membership dictionary (see “Optional
Content Membership Dictionaries” on page 365”) that facilitates the selec-
tion of which alternate image to use.
Example 4.29 shows an image with a single alternate. The base image is a gray-
scale image, and the alternate is a high-resolution RGB image stored on a Web
server.
348
CHAPTER 4
Graphics
Example 4.29
10 0 obj
% Image XObject
<< /Type /XObject
/Subtype /Image
/Width 100
/Height 200
/ColorSpace /DeviceGray
/BitsPerComponent 8
/Alternates 15 0 R
/Length 2167
/Filter
/DCTDecode
>>
stream
… Image data…
endstream
endobj
15 0 obj
% Alternate images array
[
<< /Image 16 0 R
/DefaultForPrinting true
>>
]
endobj
16 0 obj
% Alternate image
<< /Type /XObject
/Subtype /Image
/Width 1000
/Height 2000
/ColorSpace /DeviceRGB
/BitsPerComponent 8
/Length 0
% This is an external stream
/F
<< /FS /URL
/F
( http : / / www .myserver. mycorp . com / images / exttest . jpg )
>>
/FFilter
/DCTDecode
>>
stream
endstream
endobj
349
SECTION 4.8
Images
In PDF 1.5, optional content (see Section 4.10) can be used to facilitate selection
between alternate images. If an image XObject contains both an Alternates entry
and an OC entry, the choice of which image to use is determined as follows:
1. If the image’s OC entry specifies that the base image is visible, that image is dis-
played.
2. Otherwise, the list of alternates specified by the Alternates entry is examined,
and the first alternate containing an OC entry specifying that its content
should be visible is shown. (Alternate images that have no OC entry are not
shown.)
4.8.5
Masked Images
Ordinarily, in the opaque imaging model, images mark all areas they occupy on
the page as if with opaque paint. All portions of the image, whether black, white,
gray, or color, completely obscure any marks that may previously have existed in
the same place on the page. In the graphic arts industry and page layout appli-
cations, however, it is common to crop or mask out the background of an image
and then place the masked image on a different background so that the existing
background shows through the masked areas. A number of PDF features are
available for achieving such masking effects (see implementation note 54 in Ap-
pendix H):
• The ImageMask entry in the image dictionary, available in all versions of PDF,
specifies that the image data is to be used as a stencil mask for painting in the
current color.
• The Mask entry in the image dictionary (PDF 1.3) may specify a separate image
XObject to be used as an explicit mask specifying which areas of the image to
paint and which to mask out.
• Alternatively, the Mask entry (PDF 1.3) may specify a range of colors to be
masked out wherever they occur within the image. This technique is known as
color key masking.
Note: Although the Mask entry is a PDF 1.3 feature, its effects are commonly simu-
lated in earlier versions of PDF by defining a clipping path enclosing only those of an
image’s samples that are to be painted. However, implementation limits can cause
errors if the clipping path is very complex (or if there is more than one clipping
path). An alternative way to achieve the effect of an explicit mask in PDF 1.2 is to
350
CHAPTER 4
Graphics
define the image being clipped as a pattern, make it the current color, and then
paint the explicit mask as an image whose ImageMask entry is true. In any case, the
PDF 1.3 features allow masked images to be placed on the page regardless of the
complexity of the clipping path.
In the transparent imaging model, a fourth type of masking effect, soft masking, is
available through the SMask entry (PDF 1.4) or the SMaskInData entry (PDF 1.5)
in the image dictionary; see Section 7.5.4, “Specifying Soft Masks,” for further
discussion.
Stencil Masking
An image mask (an image XObject whose ImageMask entry is true) is a mono-
chrome image in which each sample is specified by a single bit. However, instead
of being painted in opaque black and white, the image mask is treated as a stencil
mask that is partly opaque and partly transparent. Sample values in the image do
not represent black and white pixels; rather, they designate places on the page that
should either be marked with the current color or masked out (not marked at all).
Areas that are masked out retain their former contents. The effect is like applying
paint in the current color through a cut-out stencil, which lets the paint reach the
page in some places and masks it out in others.
An image mask differs from an ordinary image in the following significant ways:
• The image dictionary does not contain a ColorSpace entry because sample
values represent masking properties (1 bit per sample) rather than colors.
• The value of the BitsPerComponent entry must be 1.
• The Decode entry determines how the source samples are to be interpreted. If
the Decode array is [ 0 1 ] (the default for an image mask), a sample value of 0
marks the page with the current color, and a 1 leaves the previous contents un-
changed. If the Decode array is [ 1 0 ], these meanings are reversed.
One of the most important uses of stencil masking is for painting character
glyphs represented as bitmaps. Using such a glyph as a stencil mask transfers only
its “black” bits to the page, leaving the “white” bits (which are really just back-
ground) unchanged. For reasons discussed in Section 5.5.4, “Type 3 Fonts,” an
image mask, rather than an image, should almost always be used to paint glyph
bitmaps.
351
SECTION 4.8
Images
Note: If image interpolation (see “Image Interpolation” on page 346) is requested
during stencil masking, the effect is to smooth the edges of the mask, not to interpo-
late the painted color values. This effect can minimize the jaggy appearance of a
low-resolution stencil mask.
Explicit Masking
In PDF 1.3, the Mask entry in an image dictionary may be an image mask, as de-
scribed above under “Stencil Masking,” which serves as an explicit mask for the
primary (base) image. The base image and the image mask need not have the
same resolution (Width and Height values), but since all images are defined on
the unit square in user space, their boundaries on the page will coincide; that is,
they will overlay each other. The image mask indicates which places on the page
are to be painted and which are to be masked out (left unchanged). Unmasked ar-
eas are painted with the corresponding portions of the base image; masked areas
are not.
Color Key Masking
In PDF 1.3, the Mask entry in an image dictionary may alternatively be an array
specifying a range of colors to be masked out. Samples in the image that fall with-
in this range are not painted, allowing the existing background to show through.
The effect is similar to that of the video technique known as chroma-key.
For color key masking, the value of the Mask entry is an array of 2 × n integers,
[ min1 max1 … minn maxn ], where n is the number of color components in the
image’s color space. Each integer must be in the range 0 to 2BitsPerComponent − 1,
representing color values before decoding with the Decode array. An image sam-
ple is masked (not painted) if all of its color components before decoding, c1… cn ,
fall within the specified ranges (that is, if mini ≤ ci ≤ maxi for all 1 ≤ i ≤ n).
Note: When color key masking is specified, the use of a DCTDecode filter for the
stream is not recommended. DCTDecode is a lossy filter, meaning that the output is
only an approximation of the original input data. Therefore, the use of this filter can
lead to slight changes in the color values of image samples, possibly causing samples
that were intended to be masked to be unexpectedly painted instead, in colors slight-
ly different from the mask color.
352
CHAPTER 4
Graphics
4.8.6
Inline Images
As an alternative to the image XObjects described in Section 4.8.4, “Image Dic-
tionaries,” a sampled image may be specified in the form of an inline image. This
type of image is defined directly within the content stream in which it will be
painted rather than as a separate object. Because the inline format gives the appli-
cation less flexibility in managing the image data, it should be used only for small
images (4 KB or less).
An inline image object is delimited in the content stream by the operators BI
(begin image), ID (image data), and EI (end image). These operators are summa-
rized in Table 4.42. BI and ID bracket a series of key-value pairs specifying the
characteristics of the image, such as its dimensions and color space; the image
data follows between the ID and EI operators. The format is thus analogous to that
of a stream object such as an image XObject:
BI
… Key-value pairs…
ID
… Image data…
EI
TABLE 4.42 Inline image operators
OPERANDS OPERATOR DESCRIPTION
—
BI
Begin an inline image object.
—
ID
Begin the image data for an inline image object.
—
EI
End an inline image object.
Inline image objects may not be nested; that is, two BI operators may not appear
without an intervening EI to close the first object. Similarly, an ID operator may
appear only between a BI and its balancing EI. Unless the image uses
ASCIIHexDecode or ASCII85Decode as one of its filters, the ID operator should be
followed by a single white-space character, and the next character is interpreted
as the first byte of image data.
The key-value pairs appearing between the BI and ID operators are analogous to
those in the dictionary portion of an image XObject (though the syntax is differ-
ent). Table 4.43 shows the entries that are valid for an inline image, all of which
353
SECTION 4.8
Images
have the same meanings as in a stream dictionary (Table 3.4 on page 62) or an
image dictionary (Table 4.39). Entries other than those listed are ignored; in par-
ticular, the Type, Subtype, and Length entries normally found in a stream or im-
age dictionary are unnecessary. For convenience, the abbreviations shown in the
table may be used in place of the fully spelled-out keys. Table 4.44 shows addi-
tional abbreviations that can be used for the names of color spaces and filters.
Note, however, that these abbreviations are valid only in inline images; they may
not be used in image XObjects. Also note that JBIG2Decode and JPXDecode are
not listed in Table 4.44 because those filters can be applied only to image
XObjects.
TABLE 4.43 Entries in an inline image object
FULL NAME
ABBREVIATION
BitsPerComponent
BPC
ColorSpace
CS
Decode
D
DecodeParms
DP
Filter
F
Height
H
ImageMask
IM
Intent (PDF 1.1)
No abbreviation
Interpolate
I (uppercase I)
Width
W
TABLE 4.44 Additional abbreviations in an inline image object
FULL NAME
ABBREVIATION
DeviceGray
G
DeviceRGB
RGB
DeviceCMYK
CMYK
Indexed
I (uppercase I)
354
CHAPTER 4
Graphics
FULL NAME
ABBREVIATION
ASCIIHexDecode
AHx
ASCII85Decode
A85
LZWDecode
LZW
FlateDecode (PDF 1.2)
Fl (uppercase F, lowercase L)
RunLengthDecode
RL
CCITTFaxDecode
CCF
DCTDecode
DCT
The color space specified by the ColorSpace (or CS) entry may be any of the stan-
dard device color spaces (DeviceGray, DeviceRGB, or DeviceCMYK). It may not be
a CIE-based color space or a special color space, with the exception of a limited
form of Indexed color space whose base color space is a device space and whose
color table is specified by a byte string (see “Indexed Color Spaces” on page 262).
Beginning with PDF 1.2, the value of the ColorSpace entry may also be the name
of a color space in the ColorSpace subdictionary of the current resource dictio-
nary (see Section 3.7.2, “Resource Dictionaries”). In this case, the name may des-
ignate any color space that can be used with an image XObject.
Note: The names DeviceGray, DeviceRGB, and DeviceCMYK (as well as their abbre-
viations G, RGB, and CMYK) always identify the corresponding color spaces directly;
they never refer to resources in the ColorSpace subdictionary.
The image data in an inline image may be encoded by using any of the standard
PDF filters. The bytes between the ID and EI operators are treated much the same
as a stream object’s data (see Section 3.2.7, “Stream Objects”), even though they
do not follow the standard stream syntax. (This is an exception to the usual rule
that the data in a content stream is interpreted according to the standard PDF
syntax for objects.)
Example 4.30 shows an inline image 17 samples wide by 17 high with 8 bits per
component in the DeviceRGB color space. The image has been encoded using
LZW and ASCII base-85 encoding. The cm operator is used to scale it to a width
and height of 17 units in user space and position it at coordinates (298, 388). The
q and Q operators encapsulate the cm operation to limit its effect to resizing the
image.
355
SECTION 4.9
Form XObjects
Example 4.30
q
% Save graphics state
17 0 0 17 298 388 cm
% Scale and translate coordinate space
BI
% Begin inline image object
/W 17
% Width in samples
/H 17
% Height in samples
/CS /RGB
% Color space
/BPC 8
% Bits per component
/F
[ /A85 /LZW ]
% Filters
ID
% Begin image data
J1/gKA>.]AN&J?]-<HW]aRVcg*bb.\eKAdVV%/PcZ
… Omitted data…
R.s(4KE3&d&7hb*7[%Ct2HCqC~>
EI
% End inline image object
Q
% Restore graphics state
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 cir-
cumstances 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 inter-
active form (sometimes called an AcroForm), discussed in Section 8.6, “Interactive
Forms.” Whereas the form XObjects described in this section correspond to the no-
tion 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.
356
CHAPTER 4
Graphics
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 repre-
sented 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 de-
fine transparency groups and soft masks for use in the transparent imaging
model (see “Soft-Mask Dictionaries” on page 552 and Section 7.5.5, “Transpar-
ency 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 con-
tents of the form dictionary are described in Section 4.9.1, “Form Diction-
aries.”
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.
357
SECTION 4.9
Form XObjects
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 con-
tent 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 cur-
rent 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 62).
358
CHAPTER 4
Graphics
TABLE 4.45 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,
must be XObject for a form XObject.
Subtype
name
(Required) The type of XObject that this dictionary describes; must 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 defined at the time of publication 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 are 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 Section 4.2.3, “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 Sec-
tion 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 dic-
tionary 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 dictio-
nary 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.
359
SECTION 4.9
Form XObjects
KEY
TYPE
VALUE
Group
dictionary
(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.
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
Section 4.9.3, “Reference XObjects”).
Metadata
stream
(Optional; PDF 1.4) A metadata stream containing metadata for the form
XObject (see Section 10.2.2, “Metadata Streams”).
PieceInfo
dictionary
(Optional; PDF 1.3) A page-piece dictionary associated with the form
XObject (see Section 10.4, “Page-Piece Dictionaries”).
LastModified
date
(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 modi-
fication 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”).
StructParent
integer
(Required if the form XObject is a structural content item; PDF 1.3) The inte-
ger key of the form XObject’s entry in the structural parent tree (see “Finding
Structure Elements from Content Items” on page 868).
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 “Finding Structure Elements from Content
Items” on page 868).
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.
OPI
dictionary
(Optional; PDF 1.2) An OPI version dictionary for the form XObject (see
Section 10.10.6, “Open Prepress Interface (OPI)”).
360
CHAPTER 4
Graphics
KEY
TYPE
VALUE
OC
dictionary
(Optional; PDF 1.5) An optional content group or optional content member-
ship dictionary (see Section 4.10, “Optional Content”) specifying the option-
al 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.
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 Section 3.7.2, “Resource Dictionaries”).
Note: This entry is obsolescent and its use is no longer recommended. (See
implementation note 55 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
/FormType 1
/BBox [ 0 0 1000 1000 ]
/Matrix [ 1 0 0 1 0 0 ]
/Resources << /ProcSet [ /PDF ]
>>
/Length 58
>>
stream
0 0 m
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 distin-
guished by the presence of the optional Group entry in the form dictionary (see
361
SECTION 4.9
Form XObjects
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
KEY
TYPE
VALUE
Type
name
(Optional) The type of PDF object that this dictionary describes; if present, must
be Group for a group attributes dictionary.
S
name
(Required) The group subtype, which identifies the type of group whose at-
tributes 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 re-
maining 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 XOb-
ject 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 con-
tent, 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 im-
362
CHAPTER 4
Graphics
plementation note 56 in Appendix H). Those that do implement reference XOb-
jects 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 docu-
ment. 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
KEY
TYPE
VALUE
F
file specification
(Required) The file containing the target document.
Page
integer or
(Required) A page index or page label (see Section 8.3.1, “Page Labels”) iden-
text string
tifying the page of the target document containing the content to be
imported. Note that the reference is a weak one and can be inadvertently in-
validated 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 Sec-
tion 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 bound-
ing 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 import-
ed 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 corre-
spond 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.
363
SECTION 4.9
Form XObjects
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 dic-
tionary, 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 Sec-
tion 8.4, “Annotations”), all annotations that contain a printable, unhidden,
visible appearance stream (Section 8.4.4, “Appearance Streams”) must be in-
cluded 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 mean-
ingfully be incorporated into the structure of the containing document. In a
one-page target document or one made up of independent, structurally unre-
lated pages, the logical structure for the imported page may be wholly self-con-
tained; in this case, it may be possible to incorporate this structure information
into that of the containing document. However, PDF provides no mechanism
364
CHAPTER 4
Graphics
for the logical structure hierarchy of one document to refer indirectly to that of
another.
4.10
Optional Content
Optional content (PDF 1.5) refers to sections of content in a PDF document that
can be selectively viewed or hidden by document authors or consumers. This ca-
pability is useful in items such as CAD drawings, layered artwork, maps, and
multi-language documents.
The following sections describe the PDF structures used to implement optional
content:
• Section 4.10.1, “Optional Content Groups,” describes the primary structures
used to control the visibility of content.
• Section 4.10.2, “Making Graphical Content Optional,” describes how individu-
al pieces of content in a document may declare themselves as belonging to one
or more optional content groups.
• Section 4.10.3, “Configuring Optional Content,” describes how the states of op-
tional content groups are set.
4.10.1
Optional Content Groups
An optional content group is a dictionary representing a collection of graphics
that can be made visible or invisible dynamically by users of viewer applications.
The graphics belonging to such a group can reside anywhere in the document:
they need not be consecutive in drawing order, nor even belong to the same con-
tent stream. Table 4.48 shows the entries in an optional content group dictionary.
TABLE 4.48 Entries in an optional content group dictionary
KEY
TYPE
VALUE
Type
name
(Required) The type of PDF object that this dictionary describes; must be OCG
for an optional content group dictionary.
Name
text string
(Required) The name of the optional content group, suitable for presentation in
a viewer application’s user interface.
365
SECTION 4.10
Optional Content
KEY
TYPE
VALUE
Intent
name or array
(Optional) A single intent name or an array containing any combination of
names. PDF 1.5 defines two names, View and Design, that indicate the intended
use of the graphics in the group. Future versions may define others. A process-
ing application can choose to use only groups that have a specific intent and ig-
nore others.
Default value: View. See “Intent” on page 368 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 “Usage and Usage Application Dictionaries”
on page 380 for more information.
In its simplest form, each dictionary contains a Type entry and a Name for pre-
sentation in a user interface. It may also have an Intent entry that describes its in-
tended use (see “Intent” on page 368) and a Usage entry that describes the nature
of its content (see “Usage and Usage Application Dictionaries” on page 380).
Individual content elements in a document specify the optional content group or
groups that affect their visibility (see Section 4.10.2, “Making Graphical Content
Optional”). Any content whose visibility can be affected by a given optional con-
tent group is said to belong to that group.
A group is assigned a state, which is either ON or OFF. States are not themselves
part of the PDF document but can be set programmatically or through the viewer
user interface to change the visibility of content. When a document is first
opened, the groups’ states are initialized based on the document’s default config-
uration dictionary (see “Optional Content Configuration Dictionaries” on page
375).
In the typical case, content belonging to a group is visible when the group is ON
and invisible when it is OFF. In more complex cases, content can belong to multi-
ple groups, which may have conflicting states. These cases are described by the
use of optional content membership dictionaries, described in the next section.
Optional Content Membership Dictionaries
As mentioned above, content typically belongs to a single optional content group
and is visible when the group is ON and invisible when it is OFF. To express more
complex visibility policies, content should declare itself not to belong directly to
366
CHAPTER 4
Graphics
an optional content group but rather to an optional content membership dictio-
nary, whose entries are shown in Table 4.49. (Section 4.10.2 describes how con-
tent declares its membership in a group or membership dictionary.)
TABLE 4.49 Entries in an optional content membership dictionary
KEY
TYPE
VALUE
Type
name
(Required) The type of PDF object that this dictionary describes; must be OCMD
for an optional content membership dictionary.
OCGs
dictionary or
(Optional) A dictionary or array of dictionaries specifying the optional content
array
groups whose states determine the visibility of content controlled by this member-
ship dictionary.
Note: Null values or references to deleted objects are ignored. If this entry is not
present, is an empty array, or contains references only to null or deleted objects, the
membership dictionary has 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 are:
• 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 be-
low.
An optional content membership dictionary can express its visibility policy in
two ways:
• The P entry specifies 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 introduces the VE entry, which is a visibility expression that can specify
an arbitrary boolean expression for computing the visibility of content from the
states of optional content groups.
367
SECTION 4.10
Optional Content
Note: Since the VE entry is more general, if it is present and supported by the PDF
consumer software, it should be used in preference to OCGs and P. However, for
compatibility purposes, PDF creators should use OCGs and P entries where possible.
When the use of VE is necessary to express the intended behavior, OCGs and P en-
tries should also be provided to approximate the behavior in older consumer soft-
ware.
A visibility expression is an array with the following characteristics:
• Its first element is a name representing a boolean operator (And, Or, or Not).
• Subsequent elements are either optional content groups or other visibility ex-
pressions.
• If the first element is Not, it should have only one subsequent element. If the
first element is And or Or, it may have one or more subsequent elements.
• In evaluating a visibility expression, the ON state of an optional content group is
equated to the boolean value true; OFF is equated to false.
Examples 4.33 and 4.34 illustrate the use of visibility expressions.
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 en-
try is AnyOff or AllOff.
Note: 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 must 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 4.32 below. (Example 4.33 shows the equivalent policy using visibility
expressions.)
368
CHAPTER 4
Graphics
Example 4.32
<< /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 4.33
<< /Type /OCMD
/VE [/And 12 0 R 13 0 R 14 0 R]
% Visibility expression equivalent to Example 4.32.
>>
Example 4.34 shows a more complicated visibility expression based on five op-
tional content groups, represented by objects 1 through 5. It is equivalent to
“OCG 1” OR (NOT “OCG 2”) OR (“OCG 3” AND “OCG 4” AND “OCG 5”)
Example 4.34
<< /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
]
>>
Intent
The Intent entry in Table 4.48 provides a way to distinguish between different in-
tended uses of optional content. For example, many document design applica-
tions, 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 ex-
ample) than would be useful to consumers of the document. Therefore, it is pos-
sible to specify different intents for optional content groups within a single
document. A given application may decide to use only groups that are of a specif-
ic intent.
PDF 1.5 defines two intents: Design, which is intended to represent a document
designer’s structural organization of artwork, and View, which is intended for in-
369
SECTION 4.10
Optional Content
teractive use by document consumers. More intents may be added in future PDF
versions; for compatibility with future versions, PDF consumers should allow un-
recognized Intent values.
Configuration dictionaries (see “Optional Content Configuration Dictionaries”
on page 375) 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 is used in deter-
mining visibility. If there is no match, the group has no effect on visibility.
Note: If the configuration’s Intent is an empty array, no groups are used in determin-
ing visibility; therefore, all content is considered visible.
4.10.2
Making Graphical Content Optional
Graphical content in a PDF file can be made optional by specifying membership
in an optional content group or optional content membership dictionary. Two
primary mechanisms are available:
• Sections of content streams delimited by marked-content operators can be
made optional, as described in “Optional Content in Content Streams,” below.
• Form and image XObjects and annotations can be made optional in their en-
tirety by means of a dictionary entry, as described in “Optional Content in
XObjects and Annotations” on page 374.
When a piece of optional content in a PDF file is determined to be hidden, the
following occurs:
• The content is not drawn.
• Graphics state operations, such as setting the color, transformation matrix, and
clipping, are still applied. In addition, graphics state side effects that arise from
drawing operators are applied; in particular, the current text position is updat-
ed even for text wrapped in optional content. In other words, graphics state pa-
rameters that persist past the end of a marked-content section must be the
same whether the optional content is visible or not. For example, hiding a sec-
tion of optional content does not change the color of objects that do not belong
to the same optional content group.
Note: This rule also applies to operators that set state that is not strictly graphics
state; for example, BX and EX.
370
CHAPTER 4
Graphics
• Objects such as form XObjects and annotations that are 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 con-
tent stream.
Other features in PDF consuming applications, such as searching and editing,
may be affected by the ability to selectively show or hide content. Features must
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. For exam-
ple, tools to select and move annotations should honor the current on-screen vis-
ibility 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: All optional content-related PDF structures are unknown to, and hence ig-
nored by, PDF 1.4 and earlier consumers, which therefore draw and otherwise pro-
cess all content in the document.
Optional Content in Content Streams
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) can be made optional by en-
closing them between the marked-content operators BDC and EMC (see Section
10.5, “Marked Content”) with a marked-content tag of OC. In addition, a DP
marked-content operator can be placed in a page’s content stream to force a refer-
ence 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 specifies either an optional
content group or optional content membership dictionary to which the content
belongs. Because a group must be an indirect object and a membership dictio-
nary contains references to indirect objects, the property list must be a named re-
source listed in the Properties subdictionary of the current resource dictionary
(see Section 10.5.1, “Property Lists”), as shown in Examples 4.35 and 4.36.
371
SECTION 4.10
Optional Content
Note: Although the marked-content tag must be OC, other applications of marked
content are not precluded from using OC as a tag. The marked content is 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.
To avoid conflict with other features that used marked content (such as logical
structure; see Section 10.6, “Logical Structure”), the following strategy is recom-
mended:
• 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: 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 is visible; when the group is OFF, the text is hidden.
Example 4.35
% 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
Большое спасибо!
Ваше мнение очень важно для нас.
Нет комментариевНе стесняйтесь поделиться с нами вашим ценным мнением.
Текст