Repository navigation
PDF20 Spec 12 Measurement
Part of: PDF20-Spec-12-Interactive
Navigation: PDF20-Spec-12-Signatures | PDF20-Spec-Index | PDF20-Spec-12-Geospatial
12.9 Measurement properties 12.9.1
General
PDF documents, such as those created by CAD software, may contain graphics that are intended to represent real-world objects. Users of such documents often require information about the scale and units of measurement of the corresponding real-world objects and their relationship to units in PDF user space. This information enables users of interactive PDF processors to perform measurements that yield results in the units intended by the creator of the document. A measurement in this context is the result of a canonical function that takes as input a set pairs {(𝑥0 , 𝑦0 ), … , (𝑥𝑛−1 , 𝑦𝑛−1 )} and produces a single number as output depending on the type of measurement. For example, distance measurement is equivalent to 𝑛−2
∑ √(𝑥i − 𝑥i+1 )2 + (𝑦i − 𝑦i+1 )2 i=0
Beginning with PDF 1.6, such information may be stored in a measure dictionary (see "Table 266 — Entries in a measure dictionary"). Measure dictionaries provide information about measurement units associated with a rectangular area of the document known as a viewport. A viewport (PDF 1.6) is a rectangular region of a page. The optional VP entry in a page dictionary (see "Table 31 — Entries in a page object") shall specify an array of viewport dictionaries, whose entries shall be as shown in "Table 265 — Entries in a viewport dictionary". Viewports allow different © ISO 2020 – All rights reserved
595
ISO 32000-2:2020(E)
measurement scales (specified by the Measure entry) to be used in different areas of a page, if necessary. The dictionaries in the VP array shall be in drawing order. Since viewports might overlap, to determine the viewport to use for any point on a page, the dictionaries in the array shall be examined, starting with the last one and iterating in reverse, and the first one whose BBox entry contains the point shall be chosen. Any measurement that potentially involves multiple viewports, such as one specifying the distance between two points, shall use the information specified in the viewport of the first point. Table 265 — Entries in a viewport dictionary Key
Type
Value
Type
name
(Optional) The type of PDF object that this dictionary describes; shall be Viewport for a viewport dictionary.
BBox
rectangle
(Required) A rectangle in default user space coordinates specifying the location of the viewport on the page. The two coordinate pairs of the rectangle shall be specified in normalised form; that is, lower-left followed by upper-right, relative to the measuring coordinate system. This ordering shall determine the orientation of the measuring coordinate system (that is, the direction of the positive x and y axes) in this viewport, which may have a different rotation from the page. The coordinates of this rectangle are independent of the origin of the measuring coordinate system, specified in the O entry (see "Table 267 — Additional entries in a rectilinear measure dictionary") of the measurement dictionary specified by Measure.
Name
text string
(Optional) A descriptive text string or title of the viewport, intended for use in a user interface.
Measure
dictionary
(Optional) A measure dictionary (see "Table 266 — Entries in a measure dictionary") that specifies the scale and units that shall apply to measurements taken on the contents within the viewport.
PtData
dictionary
(Optional; PDF 2.0) A point data dictionary (see "Table 272 — Entries in a point data dictionary") that shall specify the extended geospatial data that applies to this viewport.
A measure dictionary shall specify an alternative coordinate system for a region of a page. Along with the viewport dictionary, it shall provide the information needed to convert coordinates in the page’s coordinate system to coordinates in the measuring coordinate system. The measure dictionary shall provide information for formatting the resulting values into textual form for presentation in a graphical user interface. "Table 266 — Entries in a measure dictionary" shows the entries in a measure dictionary. PDF 1.6 defines only a single type of coordinate system, a rectilinear coordinate system, that shall be specified by the value RL for the Subtype entry. RL is defined as one in which the x and y axes are perpendicular and have units that increment linearly (to the right and up, respectively). PDF 2.0 defines a geospatial 596
© ISO 2020 – All rights reserved
ISO 32000-2:2020(E)
coordinate system specified by the value GEO for the Subtype entry. Other subtypes may be used, providing the flexibility to measure using other types of coordinate systems. When the value of the Subtype entry is GEO, the dictionary shall define the relationship between points or regions in the two dimensional PDF object space and points or regions with respect to an underlying model of the earth (or, potentially, other ellipsoid objects). Table 266 — Entries in a measure dictionary Key
Type
Value
Type
name
(Optional) The type of PDF object that this dictionary describes; shall be Measure for a measure dictionary.
Subtype
name
(Optional) A name specifying the type of coordinate system to use for measuring. RL for a rectilinear coordinate system GEO (PDF 2.0) for a geospatial coordinate system Default value: RL
"Table 267 — Additional entries in a rectilinear measure dictionary" shows the additional entries in a rectilinear measure dictionary. Many of the entries in this dictionary shall be number format arrays, which are arrays of number format dictionaries (see "Table 268 — Entries in a number format dictionary"). Each number format dictionary shall represent a specific unit of measurement (such as miles or feet). It shall contain information about how each unit shall be expressed in text and factors for calculating the number of units. When the subtype of a measurement dictionary is GEO, additional entries are defined. "Table 269 — Additional entries in a geospatial measure dictionary" lists and describes these additional entries in a geospatial measure dictionary. Number format arrays specify all the units that shall be used when expressing a specific measurement. Each array shall contain one or more number format dictionaries, in descending order of granularity. If one unit of measurement X is larger than one unit of measurement Y then X has a larger order of granularity than Y. All the elements in the array shall contain text strings that, concatenated together, specify how the units shall be displayed. NOTE 2
For example, a measurement of 1.4505 miles can be expressed as "1.4505 mi", which would require one number format dictionary for miles, or as "1 mi 2,378 ft 7 5/8 in", which would require three dictionaries (for miles, feet, and inches).
NOTE 3
A number format dictionary specifying feet needs to precede one specifying inches.
© ISO 2020 – All rights reserved
597
ISO 32000-2:2020(E)
Table 267 — Additional entries in a rectilinear measure dictionary Key
Type
Value
R
text string
(Required) A text string expressing the scale ratio of the drawing in the region corresponding to this dictionary. Universally recognised unit abbreviations should be used, either matching those of the number format arrays in this dictionary or those of commonly used scale ratios. EXAMPLE 1
A common scale in architectural drawings is "1/4 in = 1 ft", indicating that 1/4 inches in default user space is equivalent to 1 foot in real-world measurements.
If the scale ratio differs in the x and y directions, both scales should be specified. EXAMPLE 2
598
"in X 1 cm = 1 m, in Y 1 cm = 30 m".
X
array
(Required) A number format array for measurement of change along the x axis and, if Y is not present, along the y axis as well. The first element in the array shall contain the scale factor for converting from default user space units to the largest units in the measuring coordinate system along that axis. The directions of the x and y axes are in the measuring coordinate system and are independent of the page rotation. These directions shall be determined by the BBox entry of the containing viewport (see "Table 265 — Entries in a viewport dictionary").
Y
array
(Required when the x and y scales have different units or conversion factors) A number format array for measurement of change along the y axis. The first element in the array shall contain the scale factor for converting from default user space units to the largest units in the measuring coordinate system along the y axis.
D
array
(Required) A number format array for measurement of distance in any direction. The first element in the array shall specify the conversion to the largest distance unit from units represented by the first element in X. The scale factors from X, Y (if present) and CYX (if Y is present) shall be used to convert from default user space to the appropriate units before applying the distance function.
A
array
(Required) A number format array for measurement of area. The first element in the array shall specify the conversion to the largest area unit from units represented by the first element in X, squared. The scale factors from X, Y (if present) and CYX (if Y is present) shall be used to convert from default user space to the appropriate units before applying the area function.
T
array
(Optional) A number format array for measurement of angles. The first element in the array shall specify the conversion to the largest angle unit from degrees. The scale factor from CYX (if present) shall be used to convert from default user space to the appropriate units before applying the angle function.
S
array
(Optional) A number format array for measurement of the slope of a line. The first element in the array shall specify the conversion to the largest slope unit from units represented by the first element in Y divided by the first element in X. The scale factors from X, Y (if present) and CYX (if Y is present) shall be used to convert from default user space to the appropriate units before applying the slope function. © ISO 2020 – All rights reserved
ISO 32000-2:2020(E)
Key
Type
Value
O
array
(Optional) An array of two numbers that shall specify the origin of the measurement coordinate system in default user space coordinates. The directions by which x and y increase in value from this origin shall be determined by the viewport’s BBox entry (see "Table 265 — Entries in a viewport dictionary"). Default value: the first coordinate pair (lower-left corner) of the rectangle specified by the viewport’s BBox entry.
CYX
number
(Optional; meaningful only when Y is present) A factor that shall be used to convert the largest units along the y axis to the largest units along the x axis. It shall be used for calculations (distance, area, and angle) where the units are be equivalent; if not specified, these calculations may not be performed (which would be the case in situations such as x representing time and y representing temperature). Other calculations (change in x, change in y, and slope) shall not require this value.
The X and Y entries in a measure dictionary shall be number format arrays that shall specify the units used for measurements in the x and y directions, respectively, and the ratio between user space units and the specified units. Y is present only when the x and y measurements are in different units or have different ratios; in this case, the CYX entry shall be used to convert y values to x values when appropriate. Table 268 — Entries in a number format dictionary Key
Type
Value
Type name
(Optional) The type of PDF object that this dictionary describes; shall be NumberFormat for a number format dictionary.
U
text string
(Required) A text string specifying a label for displaying the units represented by this dictionary in a user interface; the label should use a universally recognised abbreviation.
C
number
(Required) The conversion factor used to multiply a value in partial units of the previous number format array element to obtain a value in the units of this dictionary. When this entry is in the first number format dictionary in the array, its meaning (that is, what it shall be multiplied by) depends on which entry in the rectilinear measure dictionary (see "Table 267 — Additional entries in a rectilinear measure dictionary") references the number format array.
F
name
(Optional; meaningful only for the last dictionary in a number format array) A name indicating whether and in what manner to display a fractional value from the result of converting to the units of this dictionary by means of the C entry. Valid values shall be: D Show as decimal to the precision specified by the D entry. F Show as a fraction with denominator specified by the D entry. R No fractional part; round to the nearest whole unit. T No fractional part; truncate to achieve whole units. Default value: D.
© ISO 2020 – All rights reserved
599
ISO 32000-2:2020(E)
Key
Type
Value
D
integer
(Optional; meaningful only for the last dictionary in a number format array) A positive integer that shall specify the precision or denominator of a fractional amount: When the value of F is D, this entry shall be the precision of a decimal display; it shall be a multiple of 10. Low-order zeros may be truncated unless FD is true. Default value: 100 (hundredths, corresponding to two decimal digits). When the value of F is F, this entry shall be the denominator of a fractional display. The fraction may be reduced unless the value of FD is true. Default value: 16.
FD
boolean
(Optional; meaningful only for the last dictionary in a number format array) If true, a fractional value formatted according to the D entry may not have its denominator reduced or low-order zeros truncated. Default value: false.
RT
text string
(Optional) Text that shall be used between orders of thousands in display of numerical values. An empty string indicates that no text shall be added. Default value: COMMA (2Ch).
RD
text string
(Optional) Text that shall be used as the decimal position in displaying numerical values. An empty string indicates that the default shall be used. Default value: PERIOD (2Eh).
PS
text string
(Optional) Text that shall be concatenated to the left of the label specified by U. An empty string indicates that no text shall be added. Default value: A single ASCII SPACE character (20h).
SS
text string
(Optional) Text that shall be concatenated after the label specified by U. An empty string indicates that no text shall be added. Default value: A single ASCII SPACE character (20h).
O
name
(Optional) A name indicating the position of the label specified by U with respect to the calculated unit value. Valid values shall be: S The label is a suffix to the value. P The label is a prefix to the value. The characters specified by PS and SS shall be concatenated before considering this entry. Default value: S.
12.9.2 string
Algorithm: Use of a number format array to create a formatted text
To use a number format array to create a text string containing the appropriately formatted units for display in a user interface, apply the following algorithm: a) The entry in the rectilinear measure dictionary (see "Table 267 — Additional entries in a rectilinear measure dictionary") that references the number format array determines the meaning of the initial measurement value. For example, the X entry specifies user space units, and the T entry specifies degrees. 600
© ISO 2020 – All rights reserved
ISO 32000-2:2020(E)
b) Multiply the value specified previously by the C entry of the first number format dictionary in the array, which converts the measurement to units of the largest granularity specified in the array. Apply the value of RT as appropriate. c) If the result contains no non-zero fractional portion, concatenate the label specified by the U entry in the order specified by O, after adding spacing from PS and SS. The formatting is then complete. d) If there is a non-zero fractional portion and no more elements in the array, format the fractional portion as specified by the RD, F, D, and FD entries of the last dictionary. Concatenate the label specified by the U entry in the order specified by O, after adding spacing from PS and SS. The formatting is then complete. e) If there is a non-zero fractional portion and more elements in the array, proceed to the next number format dictionary in the array. Multiply its C entry by the fractional result from the previous step. Apply the value of RT as appropriate. Then proceed to step 3. The concatenation of elements in this process assumes left-to-right order. Documents using right-toleft languages may modify the process and the meaning of the entries as appropriate to produce the correct results. EXAMPLE
The following example shows a measure dictionary that specifies that changes in x or y are expressed in miles; distances are expressed in miles, feet, and inches; and area is expressed in acres. Given a sample distance in scaled units of 1.4505 miles, the formatted text produced by applying the number format array would be "1 mi 2,378 ft 7 5/8 in". << /Type /Measure /Subtype /RL /R (1in = 0.1 mi) /X [<</U (mi) /C .00139 /D 100000
] /D [<</U (mi) /C 1>> <</U (ft) /C 5280>> <</U (in) /C 12 /F /F /D 8>> ] /A [<</U (acres) /C 640>> ]
%x offset represented in miles %Conversion from user space units to miles
%Distance: initial unit is miles; no conversion needed %Conversion from miles to feet %Conversion from feet to inches %Fractions of inches rounded to nearest 1/8 %Area: measured in acres %Conversion from square miles to acres
Navigation: PDF20-Spec-12-Signatures | PDF20-Spec-Index | PDF20-Spec-12-Geospatial