Configure measurements in a PDF using JavaScript

Use Nutrient Web SDK 2022.5 or later to measure distance and area in a PDF. To use measurement tools in your app, contact the Sales team to add the Measurement Tools component to your license, or run the SDK in trial mode.

This guide covers two tasks:

• Enable measurement tools to show measurement tools in the user interface (UI).
• Configure scale and precision. Scale defines the size of an object on a page relative to the size of a corresponding real-world object. For example, one centimeter on a floor plan can represent two meters in a house. Precision defines the decimal places or fractions shown in the measured value.

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.

Add the measurement tools item to the toolbar configuration:

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

Configuring scale and precision

Configure scale and precision with the built-in UI or programmatically:

• Using the built-in UI
• Programmatically

Configuring scale and precision using the built-in UI

Use the built-in UI to configure scale and precision in one of two ways:

• Specify how a length on the page corresponds to a real-world length.
• Draw a line on the page and specify the corresponding real-world length.

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

1. Click the measurement tools icon in the toolbar.
2. If this is the first time you’ve configured a scale, click Set Scale. If you already created a scale and want to create another one, click the scales dropdown on the right, and then click Edit or add new scale.
3. Click Add new scale.
4. Rename the scale.
5. Specify how length on a page corresponds to length in the real world.
6. 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.
7. Click Done.

To configure a scale by drawing a line on the page, follow these steps:

1. Click the measurement tools icon in the toolbar.
2. Click the scales dropdown on the right, and then click either Use calibration tool or the calibration icon.
3. Draw a line on the page.
4. In Calibrate length, specify the real-world length corresponding to the line you drew.
5. Rename the scale.
6. 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.
7. Click Done.

Examples

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

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

The following example configures precision so the scale shows four decimal places.

Selecting the scale for a measurement

To set the scale for a measurement, follow these steps:

1. Click a measurement.
2. In the toolbar, click the scales dropdown.
3. 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 following example adds a custom scale where one centimeter in the document represents two meters in the real world. Nutrient Web SDK sets the newly created measurement as the default scale when the document loads.

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

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

Displaying a secondary unit of measurement

You can display the measurement value in a secondary unit of measurement. The secondary unit appears in parentheses after the primary unit.

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

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

Snapping measurement points

When users draw with measurement tools, the cursor can snap to the nearest snapping point, such as a line endpoint, intersection, or vertex in the document. Snapping helps users place measurement points precisely.