PDF20 Spec 07 Extensions

7.12 Extensions Dictionary

Part of: PDF20-Spec-07-Syntax

Navigation: PDF20-Spec-07-Functions | PDF20-Spec-Index | Next →

ISO 32000-2:2020(E)

Type

Description

Subclause

integer

Integer number

7.3.3

name

Name object

7.3.5

name tree

Name tree (dictionary)

7.9.6

null

Null object

7.3.9

number

Number (integer or real)

7.3.3

number tree

Number tree (dictionary)

7.9.7

PDFDocEncoded string

Bytes containing a string that shall be encoded using PDFDocEncoding

7.9.2 7.9.2.3

rectangle

Rectangle (array)

7.9.5

stream

Stream object

7.3.8

string

Any string that is not a text string. Beginning with PDF 1.7, this type is further qualified as the types: ASCII string and byte string.

7.9.2

text string

Bytes that represent characters that 7.9.2 shall be encoded using either 7.9.2.2 PDFDocEncoding, UTF-16BE or UTF8 (as defined in 7.9.2.2, "Text string type".)

text stream

Text stream

7.9.3

7.9.2 String object types 7.9.2.1

General

PDF supports one fundamental string object (see 7.3.4, "String objects"). The string object shall be further qualified as a text string, ASCII string, or byte string. The further qualification reflects the encoding used to represent the characters or glyphs described by the string. The string types described in "Table 35 — PDF data types" specify increasingly specific encoding schemes, as shown in "Figure 7 — Relationship between string types".

115

ISO 32000-2:2020(E)

Figure 7 — Relationship between string types

7.9.2.2

Text string type

7.9.2.2.1

General

The text string type shall be used for character strings that contain information intended to be humanreadable, such as text annotations, document outline item names, article names, and so forth. NOTE 1

Text string type is a subtype of string type and represents data encoded using specific conventions.

The text string type shall be used for character strings that shall be encoded in PDFDocEncoding, the UTF-16BE Unicode character encoding scheme, or (PDF 2.0) the UTF-8 Unicode character encoding scheme. PDFDocEncoding can encode all of the ISO Latin 1 character set and is documented in Annex D, "Character sets and encodings". UTF-16BE and UTF-8 can encode all Unicode characters. UTF-16BE, UTF-8 and Unicode character encoding are described in The Unicode Standard by the Unicode Consortium. EXAMPLE 1

A PDF dictionary containing key ‘Key’ with the value that is the text string "text‰" will look like

<</Key(text?)>>

where the character ‘?’ after the ‘text’ is represented by the hex code 8B (octal code 213 - that is according to "D.2 Latin character set and encodings").

NOTE 2

PDFDocEncoding does not support all Unicode characters whereas UTF-16BE and UTF-8 do.

For text strings encoded in UTF-16BE, the first two bytes shall be 254 followed by 255. These two bytes represent the Unicode byte order marker, ZERO WIDTH NO-BREAK SPACE (U+FEFF), indicating that the string is encoded in the UTF-16BE (big-endian) encoding scheme specified in Unicode. EXAMPLE 2

A PDF dictionary containing key ‘Key’ with the value that is the text string "тест" (that is what the word in Russian with the translation to English as ‘test’) will look like

<</Key(??????????)>>

where the characters in parentheses is the sequence of bytes with hex codes FE, FF, 04, 42, 04, 35, 04, 41, 04, 42.

NOTE 3

This mechanism precludes beginning a string using PDFDocEncoding with the two characters thorn ydieresis, which is unlikely to be a meaningful beginning of a word or phrase.

For text strings encoded in UTF-8, the first three bytes shall be 239 followed by 187, followed by 191. These three bytes represent the Unicode byte order marker indicating that the string is encoded in the UTF-8 encoding scheme specified in Unicode. 116

ISO 32000-2:2020(E)

NOTE 4

This mechanism precludes beginning a string using PDFDocEncoding with the three characters dieresis, guillemotright, questiondown, which is unlikely to be a meaningful beginning of a word or phrase.

PDF readers that process PDF files containing Unicode text strings shall be prepared to handle supplementary characters; that is, characters requiring more than two bytes to represent. NOTE 5

7.9.2.2.2

It is important not to confuse UTF-16BE with UCS2 (i.e. wchar_t). UTF-16 is not a fixed width encoding scheme.

Text string language escape sequences

Escape sequences may appear anywhere in a Unicode text string to indicate the language in which subsequent text shall be written. NOTE 1

This is useful when the language cannot be determined from the character codes used in the text.

The escape sequence shall consist of the following elements, in order: a) The Unicode value ESCAPE (U+001B) (that is, for strings encoded in UTF-16BE, the byte sequence 0 followed by 27; for strings encoded in UTF-8 the byte value 27). b) A 2- byte BCP 47 language code. EXAMPLE 1

en for English or ja for Japanese encoded as ASCII characters.

c) (Optional) A 2-byte ISO 3166 country code. EXAMPLE 2

US for the United States or JP for Japan encoded as ASCII characters.

d) The Unicode value ESCAPE (U+001B). NOTE 2

The complete list of codes defined by BCP 47 and ISO 3166 can be obtained from the Internet Engineering Task Force and the International Organization for Standardization.

NOTE 3

Since Unicode defines an escape sequence for indicating the language of the text, this mechanism enables the alternate description to change from the language specified by the prevailing Lang entry.

7.9.2.3

PDFDocEncoded string type

A PDFDocEncoded string is a character string in which the characters shall be represented in a single byte using PDFDocEncoding. NOTE

7.9.2.4

PDFDocEncoding does not support all Unicode characters whereas UTF-16BE or UTF-8 do.

Byte string type

The byte string type shall be used for binary data that shall be represented as a series of bytes, where each byte may be any value representable in 8 bits. Byte string type is a subtype of string type. For example, byte strings are used to define a file identifier (see 14.4, "File identifiers") that is specified in ID entry of PDF file trailer (see "Table 15 — Entries in the file trailer dictionary"). In such case byte string is written in hexadecimal form (see 7.3.4.3, "Hexadecimal strings") and looks like NOTE

The string can represent characters but the encoding is not known. The bytes of the string do not have to represent characters.

117

ISO 32000-2:2020(E)

7.9.3 Text streams A text stream (PDF 1.5) shall be a PDF stream object (7.3.8, "Stream objects") whose unencoded bytes shall meet the same requirements as a text string (7.9.2.2, "Text string type") with respect to encoding, byte order, and lead bytes.

7.9.4 Dates Date values used in a PDF shall conform to a standard date format, which closely follows that of the international standard ASN.1 (Abstract Syntax Notation One), defined in ISO/IEC 8824-1. A date shall be a text string value containing no white-space, of the form: (D:YYYYMMDDHHmmSSOHH'mm) where: YYYY shall be the year MM shall be the month (01–12) DD shall be the day (01–31) HH shall be the hour (00–23) mm shall be the minute (00–59) SS shall be the second (00–59) O shall be the relationship of local time to Universal Time (UT), and shall be denoted by one of the characters PLUS SIGN (U+002B) (+), HYPHEN-MINUS (U+002D) (-), or LATIN CAPITAL LETTER Z (U+005A) (Z) (see below) HH followed by APOSTROPHE (U+0027) (') shall be the absolute value of the offset from UT in hours (00–23) mm shall be the absolute value of the offset from UT in minutes (00–59) The prefix “D:” shall be present, the year field (YYYY) shall be present and all other fields may be present but only if all of their preceding fields are also present. The APOSTROPHE following the hour offset field (HH) shall only be present if the HH field is present. The minute offset field (mm) shall only be present if the APOSTROPHE following the hour offset field (HH) is present. The default values for MM and DD shall be both 01; all other numerical fields shall default to zero values. A PLUS SIGN as the value of the O field signifies that local time is now and later than UT, a HYPHEN-MINUS signifies that local time is earlier than UT, and the LATIN CAPITAL LETTER Z signifies that local time is equal to UT. If no UT information is specified, the relationship of the specified time to UT shall be considered to be GMT. Regardless of whether the time zone is specified, the rest of the date shall be specified in local time. EXAMPLE

