Compare

Use viewer.compare.compare({ backgroundUrl, overlayUrl }) to create a visual comparison from two file sources.

Compare commands are available after the viewer is mounted and Canvas is ready. In SDK 2.2.2, await the returned Promise<ComparisonResult> to receive the generated comparison result and its outputFileUrl. viewer.compare.save({ outputName }) remains deprecated compatibility behavior and is not part of new-integration workflows.

import { createViewer } from "@rasterex/viewer";

const viewer = createViewer({
  container: "#viewer"
});

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

Because comparison calls report completion asynchronously, subscribe to the terminal compare event channels before executing a compare action:

• viewer.compare.compare({ backgroundUrl, overlayUrl }) returns Promise<ComparisonResult> and resolves after a payload-bearing comparisonComplete followed by progressEnd.
• The promise rejects on comparison errors, timeout, disconnect, or invalid input.
• Use progressStart, comparisonComplete, comparisonError, and progressEnd for observable UI state. Do not use document fileReady events as compare completion.

const cleanups = [
  viewer.compare.on("comparisonComplete", (result) => {
    if (result) console.log("Comparison completed:", result.relativePath);
  }),
  viewer.compare.on("comparisonError", (error) => {
    console.error("Comparison error:", error.message);
  })
];

Execute visual diff generation by passing background and overlay URLs:

• Canvas loads the background and overlay files, builds the comparison overlay, opens the generated file, and emits comparisonComplete followed by progressEnd. The returned promise resolves with ComparisonResult after that lifecycle.

const result = await viewer.compare.compare({
  backgroundUrl: "https://files.example.com/old-plan.pdf",
  overlayUrl: "https://files.example.com/new-plan.pdf",
  outputName: "old-vs-new.pdf",
  dpi: 200,
  backgroundColor: "#E86767",
  overlayColor: "#0E3BD8",
  equalColor: "rgb(128,128,128)"
});

console.log(result.outputFileUrl);

If files reside in the Canvas file base directory, you can query using file names directly:

const result = await viewer.compare.compare({
  backgroundFileName: "old-plan.pdf",
  overlayFileName: "new-plan.pdf",
  outputName: "old-vs-new.pdf"
});

console.log(result.outputFileUrl);

Use viewer.compare.align({ backgroundUrl, overlayUrl, alignArray }) with up to two verified point objects when the host already has alignment data. Omit alignArray when the operator should select matching points in Canvas.

Interactive alignment can emit an initial comparisonComplete without a result while Canvas waits for point selection. The later payload-bearing event identifies the generated aligned comparison.

viewer.compare.align({
  backgroundUrl: "https://files.example.com/old-plan.pdf",
  overlayUrl: "https://files.example.com/new-plan.pdf",
  dpi: 200
});

Supported compare configuration payloads and shapes:

type CompareAlignPayload = {
  backgroundUrl?: string;
  overlayUrl?: string;
  backgroundFileName?: string;
  overlayFileName?: string;
  outputName?: string;
  dpi?: number;
  backgroundColor?: string;
  overlayColor?: string;
  equalColor?: string;
  alignArray?: Array<Record<string, unknown>>;
};

type ComparisonResult = {
  relativePath: string;
  outputFileUrl: string;
  activeFile: unknown;
  otherFile: unknown;
  activeFileUrl?: string;
  otherFileUrl?: string;
  dpi?: number;
  name?: string;
  index?: number;
  mode?: "compare" | "align";
  backgroundUrl?: string;
  overlayUrl?: string;
};

The SDK performs validation before triggering the Canvas comparing commands:

• Background source (backgroundUrl or backgroundFileName) is required.
• Overlay source (overlayUrl or overlayFileName) is required.
• Background and overlay values must be different.
• dpi must be a positive finite number if provided.
• backgroundColor, overlayColor, and equalColor must be valid hex or rgb(...) colors.
• outputName must be a non-empty string if provided.
• alignArray, when provided, must contain no more than two point objects.

Complete integration code setup for Vanilla HTML/JS environments:

<div id="viewer" style="height: 640px"></div>
<button type="button" id="compare">Compare</button>
<p id="status"></p>

Broker message mapping for compare workflows:

• viewer.compare.compare({ backgroundUrl, overlayUrl }) maps to compare.
• viewer.compare.on("comparisonComplete", handleComparisonComplete) listens to comparisonComplete.
• viewer.compare.on("comparisonError", handleComparisonError) listens to comparisonError.
• viewer.compare.on("progressStart", handleProgressStart) and viewer.compare.on("progressEnd", handleProgressEnd) report Canvas activity.