Existing controller with the original query image loaded.
Result retained from the completed matching job.
Exact object selected from result.candidates (not a copy).
Reference snapshot used for that result, including its CRS.
Token captured before acquiring pixels and starting the job.
Current revision, merge/replace policy and optional projection mapping.
MatchingError with STALE if inputs/revisions no longer agree,
or BUDGET when fewer than six proposed point slots are available. Core fitting,
projection or domain validation can also throw; no controller edit precedes them.
Apply a reviewed candidate as distributed control points in one undoable edit.
No dialog or UI is supplied: invoke only after the user explicitly accepts a candidate. Matching alone does not modify the controller. Existing points and their fit model are preserved by default. All points are fitted/validated in the working CRS through core before mutation; the full source-image projective domain must remain valid. A pixel-space similarity may become affine after map-coordinate conversion. The operation adds source/backend provenance and respects the core GCP limit.