For example, December 23, 1998, at 7:52 PM, U.S. Pacific Standard Time, is represented by the string:

D:199812231952-08'00

NOTE 1

118

A date string can be any valid PDF string object as described in 7.3.4, "String objects". The description above relates to the text string value after appropriate processing. © ISO 2020 – All rights reserved

ISO 32000-2:2020(E)

NOTE 2

PDF versions up to and including 1.7 defined a date string to include a terminating apostrophe. PDF processors are recommended to accept date strings that still follow that convention.

NOTE 3

The letter Z can optionally be followed by hour and minute offsets, which are zero in this case.

7.9.5 Rectangles Rectangles are used to describe locations on a page and bounding boxes for a variety of objects. A rectangle shall be written as an array of four numbers giving the coordinates of a pair of diagonally opposite corners. Typically, the array takes the form [llx lly urx ury] specifying the lower-left x, lower-left y, upper-right x, and upper-right y coordinates of the rectangle, in that order. The other two corners of the rectangle are then assumed to have coordinates (llx, ury) and (urx, lly). NOTE

Rectangles can have a width of zero or height of zero.

7.9.6 Name trees A name tree serves a similar purpose to a dictionary — associating keys and values — but by different means. A name tree differs from a dictionary in the following important ways: •

Unlike the keys in a dictionary, which are name objects, those in a name tree are strings.

•

The keys are ordered.

•

The values associated with the keys may be objects of any type. Stream objects shall be specified by indirect object references (7.3.8, "Stream objects"). The dictionary, array, and string objects should be specified by indirect object references, and other PDF objects (null objects, numbers, booleans, and names) should be specified as direct objects.

•

The data structure can represent an arbitrarily large collection of key-value pairs, which can be looked up efficiently without requiring the entire data structure to be read from the PDF file. (In contrast, a dictionary can be subject to an implementation limit on the number of entries it can contain.)

A name tree shall be constructed of nodes, each of which shall be a dictionary object. "Table 36 — Entries in a name tree node dictionary" shows the entries in a node dictionary. The nodes shall be of three kinds, depending on the specific entries they contain. The tree shall always have exactly one root node, which shall contain a single entry: either Kids or Names but not both. If the root node has a Names entry, it shall be the only node in the tree. If it has a Kids entry, each of the remaining nodes shall be either an intermediate node, that shall contain a Limits entry and a Kids entry, or a leaf node, that shall contain a Limits entry and a Names entry.

119

ISO 32000-2:2020(E)

Table 36 — Entries in a name tree node dictionary Key

Type

Value

Kids

array

(Root and intermediate nodes only; required in intermediate nodes; present in the root node if and only if Names is not present) Shall be an array of indirect references to the immediate children of this node. The children may be intermediate or leaf nodes.

Names

array

(Root and leaf nodes only; required in leaf nodes; present in the root node if and only if Kids is not present) Shall be an array of the form [key1 value1 key2 value2 …keyn valuen] where each keyi shall be a string and the corresponding valuei shall be the object associated with that key. The keys shall be sorted in lexical order, as described below.

Limits

array

(Required for intermediate and leaf nodes; not permitted in root nodes) Shall be an array of two strings, that shall specify the (lexically) least and greatest keys included in the Names array of a leaf node or in the Names arrays of any leaf nodes that are descendants of an intermediate node.

The Kids entries in the root and intermediate nodes define the tree’s structure by identifying the immediate children of each node. The Names entries in the leaf (or root) nodes shall contain the tree’s keys and their associated values, arranged in key-value pairs and shall be sorted lexically in ascending order by key. Shorter keys shall appear before longer ones beginning with the same byte sequence. Any encoding of the keys may be used as long as it is self-consistent; keys shall be compared for equality on a simple byte-by-byte basis. The keys contained within the various nodes’ Names entries shall not overlap; each Names entry shall contain a single contiguous range of all the keys in the tree. In a leaf node, the Limits entry shall specify the least and greatest keys contained within the node’s Names entry. In an intermediate node, it shall specify the least and greatest keys contained within the Names entries of any of that node’s descendants. The value associated with a given key can thus be found by walking the tree in order, searching for the leaf node whose Names entry contains that key. EXAMPLE 1

The following is an abbreviated outline, showing object numbers and nodes, of a name tree that maps the names of all the chemical elements, from actinium to zirconium, to their atomic numbers.

Example of a name tree 1: Root node 2: Intermediate node: Actinium to Gold 5: Leaf node: Actinium = 25,…, Astatine = 31 25: Integer: 89 … 31: Integer: 85 … 11: Leaf node: Gadolinium = 56,…, Gold = 59 56: Integer: 64 … 59: Integer: 79 3: Intermediate node: Hafnium to Protactinium 12: Leaf node: Hafnium = 60,…, Hydrogen = 65 60: Integer: 72

120

ISO 32000-2:2020(E)

… 65: Integer: 1 … 19: Leaf node: Palladium = 92,…, Protactinium = 100 92: Integer: 46 … 100:Integer: 91 4: Intermediate node: Radium to Zirconium 20: Leaf node: Radium = 101,…, Ruthenium = 107 101:Integer: 89 … 107:Integer: 85 … 24: Leaf node: Xenon = 129,…, Zirconium = 133 129:Integer: 54 … 133:Integer: 40

EXAMPLE 2

The following shows the representation of this tree in a PDF file:

1 0 obj <</Kids [2 0 R 3 0 R 4 0 R ]

endobj 2 0 obj <</Limits [(Actinium) (Gold)] /Kids [5 0 R 6 0 R 7 0 R 8 0 R 9 0 R 10 0 R 11 0 R ]

endobj 3 0 obj <</Limits [(Hafnium) (Protactinium)] /Kids [12 0 R 13 0 R 14 0 R 15 0 R 16 0 R 17 0 R 18 0 R 19 0 R ]

endobj 4 0 obj <</Limits [(Radium) (Zirconium)] /Kids [20 0 R 21 0 R 22 0 R 23 0 R 24 0 R ]

endobj

%Root node

%Intermediate node

121

ISO 32000-2:2020(E)

5 0 obj <</Limits [(Actinium) (Astatine)] /Names [(Actinium) 25 0 R (Aluminum) 26 0 R (Americium) 27 0 R (Antimony) 28 0 R (Argon) 29 0 R (Arsenic) 30 0 R (Astatine) 31 0 R ]

endobj … 24 0 obj <</Limits [(Xenon) (Zirconium)] /Names [(Xenon) 129 0 R (Ytterbium) 130 0 R (Yttrium) 131 0 R (Zinc) 132 0 R (Zirconium) 133 0 R ]

endobj 25 0 obj 89 endobj … 133 0 obj 40 endobj

