Compare

Use viewer.compare.compare(...) to create a visual comparison from two file sources.

Compare commands are available after the viewer is mounted and Canvas is ready.

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:

• compare(...) starts the operation. Use local UI state for pending/loading, then clear it from comparisonComplete or comparisonError.

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.

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)"
});

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

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

Save the collaborative comparison markup or set output file naming properties:

// Save with options
viewer.compare.save({
  outputName: "old-vs-new.pdf"
});

// Save with name string
viewer.compare.save("old-vs-new.pdf");

// Save with default settings
viewer.compare.save();

// Listen for save completion
const offSave = viewer.compare.on("compareSaveComplete", (outputName) => {
  console.log("Comparison saved as:", outputName);
});

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;
  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.

Complete integration code setup for Vanilla HTML/JS environments:

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

Broker message mapping for compare workflows:

• viewer.compare.compare(...) maps to compare.
• viewer.compare.save(...) maps to compareSave.
• viewer.compare.on("comparisonComplete", ...) listens to comparisonComplete.
• viewer.compare.on("comparisonError", ...) listens to comparisonError.
• viewer.compare.on("compareSaveComplete", ...) listens to compareSaveComplete.