Configure PDF measurements in Flutter

Nutrient Flutter SDK supports multiple measurement scales in a document and includes a 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.

You can configure measurements in these ways:

• 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 displayed in the measured value.
• Disable snapping — Snapping aligns measurements to existing drawings on a page.
• Enable and disable measurement tools — Measurement tools depend on platform defaults and your license.

The document stores scale and precision configuration, so this configuration persists when users close and reopen the document on any device. Snapping configuration isn’t stored in the document. It persists only on the user’s device, including after app restarts.

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.

A scale is stored in a MeasurementValueConfiguration(opens in a new tab), which also includes an optional scale name and precision.

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

A document can store multiple scales.

Configure scale in one of these ways:

• Use the built-in UI
• Configure scale and precision programmatically

Configure scale and precision with the built-in UI

Users can configure the precision of each measurement. When a user configures precision on one measurement, Nutrient uses that value as the initial precision for future measurements.

Users can also configure the scale and precision of each measurement, or they can apply the same scale and precision to multiple annotations. When a user configures scale and precision on one measurement, Nutrient uses that scale as the initial scale for future measurements.

The measurement displays a maximum of four decimal places.

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

• iOS measurements
• Android measurements
• Web measurements

Configure scale and precision programmatically

To configure scale and precision programmatically, use the MeasurementValueConfiguration(opens in a new tab) class. Use the MeasurementScale(opens in a new tab) class to set the scale, and use the MeasurementPrecision(opens in a new tab) enum to set precision. You can also set an optional scale name. Setting precision only affects the visible value label.

The following example configures the scale so one centimeter in a floor plan document represents two meters in a house. It also configures the measurement to display four decimal places.

    var scale = MeasurementScale(
        unitFrom: UnitFrom.cm,
        valueFrom: 1.0,
        unitTo: UnitTo.m,
        valueTo: 2);

    var precision = MeasurementPrecision.fourDP;

    var measurementValueConfiguration = MeasurementValueConfiguration(
        name: 'Custom Scale', scale: scale, precision: precision);

After you set up MeasurementValueConfiguration(opens in a new tab), add it to the legacy configuration object.

NutrientView(
  documentPath: widget.documentPath,
  configuration: PdfConfiguration(
    measurementValueConfigurations: [measurementValueConfiguration],
  ),
)

Disable snapping

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

To disable snapping in a document with the built-in UI, refer to the platform-specific guides:

• iOS snapping
• Android snapping

Enable and disable measurement tools

By default, measurement tools are enabled on iOS and Android when your license includes the Measurement Tools component. On Web, measurement tools are disabled by default.

Use the legacy NutrientView configuration property to enable or disable measurement tools.

NutrientView(
  documentPath: widget.documentPath,
  configuration: PdfConfiguration(
    enableMeasurementTools: true,
    webConfiguration: PdfWebConfiguration(
      toolbarItems: [
        ...Nutrient.defaultWebToolbarItems,
        NutrientWebToolbarItem(type: NutrientWebToolbarItemType.measurements),
      ],
    ),
  ),
)

On SDK 6, you can add the measurements toolbar button on Web with the cross-platform setMainToolbarItems(opens in a new tab) controller method and ToolbarItemType.measurements.

To remove measurement tools from the annotation toolbar, refer to the customize the annotation toolbar in Flutter guide.