Align

Use viewer.compare.align(...) to align two files before generating a visual comparison.

Align 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();

Subscribe to compare event channels before executing an alignment task:

• align(...) returns void. Progress, success, interactive-ready state, and failure details arrive through these events.

const cleanups = [
  viewer.compare.on("progressStart", (event) => {
    console.log(event.message);
  }),
  viewer.compare.on("progressEnd", () => {
    console.log("Align finished");
  }),
  viewer.compare.on("comparisonComplete", (result) => {
    if (!result) {
      console.log("Interactive align is ready");
      return;
    }
    console.log("Aligned comparison created:", result.relativePath);
  }),
  viewer.compare.on("comparisonError", (error) => {
    console.error(error.message);
  })
];

Omit alignArray when the user needs to select matching points interactively in the viewer window:

• Interactive alignment fires two comparisonComplete events: first with no payload (Canvas ready for points selection), and a second with payload (generation complete).

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

Provide custom coordinate offsets if your application already has defined point mappings:

• The SDK validates that alignArray contains no more than two point coordinate mapping structures.

viewer.compare.align({
  backgroundUrl: "https://files.example.com/old-plan.pdf",
  overlayUrl: "https://files.example.com/new-plan.pdf",
  outputName: "aligned-comparison.pdf",
  dpi: 200,
  alignArray: [
    { x: 145.5, y: 210.25, page: 1 },
    { x: 151.75, y: 214.5, page: 1 }
  ]
});

Compare & align model definitions:

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;
  alignarray?: Array<Record<string, unknown>>;
  dpi?: number;
  name?: string;
  index?: number;
  mode?: "compare" | "align";
  backgroundUrl?: string;
  overlayUrl?: string;
};

The SDK rejects invalid align inputs before communicating with Canvas:

• Payload must be a valid object configuration.
• Background source (backgroundUrl or backgroundFileName) is required.
• Overlay source (overlayUrl or overlayFileName) is required.
• Background and overlay values must not be identical.
• dpi must be a positive finite number if provided.
• backgroundColor, overlayColor, and equalColor must be valid color strings.
• alignArray must contain no more than two point mappings if provided.

Complete integration code setup for Vanilla HTML/JS environments:

<div id="viewer" style="height: 640px"></div>
<button type="button" id="align">Interactive Align</button>
<p id="status"></p>

Broker message mapping for alignment workflows:

• viewer.compare.align(...) maps to align.
• viewer.compare.on("progressStart", ...) listens to progressStart.
• viewer.compare.on("progressEnd", ...) listens to progressEnd.
• viewer.compare.on("comparisonComplete", ...) listens to comparisonComplete.
• viewer.compare.on("comparisonError", ...) listens to comparisonError.