Coordinates and sizes

To use certain API functionality, you will be asked to indicate coordinates (for example for adding a signature) or sizes (adding margins when turning images to PDF).

Coordinates on a PDF page

The origin of the coordinates on a PDF is located at the bottom left of the pages.

This means that the higher the value of x, the closer you get to the right edge of the page. The higher the value of y, the closer you get to the top of the page.

Absolute coordinates

Absolute coordinates allow you to indicate a precise position on a page.

Let's take the example of the PDF signature addition tool, in which we want to add a signature centered on the position x=30 y=50:

    
      {
        tool: 'sign',
        options: {
          signatures: [
            {
              // Inserting the signature at x=30 y=50
              position: [30, 50],
              // ...
            },
          ],
        },
      },
    
  

Relative coordinates

Relative coordinates allow you to calculate a position from the height and width of the page.

To calculate a position based on the width of the page, use the prefix w. Similarly, use h to base on the page height.

A relative coordinate must be a value between 0 and 100, with 0 being 0% of the dimension (height or width) and 100 being 100% of the dimension.

In the following example, we want to add a signature at the center of the page. Now that we can compute coordinates based on the size of the page this is done very easily, knowing that the center of the page is x=50% of the width and y=50% of the height:

    
      {
        tool: 'sign',
        options: {
          signatures: [
            {
              // Inserting the signature at x=30 y=50
              position: [50w, 50h],
              // ...
            },
          ],
        },
      },
    
  

Sizes

Similar to coordinates, you can specify a width or height absolutely (fixed size) or relatively (calculated according to the height or width of the page).

Absolute size

An absolute size allows you to have a rendering that will always have the same dimension regardless of the size of the PDF page.

Let's keep our example of adding signatures. Now that we have indicated the position of our signature (in relative or absolute coordinates, it doesn't matter), we want to give it a size. This is done via the bouding-box option which corresponds to the frame enclosing the signature, and is expressed in the format [width, height].

    
      {
        tool: 'sign',
        options: {
          signatures: [
            {
              // The signature will be contained in a rectangle with a width of 150 and height of 100
              'bouding-box': [150, 100],
              // ...
            },
          ],
        },
      },
    
  

Relative size

A relative size allows you to calculate a size (height or width) from the height and width of the page.

Still on our signature example, we now want the signature to be enclosed in a frame of 15% of the page width and 10% of the height:

    
      {
        tool: 'sign',
        options: {
          signatures: [
            {
              // The signature will be contained in a rectangle with a width of 15% of the page width and height of 10% of the page height
              'bouding-box': [15w, 10h],
              // ...
            },
          ],
        },
      },
    
  

Mixing relative and absolute units

As long as the option asks for coordinates or dimensions, you can use whatever unit you want, or even use different units for the different values.