summaryrefslogtreecommitdiff
path: root/README
blob: 4907b434a97550670cbcb8a88f085a334bc56090 (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
eeshow - Eeschema schematics renderer and viewer
================================================

Eeshow is a collection of programs to render schematics made by KiCad
Eeschema to FIG, PDF, Postscript, EPS, or PNG, and to generate graphical
differences between different versions of schematics sheets. It can
work in plain files but it can also retrieve design files directly
from a git repository. Furthermore, eeshow has an interactive mode for
viewing schematics and differences.

This work is distributed under the terms of the GNU GENERAL PUBLIC
LICENSE, Version 2:

  This program is free software; you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation; either version 2 of the License, or
  (at your option) any later version.

For your convenience, a copy of the complete license has been included
in the file COPYING.GPLv2.

The file page_layout_default_description.cpp is from KiCad and is covered
by the same license.


Prerequisites
-------------

libcairo2-dev
libgit2-dev
libgtk-3-dev
transfig
imagemagick

E.g., on Ubuntu and Debian:

sudo apt-get install libgtk-3-dev libcairo2-dev libgit2-dev transfig \
  imagemagick

On Fedora:

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


If building with USE_WEBKIT=y:

libwebkit2gtk-4.0-dev


Development status
------------------

Eeshow is still incomplete. It should generally be usable, but still has
many limitations, especially in the following areas:

- not all details are rendered, e.g., pin attributes such as "clock input"

- rendering isn't always exactly the same as in KiCad, e.g., text size may
  differ significantly

- interactive use is not streamlined yet, e.g., revision selection

- there may be unknown bugs

More details on pending items can be found in the file TODO.


Non-interactive rendering
=========================

Eeshow can be invoked from the command line to render KiCad schematics
to FIG, PDF, and PNG.


Invocation
----------

The general form of invocation for rendering is as follows:

eeplot -o output [options] file.pro [file.sch]

or

eeplot -o output [options] [-1] [-e] file.lib ... file.sch

The option -o is always required. The filename extension selects the
output driver, and can be overridden with the type: prefix. If selecting
standard output the type prefix is always required, e.g., png:-

If using PDF, the option -1 can be used (after "eeshow") to process only
one sheet, not recursing into sub-sheets. -e enables the rendering of
additional information, e.g., pin types.

For PDF and PNG, the option -s scale can be used to control the size of
the output.

Examples:

eeplot -s 2 -o test.png test.lib test.sch

eeplot -o neo900.pdf  neo900.lib kicad-libs/components/powered.lib neo900.sch

eeplot -o neo900-sheet04.pdf neo900.pro neo900_SS_4.sch

More details on the above example can be found in the file DEMO.


Revision access
---------------

If the files are stored in a git repository, a revisions can be selected
by prefixing file names with the commit ID, e.g.,

eeplot -o old.png -s neo900.lib kicad-libs/components/powered.lib \
  6a9f71:neo900_SS_5.sch \

Revision selection propagates to dependent files, unless explicitly
overridden. E.g., the above example selects also revision 6a9f71 of
neo900.lib.


Using the component library cache
---------------------------------

Eeschema copies all components it uses to a file named <project>-cache.lib
When operating on files, this library can be used as a convenient
alternative to listing all the libraries that contributed content.

However, when using eeshow with a revision history, the library cache
should only be used if it is also kept in the repository. Otherwise,
library changes in older revisions may get unnoticed.


Non-interactive differences
===========================

Eeshow can render two versions of a sheet to a bitmap and then compare them
pixel by pixel, highlighting areas where differences are found. The output
is written to a PNG file.


Invocation
----------

The general form of invocation for rendering is as follows:

eediff [options] file.pro file.pro

or

eediff [options] file.lib ... file.sch file.lib ... file.sch

The usual options and revision selection can be used here as well.

Example:

LIBS="neo900.lib kicad-libs/components/powered.lib"
eediff -o diff.png -s 2 $LIBS  6a9f71:neo900_SS_5.sch \
  $LIBS neo900_SS_5.sch


GUI mode
========

GUI mode allows exploration of schematics and the comparison of different
git revisions. Compared to eeschema, eeshow currently offers the following
additional features:

- access to the git revision history with visual differences between
  versions.

- on hover, global labels show on which other sheets the label is used.
  Clicking on a name jumps to that sheet.

- fast sheet change with PgUp/PgDn


Invocation
----------

The basic invocation of GUI mode is as follows:

eeshow file.pro

or

eeshow file.lib ... file.sch

If file.sch is in a git repository, eeshow automatically loads the
revision history. The depth of the history can be limited with the
option -N number-of-commits

Examples:

eeshow -N 30 neo900.lib kicad-libs/components/powered.lib neo900.sch

eeshow `sed -n '/pcbnew/q;/^LibName[0-9]*=/{s///;s/$/.lib/p;};d' anelok.pro` \
  anelok.sch


Mouse function in GUI mode
--------------------------

Eeshow uses only the left and middle mouse button (both are equivalent)
and the scroll wheel.

Hover			show additional details on revisions, sheets, global
			labels, index
Click			jump to sheet (on sub-sheet, sheet stack, global
			label hover box, index), open index page, open history,
			select revision
Click and drag		pan sheet, scroll history
Scroll wheel		zoom in or out; scroll through history


Key functions in GUI mode
-------------------------

+ or =			zoom in
-			zoom out
*			fit to window
Home			go to the top sheet
Delete or Backspace	go to the next higher sheet in hierarchy
PgUp			go to the previous sheet in sequence
PgDn			go to the next sheet in sequence
Up or Down		invoke the revision history (WIP)
Tab			toggle between old and new revision
Esc			cancel current action (exit history, close pop-up,
			de-highlight glabel, close help)
E			show/hide extra information (pin types)
F			toggle showing footprints, even if invisible
Shift+D			toggle between "diff" and experimental "delta" mode
H			show/hide help window
T			toggle performance timer
D			when comparing revisions, show difference (default)
N			show newer sheet
O			show older sheet
Q			quit the viewer