Configure Measurements in a PDF on Android

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

• Configure the scale of the measurements, which 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 the precision of the measurements, which determines the number of decimal places displayed in the measured value.

• Disable snapping and magnification.

• Disable measurement tools.

The configurations for scale and precision are stored in a document by MeasurementValueConfiguration objects, and they persist when you close and reopen the document on any device when they’re used by annotations. The snapping setting persists over app restarts, but it isn’t stored in the document like scale and precision are.

Configuring Scales

The scale determine 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.

You can have multiple scales configured. The currently selected scale is displayed in the button in the bottom-right corner. Any future measurements use the currently selected scale.

Configure scale in one of the following ways:

• Using the built-in user interface (UI)

• Programmatically

Configuring Scales Using the Built-In UI

Configure scale in one of the following ways:

• Create a scale from the Annotation Inspector

• Create a scale using the Calibrate Length tool

• Change the current scale

• Edit a scale

• Change the scale for an existing measurement

Creating a Scale from the Annotation Inspector

1. Tap a measurement.

2. Open the Scale view in one of the following ways:

   • Tap the Inspector button that appeared in the toolbar and then tap Scale.

   • Tap the button that appears in the bottom-right corner.

3. Set the following parameters:

   • Optional: In Name, set the scale name.

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

   • In Precision, specify the number of decimal places to display. You can display a maximum of four decimal places for units using the International System of Units (SI). Additionally, you can display four proper fractions for imperial units.

The example below creates a new scale from the Inspector:

Creating a Scale Using the Calibrate Length Tool

1. Select the calibration tool from the annotation toolbar. (If you can’t locate it, touch and hold a measurement to open up the sub-toolbar.)

2. Tap the Calibrate Length tool.

3. Draw a line used for calibrating the scale. Recommended: If the PDF has a drawn scale, use it as the scale’s reference line.

4. Set the following parameters in the Calibrate Length:

   • Optional: In Name, set the scale name.

   • In Calibrate Length, set the real world length corresponding to the drawn line.

   • In Precision, specify the number of decimal places to display. You can display a maximum of four decimal places for units using the International System of Units (SI). Additionally, you can display four proper fractions for imperial units.

The drawn line is automatically removed once the scale is confirmed.

The example below creates a new scale based on the Calibrate Length tool and adds a measurement based on that scale.

Changing the Current Scale

To change the currently used scale, follow these steps:

1. Tap a measurement.

2. Open the Scale view in one of the following ways:

   • Tap the Inspector button that appeared in the toolbar.

   • Tap the button that appeared in the bottom-right corner.

3. Tap Scale.

4. Select the scale you want the measurement tool to start using.

Editing a Scale

To modify an existing scale, follow these steps:

1. Tap a measurement.

2. Open the Scale view in one of the following ways:

   • Tap the Inspector button that appeared in the toolbar.

   • Tap the button that appeared in the bottom-right corner.

3. Tap Scale.

4. Swipe the scale you want to modify and tap Edit.

5. Change any of the parameters.

The following rules apply when modifying a scale:

• When the modified scale is used by a measurement, all measurements using this scale will be updated.

• When the scale is modified and matches another existing scale (which is determined by comparing the scale value and precision of both scales), a popup window appears to confirm the operation. After accepting the changes, the measurements using the modified scale are assigned to the existing scale and the edited scale is deleted.

Changing the Scale for a Measurement

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

To change the scale for a measurement, use the following steps:

1. Tap a measurement.

2. Tap Inspector.

3. Tap Scale.

4. Select the scale you want to use and close the scale list inspector.

After this operation, the new scale is assigned to the selected measurement.

Configuring Scales Programmatically

You can programmatically perform the following operations on a scale:

• Create a new scale.

• Edit an existing scale.

• Remove an existing scale.

Creating a Scale Programmatically

To configure a scale programmatically, follow these steps:

1. Create a new MeasurementValueConfiguration object. It uses the following parameters:

• Optional: name — The name of the scale.

• Scale — The scale values and their units, represented by a Scale object.

• Precision — The precision of the measurement, represented by the Precision enumeration.

2. Add the created object to the document with the add method from the MeasurementValueConfigurationEditor interface. It uses the following parameters:

• value — The MeasurementValueConfiguration object.

• addToUndo — A Boolean value that specifies if the modification is recorded to the undo stack.

The example below creates a scale so that one centimeter in a floor plan document represents two meters in a house with one-decimal point precision, and adds it to the document:

val scaleValue = Scale(1.0f, Scale.UnitFrom.CM, 2.0f, Scale.UnitTo.M)
val scale = MeasurementValueConfiguration("Main Scale", scaleValue, MeasurementPrecision.ONE_DP)
MeasurementValueConfigurationEditor.add(scale, true)

