Package: kidiff
KiDiff (kicad-diff or kicad_pcb-diff)This program generates a PDF file showing the changes between two KiCad PCB or
SCH files.PCBs are plotted into PDF files, one for each layer. Then ImageMagick is used
to compare the layers and PNG files are generated. The PNGs are finally
assembled into one PDF file and the default PDF reader is invoked.All the intermediate files are generated in the system temporal directory and
removed as soon as the job is finished. You can cache the layers PDFs
specifying a cache directory and keep the resulting diff images specifying an
output directory.For SCHs the process is similar, but using KiAuto. Note that one schematic is
compared at a time. The--all_pagesoption allows comparing multiple pages.
In this case adding or removing pages is only supported when thersvg-converttool is available. Also note that this can't be done by the git
plug-in because git extracts only the file you want to compare. Consult the
advanced use explanation.The default resolution for the images is 150 DPI. It can be increased for
better images, at the cost of (exponentially) longer execution times. You can
provide a smaller resolution for faster processing. For high resolution you
could need to configure the ImageMagick limits. Consult the 'identify -list
resource' command.InstallationDependenciesIn order to run the scripts you need:Python 3.5 or newerKiCad 5.1 or newerPython3 wxWidgets (i.e. python3-wxgtk4.0). This is usually installed with
KiCad.ImageMagick tools (i.e. imagemagick Debian package). Used to manipulate
images and create PDF files.pdftoppm tool (i.e. poppler-utils Debian package). Used to decode PDF files.Alternative: Ghostscript (slower and worst results)rsvg-convert tool (i.e. librsvg2-bin Debian package). Needed to compare
schematics with multiple pages. Converts SVG files to PNGs.xdg-open tool (i.e. xdg-utils Debian package). Used to open the PDF viewer.KiAuto. Used to print the schematic
in PDF format.In a Debian/Ubuntu system you'll first need to add thisrepoand then use:$sudoapt-getinstallkidiff`Arch Linux can installkicad-pcb-diffusing the AUR
repository:$yay-SkidiffNote: if you are using Debian, or some derived distro like Ubuntu, you can
find a Debian package in the releases section. But using the repo is simpler.Standalone useAs root run:# make installThe scripts will be copied to/usr/local/bin. If you want to install the
scripts in/usr/binrun# make prefix=/usr installNote: if you are using Debian, or some derived distro like Ubuntu, you can
find a Debian package in the releases section.Git plug-inInstall the scriptsTo initialize a repo just run thekicad_pcb-diff-init.pyscript from the
root of the repo.This will configure the repo to read extra configuration
from the.gitconfigfile.It will also associate thekicad_pcbfile
extension with thekicad-git-diff.pyscript.The initialization script will create a list of layers to be excluded in
the.kicad-git-difffile.Review this file and adjust it to your needs.
Lines starting with#will be ignored.Once configured the tool will be used every time you do a diff usinggit.Temporarily disabling the git plug-inSometimes the graphics diff is not what you want. To disable it just invokegit diffusing the--no-ext-diffoption. It will force the text mode
original diff behavior.Disabling the pagerGit will use a pager to allow scrolling back and forth. This could be annoying
because you must exit it, the git option--no-pagerdisables it. Example:$git--no-pagerdiffXXXXXX.kicad_pcbPDF conversion policyOn some systems (i.e. Debian) ImageMagick disables PDF manipulation in itspolicy.xmlconfiguration file. Comment or remove lines like this:<policy domain="coder" rights="none" pattern="PDF" />On Debian 11/12 this applies to the/etc/ImageMagick-6/policy.xmland/or/etc/ImageMagick-7/policy.xmlfile.UsageThekicad-git-diff.pyis a plug-in forgitso you just need to configuregitand then it becomes transparent. If you need to create a diff between
two files outsidegityou can use thekicad-diff.pyscript.You have to provide the name of the two PCB/SCHs to be compared. The first is
the old one, the reference, and the second is the new, the one you want to
compare. The additional command line options are:--helpShows a detailed list of the available options.--all_pagesCompare all pages for a schematic. Note that the tool doesn't currently
support adding or removing sheets, both documents must have the same amount of
pages.--cache_dirThe PCB/SCH files are plotted to PDF files. One PDF file for layer. To avoid
plotting them over and over you can specify a cache directory to store the
PDFs.--diff_modeSelects the mechanism used to represent the differences:red_greenthis is the default mode. Here we try to mimic the colored
text mode diff tools. Things added to theoldfile are represented in
green and things removed in red.statsin this mode all difference are represented in red. We compute the
amount of pixels that are different, you can use this value to determine if
the changes are significant. See the--fuzzand--thresholdoptions.--excludeSpecifies the name of a file containing a list of layers to be excluded. Each
line of the file is interpreted as a layer name. An example for this file
could be:B.Adhes
F.Adhes
Cmts.User
Eco1.User
Eco2.User
Edge.Cuts
MarginYou can also use the KiCad internal layer ID number. This will avoid warnings
about undefined layer names.Note that when using thegitplug-in the script looks for a file named.kicad-git-diffat the root of the repo.Using this you can reduce the time wasted computing diffs for empty or useless
layers.Note that lines starting with # are skipped.See also--layers--force_gsKiDiff uses poppler utils if they are available. When they aren't KiDiff can
use Ghostscript. The results using poppler are better and the process is
faster, but you can choose to use Ghostscript using this option.--fuzzWhen comparing using thestatsmode (see--diff_mode) this option controls
how strict is the color comparison. The default is to tolerate 5 % of error in
the colors. Enlarge it if you want to ignore bigger differences in the colors.--keep_pngsDon't remove the individual PNGs. Complements--output_dir. They are usually
removed as soon as we get the output PDF.--layersSpecifies the name of a file containing a list of layers to be included. This
option works similar to--excludebut we process only the layers indicated
here.Important: when this list is only composed by layer numbers KiDiff skips any
check and uses this list of layers, even if they aren't defined in any of the
specified PCBs. Otherwise you can get warnings about names not defined.--layersand--excludeare mutually exclusive.--new_file_hashThis is the equivalent of the--old_file_hashoption used for the new
PCB/SCH file.--no_readerUse it to avoid invoking the default PDF viewer. Note that you should also
provide an output directory using--output_dir.The default PDF reader is invoked usingxdg-open--old_file_hashThe plotted PDF files for each layer are stored in the cache directory using a
SHA1 of the PCB/SCH file as name for the directory. You can specify another
hash here to identify the old PCB/SCH file.Thegitplug-in uses the hash provided bygitinstead of the SHA1 for the
file.--output_dirFive seconds after invoking the PDF viewer the output files are removed. If
you want to keep them for later review, or five seconds isn't enough for your
system, you can specify a directory to store the generated files.Note: individual PNGs are always removed, consult--keep_pngs--output_nameUsed to complement--output_dir. The default name isdiff.pdf--resolutionThe PDF files are converted to bitmaps to be compared. The default resolution
for these bitmaps is 150 DPIs. This is a compromise between speed and
legibility. For faster compares you can use a smaller resolution. For detailed
comparison you can use a higher resolution. Be careful because the time is
increased exponentially. You can also run out of resources. In particular
ImageMagick defines some limits to the disk used for operations. These limits
can be very low for default installations. You can consult the limits using
the following command:identify -list resourceConsult ImageMagick documentation in order to increase them.--thresholdIn thestatsmode this option can make KiDiff to return an error value if
the difference is bigger than the specified threshold. Indicating 0 means that
we don't look for errors, KiDiff always returns 0.-v/--verboseIncreases the level of verbosity. The default is a quite mode, specifying one
level (-v) you'll get information messages about what's going on. If you
increase the level to two (-vv) you'll get very detailed information, most
probably useful only to debug problems.--versionPrint the script version, copyright and license.Advanced usekicad-diff.pycan be run using the--only_cacheoption. In this mode thenew_fileargument can be the same as theold_fileargument. This operation
is used to store the images, but skip the comparison. In order to work you
must specify a validcache_dir. You should also take note of the hash used
bykicad-diff.py, or just provide one using the--old_file_hash.You can then compare two files using the cached images, you just need to
provide the hashes you want to compare. Theold_fileandnew_filewon't be
used.Similar toolsKiCad-DiffKiCad-Diffis a diff tool for
PCBs, is more oriented to GUI use. It has support not only forgitbut also
forfossilandsvn. You can navigate the diffs and get information about
added or removed items, all using a browser. And is fast (all is handled using
SVGs).It doesn't support schematics, can't be directly used as a git plug-in
(perhaps using some wrapper), can't measure the ammout of difference and
doesn't generate a file to see the differences (only browsable).Credits and notesThis script is strongly based on Jesse Vincentwork.I borrowed the command to compare two images from Brecht Machiels. In
particular from hisdiffpdf.shtool.I'm not a Python programmer, stackoverflow helps me ...