Units

If information about positions, lengths or sizes has to be provided in the parameters when calling a web service (e.g. in the Toolbox web service when adding a text watermark), then a data type metrics is usually available, which specifies the unit of the associated positions and measurements.

An example of a text watermark in the Toolbox web service with information on metrics in position

{
  "toolbox": [
    {
      "watermark": {
        "angle": 0,
        "pages": "1",
        "text": {
          "font": {
            "bold": false,
            "color": "#888888",
            "italic": false,
            "name": "Arial",
            "opacity": 20,
            "outline": false,
            "size": 24
          },
          "position": {
            "aspectRatio": false,
            "height": 39.94,
            "metrics": "mm",
            "position": "custom",
            "width": 41.39,
            "x": 138.96,
            "y": 44.41
          },
          "text": "Confidential"
        }
      }
    }
  ]
}

In the following, these units and their relationships with the PDF standard will be explained.

Point [pt]

One of the objectives of the PDF format is to formulate a document constantly and independently of possible display and output devices. For this reason, the PDF specification defines a device- and resolution-independent coordinate space into which all positioning information and dimensions are transferred.

The length dimension of this coordinate space is the default unit of a PDF document and is also called the "user unit". It is defined as 1/72 of an inch. This unit is thus defined in relation to an absolute and tangible length measure (the inch) and can thus be converted and processed without loss of accuracy due to different resolutions.

Since the typographic point is the more common term and the "user unit" is defined approximately identically to it, we use the point [pt] synonymously in the following and also in the parameter structure.

Pica [pc]

Pica is another measurement used in the printing industry and is most commonly used in the United States. A pica is approximately defined as 1/6 of an inch, which means that a pica corresponds to 12 pt.

Inch [in]

Most of the units of measurement used here are defined in relation to the imperial "inch", making it the basis of the other units of measurement listed here.

Millimeter [mm]

1 inch is defined as 25.4 millimeters in the metric system.

Pixel [px]

The units listed above are all absolute measures of length with a clear definition and length. For example, an inch will always be 25.4 mm long. However, this does not apply to the pixel.

A pixel roughly describes a single (indivisible) picture element of a raster, which also means that the "length" of a pixel directly depends on the resolution of this raster. How many pixels fit into an inch depends directly on the pixel density of the raster (PPI - Pixels Per Inch).

However, in web development and especially in connection with raster graphics (e.g. JPEG, PNG, ...) it is absolutely sensible and common to specify dimensions in pixels. In order to be able to transfer the pixel in the parameters of the web services stably and constantly into other length measures, it is meaningful for this to specify a static standard resolution. We follow the definition of the W3C, which defines a pixel as 1/96 inch.

caution

If you want to transfer pixel dimensions from other applications into the parameters of the web service, the transferred dimensions must be converted according to the above definition.