Measurement Guide

This guide covers the NPM SDK measurement workflow. Do not apply its method names or event contracts to a PostMessage integration.

Before calibration, scale, tool, save, or extraction actions, mount the viewer, wait for viewer.ready(), and open the intended document. Keep the active fileIndex available in host state because calibration and scale operations target a specific file.

• Measurement overview
• Calibration API
• Scale API

Build the workflow in this order. It prevents measurement controls from becoming available before the document and its scale are trustworthy.

• 1Mount the viewer, wait for readiness, open the drawing, and retain its active file index.
• 2Read the current scale and show it in the host UI.
• 3Calibrate when the scale is missing, uncertain, or needs to vary by page range.
• 4Enable the required measurement action only after the scale is accepted.
• 5Create, review, save, or extract measurement data.
• 6Handle cancellation, failed operations, and cleanup before enabling another workflow.

Call viewer.measurements.scale.get({ fileIndex }) before enabling takeoff controls when the application needs to confirm the active scale. Subscribe with viewer.measurements.scale.on("snapshot", handleSnapshot) when the displayed scale must follow Canvas changes.

A scale snapshot is filtered by file index when Canvas includes one; it is not correlated by request ID. After viewer.measurements.scale.add({ fileIndex, scale }), wait for a later snapshot or call viewer.measurements.scale.get({ fileIndex }) before claiming that the UI has the updated value.

• viewer.measurements.scale.get({ fileIndex })
• viewer.measurements.scale.add({ fileIndex, scale })
• viewer.measurements.scale.request({ fileIndex })
• viewer.measurements.scale.on("snapshot", handleSnapshot)

Match the Canvas reference with a compact engineering ribbon, a persistent active-scale card, and a Calibrate and Calculator sidebar. Keep the active scale visible beside the drawing; reserve the floating Canvas overlay for the short "pick a known line" calibration state.

• Open the sidebar after the drawing is ready, then call viewer.measurements.scale.get({ fileIndex }) or use an existing snapshot subscription to populate the saved-scale list.
• Keep measurement tools unavailable until a snapshot confirms an active scale for the current file.
• For manual scale, validate metric or imperial fields before viewer.measurements.scale.add({ fileIndex, scale }).
• After add, keep the form pending and refresh with viewer.measurements.scale.get({ fileIndex }) or wait for viewer.measurements.scale.on("snapshot", handleSnapshot) before showing the scale as active.
• The NPM API has no dedicated select or delete scale method. A scale-library row can make a known full scale active only by sending viewer.measurements.scale.add({ fileIndex, scale: selectedScale }) with selectedScale.isSelected set to true and waiting for a later snapshot; do not offer deletion unless it is a host-only preset action.
• When dismissing an active calibration sidebar, cancel the NPM calibration flow before discarding its request state.

Calibration is a guided NPM SDK flow, not a single submit action. Keep the request ID returned by viewer.measurements.calibration.start({ fileIndex }) and use it only for that active calibration request.

• 1Ready: Enable “Pick reference line” only after the drawing is open.
• 2Picking: Call viewer.measurements.calibration.start({ fileIndex }); retain the returned request ID and keep Cancel available.
• 3Picked: Wait for viewer.measurements.calibration.on("finished", handleFinished) with a finished event before enabling Calculate.
• 4Candidate: Call viewer.measurements.calibration.calculate({ requestId, fileIndex, measurementSystem, dimPrecision }), then show the candidate scale returned by the SDK or emitted through scaleCalculated.
• 5Applied: Call viewer.measurements.calibration.apply({ requestId, fileIndex }) only for the active candidate; enable measurement controls only when its returned scale snapshot identifies an active scale.

Use the Calibrate sidebar tab alongside the manual calculator, but make calibration a visible sequence. The measured Canvas line is read-only feedback; the operator enters the known real-world length and unit required for the NPM calculate call.

• 1Ready: show Start and the known-length inputs; disable Calculate and Apply.
• 2Picking: after viewer.measurements.calibration.start({ fileIndex }), show a clear instruction over Canvas to pick the reference line and keep Cancel available in the sidebar.
• 3Picked: when viewer.measurements.calibration.on("finished", handleFinished) reports the active request, display measuredLength as read-only and enable Calculate.
• 4Candidate: display the calculated scale from calculate or scaleCalculated; enable Apply only for that active request and file.
• 5Applied: after apply returns a scale snapshot, reset the sidebar only when the snapshot confirms the active scale.
• 6Error or cancel: keep correctable inputs, clear the request-specific candidate and measured length, and return the Calibrate tab to Ready.

Validate values in the host UI before calling the SDK, and retain valid user input when a request fails. Metric and imperial calibration use different payload shapes.

• Metric calibration uses measurementSystem: 1, a supported full unit name, and a positive calibrateCorrectionMetricValue.
• Imperial calibration uses measurementSystem: 2 and requires positive feet, inches, or both; dimPrecision is the fractional denominator.
• dimPrecision must be a non-negative integer, and totalPages must be positive when supplied.
• Page ranges are 1-based inclusive [start, end] pairs. Use them only when the scale is intentionally limited to selected pages.
• Never reuse a request ID, candidate scale, or active file index after cancellation or after the user changes drawings.

After the drawing is ready and its scale is accepted, activate a measurement action through viewer.tools.set({ action, enabled: true }). Await the command result and show any failure in the host UI. Use viewer.tools.clear() when exiting a mode or before switching to an incompatible action.

• MEASURE_LENGTH: distance between selected points.
• MEASURE_AREA: area measurement.
• MEASURE_PATH, MEASURE_ARC, and MEASURE_RECTANGULAR_AREA: specialized geometry measurements.
• MEASURE_ANGLE_CCLOCKWISE: angle measurement.
• COUNT: point counting; SNAP: precision snapping behavior.
• Measurement tools reference

Saving and extracting are separate NPM workflows. Use viewer.annotations.save() when the host needs a completed save result; it resolves after the matching save completion response. Auto-save is a fire-and-forget setting, not confirmation that a save finished.

Use viewer.annotations.getData({ filter: "measurements" }) for a measurement-only snapshot. Use all when the host also needs annotation data, and keep the returned data as an application snapshot rather than assuming it stays live.

• Save and auto-save
• Data extraction
• Measurement creation events
• Select, visibility, delete, and clear

Every failed or cancelled operation must return the host UI to a usable state without applying a stale scale or leaving a drawing tool active.

• Cancel calibration when the reference line is wrong; clear the request ID, candidate scale, and calibration-only UI state.
• If calculation or apply fails, preserve the known-length input and units but require a valid active request before retrying.
• If a tool command fails, keep the prior active tool state visible and let the user retry or clear tools.
• If save or extraction fails, show the error and allow a manual retry; do not report persistence or exported quantities as complete.
• On route cleanup, unsubscribe listeners, clear transient host state, and destroy the viewer according to the integration lifecycle.

Verify the complete NPM workflow with a known drawing and a reference dimension whose real-world value is already established.

• The drawing is open and the intended file index is used for scale and calibration calls.
• Calculate remains unavailable until the calibration finished event arrives.
• Apply remains unavailable until a candidate scale exists for the current request and file.
• Changing drawings or cancelling calibration does not reuse an old request ID or candidate scale.
• Each enabled tool uses a documented action ID and can be cleared.
• Save returns a completed result, and extraction with the measurements filter returns only measurement data.
• Route unmount removes listeners and destroys the viewer without retaining stale UI state.