Configure measurements in a PDF using JavaScript

Measure distance and area in a PDF using Nutrient Web SDK 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 user interface (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 of the viewer if your license doesn’t include the Measurement Tools component.

Enable measurement tools as demonstrated in the code snippet below:

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

Configuring scale and precision

Configure the scale and precision in one of the following ways:

Using the built-in user interface (UI)
Programmatically

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 the steps below:

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 the steps below:

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.

Examples

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

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

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

Setting the precision only affects the visible value label. You can retrieve the unrounded measurement value through 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 the steps below:

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 the steps below:

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.