Client-Side Compare

Use viewer.clientCompare for an in-viewer comparison. It keeps the background and overlay documents open in Canvas and does not create a server-side comparison file.

This API is separate from viewer.compare, which creates a comparison file.

Mount the viewer and wait for readiness before creating the comparison. Provide one source for each document; each source may be a URL or a Canvas-resolved file name.

await viewer.mount();
await viewer.ready();

const comparison = await viewer.clientCompare.create({
  backgroundUrl: "https://files.example.com/old-plan.pdf",
  overlayUrl: "https://files.example.com/new-plan.pdf",
  backgroundColor: "#E86767",
  overlayColor: "#0E3BD8"
});

Change the blend and common geometry after the comparison is ready.

• Opacity: accepts a value from 0 to 100. 0 fades the background, 50 balances the blend, and 100 fades the overlay.
• Common level: accepts a value from 1 to 10. 1 is near white and 10 is black.

await viewer.clientCompare.setOpacity(50);
await viewer.clientCompare.setCommonLevel(5);

Subscribe before starting alignment. alignStarted acknowledges the request; the completion event arrives after the user selects a point in each document.

• Keep alignment pending until alignComplete or failed is received.
• Only one alignment session should run at a time.

const stop = viewer.clientCompare.on("alignComplete", (result) => {
  console.log("Client comparison aligned", result.comparisonFileIndex);
});

await viewer.clientCompare.startAlign();
// The user selects the two points in Canvas.

stop();

Call close() to stop alignment and clear its active state. The source documents remain open.

await viewer.clientCompare.close();

The available events are ready, opacityChanged, commonLevelChanged, alignStarted, alignComplete, closed, and failed.

The SDK correlates responses by request ID, applies the configured command timeout, rejects overlapping create or alignment commands, and rejects pending commands when the viewer is destroyed.

const stop = viewer.clientCompare.on("failed", (error) => {
  console.error("Client comparison failed", error);
});

// Remove subscriptions when the viewer is disposed.
stop();
viewer.destroy();