Eeshow ‐ Schematics renderer and viewer

Eeshow is a collection of programs that read schematics made by KiCad's Eeschema. Eeshow can be used as interactive viewer, or as a command-line tool to convert schematics to PNG, PDF, Postscript, EPS, or FIG.
Eeshow can show the differences between two versions of schematics sheets and it can retrieve files directly from a git repository.
Eeshow was developed as part of the Neo900 project.

Sections:

Building eeshow

Eeshow currently only works on Linux. To build, the development libraries for Gtk+ 3, Cairo, and libgit2 have to be installed. It also uses the command-line tools from transfig and ImageMagick.
On Ubuntu 16.04 and Debian 8.5, the names of the corresponding package would be libgtk-3-dev, libcairo2-dev, libgit2-dev, transfig, and imagemagick, e.g.,
sudo apt-get install libgtk-3-dev libcairo2-dev libgit2-dev transfig imagemagick

On Fedora 24: 

sudo dnf install gtk3-devel cairo-devel libgit2-devel transfig ImageMagick

Then download, compile, and install with 

git clone http://neo900.org/git/eeshow
cd eeshow
make
sudo make install

Motivation

The Neo900 project uses complex schematics that are edited by several people. We keep a revision history in git. For such a collaborative project, it is crucial to coordinate changes and to be able to see exactly what happened when conflicts occur.
Unfortunately, it is not always easy to tell from a textual difference what has changed between two versions of schematics. Worse, even small changes can sometimes result in Eeschema producing large numbers of differences.

Eeshow aims to provide a convenient means for visually comparing differences in schematics. Furthermore, by being able to work directly from a git repository and not requiring files to be changed on disk, it helps to streamline the workflow.

Eeshow has evolved from the much older schhist project at Qi-Hardware that provided a collection of scripts that used Eeschema (with the help of Wolfgang Spraul's command-line patches) to render schematics to bitmap images and then to compare these, producing a large HTML table.
However, this system was very slow and the approach of using a table would not have scaled to a project as large as Neo900.

Walk-through

Below is a quick tour of the key features of eeshow. We use the Neo900 schematics as an example. You can download them with: 
git clone http://neo900.org/git/ee
cd ee/hw
Start eeshow with: 
eeshow neo900.pro
Eshow displays a progress bar while loading. Since it retrieves files from the project's entire revision history, this can take a moment. If the wait gets unbearable, consider using the option -N depth to limit the number of revision eeshow uses.
Eeshow will typically complain about not finding files or components. Such small problems are common in many projects, and eeshow just omits parts it can't find, and skips revisions it cannot load.

Once done, eeshow displays the top-level page of the schematics. In our case, this page contains all the sub-sheets.

You can drag to pan, use the scroll wheel or the + or - keys to zoom, * to fit the sheet to the window, click a sub-sheet symbol to open the respective sheet, get help with H, or exit with Q.

Sheets are rendered almost like in Eeschema. The main difference is that eeshow uses system fonts for text, which can sometimes produce small size differences.

To return to the sheet next higher in the hierarchy, click on the box with the sheet name. To show eeshow's sheet index, click on the box with the name of the top sheet.

The index shows thumbnails for all the sheets. Clicking on a thumbnail selects the respective sheet. Clicking anywhere else (or pressing Escape) returns to the sheet.

While Eeschema largely avoids the use of settings that are invisible to the user, there is one major exception: pin types.
In eeshow, displaying symbols representing pin types can be toggled by pressing E.

Another extension of eeshow is that it can help navigate nets using global labels. When hovering over a global label, a pop-up showing the net name and the sheets on which it used appears. Clicking on a sheet goes there.
Furthermore, all occurreces of the global label on the sheet are highlighted. This highlighting remains effective also when changing sheets. It can be removed by pressing Escape.

We now come to eeshow's main feature. On the left-hand side of the screen, a box with the latest revision in the git history is shown. Clicking on it displays the revision history, with all branches.

Clicking on an entry shows the schematics as they were at that revision.

To compare two revisions, click on the double triangle symbol and select the revision to compare with. Eeshow then displays the difference beteen the two.

The difference is generated by rendering both versions, then comparing them pixel by pixel for differences. This means that only changes resulting in a visible difference will be shown.

The two versions being compared can be shown also without differences: O shows the old version, N the new version, D the differences. Tab toggles between old and new.

Versions can also be selected by clicking on the respective box in the upper left corner. Clicking on an already active version opens the history viewer for changing the version.

When showing differences, sub-sheets containing changes (or that have sub-sheets with changes) are highlighted. The same highlighting is also applied on the index page.

Note: eeshow bases this highlighting on comparing objects and their parameters ("delta mode"), not on rendering them and then comparing images ("diff mode").
This can sometimes produce diverging results, e.g., a sheet may be highlighted but have no visible changes.
Delta mode can also be selected for visualization, by pressing Shift-D.

Experimental features

The following features are experimental and may exhibit quirks.

Documentation

Eeshow can be given a list of documents to show for components (identified by their component reference).
When hovering over a component, a pop-up appears, showing the component reference and the documents associated with it.
When clicking on a document entry, eeshow launches an external viewer to display the document.

Further details can be found towards the end of README.

The Neo900 project makes use of this functionality, as explained in the section "Viewing documentation" in
https://neo900.org/git/ee/plain/README

Copy and paste

To copy text from schematics to the clipboard, move the mouse on the text in question, push and hold the mouse button, and swipe/drag it a little.
The text is then highlighted and copied to the clipboard.
This requires the xsel command-line utility to be installed.

Non-interactive use

Eeshow can also be used from the command line to render schematics. The most common use may be to render the schematics as PDF, with the command eeplot. Example: 

eeplot -o neo900.pdf neo900.pro

The command eediff makes a pixel-wised comparison of two schematics sheets, like "diff mode" in eeshow does: 

eediff -o diff.png -s 2 6a9f71:neo900.pro neo900_SS_5.sch \
  neo900.pro neo900_SS_5.sch

Additional functions are explained in the README.