PDFKit Node.js measurement unit

Question

What is the measurement unit used in PDFKit (Node.js)? For example we use:

doc.text(20, 20, 'Message')

What does 20(x) and 20(x) stand for? Is it centimeter, millimeter, inch? Can I change it to any familiar format like cm, mm, or inch?

Any ideas?

Answer 1

As most PDF generators (if not any), PDFKit uses points too as stated in the official documentation under the Adding pages section as PDF Points:

The layout property can be either portrait (the default) or landscape. The size property can be either an array specifying [width, height] in PDF points (72 per inch), or a string specifying a predefined size. A list of the predefined paper sizes can be seen here. The default is letter.

...

You can set the page margins in two ways. The first is by setting the margin property (singular) to a number, which applies that margin to all edges. The other way is to set the margins property (plural) to an object with top, bottom, left, and right values. The default is a 1 inch (72 point) margin on all sides.

This unit is not only applicable, when specifying the layout dimensions, but also, when any type of numbered unit is used to modify the generated PDF. (e.g. drawing text, images, vectors, etc.)

---

Since PDF is derived from PostScript, it uses internally the same graphics model too including the same basic measurement unit as PostScript, which is points (72 points == 1 inch). This measurement unit is the device-independent way of using and stating dimensions.

---

You cannot change PDFKit's measurement unit. In order to use other units rather, than points, you have to calculate yourself the unit and multiply by a factor according to points. Since you are not bound to integer points, you can use floats, when specifying points too (e.g.: 100.15).

---

Example:

If you use an A4-sized page (which is 8.27 × 11.69 inches or 210 × 297 mm), its dimensions are rounded off to 595 × 842 points (pt in short):

• 1pt is ~0.35mm, or ~0.04cm
• 10pt is ~3.53mm, or ~0.35cm
• 100pt is ~35.28mm, or ~3.53cm
• 148.75pt (quarter page width) is ~52.48mm or ~5.25cm
• 297.5pt (half page width) is ~104.95mm or ~10.50cm

In case you need pixels, you have to base your calculations by a specific DPI too, so the size in pixels of an A4-sized page with:

• 72 DPI is 595 x 842px
• 96 DPI is 794 x 1123px
• 150 DPI is 1240 x 1754px
• 300 DPI is 2480 x 3508px

---

For starters, here is a simple script listing the basic units and their values after converting to points you have mentioned:

function mmToPt (mm) {
  return mm * 2.83465;
}

function cmToPt (cm) {
  return cm * 28.3465;
}

function inchToPt (inch) {
  return inch * 72;
}

const units = [
  1,
  2,
  3,
  5,
  10,
  15,
  20,
  25,
  50,
  100,
  150,
  250,
  500,
  1000
];

function convert (unit) {
  let name;
  let converter;
  
  switch (unit) {
    case 'mm':
      name = 'millimeters';
      converter = mmToPt;
      break;
    
    case 'cm':
      name = 'centimeters';
      converter = cmToPt;
      break;
      
    case 'inch':
      name = 'inches';
      converter = inchToPt;
      break;
  }
  
  console.log(`Convert ${name} to points:`);
  
  units.forEach(u => {
    let converted = converter(u).toFixed(2);
    
    // get rid of unneeded .00 decimals
    if (+converted === parseInt(converted, 10)) {
      converted = +converted;
    }
    
    console.log(`${u}${unit} is ${converted}pt, so in doc.text(${converted}, ${converted}, 'Message')`);
  });
  
  console.log('--------------------------------------------');
}

convert('mm');
convert('cm');
convert('inch');

You can find a table of paper sizes with corresponding dimensions in points. This table is applicable to PDFKit and to most (if not any) of the PDF generators too.