PCB visual diff with kicad-cli and lukaj

Issue

While working on the functional tests of kicad-kbplacer I found that automatic SVG file comparison is harder than it seems. That’s because different textual representations can produce same graphical result.

The current tests implementation, while not simple, works pretty well. The PCB output file is used to render multiple SVG files (one per layer) and these files are compared with references using xmldiff which does most of the heavy lifting. Some of differences found, such as moved nodes or changed textLength attributes, are ignored (KiCad does not keep the order of nodes), and the other are indication of failed test.¹

Unfortunately this approach does not always work. I’m still getting false positives from time to time - for example after KiCad version updates.² Another situation where this is not enough, is when I’m changing the behaviour of the plugin and need an easy way to check if produced PCB files are ok or if the references must be regenerated³ to match new implementation. This requires visual inspection.

Solution

To my surprise, I couldn’t find any a good standalone SVG visual comparison tool, so I started the lukaj project.

It is currently in the early stages, with some of rough edges, but already quite usable (if you don’t mind crashes when zooming too much).

I’m using lukaj with the kicad-cli and a simple wrapper shell script:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
#!/bin/sh

# ~/.local/bin/diff-kicad - wrapper for lukaj and kicad-cli

set -euo pipefail

TEMP1=$(mktemp)
TEMP2=$(mktemp)

generate_svg() {
  INPUT=$1
  OUTPUT=$2
  kicad-cli pcb export svg --exclude-drawing-sheet --page-size-mode 2 \
    -l "B.Cu,F.Cu,B.Silkscreen,F.Silkscreen,Edge.Cuts,B.Mask,F.Mask" \
    -o $OUTPUT $INPUT
}

generate_svg $1 $TEMP1
generate_svg $2 $TEMP2

~/.cargo/bin/lukaj $TEMP1 $TEMP2

rm $TEMP1 $TEMP2

The diff-kicad wrapper can be used directly or be configured as git difftool. To use it with git, add following sections to .gitconfig:

1
2
3
4
[difftool "diff-kicad"]
    cmd = ~/.local/bin/diff-kicad $LOCAL $REMOTE
[alias]
    diff-kicad = "difftool -t diff-kicad"

Now, it is available with git diff-kicad command:

demo

To learn more about lukaj, visit https://github.com/adamws/lukaj.

I also developed small convenience KiCad plugin which adds git GUI launcher to toolbar, see: https://github.com/adamws/kicad-git. This GUI has Tools menu entry which is user configurable. To add diff-kicad to it, append following settings to .gitconfig:

1
2
3
4
[guitool "diff-kicad"]
    cmd = git difftool -y -t diff-kicad $FILENAME
    noconsole = yes
    needsfile = yes