Calibrate Drawing Scale

Enable the Calibrate tab only after the viewer is ready, the intended drawing is active, and its fileIndex is known. Keep the sidebar visible or restore it when Canvas needs the operator to complete a calibration step.

• Show active file and confirmed scale details in the active-scale card.
• Keep calibration and calculator values in host state, scoped to the active file.
• Subscribe to finished, scaleCalculated, and scale snapshot events before Start.
• Do not reuse a request ID after changing the active file or cancelling.

The reference sidebar maps to a longer NPM flow than its demo controls imply. Apply is not available immediately after the reference line is picked: calculate a candidate first.

• 1Ready: show Start and the system, unit, precision, and known real-world length inputs in the Calibrate sidebar tab.
• 2Picking: call viewer.measurements.calibration.start({ fileIndex }), store its returned request ID, show the floating pick instruction over Canvas, and keep Cancel available in the sidebar.
• 3Picked: handle viewer.measurements.calibration.on("finished", handleFinished) only when it belongs to the active request and file; display measuredLength as read-only feedback.
• 4Candidate: call viewer.measurements.calibration.calculate({ requestId, fileIndex, measurementSystem, dimPrecision }) with the validated system-specific length values, then display the returned or emitted candidate scale.
• 5Applied: call viewer.measurements.calibration.apply({ requestId, fileIndex }) and wait for its returned scale snapshot before enabling measurement tools or resetting the sidebar.
• 6Cancelled: call viewer.measurements.calibration.cancel({ requestId, fileIndex }), clear request-specific state, and keep valid form values for retry.

Use disabled states that reflect the documented NPM validation rules, not just visual sidebar steps.

• Start is available only when the active file is ready and no calibration request is active.
• Calculate is unavailable until the active request has a finished event and the metric or imperial form values are valid.
• Metric calculation requires measurementSystem: 1, a supported full unit name, and a positive calibrateCorrectionMetricValue.
• Imperial calculation requires measurementSystem: 2 and positive feet, inches, or both.
• Apply is unavailable until a candidate exists for the active request and file.
• Cancel remains available while picking or after a candidate is displayed.
• A busy request disables duplicate submission but keeps status text visible through an aria-live region.

If the reference is wrong, the command times out, or the sidebar is dismissed, return the host UI to a safe ready state without applying a stale candidate.

• Retain the known-length, unit, precision, and page-range inputs after a recoverable calculation failure.
• Clear the active request ID, picked measurement, and candidate scale after cancellation or a file change.
• Do not report the scale as active until the apply result returns a confirming snapshot.
• If apply fails, keep the Calibrate tab open, unlock Apply after the error, and require a valid active request before retry.
• On route cleanup, cancel an active calibration when appropriate, unsubscribe listeners, and destroy the viewer.

Use the component pages for exact option shapes and event payloads.

• Calibration API
• Scale management
• Measurement tools