Align Revisions

Preconditions: The background and overlay files are prepared, accessible, and represent the same intended document area.

• Skip alignment only when the sources share page size, orientation, scale, margins, and drawing coordinates.
• Start alignment when one source is scanned, cropped, rotated, exported from a different system, or visibly offset from the other source.
• Treat alignment as an operator-assisted step. The documented Revision API exposes an align command that starts the alignment workflow in the viewer.

Steps to execute:

• 1Disable duplicate compare and align actions while alignment is active.
• 2Call viewer.compare.align(...) with the prepared background and overlay file targets.
• 3Show user guidance that the operator must pick matching reference locations on both revisions.
• 4Keep cancellation available so the operator can exit without producing a comparison.
• 5Listen for the terminal viewer event. Treat comparisonComplete as success and comparisonError as failure.
• 6On success, clear the active alignment state and display the aligned comparison result.
• 7On cancellation or failure, clear loading state, unlock inputs, and allow the user to restart alignment or return to direct comparison settings.

Give operators concise guidance before they start selecting points. Better points reduce false differences in the final comparison.

• Choose distinct landmarks that exist in both revisions.
• Prefer sharp geometry such as grid intersections, corners, or clear boundary crossings.
• Use points that are far apart across the drawing area.
• Zoom in before selecting each reference point.
• Avoid ambiguous marks, thick scanned lines, or points that may have changed between revisions.

The viewer uses the selected reference points to align the revisions and then returns a comparison result through the same terminal success event used by compare.

If alignment fails, do not leave the UI locked. Clear the active state, keep the prepared file inputs intact, explain that alignment could not be completed, and let the operator retry with clearer reference points or cancel the alignment path.