summaryrefslogtreecommitdiff
path: root/web/index.html
blob: 0769f9069e5b17a237b04076982831109523dd5a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
<HTML>
<TITLE>Eeshow</TITLE>
<BODY>

<STYLE type="text/css">
body {
	background-color:	#e0e0e0;
}

img {
	padding:	10px;
}
</STYLE>

<H1>Eeshow &dash; Schematics renderer and viewer</H1>

Eeshow is a collection of programs that read schematics made by
<A href="http://kicad-pcb.org/">KiCad</A>'s
<A href="http://kicad-pcb.org/discover/eeschema/">Eeschema</A>.
Eeshow can be used as
interactive viewer, or as a command-line tool to convert schematics
to PNG, PDF, Postscript, EPS, or FIG.
<BR>
Eeshow can show the differences between two versions of schematics sheets
and it can retrieve files directly from a
<A href="https://git-scm.com/">git</A> repository.
<BR>
Eeshow was developed as part of the
<A href="http://neo900.org/">Neo900</A> project.
<P>
Sections:
<UL>
  <LI><A href="#building">Building eeshow</A>
  <LI><A href="#motivation">Motivation</A>
  <LI><A href="#walk-through">Walk-through</A>
  <LI><A href="#experimental">Experimental features</A>
    <UL>
      <LI><A href="#documentation">Documentation</A>
      <LI><A href="#copy-paste">Copy and paste</A>
    </UL>
  <LI><A href="#non-interactive">Non-interactive use</A>
</UL>


<A name="building">
<H2>Building eeshow</H2>

Eeshow currently only works on Linux.

To build, the development libraries for
<A href="http://www.gtk.org/">Gtk+ 3</A>,
<A href="https://cairographics.org/">Cairo</A>, and
<A href="https://libgit2.github.com/">libgit2</A>
have to be installed. It also uses the command-line tools from
transfig and
<A href="http://www.imagemagick.org/">ImageMagick</A>.
<BR>
On Ubuntu 16.04 and Debian 8.5, the names of the corresponding package would be
<code>libgtk-3-dev</code>,
<code>libcairo2-dev</code>,
<code>libgit2-dev</code>,
<code>transfig</code>, and
<code>imagemagick</code>, e.g.,<BR>
<PRE>
sudo apt-get install libgtk-3-dev libcairo2-dev libgit2-dev transfig imagemagick
</PRE>
<P>
On Fedora 24:
<PRE>
sudo dnf install gtk3-devel cairo-devel libgit2-devel transfig ImageMagick
</PRE>
<P>
Then download, compile, and install with
<BR>
<PRE>
git clone http://neo900.org/git/eeshow
cd eeshow
make
sudo make install
</PRE>


<A name="motivation">
<H2>Motivation</H2>

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.
<BR>
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.
<P>
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.
<P>
Eeshow has evolved from the much older
<A href="http://projects.qi-hardware.com/index.php/p/eda-tools/source/tree/master/schhist">schhist</A>
project at
<A href="http://qi-hardware.com">Qi-Hardware</A>
that provided a collection of scripts that used Eeschema
(with the help of Wolfgang Spraul's
<A href="http://projects.qi-hardware.com/index.php/p/eda-tools/source/tree/master/kicad-patches">command-line patches</A>)
to render schematics to bitmap images and then to compare these,
producing a large HTML table.
<BR>
However, this system was very slow
and the approach of using a table would not have scaled to a project
as large as Neo900.


<A name="walk-through">
<H2>Walk-through</H2>

Below is a quick tour of the key features of eeshow. We use the Neo900
schematics as an example. You can download them with:
<pre>
git clone http://neo900.org/git/ee
cd ee/hw
</pre>

Start eeshow with:
<pre>
eeshow neo900.pro
</pre>

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
<CODE>-N <I>depth</I></CODE>
to limit the number of revision eeshow uses.
<BR>
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.
<P>
Once done, eeshow displays the top-level page of the schematics. In
our case, this page contains all the sub-sheets.
<P>
<IMG src="wt-start.png">
<P>
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.
<P>
<IMG src="wt-plain.png">
<P>
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.
<P>
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.
<P>
<IMG src="wt-index.png"><P>
<P>
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.
<P>
While Eeschema largely avoids the use of settings that are invisible
to the user, there is one major exception: pin types.
<BR>
In eeshow,
displaying symbols representing pin types can be toggled by pressing E.
<P>
<IMG src="wt-pin-type.png">
<P>
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.
<BR>
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.
<P>
<IMG src="wt-glabel.png">
<P>
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.
<P>
<IMG src="wt-history.png"><P>
<P>
Clicking on an entry shows the schematics as they were at that revision.
<P>
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.
<P>
<IMG src="wt-diff.png">
<P>
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.
<P>
<IMG src="wt-diff-old.png">
<P>
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.
<P>
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.
<P>
<IMG src="wt-diff-new.png"><P>
<P>
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.
<P>
<IMG src="wt-diff-index.png"><P>
<P>
Note: eeshow bases this highlighting on comparing objects and their
parameters ("delta mode"), not on rendering them and then comparing
images ("diff mode").
<BR>
This can sometimes produce diverging results,
e.g., a sheet may be highlighted but have no visible changes.
<BR>
Delta mode can also be selected for visualization, by pressing Shift-D.


<A name="experimental">
<H2>Experimental features</H2>

The following features are experimental and may exhibit quirks.


<A name="documentation">
<H3>Documentation</H3>

Eeshow can be given a list of documents to show for components (identified
by their component reference).
<BR>
When hovering over a component, a pop-up appears, showing the component
reference and the documents associated with it.
<BR>
When clicking on a document entry, eeshow launches an external viewer
to display the document.
<P>
<IMG src="wt-doc.png">
<P>
Further details can be found towards the end of
<A href="https://neo900.org/git/eeshow/plain/README">README</A>.
<P>
The Neo900 project makes use of this functionality, as explained in
the section "Viewing documentation" in
<BR>
<A href="https://neo900.org/git/ee/plain/README"><code>https://neo900.org/git/ee/plain/README</code></A>
<P>


<A name="copy-paste">
<H3>Copy and paste</H3>

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.
<BR>
The text is then highlighted and copied to the clipboard.
<BR>
This requires the <B>xsel</B> command-line utility to be installed.
<P>
<IMG src="wt-cp.png">
<P>


<A name="non-interactive">
<H2>Non-interactive use</H2>

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 <code>eeplot</code>. Example:
<P>
<PRE>
eeplot -o neo900.pdf neo900.pro
</PRE>
<P>
The command <code>eediff</code> makes a pixel-wised comparison of two
schematics sheets, like "diff mode" in eeshow does:
<P>
<PRE>
eediff -o diff.png -s 2 6a9f71:neo900.pro neo900_SS_5.sch \
  neo900.pro neo900_SS_5.sch
</PRE>
<P>
Additional functions are explained in the
<A href="https://neo900.org/git/eeshow/plain/README">README</A>.
</BODY>