Measure and Take Off Quantities in the Browser

Use the NPM SDK after mounting the viewer, waiting for viewer.ready(), opening the intended drawing, and retaining its active fileIndex. Do not enable measurement controls until the current file and scale state are known.

Read the NPM Measurement Guide, Scale API, Calibration API, and Tools API for the detailed contracts.

Keep scale confirmation, tool activation, and takeoff persistence as separate host states.

• 1Register document and measurement listeners before opening the drawing.
• 2Await viewer.ready() and track viewer.documents.on("fileInfo", handleFileInfo) for the active file index.
• 3Call viewer.measurements.scale.get({ fileIndex }) before enabling measurement controls.
• 4Start calibration with viewer.measurements.calibration.start({ fileIndex }) when a trusted scale is not available.
• 5Wait for viewer.measurements.calibration.on("finished", handleFinished) before calculating and applying a candidate scale.
• 6Call viewer.tools.set({ action, enabled: true }) only after a scale snapshot confirms the active scale.
• 7Await the returned tool result and require result.success before marking the host tool active.
• 8Use viewer.annotations.save() or viewer.annotations.getData({ filter: "measurements" }) only for the separate save or extraction step.

Validate host input before sending an SDK request and scope transient state to the current file.

• Require a positive finite known length for calibration.
• Use the documented metric or imperial payload shape and exact unit names.
• Use a non-negative integer for dimPrecision and positive page counts when supplied.
• Treat page ranges as 1-based inclusive ranges.
• Require an active calibration request before calculating or applying a candidate scale.
• Use documented measurement action IDs such as MEASURE_LENGTH, MEASURE_AREA, and COUNT.
• Do not reuse a request ID, candidate scale, or file index after cancellation or a document change.

A measurement creation event updates the host review state; it does not by itself prove persistence. Await viewer.annotations.save() when the host needs a completed save operation. Use viewer.annotations.getData({ filter: "measurements" }) for a measurement-only snapshot and treat the returned data as an application snapshot.

Keep host JSON, XLSX, database, and work-order exports separate from Canvas save and extraction results. Report each operation using its own completion condition.

On calibration, tool, save, or extraction failure, preserve correctable input, clear stale candidates and result state, and offer retry. Cancellation must clear the active request and leave no measurement tool active by accident.

On route cleanup, unsubscribe listeners, clear transient host state, and destroy the viewer according to the NPM lifecycle. A failed host export must not erase a confirmed viewer result.

Use the workflow pages and reference example for the complete React sequence and acceptance checks.