Repository navigation
PDF Spec 08 XObjects
Part of: PDF-Spec-08-Graphics
Navigation: PDF-Spec-08-Patterns | PDF-Spec-Index | PDF-Spec-08-Images
Each image has its own internal coordinate system, or image space . The image occupies 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 34, 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 preclude 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 35). 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 implicit transformation from image space to user space, if specified explicitly, would be described by the matrix [ 1 Ú w 0 0 -1 Ú h 0 1 ].
Figure 34 - Source Image Coordinate System
Figure 35 - 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 shall be painted. Typically, this is done within a pair of q and Q operators to
isolate the effect of the transformation, which can include translation, rotation, reflection, and skew (see 8.3, "Coordinate Systems").
EXAMPLE If the XObject subdictionary of the current resource dictionary defines the name Image1 to denote an image XObject, the code shown in this example paints the image in a rectangle whose lower-left corner is at coordinates (100, 200), that is rotated 45 degrees counter clockwise, and that is 150 units wide and 80 units high.
- q 1 0 0 1 100 200 cm 0. 7071 0. 7071 -0. 7071 0. 7071 0 0 cm 150 0 0 80 0 0 cm /Image1 Do
Q
% Save graphics state
% Translate % Rotate % Scale % Paint image % Restore graphics state
As discussed in 8.3.4, "Transformation Matrices", these three transformations 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.
An image dictionary-that is, the dictionary portion of a stream representing an image XObject-may contain the entries listed in Table 89 in addition to the usual entries common to all streams (see Table 5). There are many relationships among these entries, and the current colour 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 colour space shall cause an error.
The entries described here are appropriate for a base image -one that is invoked directly with the Do operator. Some of the entries should not be used for images used in other ways, such as for alternate images (see 8.9.5.4, "Alternate Images"), image masks (see 8.9.6, "Masked Images"), or thumbnail images (see 12.3.4, "Thumbnail Images"). Except as noted, such irrelevant entries are simply ignored by a conforming reader
Table 89 - Additional Entries Specific to an Image Dictionary
| Key | Type | Value |
|---|---|---|
| Type | name | (Optional) The type of PDF object that this dictionary describes; if present, shall be XObject for an image XObject. |
| Subtype | name | (Required) The type of XObject that this dictionary describes; shall 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 array | (Required for images, except those that use the JPXDecode filter; not allowed forbidden for image masks) The colour space in which image samples shall be specified; it can be any type of colour space except Pattern . If the image uses the JPXDecode filter, this entry may be present: • If ColorSpace is present, any colour space specifications in the JPEG2000 data shall be ignored. • If ColorSpace is absent, the colour space specifications in the JPEG2000 data shall be used. The Decode array shall also be ignored unless ImageMask is true . |
Table 89 - Additional Entries Specific to an Image Dictionary (continued)
| Key | Type | Value |
|---|---|---|
| BitsPerComponent | integer | (Required except for image masks and images that use the JPXDecode filter) The number of bits used to represent each colour component. Only a single value shall be specified; the number of bits shall be the same for all colour components. The value shall be 1, 2, 4, 8, or (in PDF 1.5) 16. If ImageMask is true , this entry is optional, but if specified, its value shall be 1. If the image stream uses a filter, the value of BitsPerComponent shall be consistent with the size of the data samples that the filter delivers. In particular, a CCITTFaxDecode or JBIG2Decode filter shall always deliver 1-bit samples, a RunLengthDecode or DCTDecode filter shall always deliver 8-bit samples, and an LZWDecode or FlateDecode filter shall deliver samples of a specified size if a predictor function is used. If the image stream uses the JPXDecode filter, this entry is optional and shall be ignored if present. The bit depth is determined by the conforming reader in the process of decoding the JPEG2000 image. |
| Intent | name | (Optional; PDF 1.1) The name of a colour rendering intent to be used in rendering the image (see 8.6.5.8, "Rendering Intents"). Default value: the current rendering intent in the graphics state. |
| ImageMask | boolean | (Optional) A flag indicating whether the image shall be treated as an image mask (see 8.9.6, "Masked Images"). If this flag is true , the value of BitsPerComponent shall be 1 and Mask and ColorSpace shall not be specified; unmasked areas shall be painted using the current nonstroking colour. Default value: false . |
| Mask | stream or array | (Optional except for image masks; not allowed for image masks; PDF 1.3) An image XObject defining an image mask to be applied to this image (see 8.9.6.3, "Explicit Masking"), or an array specifying a range of colours to be applied to it as a colour key mask (see 8.9.6.4, "Colour Key Masking"). If ImageMask is true , this entry shall not be present. |
| Decode | array | (Optional) An array of numbers describing how to map image samples into the range of values appropriate for the image's colour space (see 8.9.5.2, "Decode Arrays"). If ImageMask is true , the array shall be either [0 1] or [1 0]; otherwise, its length shall be twice the number of colour components required by ColorSpace . If the image uses the JPXDecode filter and ImageMask is false , Decode shall be ignored by a conforming reader. Default value: see 8.9.5.2, "Decode Arrays". |
| Interpolate | boolean | (Optional) A flag indicating whether image interpolation shall be performed by a conforming reader (see 8.9.5.3, "Image Interpolation"). Default value: false . |
| Alternates | array | (Optional; PDF 1.3) An array of alternate image dictionaries for this image (see 8.9.5.4, "Alternate Images"). The order of elements within the array shall have no significance. This entry shall not be present in an image XObject that is itself an alternate image. |
Table 89 - Additional Entries Specific to an Image Dictionary (continued)
| Key | Type | Value |
|---|---|---|
| SMask | stream | (Optional; PDF 1.4) A subsidiary image XObject defining a soft- mask image (see 11.6.5.3, "Soft-Mask Images") that shall 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 shall be interpreted as shape or opacity. If present, this entry shall override 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-shall remain in effect. If SMask is absent, the image shall have no associated soft mask (although the current soft mask in the graphics state may still apply). |
| SMaskInData | integer | (Optional for images that use the JPXDecode filter, meaningless otherwise; PDF 1.5) A code specifying how soft-mask information (see 11.6.5.3, "Soft-Mask Images") encoded with image samples shall be used: 0 If present, encoded soft-mask image information shall be ignored. 1 The image's data stream includes encoded soft-mask values. A conforming reader may create a soft-mask image from the information to be used as a source of mask shape or mask opacity in the transparency imaging model. 2 The image's data stream includes colour channels that have been preblended with a background; the image data also includes an opacity channel. A conforming reader may 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 model. If this entry has a nonzero value, SMask shall not be specified. See also 7.4.9, "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 7.8.3, "Resource Dictionaries"). This entry is obsolescent and shall no longer be used. |
| 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 14.7.4.4, "Finding Structure Elements from Content Items"). |
| ID | byte string | (Optional; PDF 1.3; indirect reference preferred) The digital identifier of the image's parent Web Capture content set (see 14.10.6, "Object Attributes Related to Web Capture"). |
| OPI | dictionary | (Optional; PDF 1.2) An OPI version dictionary for the image; see 14.11.7, "Open Prepress Interface (OPI)". If ImageMask is true , this entry shall be ignored. |
| Metadata | stream | (Optional; PDF 1.4) A metadata stream containing metadata for the image (see 14.3.2, "Metadata Streams"). |
| OC | dictionary | (Optional; PDF 1.5) An optional content group or optional content membership dictionary (see 8.11, "Optional Content"), specifying the optional content properties for this image XObject. Before the image is processed by a conforming reader, its visibility shall be determined based on this entry. If it is determined to be invisible, the entire image shall be skipped, as if there were no Do operator to invoke it. |
This example defines an image 256 samples wide by 256 high, with 8 bits per sample in the DeviceGray colour 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.
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 >> 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
An image's data stream is initially decomposed into integers in the domain 0 to 2 n -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 colour 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 shall contain one pair of numbers for each component in the colour space specified by the image's ColorSpace entry. The mapping for each colour component, by a conforming reader shall be a linear transformation; that is, it shall use the following formula for linear interpolation:
This formula is used to convert a value x between x min and x max to a corresponding value y between y min and y max , projecting along the line defined by the points ( x min , y min ) and ( x max , y max ).
NOTE 1 While this formula applies to values outside the domain x min to x max and does not require that x min < x max , note that interpolation used for colour conversion, such as the Decode array, does require that x min < x max and clips x values to this domain so that y = y min for all x £ x min , and y = y max for all x Š x max .
For a Decode array of the form [ D min D max ], this can be written as
where n shall be the value of BitsPerComponent
x shall be the input value, in the domain 0 to 2 n - 1
D min and D max shall be the values specified in the Decode array y is the output value, which shall be interpreted in the image's colour space
Samples with a value of 0 shall be mapped to D min , those with a value of 2 n - 1 shall be mapped to D max , and those with intermediate values shall be mapped linearly between D min and D max . Table 90 lists the default Decode arrays which shall be used with the various colour spaces by a conforming reader.
NOTE 2 For most colour spaces, the Decode arrays listed in the table map into the full range of allowed component values. For an Indexed colour space, the default Decode array ensures that component values that index a colour table are passed through unchanged.
Table 90 - Default Decode Arrays
| Colour 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 a min a max b min b max ] where a min , a max , b min , and b max correspond to the values in the Range array of the image's colour space |
Table 90 - Default Decode Arrays (continued)
| Colour Space | Decode Array |
|---|---|
| ICCBased | Same as the value of Range in the ICC profile of the image's colour space |
| Indexed | [0 N ], where N = 2 n - 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 colour component) |
- NOTE 3 It is possible to specify a mapping that inverts sample colour intensities by specifying a D min value greater than D max . For example, if the image's colour 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 2 n - 1 is mapped to 0.0 (black).
The D min and D max parameters for a colour component need not fall within the range of values allowed for that component.
- NOTE 4 For instance, if an application 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 shall be automatically adjusted to the nearest allowed value.
When the resolution of a source image is significantly lower than that of the output 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 image interpolation algorithm during rendering. Instead of painting all pixels covered by a source sample with the same colour, image interpolation attempts to produce a smooth transition between adjacent sample values.
Image interpolation is enabled by setting the Interpolate entry in the image dictionary to true . It shall be disabled by default because it may increase the time required to render the image.
- NOTE A conforming Reader may choose to not implement this feature of PDF, or may use any specific implementation of interpolation that it wishes.
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 colour 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.
A base image (that is, the image XObject referred to in a resource dictionary) may contain an Alternates entry. The value of this entry shall be an array of alternate image dictionaries specifying variant representations of the base image. Each alternate image dictionary shall contain an image XObject for one variant and shall specify its properties. Table 91 shows the contents of an alternate image dictionary.
Table 91 - 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 shall be the default version to be used for printing. At most one alternate for a given base image shall be so designated. If no alternate has this entry set to true , the base image shall be used for printing by a conforming reader. |
| OC | dictionary | (Optional; PDF 1.5) An optional content group (see 8.11.2, "Optional Content Groups") or optional content membership dictionary (see 8.11.2.2, "Optional Content Membership Dictionaries") that facilitates the selection of which alternate image to use. |
The following shows an image with a single alternate. The base image is a grayscale image, and the alternate is a high-resolution RGB image stored on a Web server.
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
In PDF 1.5, optional content (see 8.11, "Optional Content") may 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 shall be determined as follows:
- a) If the image's OC entry specifies that the base image is visible, that image shall be displayed.
- b) 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 shall be shown. (Alternate images that have no OC entry shall not be shown.)
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 colour, completely obscure any marks that may previously have existed in the same place on the page. In the graphic arts industry and page layout applications, 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:
- The ImageMask entry in the image dictionary, specifies that the image data shall be used as a stencil mask for painting in the current colour.
- The Mask entry in the image dictionary (PDF 1.3) specifies a separate image XObject which shall 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) specifies a range of colours which shall be masked out wherever they occur within the image. This technique is known as colour key masking .
- NOTE 5 Earlier versions of PDF commonly simulated masking by defining a clipping path enclosing only those of an image's samples that are to be painted. However, if the clipping path is very complex (or if there is more than one clipping path) not all conforming Readers will render the results in the same way. An alternative way to achieve the effect of an explicit mask is to define the image being clipped as a pattern, make it the current colour, and then paint the explicit mask as an image whose ImageMask entry is true .
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 11.6.5, "Specifying Soft Masks", for further discussion.
An image mask (an image XObject whose ImageMask entry is true ) is a monochrome 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 colour 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 colour 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 shall not contain a ColorSpace entry because sample values represent masking properties (1 bit per sample) rather than colours.
- The value of the BitsPerComponent entry shall be 1.
- The Decode entry determines how the source samples shall be interpreted. If the Decode array is [ 0 1 ] (the default for an image mask), a sample value of 0 shall mark the page with the current colour, and a 1
shall leave the previous contents unchanged. If the Decode array is [ 1 0 ], these meanings shall be reversed.
- NOTE 6 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 background) unchanged. For reasons discussed in 9.6.5, "Type 3 Fonts", an image mask, rather than an image, should almost always be used to paint glyph bitmaps.
If image interpolation (see 8.9.5.3, "Image Interpolation") is requested during stencil masking, the effect shall be to smooth the edges of the mask, not to interpolate the painted colour values. This effect can minimize the jaggy appearance of a low-resolution stencil mask.
In PDF 1.3, the Mask entry in an image dictionary may be an image mask, as described in sub-clause 8.9.6.2, "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 shall be 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 shall be painted and which shall be masked out (left unchanged). Unmasked areas shall be painted with the corresponding portions of the base image; masked areas shall not be.
In PDF 1.3, the Mask entry in an image dictionary may be an array specifying a range of colours to be masked out. Samples in the image that fall within this range shall not be painted, allowing the existing background to show through.
NOTE 1 The effect is similar to that of the video technique known as chroma-key.
For colour key masking, the value of the Mask entry shall be an array of 2 ¥ n integers, [ min 1 max 1 … min n max n ], where n is the number of colour components in the image's colour space. Each integer shall be in the range 0 to 2 BitsPerComponent - 1, representing colour values before decoding with the Decode array. An image sample shall be masked (not painted) if all of its colour components before decoding, c … , fall within the specified ranges (that is, if £ £ for all 1 £ i £ n ).
1 c n min i c i max i
When colour key masking is specified, the use of a DCTDecode or lossy JPXDecode filter for the stream can produce unexpected results.
- NOTE 2 DCTDecode is always a lossy filter while JPXDecode has a lossy filter option. The use of a lossy filter mean that the output is only an approximation of the original input data. Therefore, the use of this filter may lead to slight changes in the colour values of image samples, possibly causing samples that were intended to be masked to be unexpectedly painted instead, in colours slightly different from the mask colour.
As an alternative to the image XObjects described in 8.9.5, "Image Dictionaries", a sampled image may be specified in the form of an inline image . This type of image shall be defined directly within the content stream in which it will be painted rather than as a separate object. Because the inline format gives the reader less flexibility in managing the image data, it shall be used only for small images (4 KB or less).
An inline image object shall be delimited in the content stream by the operators BI (begin image), ID (image data), and EI (end image). These operators are summarized in Table 92. BI and ID shall bracket a series of key-value pairs specifying the characteristics of the image, such as its dimensions and colour space; the image data shall follow 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 92 - 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 shall not be nested; that is, two BI operators shall not appear without an intervening EI to close the first object. Similarly, an ID operator shall only appear between a BI and its balancing EI . Unless the image uses ASCIIHexDecode or ASCII85Decode as one of its filters, the ID operator shall be followed by a single white-space character, and the next character shall be 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 different). Table 93 shows the entries that are valid for an inline image, all of which shall have the same meanings as in a stream dictionary (see Table 5) or an image dictionary (see Table 89). Entries other than those listed shall be ignored; in particular, the Type , Subtype , and Length entries normally found in a stream or image dictionary are unnecessary. For convenience, the abbreviations shown in the table may be used in place of the fully spelled-out keys. Table 94 shows additional abbreviations that can be used for the names of colour spaces and filters.
These abbreviations are valid only in inline images; they shall not be used in image XObjects. JBIG2Decode and JPXDecode are not listed in Table 94 because those filters shall not be used with inline images.
Table 93 - 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 94 - Additional Abbreviations in an Inline Image Object
| Full Name | Abbreviation |
|---|---|
| DeviceGray | G |
| DeviceRGB | RGB |
Table 94 - Additional Abbreviations in an Inline Image Object (continued)
| Full Name | Abbreviation |
|---|---|
| DeviceCMYK | CMYK |
| Indexed | I (uppercase I) |
| ASCIIHexDecode | AHx |
| ASCII85Decode | A85 |
| LZWDecode | LZW |
| FlateDecode (PDF 1.2) | Fl (uppercase F, lowercase L) |
| RunLengthDecode | RL |
| CCITTFaxDecode | CCF |
| DCTDecode | DCT |
The colour space specified by the ColorSpace (or CS ) entry shall be one of the standard device colour spaces ( DeviceGray , DeviceRGB , or DeviceCMYK ). It shall not be a CIE-based colour space or a special colour space, with the exception of a limited form of Indexed colour space whose base colour space is a device space and whose colour table is specified by a byte string (see 8.6.6.3, "Indexed Colour Spaces"). Beginning with PDF 1.2, the value of the ColorSpace entry may also be the name of a colour space in the ColorSpace subdictionary of the current resource dictionary (see 7.8.3, "Resource Dictionaries"). In this case, the name may designate any colour space that can be used with an image XObject.
- NOTE 1 The names DeviceGray , DeviceRGB , and DeviceCMYK (as well as their abbreviations G , RGB , and CMYK ) always identify the corresponding colour 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 except JPXDecode and JBIG2Decode. The bytes between the ID and EI operators shall be treated the same as a stream object's data (see 7.3.8, "Stream Objects"), even though they do not follow the standard stream syntax.
- NOTE 2 This is an exception to the usual rule that the data in a content stream shall be interpreted according to the standard PDF syntax for objects.
- EXAMPLE This example shows an inline image 17 samples wide by 17 high with 8 bits per component in the DeviceRGB colour 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.
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 % Colour 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
A form XObject is a PDF content stream that is a self-contained description of any sequence of graphics objects (including path objects, text objects, and sampled images). A form XObject may be painted multiple times-either on several pages or at several locations on the same page-and produces the same results each time, subject only to the graphics state at the time it is invoked. Not only is this shared definition economical to represent in the PDF file, but under suitable circumstances the conforming reader can optimize execution by caching the results of rendering the form XObject for repeated reuse.
- NOTE 1 The term form also refers to a completely different kind of object, an interactive form (sometimes called an AcroForm ), discussed in 12.7, "Interactive Forms". Whereas the form XObjects described in this sub-clause correspond to the notion of forms in the PostScript language, interactive forms are the PDF equivalent of the familiar paper instrument. Any unqualified use of the word form is understood to refer to an interactive form; the type of form described here is always referred to explicitly as a form XObject .
Form XObjects have various uses:
- As its name suggests, a form XObject may serve as the template for an entire page.
EXAMPLE A program that prints filled-in tax forms can first paint the fixed template as a form XObject and then paint the variable information on top of it.
- Any graphical element that is to be used repeatedly, such as a company logo or a standard component in the output from a computer-aided design system, may be defined as a form XObject.
- Certain document elements that are not part of a page's contents, such as annotation appearances (see 12.5.5, "Appearance Streams"), shall be represented as form XObjects.
- A specialized type of form XObject, called a group XObject (PDF 1.4) , can be used to group graphical elements together as a unit for various purposes (see 8.10.3, "Group XObjects"). In particular, group XObjects shall be used to define transparency groups and soft masks for use in the transparent imaging model (see 11.6.5.2, "Soft-Mask Dictionaries" and 11.6.6, "Transparency Group XObjects").
- Another specialized type of form XObject, a reference XObject (PDF 1.4) , may be used to import content from one PDF document into another (see 8.10.4, "Reference XObjects").
A writer shall perform the following two specific operations in order to use a form XObject:
- a) Define the appearance of the form XObject . A form XObject is a PDF content stream. The dictionary portion of the stream (called the form dictionary ) shall contain descriptive information about the form XObject; the body of the stream shall describe the graphics objects that produce its appearance. The contents of the form dictionary are described in 8.10.2, "Form Dictionaries".
- b) Paint the form XObject . The Do operator (see 8.8, "External Objects") shall paint a form XObject whose name is supplied as an operand. The name shall be defined in the XObject subdictionary of the current resource dictionary. Before invoking this operator, the content stream in which it appears should set appropriate parameters in the graphics state. In particular, it should alter the current transformation matrix to control the position, size, and orientation of the form XObject in user space.
Each form XObject is defined in its own coordinate system, called form space . The BBox entry in the form dictionary shall be expressed in form space, as shall be any coordinates used in the form XObject's content stream, such as path coordinates. The Matrix entry in the form dictionary shall specify the mapping from form space to the current user space. Each time the form XObject is painted by the Do operator, this matrix shall be concatenated with the current transformation matrix to define the mapping from form space to device space.
- NOTE 2 This differs from the Matrix entry in a pattern dictionary, which maps pattern space to the initial user space of the content stream in which the pattern is used.
When the Do operator is applied to a form XObject, a conforming reader shall perform the following tasks:
- a) Saves the current graphics state, as if by invoking the q operator (see 8.4.4, "Graphics State Operators")
- b) Concatenates the matrix from the form dictionary's Matrix entry with the current transformation matrix (CTM)
- c) Clips according to the form dictionary's BBox entry
- d) Paints the graphics objects specified in the form's content stream
- e) Restores the saved graphics state, as if by invoking the Q operator (see 8.4.4, "Graphics State Operators")
Except as described above, the initial graphics state for the form shall be inherited from the graphics state that is in effect at the time Do is invoked.
Every form XObject shall have a form type , which determines the format and meaning of the entries in its form dictionary. This specification only defines one form type, Type 1. Form XObject dictionaries may contain the entries shown in Table 95, in addition to the usual entries common to all streams (see Table 5).
Table 95 - Additional Entries Specific to a Type 1 Form Dictionary
| Key | Type | Value |
|---|---|---|
| Type | name | (Optional) The type of PDF object that this dictionary describes; if present, shall be XObject for a form XObject. |
| Subtype | name | (Required) The type of XObject that this dictionary describes; shall be Form for a form XObject. |
| FormType | integer | (Optional) A code identifying the type of form XObject that this dictionary describes. The only valid value is 1. Default value: 1. |
| BBox | rectangle | (Required) An array of four numbers in the form coordinate system (see above), giving the coordinates of the left, bottom, right, and top edges, respectively, of the form XObject's bounding box. These boundaries shall be used to clip the form XObject and to determine its size for caching. |
| Matrix | array | (Optional) An array of six numbers specifying the form matrix , which maps form space into user space (see 8.3.4, "Transformation Matrices"). Default value: the identity matrix [1 0 0 1 0 0]. |
| Resources | dictionary | (Optional but strongly recommended; PDF 1.2) A dictionary specifying any resources (such as fonts and images) required by the form XObject (see 7.8, "Content Streams and Resources"). In a PDF whose version is 1.1 and earlier, all named resources used in the form XObject shall be included in the resource dictionary of each page object on which the form XObject appears, regardless of whether they also appear in the resource dictionary of the form XObject. These resources should also be specified in the form XObject's resource dictionary as well, to determine which resources are used inside the form XObject. If a resource is included in both dictionaries, it shall have the same name in both locations. In PDF 1.2 and later versions, form XObjects may be independent of the 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 shall contain all named resources used by the form XObject. These resources shall not be promoted to the outer content stream's resource dictionary, although that stream's resource dictionary refers to the form XObject. |
Table 95 - Additional Entries Specific to a Type 1 Form Dictionary (continued)
| Key | Type | Value |
|---|---|---|
| Group | dictionary | (Optional; PDF 1.4) A group attributes dictionary indicating that the contents of the form XObject shall be treated as a group and specifying the attributes of that group (see 8.10.3, "Group XObjects"). If a Ref entry (see below) is present, the group attributes shall also apply to the external page imported by that entry, which allows such an imported page to be treated as a group without further modification. |
| Ref | dictionary | (Optional; PDF 1.4) A reference dictionary identifying a page to be imported from another PDF file, and for which the form XObject serves as a proxy (see 8.10.4, "Reference XObjects"). |
| Metadata | stream | (Optional; PDF 1.4) A metadata stream containing metadata for the form XObject (see 14.3.2, "Metadata Streams"). |
| PieceInfo | dictionary | (Optional; PDF 1.3) A page-piece dictionary associated with the form XObject (see 14.5, "Page-Piece Dictionaries"). |
| LastModified | date | (Required if PieceInfo is present; optional otherwise; PDF 1.3) The date and time (see 7.9.4, "Dates") when the form XObject's contents were most recently modified. If a page-piece dictionary ( PieceInfo ) is present, the modification date shall be used to ascertain which of the application data dictionaries it contains correspond to the current content of the form (see 14.5, "Page-Piece Dictionaries"). |
| StructParent | integer | (Required if the form XObject is a structural content item; PDF 1.3) The integer key of the form XObject's entry in the structural parent tree (see 14.7.4.4, "Finding Structure Elements from Content Items"). |
| StructParents | integer | (Required if the form XObject contains marked-content sequences that are structural content items; PDF 1.3) The integer key of the form XObject's entry in the structural parent tree (see 14.7.4.4, "Finding Structure Elements from Content Items"). At most one of the entries StructParent or StructParents shall be present. A form XObject shall be either a content item in its entirety or a container for marked-content sequences that are content items, but not both. |
| OPI | dictionary | (Optional; PDF 1.2) An OPI version dictionary for the form XObject (see 14.11.7, "Open Prepress Interface (OPI)"). |
| OC | dictionary | (Optional; PDF 1.5) An optional content group or optional content membership dictionary (see 8.11, "Optional Content") specifying the optional content properties for the form XObject. Before the form is processed, its visibility shall be determined based on this entry. If it is determined to be invisible, the entire form shall be skipped, as if there were no Do operator to invoke it. |
| Name | name | (Required in PDF 1.0; optional otherwise) The name by which this form XObject is referenced in the XObject subdictionary of the current resource dictionary (see 7.8.3, "Resource Dictionaries"). NOTE This entry is obsolescent and its use is no longer |
EXAMPLE The following shows a simple form XObject that paints a filled square 1000 units on each side.
6 0 obj
% Form XObject
<< /Type /XObject /Subtype /Form /FormType 1 /BBox [ 0 0 1000 1000 ] /Matrix [ 1 0 0 1 0 0 ] /Resources << /ProcSet [ /PDF ] >>
/Length 58 >> stream 0 0 m 0 1000 l 1000 1000 l 1000 0 l f endstream endobj
A group XObject (PDF 1.4) is a special type of form XObject that can be used to group graphical elements together as a unit for various purposes. It shall be distinguished by the presence of the optional Group entry in the form dictionary (see 8.10.2, "Form Dictionaries"). The value of this entry shall be a subsidiary group attributes dictionary describing the properties of the group.
As shown in Table 96, every group XObject shall have a group subtype (specified by the S entry in the group attributes dictionary) that determines the format and meaning of the dictionary's remaining entries. This specification only defines one subtype, a transparency group XObject (subtype Transparency ) representing a transparency group for use in the transparent imaging model (see 11.4, "Transparency Groups"). The remaining contents of this type of dictionary are described in 11.6.6, "Transparency Group XObjects".
Table 96 - Entries Common to all Group Attributes Dictionaries
| Key | Type | Value |
|---|---|---|
| Type | name | (Optional) The type of PDF object that this dictionary describes; if present, shall be Group for a group attributes dictionary. |
| S | name | (Required) The group subtype , which identifies the type of group whose attributes this dictionary describes and determines the format and meaning of the dictionary's remaining entries. The only group subtype defined is Transparency ; see 11.6.6, "Transparency Group XObjects", for the remaining contents of this type of dictionary. |
Reference XObjects (PDF 1.4) enable one PDF document to import content from another. The document in which the reference occurs is called the containing document ; the one whose content is being imported is the target document . The target document may reside in a file external to the containing document or may be included within it as an embedded file stream (see 7.11.4, "Embedded File Streams").
Navigation: PDF-Spec-08-Patterns | PDF-Spec-Index | PDF-Spec-08-Images