`

%Leaf node

%Atomic number (Actinium)

%Atomic number (Zirconium)

7.9.7 Number trees A number tree is similar to a name tree (see 7.9.6, "Name trees"), except that its keys shall be integers instead of strings and shall be sorted in ascending numerical order. The entries in the leaf (or root) nodes containing the key-value pairs shall be named Nums instead of Names as in a name tree. "Table 37 — Entries in a number tree node dictionary" shows the entries in a number tree’s node dictionaries. Table 37 — Entries in a number tree node dictionary Key

Type

Value

Kids

array

(Root and intermediate nodes only; required in intermediate nodes; present in the root node if and only if Nums is not present) Shall be an array of indirect references to the immediate children of this node. The children may be intermediate or leaf nodes.

Nums

array

(Root and leaf nodes only; shall be required in leaf nodes; present in the root node if and only if Kids is not present) Shall be an array of the form: [key1 value1 key2 value2 …keyn valuen] where each keyi is an integer and the corresponding valuei shall be the object associated with that key. The keys shall be sorted in numerical order, analogously to the arrangement of keys in a name tree as described in 7.9.6, "Name trees".

122

ISO 32000-2:2020(E)

Key

Type

Value

Limits

array

(Shall be present in Intermediate and leaf nodes only) Shall be an array of two integers, that shall specify the (numerically) least and greatest keys included in the Nums array of a leaf node or in the Nums arrays of any leaf nodes that are descendants of an intermediate node.

7.10 Functions 7.10.1

General

PDF is not a programming language, and a PDF file is not a program. However, PDF provides several types of function objects (PDF 1.2) that represent parameterised classes of functions, including mathematical formulas and sampled representations with arbitrary resolution. NOTE 1

Functions can be used in various ways in PDF, including device-dependent rasterization information for high-quality printing (halftone spot functions and transfer functions), colour transform functions for certain colour spaces, and specification of colours as a function of position for smooth shadings.

Functions in PDF represent static, self-contained numerical transformations. NOTE 2

A function to add two numbers has two input values and one output value:

𝑓(𝑥0 , 𝑥1 ) = 𝑥0 + 𝑥1 Similarly, a function that computes the arithmetic and geometric mean of two numbers can be viewed as a function of two input values and two output values: 𝑓(𝑥0 , 𝑥1 ) =

𝑥0 + 𝑥1 , √𝑥0 × 𝑥1 2

In general, a function can take any number (m) of input values and produce any number (n) of output values: 𝑓(𝑥0 , … , 𝑥𝑚−1 ) = 𝑦0 , … , 𝑦𝑛−1 In PDF functions, all the input values and all the output values shall be numbers, and functions shall have no side effects. Each function definition includes a domain, the set of valid values for the input. Some types of functions also define a range, the set of valid values for the output. Input values passed to the function shall be clipped to the domain, and output values produced by the function shall be clipped to the range. EXAMPLE

Suppose the following function is defined with a domain of [-1 1]. If the function is called with the input value 6, that value is replaced with the nearest value in the defined domain, 1, before the function is evaluated; the resulting output value is therefore 3.

123

ISO 32000-2:2020(E)

passed to the function (and are within its domain), then the output value produced by the function, -14, is replaced with 0, the nearest value in the defined range. 𝑓(𝑥0 , 𝑥1 ) = 3 × 𝑥0 + 𝑥1 A function object may be a dictionary or a stream, depending on the type of function. The term function dictionary is used generically in this subclause to refer to either a dictionary object or the dictionary portion of a stream object. A function dictionary specifies the function’s representation, the set of attributes that parameterize that representation, and the additional data needed by that representation. Four types of functions are available, as indicated by the dictionary’s FunctionType entry: •

(PDF 1.2) A sampled function (Type 0) uses a table of sample values to define the function. Various techniques are used to interpolate values between the sample values; see 7.10.2, "Type 0 (sampled) functions"

•

(PDF 1.3) An exponential interpolation function (Type 2) defines a set of coefficients for an exponential function; see 7.10.3, "Type 2 (exponential interpolation) functions"

•

(PDF 1.3) A stitching function (Type 3) is a combination of other functions, partitioned across a domain; see 7.10.4, "Type 3 (stitching) functions"

•

(PDF 1.3) A PostScript calculator function (Type 4) uses operators from the PostScript language to describe an arithmetic expression; see 7.10.5, "Type 4 (PostScript calculator) functions"

All function dictionaries shall share the entries listed in "Table 38 — Entries common to all function dictionaries". Table 38 — Entries common to all function dictionaries Key

124

Type

Value

FunctionType integer

(Required) The function type: 0 Sampled function 2 Exponential interpolation function 3 Stitching function 4 PostScript calculator function

Domain

array

(Required) An array of 2 × m numbers, where m shall be the number of input values. For each i from 0 to m - 1, Domain2i shall be less than or equal to Domain2i+1, and the ith input value, xi, shall lie in the interval Domain2i ≤ xi ≤ Domain2i+1 . Input values outside the declared domain shall be clipped to the nearest boundary value.

Range

array

(Required for Type 0 and Type 4 functions, optional otherwise; see below) An array of 2 × n numbers, where n shall be the number of output values. For each j from 0 to n - 1, Range2j shall be less than or equal to Range2j+1, and the jth output value, yj, shall lie in the interval Range2j ≤ yj ≤ Range2j+1. Output values outside the declared range shall be clipped to the nearest boundary value. If this entry is absent, no clipping shall be done (subject to implementation limits).

ISO 32000-2:2020(E)

In addition, each type of function dictionary shall include entries appropriate to the particular function type. The number of output values can usually be inferred from other attributes of the function; if not (as is always the case for Type 0 and Type 4 functions), the Range entry is required. The dimensionality of the function implied by the Domain and Range entries shall be consistent with that implied by other attributes of the function. 𝑦 = Interpolate(𝑥, 𝑥min , 𝑥max , 𝑦min , 𝑦max ) 𝑦

−𝑦

= 𝑦min + ((𝑥 − 𝑥min ) × 𝑥max −𝑥min ) max

min

For a given value of x, Interpolate calculates the y value on the line defined by the two points (xmin, ymin) and (xmax, ymax).

7.10.2

Type 0 (sampled) functions

Type 0 functions use a sequence of sample values (contained in a stream) to provide an approximation for functions whose domains and ranges are bounded. The samples are organised as an m-dimensional table in which each entry has n components. NOTE 1

Sampled functions are highly general and offer reasonably accurate representations of arbitrary analytic functions at low expense. For example, a 1-input sinusoidal function can be represented over the range [0 180] with an average error of only 1 percent, using just ten samples and linear interpolation. Two-input functions require significantly more samples but usually not a prohibitive number if the function does not have high frequency variations.

There shall be no dimensionality limit of a sampled function except for possible implementation limits. NOTE 2

The number of samples required to represent functions with high dimensionality multiplies rapidly unless the sampling resolution is very low. Also, the process of multilinear interpolation becomes computationally intensive if the number of inputs m is greater than 2. The multidimensional spline interpolation is even more computationally intensive.

In addition to the entries in "Table 38 — Entries common to all function dictionaries", a Type 0 function dictionary includes those shown in "Table 39 — Additional entries specific to a Type 0 function dictionary". The Domain, Encode, and Size entries determine how the function’s input variable values are mapped into the sample table. For example, if Size is [21 31], the default Encode array shall be [0 20 0 30], which maps the entire domain into the full set of sample table entries. Other values of Encode may be used. The interpolate function (7.10.1, "General") explains the relationship between Domain, Encode, Size, Decode, and Range. Table 39 — Additional entries specific to a Type 0 function dictionary Key

Type

Value

Size

array

(Required) An array of m positive integers that shall specify the number of samples in each input dimension of the sample table.

125

ISO 32000-2:2020(E)

Key

Type

Value

BitsPerSample

integer

(Required) The number of bits that shall represent each sample. (If the function has multiple output values, each one shall occupy BitsPerSample bits.) Valid values shall be 1, 2, 4, 8, 12, 16, 24, and 32.

Order

integer

(Optional) The order of interpolation between samples. Valid values shall be 1 and 3, specifying linear and cubic spline interpolation, respectively. Default value: 1.

Encode

array

(Optional) An array of 2 × m numbers specifying the linear mapping of input values into the domain of the function’s sample table. Default value: [0 (Size0 -1) 0 (Size1 - 1)…].

Decode

array

(Optional) An array of 2 × n numbers specifying the linear mapping of sample values into the range appropriate for the function’s output values. Default value: same as the value of Range.

other stream attributes

(various) (Optional) Other attributes of the stream that shall provide the sample values, as appropriate (see "Table 5 — Entries common to all stream dictionaries").

When a sampled function is called, each input value xi, for 0 ≤ i < m, shall be clipped to the domain: xi′ = min(max (xi , Domain2i ), Domain2i+1 ) That value shall be encoded: ei = Interpolate (xi′ , Domain2i , Domain2i+1 , Encode2i , Encode2i+1 ) That value shall be clipped to the size of the sample table in that dimension: e′i = min (max(ei , 0), Sizei − 1) The encoded input values shall be real numbers, not restricted to integers. Interpolation shall be used to determine output values from the nearest surrounding values in the sample table. Each output value rj, for 0 ≤ j < n, shall then be decoded: rj′ = Interpolate (rj , 0, 2BitsPerSample − 1, Decode2j , Decode2j+1 ) Finally, each decoded value shall be clipped to the range: yj = min(max (rj′ , Range2j ), Range2j+1 ) Sample data shall be represented as a stream of bytes. The bytes shall constitute a continuous bit stream, with the high-order bit of each byte first. Each sample value shall be represented as a sequence of BitsPerSample bits. Successive values shall be adjacent in the bit stream; there shall be no padding at byte boundaries. For a function with multidimensional input (more than one input variable), the sample values in the first dimension vary fastest, and the values in the last dimension vary slowest. 126

ISO 32000-2:2020(E)

EXAMPLE 1

For a function f(a, b, c), where a, b, and c vary from 0 to 9 in steps of 1, the sample values would appear in this order: f(0, 0, 0), f(1, 0, 0),…, f(9, 0, 0), f(0, 1, 0), f(1, 1, 0),…, f(9, 1, 0), f(0, 2, 0), f(1, 2, 0),…, f(9, 9, 0), f(0, 0, 1), f(1, 0, 1), and so on.

For a function with multidimensional output (more than one output value), the values shall be stored in the same order as Range. The stream data shall be long enough to contain the entire sample array, as indicated by Size, Range, and BitsPerSample; see 7.3.8.2, "Stream extent". Example 2 illustrates a sampled function with 4-bit samples in an array containing 21 columns and 31 rows (651 values). The function takes two arguments, x and y, in the domain [-1.0 1.0], and returns one value, z, in that same range. The x argument shall be linearly transformed by the encoding to the domain [0 20] and the y argument to the domain [0 30]. Using bilinear interpolation between sample points, the function computes a value for z, which (because BitsPerSample is 4) will be in the range [0 15], and the decoding transforms z to a number in the range [-1.0 1.0] for the result. The sample array shall be stored in a string of 326 bytes, calculated as follows (rounded up): 326 bytes = 31 rows × 21 samples /row × 4 bits /sample ÷ 8 bits /byte The first byte contains the sample for the point (-1.0, -1.0) in the high-order 4 bits and the sample for the point (-0.9, -1.0) in the low-order 4 bits. EXAMPLE 2 14 0 obj <</FunctionType 0 /Domain [-1.0 1.0 -1.0 1.0] /Size [21 31] /Encode [0 20 0 30] /BitsPerSample 4 /Range [-1.0 1.0] /Decode [-1.0 1.0] /Length … /Filter…

stream …651 sample values… endstream endobj

NOTE 3 EXAMPLE 3

The Decode entry can be used creatively to increase the accuracy of encoded samples corresponding to certain values in the range. If the range of the function is [-1.0 1.0] and BitsPerSample is 4, the usual value of Decode would be [-1.0 1.0] and the sample values would be integers in the interval [0 15] (as shown in "Figure 8 — Mapping with the Decode array"). But if these values are used, the midpoint of the range, 0.0, is not represented exactly by any sample value, since it falls halfway between 7 and 8. However, if the Decode array is [-1.0 +1.1429] (1.1429 being approximately equal to 16 ÷ 14) and the sample values supplied are in the interval [0 14], the

127

ISO 32000-2:2020(E)

effective range of [-1.0 1.0] is achieved, and the range value 0.0 is represented by the sample value 7.

Figure 8 — Mapping with the Decode array The Size value for an input dimension can be 1, in which case all input values in that dimension shall be mapped to the single allowed value. If Size is less than 4, cubic spline interpolation is not possible and Order 3 shall be ignored if specified.

7.10.3

Type 2 (exponential interpolation) functions

Type 2 functions (PDF 1.3) include a set of parameters that define an exponential interpolation of one input value and n output values: 𝑓(𝑥) = 𝑦0 , … , 𝑦𝑛−1 In addition to the entries in "Table 38 — Entries common to all function dictionaries", a Type 2 function dictionary shall include those listed in "Table 40 — Additional entries specific to a Type 2 function dictionary". Table 40 — Additional entries specific to a Type 2 function dictionary Key

Type

Value

C0

array

(Optional) An array of n numbers that shall define the function result when 𝑥 = 0.0. Default value: [0.0].

C1

array

(Optional) An array of n numbers that shall define the function result when 𝑥 = 1.0. Default value: [1.0].

N

number

(Required) The interpolation exponent. Each input value x shall return n values, given by yj = C0j + x N × (C1j − C0j ), for 0 ≤ j < n . 24T

Values of Domain shall constrain x in such a way that if N is not an integer, all values of x will be nonnegative, and if N is negative, no value of x will be zero. Typically, Domain is declared as [0.0 1.0], and N is a positive number. To clip the output to a specified range the Range attribute shall be used. NOTE

7.10.4

When N is 1, the function performs a linear interpolation between C0 and C1; therefore, the function can also be expressed as a sampled function (Type 0).

Type 3 (stitching) functions

ISO 32000-2:2020(E)

a single new 1-input function. Since the resulting stitching function is a 1-input function, the domain is given by a two-element array, [Domain0 Domain1]. In addition to the entries in "Table 38 — Entries common to all function dictionaries", a Type 3 function dictionary shall include those listed in "Table 41 — Additional entries specific to a Type 3 function dictionary". Table 41 — Additional entries specific to a Type 3 function dictionary Key

Type Value

Functions array (Required) An array of k, 1-input functions that shall make up the stitching function. The output dimensionality of all functions shall be the same, and compatible with the value of Range if Range is present. Bounds

array (Required) An array of 𝑘 − 1 numbers that, in combination with Domain, shall define the intervals to which each function from the Functions array shall apply. Bounds elements shall be in order of increasing value, and each value shall be within the domain defined by Domain.

Encode

array (Required) An array of 2 × 𝑘 numbers that, taken in pairs, shall map each subset of the domain defined by Domain and the Bounds array to the domain of the corresponding function.

Domain shall be of size 2 (that is, 𝑚 = 1), and Domain0 shall be strictly less than Domain1 unless 𝑘 = 1. The domain shall be partitioned into k subdomains, as indicated by the dictionary’s Bounds entry, which shall be an array of 𝑘 − 1 numbers that obey the following relationships (with exceptions as noted below): 𝐷𝑜𝑚𝑎𝑖𝑛0 ≤ 𝐵𝑜𝑢𝑛𝑑𝑠0 < 𝐵𝑜𝑢𝑛𝑑𝑠1 < ⋯ < 𝐵𝑜𝑢𝑛𝑑𝑠𝑘−2 ≤ 𝐷𝑜𝑚𝑎𝑖𝑛1 The Bounds array shall describe a series of k half-open intervals, closed on the left and open on the right with the following exceptions: •

the last interval, shall always be closed on the right,

•

if 𝐷𝑜𝑚𝑎𝑖𝑛0 = 𝐵𝑜𝑢𝑛𝑑𝑠0 then the first interval shall be closed on both the left and right and the second (next) interval shall be open on the left.

EXAMPLE 1

Using the normal notation where ( and ) mean open on the left and right, respectively, and [ and ] mean close on the left and right, the following cases are depicted: 𝑘 = 1 and 𝐷𝑜𝑚𝑎𝑖𝑛0 ≤ 𝐷𝑜𝑚𝑎𝑖𝑛1 results in one interval [𝐷𝑜𝑚𝑎𝑖𝑛0 , 𝐷𝑜𝑚𝑎𝑖𝑛1 ]. 𝑘 = 2 and 𝐷𝑜𝑚𝑎𝑖𝑛0 < 𝐵𝑜𝑢𝑛𝑑𝑠0 ≤ 𝐷𝑜𝑚𝑎𝑖𝑛1 results in two intervals [𝐷𝑜𝑚𝑎𝑖𝑛0 , 𝐵𝑜𝑢𝑛𝑑𝑠0 ); [𝐵𝑜𝑢𝑛𝑑𝑠0 , 𝐷𝑜𝑚𝑎𝑖𝑛1 ]. 𝑘 = 2 and 𝐷𝑜𝑚𝑎𝑖𝑛0 = 𝐵𝑜𝑢𝑛𝑑𝑠0 < 𝐷𝑜𝑚𝑎𝑖𝑛1 results in two intervals [𝐷𝑜𝑚𝑎𝑖𝑛0 , 𝐵𝑜𝑢𝑛𝑑𝑠0 ]; (𝐵𝑜𝑢𝑛𝑑𝑠0 , 𝐷𝑜𝑚𝑎𝑖𝑛1 ]. 𝑘 = 3 and 𝐷𝑜𝑚𝑎𝑖𝑛0 < 𝐵𝑜𝑢𝑛𝑑𝑠0 < 𝐵𝑜𝑢𝑛𝑑𝑠1 < 𝐷𝑜𝑚𝑎𝑖𝑛1 results in three intervals [𝐷𝑜𝑚𝑎𝑖𝑛0 , 𝐵𝑜𝑢𝑛𝑑𝑠0 ); [𝐵𝑜𝑢𝑛𝑑𝑠0 , 𝐵𝑜𝑢𝑛𝑑𝑠1 ); [𝐵𝑜𝑢𝑛𝑑𝑠1 , 𝐷𝑜𝑚𝑎𝑖𝑛1 ]. 𝑘 = 3 𝑎𝑛𝑑 𝐷𝑜𝑚𝑎𝑖𝑛0 = 𝐵𝑜𝑢𝑛𝑑𝑠0 < 𝐵𝑜𝑢𝑛𝑑𝑠1 < 𝐷𝑜𝑚𝑎𝑖𝑛1 results in three intervals [𝐷𝑜𝑚𝑎𝑖𝑛0 , 𝐵𝑜𝑢𝑛𝑑𝑠0 ];

129

ISO 32000-2:2020(E)

(𝐵𝑜𝑢𝑛𝑑𝑠0 , 𝐵𝑜𝑢𝑛𝑑𝑠1 ); [𝐵𝑜𝑢𝑛𝑑𝑠1 , 𝐷𝑜𝑚𝑎𝑖𝑛1 ].

The value of the Functions entry shall be an array of k functions. The first function shall apply to x values in the first subdomain (interval), defined by Domain0 and Bounds0 as defined just above; the second function shall apply to x values in the second subdomain, defined by Bounds0 and Bounds1; and so on. The last function shall apply to x values in the last subdomain, which includes the upper bound defined by Boundsk-2 and Domain1. The value of k may be 1, in which case the Bounds array shall be empty and the single item in the Functions array shall apply to all x values, Domain0 ≤ x ≤ Domain1. The Encode array contains 2 × 𝑘 numbers. A value x from the ith subdomain shall be encoded as follows: x ′ = Interpolate(x, Boundsi−1 , Boundsi , Encode2i , Encode2i+1 ) for 0 ≤ 𝑖 < 𝑘. In this equation, Bounds-1 means Domain0, and Boundsk-1 means Domain1. If the last bound, Boundsk-2, is equal to Domain1, then x′ shall be defined to be Encode2(k-1). For the degenerate case, if the first bound, Bounds0, is equal to Domain0 then x′ shall be defined to be Encode0. NOTE

The stitching function is designed to make it easy to combine several functions to be used within one shading pattern over different parts of the shading’s domain. Shading patterns are discussed in 8.7.4, "Shading patterns". The same effect could be achieved by creating a separate shading dictionary for each of the functions, with adjacent domains. However, since each shading would have similar parameters, and because the overall effect is one shading, it is more convenient to have a single shading with multiple function definitions. Also, Type 3 functions provide a general mechanism for inverting the domains of 1-input functions.

EXAMPLE 2

Consider a function f with a Domain of [0.0 1.0] and a stitching function g with a Domain of [0.0 1.0], a Functions array containing f, and an Encode array of [1.0 0.0]. In effect, 𝑔 (𝑥) = 𝑓 (1 − 𝑥).

7.10.5

Type 4 (PostScript calculator) functions

7.10.5.1

General

A Type 4 function (PDF 1.3), also called a PostScript calculator function, shall be represented as a stream containing code written in a small subset of the PostScript language. This subset is comprised of the following PostScript language features: •

Expressions involving only integers, real numbers, and boolean values

•

Comments

•

No composite data structures (such as strings or arrays)

•

No procedures

•

No variables or names

NOTE 1

130

Although any function can be sampled (in a Type 4 PDF function) and others can be described with exponential functions (Type 2 in PDF), Type 4 functions offer greater flexibility and potentially greater accuracy. For example, a tint transformation function for a hexachrome (sixcomponent) DeviceN colour space with an alternative colour space of DeviceCMYK (see 8.6.6.5, "DeviceN colour spaces") requires a 6-in, 4-out function. If such a function were sampled with m values for each input variable, the number of samples, 4 × m6, could be prohibitively large. In practice, such functions can often be written as short, simple PostScript language functions. © ISO 2020 – All rights reserved

ISO 32000-2:2020(E)

NOTE 2

7.10.5.2

Type 4 functions also facilitate inclusion of a wide variety of halftone spot functions without the loss of accuracy that comes from sampling, and without adding to the list of predefined spot functions (see 10.6.3, "Spot functions"). All of the predefined spot functions can be written as Type 4 functions.

Operators and operands

"Table 42 — Operators in Type 4 functions" lists the operators that can be used in this type of function. The PostScript Language Reference, Third Edition shall define the semantics of these operators and all other syntax rules of the PostScript language. Although the semantics are those of the corresponding PostScript language operators, a full PostScript language compatible interpreter is not required. Table 42 — Operators in Type 4 functions Operator Type

Operators

Arithmetic operators

abs

cvi

floor

mod

sin

add

cvr

idiv

mul

sqrt

atan

div

ln

neg

sub

ceiling

exp

log

round

truncate

and

false

le

not

true

bitshift

ge

lt

or

xor

eq

gt

ne

Conditional operators

If

ifelse

Stack operators

copy

exch

pop

dup

index

roll

cos Relational, boolean, and bitwise operators

The operand syntax for Type 4 functions shall follow PDF conventions rather than PostScript language conventions. The entire code stream defining the function shall be enclosed in braces { } (using LEFT CURLY BRACE (7Bh) and RIGHT CURLY BRACE (07hD)). Braces also shall delimit expressions that are executed conditionally by the if and ifelse operators: •

boolean {expression} if

•

boolean {expression1} {expression2} ifelse

This construct is purely syntactic; unlike in the PostScript language, no "procedure objects" shall be involved.

7.10.5.3

Type 4 function dictionary

A Type 4 function dictionary shall include the entries in "Table 38 — Entries common to all function dictionaries", as well as other appropriate stream attributes (see "Table 5 — Entries common to all stream dictionaries"). The following example shows a Type 4 function equivalent to the predefined © ISO 2020 – All rights reserved

131

ISO 32000-2:2020(E)

spot function DoubleDot (see 10.6.3, "Spot functions"). EXAMPLE 10 0 obj <</FunctionType 4 /Domain [-1.0 1.0 -1.0 1.0] /Range [-1.0 1.0] /Length 71

stream {360 mul sin 2 div exch 360 mul sin 2 div add } endstream endobj

The Domain and Range entries shall both be required. The input variables shall constitute the initial operand stack; the items remaining on the operand stack after execution of the function shall be the output variables. It shall be an error for the number of remaining operands to differ from the number of output variables specified by Range or for any of them to be objects other than numbers. Implementations of Type 4 functions shall provide a stack with room for at least 100 entries. No implementation shall be required to provide a larger stack, and it shall be an error to overflow the stack. A PDF writer shall not use a nesting depth for { } greater than 255 in order to prevent unwanted stack overflows. Annex B, "Operators in Type 4 Functions", contains a summary of these operators.

7.11 File specifications 7.11.1

General

A PDF file can refer to the contents of another file by using a file specification (PDF 1.1), which shall take either of two forms: •

A simple file specification shall give just the name of the target file in a standard format, independent of the naming conventions of any particular file system. It shall take the form of either a string or a dictionary.

•

A full file specification shall include information related to one or more specific file systems. It shall only be represented as a dictionary.

A file specification shall refer to a file external to the PDF file or to a file embedded within the referring PDF file, allowing its contents to be stored or transmitted along with the PDF file. The file is considered external to the PDF file in either case.

7.11.2

File specification strings

7.11.2.1

General

The standard format for representing a simple file specification in string form divides the string into component substrings separated by the SOLIDUS character (2Fh) (/). The SOLIDUS is a generic 132

ISO 32000-2:2020(E)

component separator that shall be mapped to the appropriate platform-specific separator when generating a platform-dependent file name. Any of the components may be empty. If a component contains one or more literal SOLIDIUS character, each shall be preceded by a REVERSE SOLIDUS (5Ch) (), which in turn shall be preceded by another REVERSE SOLIDUS to indicate that it is part of the string and not an escape character. EXAMPLE (in\/out)

represents the file name in/out

The REVERSE SOLIDIUS character shall be removed in processing the string; they are needed only to distinguish the component values from the component separators. The component substrings shall be stored as bytes and shall be passed to the operating system without interpretation or conversion of any sort.

7.11.2.2

Absolute and relative file specifications

A simple file specification that begins with a SOLIDUS shall be an absolute file specification. The last component shall be the file name; the preceding components shall specify its context. In some file specifications, the file name may be empty; for example, URL (uniform resource locator) specifications can specify directories instead of files. A file specification that does not begin with a SOLIDUS shall be a relative file specification giving the location of the file relative to that of the PDF file containing it. In the case of a URL-based file system, the rules of Internet RFC 3986 shall be used to compute an absolute URL from a relative file specification and the specification of the PDF file. Prior to this process, the relative file specification shall be converted to a relative URL by using the escape mechanism of Internet RFC 3986 to represent any bytes that would be either unsafe according to Internet RFC 3986 or not representable in 7-bit U.S. ASCII. In addition, such URL-based relative file specifications shall be limited to paths as defined in Internet RFC 3986. The scheme, network location/login, fragment identifier, query information, and parameter sections shall not be allowed. In the case of other file systems, a relative file specification shall be converted to an absolute file specification by removing the file name component from the specification of the containing PDF file and appending the relative file specification in its place. EXAMPLE 1

The relative file specification ArtFiles/Figure1.pdf

appearing in a PDF file whose specification is /HardDisk/PDFDocuments/AnnualReport/Summary.pdf

yields the absolute specification /HardDisk/PDFDocuments/AnnualReport/ArtFiles/Figure1.pdf

The special component . . (two PERIODs) (2Eh) can be used in a relative file specification to move up a level in the file system hierarchy. After an absolute specification has been derived, when the component immediately preceding . . is not another . ., the two cancel each other; both are eliminated © ISO 2020 – All rights reserved

133

ISO 32000-2:2020(E)

from the file specification and the process is repeated. EXAMPLE 2

The relative file specification from Example 1 in this subclause using the .. (two PERIODs) special component ../../ArtFiles/Figure1.pdf

would yield the absolute specification /HardDisk/ArtFiles/Figure1.pdf

7.11.3

File specification dictionaries

The dictionary form of file specification provides more flexibility than the string form, allowing different files to be specified for different file systems or platforms. "Table 43 — Entries in a file specification dictionary" shows the entries in a file specification dictionary. PDF writers should use the F entries to specify files. The UF entry is optional, but should be included because it enables crossplatform and cross-language compatibility. Table 43 — Entries in a file specification dictionary Key

Type

Value

Type

name

(Required if an EF, EP or RF entry is present; recommended always) The type of PDF object that this dictionary describes; shall be Filespec for a file specification dictionary.

FS

name

(Optional) The name of the file system that shall be used to interpret this file specification. If this entry is present, all other entries in the dictionary shall be interpreted by the designated file system. PDF shall define only one standard file system name, URL (see 7.11.5, "URL specifications"); an application can register other names (see Annex E, "Extending PDF"). This entry shall be independent of the F and UF entries.

F

string

(Required if the DOS, Mac, and Unix entries are all absent; amended with the UF entry for PDF 1.7) A file specification string of the form described in 7.11.2, "File specification strings" or (if the file system is URL) a uniform resource locator, as described in 7.11.5, "URL specifications". The UF entry should be used in addition to the F entry. The UF entry provides cross-platform and cross-language compatibility and the F entry provides backwards compatibility. A PDF reader shall use the value of the UF key, when present, instead of the F key. (PDF 2.0) For unencrypted wrapper documents for an encrypted payload document (see 7.6.7, "Unencrypted wrapper document") the F entry shall not contain or be derived from the encrypted payload’s actual file name. This is to avoid potential disclosure of sensitive information in the original filename. The value of F for encrypted payload documents should include the name of the cryptographic filter needed to decrypt the document. See the example in 7.6.7, "Unencrypted wrapper document".

134

ISO 32000-2:2020(E)

Key

Type

Value

UF

text string

(Optional, but recommended if the F entry exists in the dictionary; PDF 1.7) A Unicode text string that provides file specification of the form described in 7.11.2, "File specification strings". This is a text string as defined in 7.9.2.2, "Text string type". The F entry should be included along with this entry for backwards compatibility reasons. A PDF reader shall use the value of the UF key, when present, instead of the F key. (PDF 2.0) For unencrypted wrapper documents for an encrypted payload document (see 7.6.7, "Unencrypted wrapper document") the UF entry shall not contain or be derived from the encrypted payload’s actual file name. This is to avoid potential disclosure of sensitive information in the original filename.

DOS

byte string (Optional; deprecated in PDF 2.0) A file specification string (see 7.11.2, "File specification strings") representing a DOS file name.

Mac

byte string (Optional; deprecated in PDF 2.0) A file specification string (see 7.11.2, "File specification strings") representing a Mac OS file name.

Unix

byte string (Optional; deprecated in PDF 2.0) A file specification string (see 7.11.2, "File specification strings") representing a UNIX file name.

ID

array

(Optional) An array of two byte strings constituting a file identifier (see 14.4, "File identifiers") that should be included in the referenced file. NOTE 1 The use of this entry improves a PDF processor’s chances of finding the intended file, and allows a PDF processor to warn the user if the file has changed since the link was made.

V

boolean

(Optional; PDF 1.2) A flag indicating whether the file referenced by the file specification is volatile (changes frequently with time). If the value is true, applications shall not cache a copy of the file. For example, a movie annotation referencing a URL to a live video camera could set this flag to true to notify the PDF reader that it should re-acquire the movie each time it is played. Default value: false.

EF

dictionary

(Required if RF is present; PDF 1.3; amended to include the UF key in PDF 1.7) A dictionary containing a subset of the F and UF keys corresponding to the entries by those names in the file specification dictionary. The value of each such key shall be an embedded file stream (see 7.11.4, "Embedded file streams") containing the corresponding file. If this entry is present, the Type entry is required and the file specification dictionary shall be indirectly referenced. (PDF 2.0) For unencrypted wrapper documents for an encrypted payload document (see 7.6.7, "Unencrypted wrapper document") the EF dictionary is required for the file stream containing the encrypted payload.

RF

dictionary

(Optional; PDF 1.3) A dictionary with the same structure as the EF dictionary, which shall be present. For each key in this dictionary, the same key shall appear in the EF dictionary of this file specification dictionary. Each value shall be a related files array (see 7.11.4.2, "Related files arrays") identifying files that are related to the corresponding file in the EF dictionary. If this entry is present, the Type entry is required and the file specification dictionary shall be indirectly referenced.

135

ISO 32000-2:2020(E)

Key

Type

Value

Desc

text string

(Optional; PDF 1.6) Descriptive text associated with the file specification. It shall be used for file specification dictionaries referenced from the EmbeddedFiles name tree (see 7.7.4, "Name dictionary").

CI

dictionary

(Optional; shall be indirect reference; PDF 1.7) A collection item dictionary, which shall be used to create the user interface for portable collections (see 7.11.6, "Collection items").

Thumb

stream

(Optional; PDF 2.0) A stream object defining the thumbnail image for the file specification. (See 12.3.4, "Thumbnail images")

EP

dictionary

(PDF 2.0; Required if this file specification references an encrypted payload document as described in 7.6.7, "Unencrypted wrapper document") The value of this key is an encrypted payload dictionary which identifies that the file specified in the EF dictionary is an encrypted payload.

136

ISO 32000-2:2020(E)

Key

Type

Value

AFRelationship

name

(Optional; PDF 2.0) A name value that represents the relationship between the component of this PDF document that refers to this file specification and the associated file denoted by this file specification dictionary. See 14.13, "Associated files" for more details. These values represent the following relationships: Source shall be used if this file specification is the original source material for the associated content. Data shall be used if this file specification represents information used to derive a visual presentation – such as for a table or a graph. Alternative shall be used if this file specification is an alternative representation of content, for example audio. Supplement shall be used if this file specification represents a supplemental representation of the original source or data that may be more easily consumable (e.g., A MathML version of an equation). EncryptedPayload shall be used if this file specification is an encrypted payload document that should be displayed to the user if the PDF processor has the cryptographic filter needed to decrypt the document. FormData shall be used if this file specification is the data associated with the AcroForm (see 12.7.3, "Interactive form dictionary") of this PDF. Schema shall be used if this file specification is a schema definition for the associated object (e.g. an XML schema associated with a metadata stream). Unspecified shall be used when the relationship is not known or cannot be described using one of the other values. NOTE 2 Unspecified is to be used only when no other value correctly reflects the relationship.

Second-class names (see Annex E, “Extending PDF") should be used to represent other types of relationships. Default: Unspecified NOTE 3 The value of AFRelationship does not explicitly provide any processing instructions for a PDF processor. It is provided for information and semantic purposes for those processors that are able to use such additional information.

7.11.4

Embedded file streams

7.11.4.1

General

If a PDF file contains file specifications that refer to an external file and the PDF file is archived or transmitted, some provision should be made to ensure that the external references will remain valid. One way to do this is to arrange for the external files to accompany the PDF file. Embedded file streams (PDF 1.3) address this problem by allowing the contents of referenced files to be embedded directly within the body of the PDF file. This makes the PDF file a self-contained unit that can be stored or transmitted as a single entity. (The embedded files are included purely for convenience and need not be directly processed by any PDF processor.) © ISO 2020 – All rights reserved

137

ISO 32000-2:2020(E)

NOTE

If the file contains OPI (Open Prepress Interface) dictionaries that refer to externally stored highresolution images (see 14.11.7, "Open prepress interface (OPI)"), the image data can be incorporated into the PDF file with embedded file streams.

An embedded file stream shall be included in a PDF file in one of the following ways: •

Any file specification dictionary in the document may have an EF entry that specifies an embedded file stream. The stream data shall still be associated with a location in the file system. In particular, this method shall be used for file attachment annotations (see 12.5.6.15, "File attachment annotations"), which associate the embedded file with a location on a page in the document.

•

Embedded file streams may be associated with the document as a whole through the EmbeddedFiles entry in the PDF file’s name dictionary (see 7.7.4, "Name dictionary"). The associated name tree shall map name strings to file specifications that refer to embedded file streams through their EF entries.

Beginning with PDF 1.6, the Desc entry of the file specification dictionary (see "Table 43 — Entries in a file specification dictionary") should be used to provide a textual description of the embedded file, which can be displayed in the user interface of an interactive PDF processor. Previously, it was necessary to identify document-level embedded files by the name string provided in the name dictionary associated with an embedded file stream in much the same way that the ECMAScript name tree associates name strings with document-level ECMAScript actions (see 12.6.4.17, "ECMAScript actions"). The stream dictionary describing an embedded file shall contain the standard entries for any stream, such as Length and Filter (see "Table 5 — Entries common to all stream dictionaries"), as well as the additional entries shown in "Table 44 — Additional entries in an embedded file stream dictionary". Table 44 — Additional entries in an embedded file stream dictionary Key

Type

Value

Type

name

(Optional) The type of PDF object that this dictionary describes; if present, shall be EmbeddedFile for an embedded file stream.

Subtype

name

(Optional, required in the case of an embedded file stream used as an associated file) The subtype of the embedded file. The value of this entry shall conform to the MIME media type names defined in Internet RFC 2046, with the provision that characters not permitted in names shall use the 2-character hexadecimal code format described in 7.3.5, "Name objects". NOTE The media type for PDF is defined by Internet RFC 8118.

Params

dictionary

(Optional, required in the case of an embedded file stream used as an associated file) An embedded file parameter dictionary that shall contain additional filespecific information (see "Table 45 — Entries in an embedded file parameter dictionary").

Table 45 — Entries in an embedded file parameter dictionary Key

Type

Value

Size

integer

(Optional) The size of the uncompressed embedded file, in bytes. See "Table 155 — Entries in a collection field dictionary".

138

ISO 32000-2:2020(E)

Key

Type

Value

CreationDate

date

(Optional) The date and time when the embedded file was created. See "Table 155 — Entries in a collection field dictionary".

ModDate

date

(Optional, required in the case of an embedded file stream used as an associated file) The date and time when the embedded file was last modified. See "Table 155 — Entries in a collection field dictionary".

Mac

dictionary

(Optional; deprecated in PDF 2.0) A subdictionary containing additional information specific to Mac OS files.

CheckSum

string

(Optional) A 16-byte string that is the checksum of the bytes of the uncompressed embedded file. The checksum shall be calculated by applying the standard MD5 message-digest algorithm (defined in Internet RFC 1321) to the bytes of the embedded file stream. NOTE

7.11.4.2

This is strictly a checksum, and is not used for security purposes.

Related files arrays

In some circumstances, a PDF file can refer to a group of related files, such as the set of five files that make up a DCS 1.0 colour-separated image. The file specification explicitly names only one of the files; the rest shall be identified by some systematic variation of that file name (such as by altering the extension). When such a file is to be embedded in a PDF file, the related files shall be embedded as well. This is accomplished by including a related files array (PDF 1.3) as the value of the RF entry in the file specification dictionary. The array shall have 2 × n elements, which shall be paired in the form [

string1 stream1 string2 stream2 … stringn streamn

] The first element of each pair shall be a string giving the name of one of the related files; the second element shall be an embedded file stream holding the file’s contents. EXAMPLE

In the following example, object 31 is an embedded file stream containing Encapsulated Postscript File (EPSF) file Sunset.eps. The file specification dictionary’s RF entry specifies an array, object 30, identifying a set of embedded files, forming a DCS 1.0 set.

10 0 obj <</Type /Filespec /F (Sunset.eps) /UF (Sunset.eps) /EF <</F 21 0 R /UF 41 0 R

/RF <</UF 30 0 R>>

%File specification dictionary

%Related files array

endobj

30 0 obj [(Sunset.eps) 31 0 R (Sunset.C) 32 0 R

%Related files array %Embedded file stream for the EPSF Sunset.eps

139

ISO 32000-2:2020(E)

(Sunset.M) 33 0 R (Sunset.Y) 34 0 R (Sunset.K) 35 0 R ] endobj 31 0 obj <</Type /EmbeddedFile /Length … /Filter…

stream … Data for Sunset.eps … endstream endobj

%Embedded file stream for Mac OS file %Sunset.eps

32 0 obj <</Type /EmbeddedFile /Length … /Filter…

stream … Data for Sunset.C … endstream endobj

%Embedded file stream for related file %Sunset.C

7.11.5

URL specifications

When the FS entry in a file specification dictionary has the value URL, the value of the F entry in that dictionary is not a file specification string, but a uniform resource locator (URL) of the form defined in Internet RFC 3986. EXAMPLE

The following example shows a URL specification.

<< /FS /URL /F (ftp://www.beatles.com/Movies/AbbeyRoad.mov)

The URL shall adhere to the character-encoding requirements specified in Internet RFC 3986. Because 7-bit U.S. ASCII is a strict subset of PDFDocEncoding, this value shall also be considered to be in PDFDocEncoding.

7.11.6

Collection items

Beginning with PDF 1.7, a collection item dictionary shall contain the data described by the collection schema dictionary for a particular file in a collection (see 12.3.5, "Collections"). "Table 46 — Entries in a collection item dictionary" describes the entries in a collection item dictionary. Table 46 — Entries in a collection item dictionary Key

Type

Value

Type

name

(Optional) The type of PDF object that this dictionary describes; if present, shall be CollectionItem for a collection item dictionary.

140

ISO 32000-2:2020(E)

Key

Type

Value

Other keys text string, date, number or dictionary

(Optional) Provides the data corresponding to the related fields in the collection dictionary. If the entry is a dictionary, then it shall be a collection subitem dictionary (see "Table 47 — Entries in a collection subitem dictionary"). The type of each entry shall match the type of data identified by the collection field dictionary (see "Table 155 — Entries in a collection field dictionary") referenced by the same key in the collection schema dictionary (see "Table 154 — Entries in a collection schema dictionary"). EXAMPLE

If the corresponding collection field has a Subtype entry of S, then the entry is a text string.

A single collection item dictionary may contain multiple entries, with one entry representing each key (see Example 1 in 12.3.5, "Collections").

A collection subitem dictionary provides the data corresponding to the related fields in the collection dictionary, and it provides a means of associating a prefix string with that data value. The prefix shall be ignored by the sorting algorithm. "Table 47 — Entries in a collection subitem dictionary" describes the entries in a collection subitem dictionary. Table 47 — Entries in a collection subitem dictionary Key

Type

Value

Type name

(Optional) The type of PDF object that this dictionary describes; if present, shall be CollectionSubitem for a collection item dictionary.

D

text string, date, or number

(Optional) The data corresponding to the related entry in the collection field dictionary (see "Table 155 — Entries in a collection field dictionary"). The type of data shall match the data type identified by the corresponding collection field dictionary. Default: none.

P

text string

(Optional) A prefix string that shall be concatenated with the text string presented to the user. This entry is ignored when an interactive PDF processor sorts the items in the collection. Default: none.

7.12 Extensions dictionary 7.12.1

General

An optional key, Extensions, in the document’s catalog dictionary shall have as its value an Extensions dictionary (see "Table 48 — Entries in an extensions dictionary") containing one or more entries identifying developer-defined extensions to this document. The keys allowed in an extensions dictionary, are shown in "Table 48 — Entries in an extensions dictionary", and may optionally contain a Type entry whose value is the name Extensions. The remaining keys shall be names consisting of registered prefix names of the developer extensions used, as described in Annex E, "Extending PDF". The values of those prefix name keys shall be developer extensions dictionaries (see "Table 49 — Entries in a developer extensions dictionary") specifying developer-defined version information. The extensions dictionary, all developer extensions dictionaries, as well as their entries, shall be direct objects (i.e., this information shall be nested directly within the catalog dictionary with no indirect © ISO 2020 – All rights reserved

141

ISO 32000-2:2020(E)

objects used).

7.12.2

Extensions dictionary

"Table 48 — Entries in an extensions dictionary" describes the entries in an extensions dictionary. Table 48 — Entries in an extensions dictionary Key

Type

Value

Type

name

(Optional; , shall be a direct objectif present) The type of PDF object that this dictionary describes; if present, shall be Extensions.

Prefix name array or dictionary

(Required; PDF 1.7; shall be a direct object) A developer extensions dictionary, or an array of developer extension dictionaries (PDF 2.0), denoting extensions used (See "Table 49 — Entries in a developer extensions dictionary"). The key shall be a registered prefix name as described in Annex E, “Extending PDF". This entry is repeated for each different developer’s extensions used. Multiple distinct registered prefix names for different developers may be used for each different developer’s extensions used. See Example 3 below. NOTE

7.12.3

Arrays of developer extension dictionaries were introduced in this document (2020).

Developer extensions dictionary

"Table 49 — Entries in a developer extensions dictionary" describes the entries in a developer extensions dictionary. Table 49 — Entries in a developer extensions dictionary Key

Type

Value

Type

name

(Optional; shall be a direct object if present) The type of PDF object that this dictionary describes; if present, shall be DeveloperExtensions.

BaseVersion

name

(Required; shall be a direct object) The name of the PDF version to which this extension applies. The name shall be consistent with the syntax used for the Version entry of the catalog dictionary (see 7.7.2, "Document catalog dictionary").

ExtensionLevel

integer

(Required; shall be a direct object) An integer defined by the developer to denote the extension being used. If the developer introduces more than one extension to a given BaseVersion the extension level numbers assigned by that developer should increase over time.

URL

string

(Optional; PDF 2.0; shall be a direct object if present) A URL that refers to the documentation for this extension (see Annex E, "Extending PDF").

ExtensionRevision text string (Optional; PDF 2.0; shall be a direct object if present) An optional text string that provides additional revision information on the extension level being used. NOTE

142

ISO 32000-2:2020(E)

7.12.4

BaseVersion

The value of the BaseVersion entry shall be a name and shall be consistent with the syntax used for the Version entry value of the catalog dictionary (see 7.7.2, "Document catalog dictionary"). The value of BaseVersion, when treated as a version number, shall be less than or equal to the PDF version, both in the document header (see 7.5.2, "File header") and the catalog dictionary Version key value, if present. The value of BaseVersion may be different from the version number in the document header or that supplied by the Version key in the catalog dictionary. This is because it reflects the version of the standard that has been extended and not the version of this particular file. NOTE

The value of BaseVersion is not to be interpreted as a real number but as two integers with a PERIOD (2Eh) between them.

7.12.5

ExtensionLevel

The value of the ExtensionLevel entry shall be an integer, which shall be interpreted with respect to the BaseVersion value. If a developer has released multiple extensions against the same BaseVersion value, they shall be ordered over time and the ExtensionLevel numbers shall be a monotonically increasing sequence over time.

7.12.6

URL

The value of the optional URL entry shall be a string containing a URL to the documentation that is provided by the developer of this extension and as registered in the PDF Registry (see Annex E, "Extending PDF"). EXAMPLE 1 %PDF–2.0 << /Type /Catalog /Extensions << /Type /Extensions /ADBE << /BaseVersion /1.7 /ExtensionLevel 3 /URL (http://www.adobe.com/documentation/ext3.pdf)

EXAMPLE 2

This is a minimal example.

%PDF–2.0 << /Type /Catalog /Extensions << /GLGR << /BaseVersion /1.7 /ExtensionLevel 1002 >> >>

EXAMPLE 3

This example shows the use of both arrays (PDF 2.0) and dictionaries with different developer prefixes.

%PDF–2.0 << /Type /Catalog /Extensions << /Type /Extensions /ISO_ [ % Multiple developer extensions under the registered prefix “ISO_” << /Type /DeveloperExtensions /BaseVersion /2.0 /ExtensionLevel 24064

143

ISO 32000-2:2020(E)

/URL (https://www.iso.org/standard/77686.html)

<< /Type /DeveloperExtensions /BaseVersion /2.0 /ExtensionLevel 24654 /URL (https://www.iso.org/standard/79150.html)

] /GLGR << /Type /DeveloperExtensions /BaseVersion /1.7 /ExtensionLevel 1002 /URL (http://www.generallanguage.com/ISO32000/extension1002.pdf)

144

ISO 32000-2:2020(E)

Navigation: PDF20-Spec-07-Functions | PDF20-Spec-Index | Next →

PDF20 Spec 07 Extensions

7.12 Extensions Dictionary

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!