Configure PDF Measurements in React Native

Bridging of measurement configuration in PSPDFKit for React Native was introduced in version 2.6, adding support to store multiple scales in a document and improving the calibration tool. 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. The configuration for snapping isn’t stored in the document, and it persists only when you close and reopen the document on your own device.

The snapping setting persists over app restarts, but it isn’t stored in the document like scale and precision are.

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.

A scale is stored within a MeasurementValueConfiguration, which also includes an optional name for the scale and the precision.

The precision determines the number of decimal places or fractions displayed in the measured value. You can select fractional precision for inches, feet, and yards. The fractional value in the measurement displays fractions of an inch.

There can be multiple scales stored in the document.

Configure scale in one of the following ways:

Configuring Scale and Precision Using the Built-In UI

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

You can configure the scale and precision of each measurement individually or make multiple annotations use the same one. Configuring the scale and precision on one measurement sets the initial scale value for all future measurements. The measurement displays a maximum of four decimal places.

For more detailed instructions on configuring the scale and precision using the built-in UI, refer to the corresponding platform-specific guides:

Configuring Scale and Precision Programmatically

To configure the scale and precision programmatically, use the MeasurementValueConfiguration class. This allows setting the scale using the MeasurementScale class and setting the precision using the MeasurementPrecision enum. It also has an optional name parameter for the scale. Setting the precision only affects the visible value label.

The example below configures the scale so that one centimeter in a floor plan document represents two meters in a house and configures precision so that four decimal values are displayed:

import PSPDFKitView, {
	Measurements,
	MeasurementScale,
	MeasurementValueConfiguration,
} from 'react-native-pspdfkit';

const scale: MeasurementScale = {
	unitFrom: Measurements.ScaleUnitFrom.CM,
	valueFrom: 1.0,
	unitTo: Measurements.ScaleUnitTo.M,
	valueTo: 2.0,
};

const precision = Measurements.Precision.FOUR_DP;

const measurementValueConfig: MeasurementValueConfiguration = {
	name: 'My Custom Scale',
	scale: scale,
	precision: precision,
	isSelected: true,
};

After setting up the MeasurementValueConfiguration, you can then incorporate it into the configuration object as follows:

<PSPDFKitView
	ref={this.pdfRef}
	document={measurementsDocument}
	configuration={{
		iOSBackgroundColor: processColor('lightgrey'),
		pageMode: 'single',
		measurementValueConfigurations: [measurementValueConfig],
	}}
	fragmentTag="PDF1"
	style={styles.pdfColor}
/>

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.

To disable snapping in a document using the built-in UI, check out the corresponding platform-specific guides:

Enabling and Disabling Measurement Tools

By default, measurement tools are enabled on iOS and Android if your license includes the Measurement Tools component.

To remove measurement tools from the annotation toolbar, refer to the guide on customizing the annotation toolbar in React Native.