Document Version v2026.10.17.0

Compare two board revisions (Board Diff)¶

This pass only verified the library Compare Revisions… entry. The comparison flow below was not re-operated on 2026-09-11. Do not treat this page as a complete Diff acceptance record for the current build.

Page goal¶

Help you start Board Diff from library revisions, understand the Before / After direction, inspect object-by-object changes, and export reviewable JSON or PNG.

Supported platforms¶

macOS 14 or later: the primary wide-screen experience and first acceptance platform for Board Diff today.
iOS / iPadOS 17.0 or later: the entry is provided with the app. Prefer landscape or a wider window; dedicated narrow-screen optimization is still follow-up work.

Intended audience¶

Design, manufacturing, or review staff who need to compare two revisions of the same PCB
Testers who need to accept Diff by direction, layer, object, and risk hints

Prerequisites¶

Choose a pair of boards whose contents differ but whose actually parsed formats are the same:

Input	Current status
DSN	Supported
Single-board KiCad `.kicad_pcb`	Supported
Gerber + Excellon folder or archive	Supported
SES	Supported only when both sides can be verified and point at the same base design
ODB++, IPC-2581, Altium PCB / library, complete KiCad Project	Explicitly not supported for Board Diff today

Before and After are directional:

Added: exists only in After.
Removed: exists only in Before.
Modified: objects on both sides can be paired, but attributes or geometry differ.
Unchanged: the same on both sides, shown only as context.

The same file extension does not guarantee the same format. PCBAtlas parses each side separately, then decides whether comparison is possible.

Steps¶

Compare two revisions in the library¶

In the library, find a document with at least two revisions.
Open the more-actions menu on the document card.
Click Compare Revisions….
In Before and After, choose two different revisions of the same format.
Click Compare.

If the current revision has a parent, the page prefers parent as Before and current as After. You can still change either side manually.

A completed hosted comparison saves a validated artifact. The next time you enter the comparison page for the same document, you can use Reopen Saved Comparison.

Confirm ambiguous layer pairing¶

If PcbCore finds multiple compatible candidates, comparison pauses at Layer pairing needs confirmation:

For each Before layer, check name, role, order, and object count.
On the right, choose the correct After layer.
Confirm that every item has a selection.
Click Confirm and Compare to run again.

PCBAtlas does not guess a layer when the pairing is ambiguous, and it does not force two boards into alignment with automatic translate / rotate. Whole-board translation or rotation is kept as a real change.

Wait for or cancel comparison¶

Comparison shows progress through input validation, importing Before / After, layer pairing, snapshot, geometric matching, risk analysis, Diff scene, and persistence.

After you click Cancel, wait until Cancelling comparison… finishes. The page allows a safe retry only after both native sessions and temporary staging data are released.

Read the comparison workspace¶

Display modes¶

Overlay: superimpose changes in one exact composite scene; Context controls the strength of unchanged context.
Split: Before on the left, After on the right; Sync Camera is on by default, and turning it off lets you inspect each side separately.
Blink: automatically switch Before / After with the same camera, useful for small displacements.
Fit: refit the current scene to the visible area.

Layers and changes¶

Left Layer Pairs shows pairing results and the change count for each pair.
Choose All layers for the whole board, or one layer pair to narrow the scope.
Right Changes can toggle Added / Removed / Modified and filter by object type and Net.
Clicking a change row locates and highlights the object; picking in Viewer also looks up the matching change.
Previous / Next walk the current filtered results; macOS shortcuts are ⌘[ and ⌘].
The Risks panel filters directional hints by risk level. Risk hints are for review location, not a substitute for DRC or manufacturing sign-off.

Swap direction, export, and reopen¶

Swap creates a reversed request and recalculates; original Added / Removed, statistics, risks, and details reverse with the direction.
JSON exports a stable, versioned semantic result; iOS hands the file to other apps.
PNG exports a screenshot of the current Diff view; iOS saves it directly to Photos, while macOS continues to use the system file-delivery UI.
After a hosted revision comparison completes, reopen the validated result from Reopen Saved Comparison.
If revision content, format, policy, or layer pairing has changed, the old artifact is treated as invalid instead of silently showing a stale result.

Wide shell and narrow shell¶

Both layouts enter comparison from the document action menu in the library. Do not use ordinary Viewer Split as a substitute for Board Diff. Ordinary project Split is a PCB and schematic dual canvas; Diff Split is Before and After. If comparison settings or result panels are crowded in a narrow window, enlarge the window to read them. This pass did not verify the narrow-shell Diff layout.

Acceptance checklist¶

Current explicit boundaries¶

Only same-format inputs are compared; cross-format comparison is not supported.
ODB++, IPC-2581, Altium PCB / library, complete KiCad Project, schematic Diff, and 3D Diff are not supported.
There is no automatic merge, accept-change, or reverse modification of source files.
There is no automatic alignment; whole-board translation and rotation remain visible differences.
Image pixels, bbox, or file text are not used as a fallback for exact geometric Diff.

FAQ¶

Why is the `Compare` button unavailable?¶

Check that both sides are selected, that the contents differ, and that they parse as the same supported format. For Gerber / Excellon, give each side the complete package folder or archive; two arbitrary single-layer files cannot stand in for a complete board.

Why does the same extension still report a format mismatch?¶

Format is decided by actual parse results, not the filename alone. Directories, archives, SES base designs, and the actual board entry all take part in validation.

Why can I not compare again immediately after cancelling?¶

The page waits for PcbCore to release both Before / After sessions and temporary data, so a new task does not occupy resources at the same time as an old one. Retry after Cancelling comparison… disappears.

Why did change counts or risks also change after Swap?¶

Added / Removed and risk hints are directional. Swap does not just exchange display labels; it recalculates with reversed Before / After.

Result¶

After comparison, you can locate exact changes on both sides in the same workspace, check directional risks, and export JSON / PNG. Library revision comparisons can also be saved and reopened after validation.

Last verified¶

2026-07-30 (original flow record); 2026-09-11 verified the library entry and did not rerun comparison.