Editing a Scale Programmatically

To edit an existing scale programmatically, use the modify method from the MeasurementValueConfigurationEditor interface. It uses the following parameters:

• oldValue — The MeasurementValueConfiguration object you want to modify.

• newValue — A new MeasurementValueConfiguration object with the updated parameters.

• modifyAssociatedAnnotations — A Boolean value that specifies whether measurements using the oldValue are to be updated.

• addToUndo — A Boolean value that specifies if the modification is recorded to the undo stack.

The example below modifies the scale value from 1:1 to 1:2 and updates all previously drawn measurements:

val scaleValue = Scale(1.0f, Scale.UnitFrom.CM, 1.0f, Scale.UnitTo.CM)
val oldScale = MeasurementValueConfiguration("One-to-One", scaleValue, MeasurementPrecision.ONE_DP)
// Update the scale value.
scaleValue = Scale(1.0f, Scale.UnitFrom.CM, 2.0f, Scale.UnitTo.CM)
val newScale = MeasurementValueConfiguration("One-to-One", scaleValue, MeasurementPrecision.ONE_DP)
MeasurementValueConfigurationEditor.modify(oldScale, newScale, true, true)

Removing a Scale Programmatically

To remove a scale programmatically, use the remove method from the MeasurementValueConfigurationEditor interface. It uses the following parameters:

• value — The MeasurementValueConfiguration object you want to remove.

• deleteAssociatedAnnotations — A Boolean value that specifies whether to delete measurements using the deleted object.

• addToUndo — A Boolean value that specifies if the modification is recorded to the undo stack.

The example below deletes a scale and all measurements using it:

val scaleValue = Scale(1.0f, Scale.UnitFrom.CM, 1.0f, Scale.UnitTo.CM)
val scale = MeasurementValueConfiguration("", scaleValue, MeasurementPrecision.ONE_DP)
MeasurementValueConfigurationEditor.delete(scale, true, true)

Configuring Precision

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

Configure precision in one of the following ways:

• Using the built-in user interface (UI)

• Programmatically

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. Tap the measurement.

2. In the toolbar that appears, tap Inspector.

3. Tap Scale.

4. Swipe the scale you want to modify and tap Edit.

5. In Precision, specify the number of decimal places to display. You can display a maximum of four decimal places for units using the International System of Units (SI). Additionally, you can display four proper fractions for imperial units.

Changing the precision of a measurement creates a new scale assigned to the selected measurement. The newly created scale is a copy of the previously used scale with the precision changed to the new value.

Setting the precision only affects the visible value label. You can retrieve the unrounded measurement value from the Annotation object via the getMeasurementInfo method.

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 MeasurementPrecision enumeration.

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

A measurement displays a maximum of four decimal places with the additional four proper fractions for imperial units.

Disabling Snapping and Magnification

By default, PSPDFKit snaps measurements to existing drawings on a page (the Snap to Point option) and to the measurement itself (the Snap to Self option). This helps you make precise measurements. A built-in magnifier displays the zoomed-in view of the currently drawn measurement.

Snapping and magnification are enabled by default. Disable snapping and magnification in one of the following ways:

• Disable snapping using the built-in user interface (UI)

• Disable snapping and magnification programmatically

Disabling Snapping Using the Built-In UI

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

1. Tap Settings.

2. Disable the Snap to Point or the Snap to Self toggle.

Disabling Snapping and Magnification Programmatically

To disable snapping to point programmatically, use the isMeasurementSnappingEnabled method:

PSPDFKitPreferences.get(context).isMeasurementSnappingEnabled = false

To disable snapping to point programmatically, use the isSnapToSelfEnabled method:

PSPDFKitPreferences.get(context).isSnapToSelfEnabled = false

To disable the magnifier programmatically, use the enableMagnifier method:

val configuration = PdfConfiguration.Builder()
    .enableMagnifier(false)
    .build()

This also disables the magnifier for all other PSPDFKit features, such as text selection.

Disabling Measurement Tools

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

To disable all measurement tools, use the setMeasurementToolsEnabled method:

val configuration = PdfConfiguration.Builder()
    .setMeasurementToolsEnabled(false)
    .build()

To disable each measurement tool individually, use the enabledAnnotationTools method. The example below disables the elliptical and rectangular area measurement tools:

val annotationTools = mutableListOf(*AnnotationTool.values())
annotationTools.remove(AnnotationTool.MEASUREMENT_AREA_ELLIPSE)
annotationTools.remove(AnnotationTool.MEASUREMENT_AREA_RECT)

val configuration = PdfConfiguration.Builder()
    .enabledAnnotationTools(annotationTools)
    .build()