Document Version v2026.08.31.0

Compare two board revisions (Board Diff)¶

Page goal¶

Start Board Diff from managed revisions, understand the Before / After direction, inspect object-level changes, and export reviewable JSON or PNG output.

Supported platforms¶

macOS 14 or later: the primary wide-screen Board Diff experience and first-round acceptance platform.
iOS / iPadOS 17.0 or later: the entry is included in the app; landscape or a wide window is recommended while dedicated narrow-screen refinement continues.

Intended audience¶

PCB design, manufacturing, and review users comparing two revisions of the same board
Testers validating directional changes, layer pairs, objects, and risk hints

Prerequisites¶

Choose two boards with different content that resolve to the same actual format:

Input	Current status
DSN	Supported
Standalone KiCad `.kicad_pcb`	Supported
Gerber + Excellon folder or archive	Supported
SES	Supported only when both sides identify the same verified base design
ODB++, IPC-2581, complete KiCad Project	Explicitly unsupported for Board Diff

Before and After are directional:

Added: present only in After.
Removed: present only in Before.
Modified: a paired object whose properties or geometry differ.
Unchanged: identical on both sides and shown only as context.

Matching extensions do not prove matching formats. PCBAtlas resolves both sides independently before allowing a comparison.

Steps¶

Compare two managed revisions¶

Find a library document containing at least two revisions.
Open the document card's more-actions menu.
Select Compare Revisions….
Choose two different same-format revisions in Before and After.
Select Compare.

When the current revision has a parent, the page prefers the parent for Before and the current revision for After. You can replace either selection.

A completed managed comparison stores a verified artifact. Return to the same document's comparison page and use Reopen Saved Comparison to open it again.

Confirm ambiguous layer pairing¶

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

Review the name, role, order, and object count of each Before layer.
Choose the correct After layer.
Make a selection for every ambiguous item.
Select Confirm and Compare.

PCBAtlas does not guess when pairing is ambiguous and does not force the boards together with automatic translation or rotation. A whole-board translation or rotation remains a real visible change.

Wait for or cancel a comparison¶

Progress covers validation, Before / After import, layer pairing, snapshots, geometry matching, risk analysis, the exact Diff scene, and persistence.

After selecting Cancel, wait for Cancelling comparison… to finish. A safe retry is available only after both native sessions and temporary staging data have been released.

Read the comparison workspace¶

Display modes¶

Overlay: combines exact changes in one scene; Context controls unchanged context intensity.
Split: shows Before on the left and After on the right; Sync Camera is enabled by default and can be turned off for independent inspection.
Blink: alternates Before and After with the same camera to reveal small movement.
Fit: fits the current scene back into the visible area.

Layers and changes¶

Layer Pairs lists paired layers and the change count for each pair.
Select All layers for the whole board or one pair to narrow the view.
In Changes, toggle Added / Removed / Modified and filter by object type or Net.
Selecting a change row locates and highlights it; selecting an object in the Viewer also looks up its change.
Previous / Next walk the current filtered results. The macOS shortcuts are ⌘[ and ⌘].
Risks filters directional hints by severity. Risk hints help review and do not replace DRC or manufacturing approval.

Swap, export, and reopen¶

Swap creates and recomputes a reverse request. Added / Removed, statistics, risks, and details change direction.
JSON exports the stable, versioned semantic result; iOS hands the file to other apps.
PNG exports the current Diff view; iOS saves it directly to Photos, while macOS continues through the system file-delivery interface.
A managed revision comparison can be reopened through Reopen Saved Comparison.
If revision content, format, policy, or layer pairing changes, the old artifact becomes invalid instead of being displayed silently.

Acceptance checklist¶

Current boundaries¶

Inputs must have the same format; cross-format comparison is not supported.
ODB++, IPC-2581, complete KiCad Project, schematic Diff, and 3D Diff are not supported.
Board Diff does not merge, accept, or write changes back to source files.
There is no automatic alignment; whole-board translation and rotation remain visible differences.
Image pixels, bounding boxes, and file text are not used as a fallback for exact geometry Diff.

FAQ¶

Why is `Compare` disabled?¶

Check that both sides are selected, contain different content, and resolve to the same supported format. For Gerber / Excellon, provide the complete package folder or archive on each side rather than two arbitrary individual layer files.

Why do matching filename extensions still produce a format mismatch?¶

The format comes from actual resolution, not just the filename. Directories, archives, SES base designs, and the resolved board entry are part of validation.

Why can I not retry immediately after cancelling?¶

The page waits for PcbCore to release both Before / After sessions and temporary data so a new task cannot overlap the old one. Retry after Cancelling comparison… disappears.

Why did the change count or risks change after Swap?¶

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

Result¶

You can locate exact bilateral changes, review directional risks, and export JSON / PNG in one workspace. Managed revision comparisons can also be stored, verified, and reopened.

Last verified¶

2026-07-30