Configure Measurements in a PDF Using JavaScript

Measure distance and area in a PDF using PSPDFKit for Web starting with version 2022.5. To measure distance and area in your app, contact the Sales team to add the Measurement Tools component to your license, or run the SDK in trial mode.

Configure measurements in one of the following ways:

Enable measurement tools, which is required to show the measurement tools in the UI.
Configure the scale and the precision of the measurements. The scale determines the size of an object on a page relative to the size of a corresponding real-world object. For example, a document shows the floor plan of a house where one centimeter on the floor plan represents two meters in the house. The precision determines the decimal places or fractions displayed in the measured value.

The configuration for scale and precision is stored in a document, and it persists when you close and reopen the document on any device.

Enabling Measurement Tools

By default, measurement tools aren’t visible in the main toolbar if your license includes the Measurement Tools component.

To enable measurement tools, use the following code:

PSPDFKit.load({
  // Other options.
  toolbarItems: [
    ...PSPDFKit.defaultToolbarItems,
    { type: "measure" }
  ]
});

Configuring Scale and Precision

The scale determines the size of an object on a page relative to the size of a corresponding real-world object. For example, a document shows the floor plan of a house where one centimeter on the floor plan represents two meters in the house.

The precision determines the decimal places or fractions displayed in the measured value.

Configuring Scale and Precision Using the Built-In UI

To configure scale and precision using the built-in UI, choose one of the following options:

Specify how length on a page corresponds to length in the real world.
Specify the real-world length corresponding to a line you draw on the page.

To configure a scale by specifying how length on a page corresponds to length in the real world, follow these steps:

Click the measurement tools icon in the toolbar.
If this is the first time you configure a scale, click Set Scale. If you already created a scale and want to create a new scale, click the scales dropdown on the right, and then click Edit or add new scale.
Click Add new scale.
Rename the scale.
Specify how length on a page corresponds to length in the real world.
In Precision, specify the decimal places or fractions to display. You can display a maximum of four decimal places or fractions up to one sixteenth.
Click Done.

When you delete a scale, all measurements associated with that scale are automatically deleted.

To configure a scale by specifying the real-world length corresponding to a line you draw on the page, follow these steps:

Click the measurement tools icon in the toolbar.
Click the scales dropdown on the right, and then click either Use calibration tool or the calibration icon.
Draw a line on the page.
In Calibrate length, specify the real-world length corresponding to the line you drew.
Rename the scale.
In Precision, specify the decimal places or fractions to display. You can display a maximum of four decimal places or fractions up to one sixteenth.
Click Done.

The example below creates a new scale so that one centimeter in a floor plan document represents one meter in a house.

The example below calibrates a new scale so that the length of the distance measurement represents 24 meters in the real world.

The example below configures precision so that four decimal places are displayed for a scale.

Setting the precision only affects the visible value label. You can retrieve the unrounded measurement value via the API.

Selecting the Scale for a Measurement

You can set the scale you want to use for each measurement. To set the scale for a measurement, follow these steps:

Click a measurement.
In the toolbar, click the scales dropdown.
Select the scale you want to use for the measurement.

Configuring Scales Programmatically

To configure the scale of a measurement programmatically, use the measurementValueConfiguration property. The example below adds a new custom scale where one centimeter in the document represents two meters in the real world. The newly created measurement is set as the default scale when the document is loaded:

const customScales = [
  {
    name: 'myScale',
    scale: {
      unitFrom: PSPDFKit.MeasurementScaleUnitFrom.CENTIMETERS,
      unitTo: PSPDFKit.MeasurementScaleUnitTo.METERS,
      fromValue: 1,
      toValue: 2
    },
    precision: PSPDFKit.MeasurementPrecision.FOUR,
    selected: true
  }
];

PSPDFKit.load({
  // Other options.
  measurementValueConfiguration: (documentScales) => {
    return [...customScales, ...documentScales];
  }
});

Displaying a Secondary Unit of Measurement

The measurement value can be displayed in a secondary unit of measurement. This is displayed in parentheses after the primary unit of measurement.

To display the measurement value in a secondary unit of measurement, follow these steps:

Click the measurement tools icon in the toolbar.
Click the scales dropdown on the right, and then click Edit or add new scale.
Enable Display Secondary Unit.
Select the unit of measurement and the precision used to display the secondary unit of measurement.
Click Done.