Skip to content

Measurement ​

Measurement calculates distance, perimeter, and area on a PDF page. The result is shown after scale conversion and can be written as a measurement annotation.

The full UI (UIExtension) includes measurement tools in the toolbar: distance, perimeter, polygon area, and circle area. Those buttons do not need extra tool registration. Use the APIs below to set scale, label, and snapping before creation, or to switch measurement tools in code.

From 11.1.0, configure measurement annotations with PDFViewer.getCreateMeasurementService(). The service applies only to measurements created afterward. It does not update measurement annotations already on the page.

Measurement tools ​

ToolState nameResult
DistancecreateDistanceDistance between two points
PerimetercreatePerimeterLength of a polyline
Polygon areacreateAreaArea enclosed by a polygon
Circle areacreateCircleAreaArea of a circle

The same state names are STATE_HANDLER_CREATE_DISTANCE, STATE_HANDLER_CREATE_PERIMETER, STATE_HANDLER_CREATE_AREA, and STATE_HANDLER_CREATE_CIRCLE_AREA on PDFViewCtrl.constants.STATE_HANDLER_NAMES.

Switch the tool on PDFViewer:

javascript
pdfViewer.getStateHandlerManager().switchTo(
    PDFViewCtrl.constants.STATE_HANDLER_NAMES.STATE_HANDLER_CREATE_DISTANCE
);

Switch the tool on PDFUI:

javascript
const stateHandlerManager = await pdfui.getStateHandlerManager();
stateHandlerManager.switchTo(
    PDFViewCtrl.constants.STATE_HANDLER_NAMES.STATE_HANDLER_CREATE_DISTANCE
);

Distance ends on the second click. Perimeter and polygon area take multiple clicks, then finish or cancel from the context menu.

Scale, label, and markup before creation ​

Settings from getCreateMeasurementService() apply to measurements created next. The scale maps a length on the page to a real-world length, for example 1 centimeter on the page to 1 foot in the field.

javascript
const service = pdfViewer.getCreateMeasurementService();

await service.setScaleRatio({
    userSpaceScaleValue: 1,
    userSpaceUnit: PDF.annots.constant.Annot_Unit_Type.cm,
    realScaleValue: 1,
    realUnit: PDF.annots.constant.Annot_Unit_Type.ft
});

await service.setLabel('Wall length');
await service.setMarkupEnabled(true);

With setMarkupEnabled(false), the tool leaves a measurement mark on the page and does not create a measurement annotation.

Annot_Unit_Type values are inch, ft, yd, mi, pt, pica, mm, cm, m, km, and custom.

Result panel and snapping ​

The result panel shows the current distance, perimeter, or area. Snapping pulls an endpoint to a path endpoint, midpoint, intersection, or nearest point.

javascript
const service = pdfViewer.getCreateMeasurementService();

await service.setShowResultInfomation(true);
service.setSnapModes([
    PDFViewCtrl.constants.SNAP_MODE.EndPoint,
    PDFViewCtrl.constants.SNAP_MODE.IntersectionPoint
]);

setSnapModes([]) turns snapping off. MidPoint and NearestPoint are also available. The method name setShowResultInfomation is spelled as in the API.

To set snapping for one measurement tool, use PDFViewer.setSnapMode(stateHandlerName, modes). PDFViewer.getSnapMode(stateHandlerName) reads that tool's current snap settings and returns an empty array when none are set.

Update the scale of existing measurements ​

PDFPage.setMeasureScaleRatio() has been available since 8.4.0. It updates measurement annotations that already exist on a page and requires assemble or modify permission. The ratio string uses the form "1 inch = 1 ft".

javascript
const page = await pdfDoc.getPageByIndex(0);

await page.setMeasureScaleRatio(true, 'inch', '1 inch = 1 ft', 2);

When the first argument is true, the scale is stored on the current page. This API does not replace CreateMeasurementService.setScaleRatio(): the page API changes existing annotations, and the service chooses the scale for measurements created next.

Custom measurement tools ​

To measure something the built-in tools do not cover, such as a rectangular area, implement a StateHandler. See Custom area measurement tool.