Configure PDF Measurements in React Native

Measure distance and area in a PDF using PSPDFKit for React Native starting with version 2.6. 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:

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

Configuring Scale

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.

Configure scale in one of the following ways:

Configuring Scale Using the Built-In UI

To configure the scale of a measurement using the built-in UI, follow the steps below.

  1. Touch and hold the measurement.

  2. In the dialog that appears, tap Inspector.

  3. Choose one of the following options:

    • In Scale, specify how length on a page corresponds to length in the real world.

    • In Calibrate Length, specify the real-world length corresponding to the measurement. This option is only available for distance measurements.

The example below configures the scale so that one centimeter in a floor plan document represents two meters in a house.

Android
iOS

The example below configures the scale so that the length of an existing distance measurement represents eight feet in the real world.

Android
iOS

You can configure the scale of each measurement individually. Configuring the scale on one measurement sets the initial scale value for all future measurements.

Configuring Scale Programmatically

To configure the scale of a measurement programmatically, use the setMeasurementScale method for the PSPDFKitView. The example below configures the scale so that one centimeter in a floor plan document represents two meters in a house:

// Import the `PSPDFKitView` component.
import PSPDFKitView from 'react-native-pspdfkit';

...

// Load the PDF document with the `PSPDFKitView` component.
<PSPDFKitView
	ref={this.pdfRef}
	document={exampleDocumentPath}
	configuration={{
		pageMode: 'single',
	}}
/>

// Set the measurement scale.
ref.current?.setMeasurementScale({
    fromUnits: 'cm',
    valueFrom: 1,
    toUnits: 'm',
    valueTo: 2,
});

Available configuration parameters for scale are:

Option
Attribute Function
fromUnits Origin scale unit in PDF document. Available: inch, mm, cm, pt
unitTo Scale unit you’re converting to. Available: inch, mm, cm, pt, ft, m, yd, km, mi
valueFrom Multiplier for scale amount in PDF document (eg. 1mm to 1m: 1mm is valueFrom attribute)
valueTo Multiplier for scale amount you’re converting to

Configuring Precision

The precision determines the number of decimal places displayed in the measured value.

Configure precision in one of the following ways:

Configuring Precision Using the Built-In UI

To configure the number of decimal places displayed in a measured value using the built-in UI, follow these steps:

  1. Touch and hold the measurement.

  2. In the dialog that appears, tap Inspector.

  3. In Precision, specify the number of decimal places to display. You can display a maximum of four decimal places.

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

Android
iOS

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

You can configure the precision of each measurement individually. Configuring the precision on one measurement sets the initial precision value for all future measurements.

Configuring Precision Programmatically

To configure the precision of a measurement programmatically, use the setMeasurementPrecision method for the PSPDFKitView. The example below configures precision so that four decimal values are displayed:

// Load a PDF document using the `PSPDFKitView` component.

<PSPDFKitView
	ref={this.pdfRef}
	document={exampleDocumentPath}
	configuration={{
		pageMode: 'single',
	}}
/>;

// Set the measurement precision to four decimal places.
ref.current?.setMeasurementPrecision('fourDP');

Available options for precision are:

Key
Result
whole
Whole number
oneDP
Number with one decimal place
twoDP
Number with two decimal places
threeDP
Number with three decimal places
fourDP
Number with four decimal places

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

The measurement displays a maximum of four decimal places, and you can configure the precision of each measurement individually. Configuring the precision on one measurement sets the initial precision value for all future measurements.

Disabling Snapping

By default, PSPDFKit snaps measurements to existing drawings on a page. This helps you make precise measurements. A built-in magnifier displays the zoomed-in view of the currently drawn measurement.

Android
iOS

To disable snapping in a document using the built-in UI, follow these steps:

  1. Touch and hold a measurement.

  2. In the dialog that appears, tap Inspector.

  3. In Snapping, disable the toggle.

Disabling Measurement Tools

By default, measurement tools are enabled if your license includes the Measurement Tools component. To disable all measurement tools on React Native, contact Support.