Debian Codegraph @

texmf-dist/doc/generic/pgf/pgfmanual-en-library-spy.tex

raw
1 % Copyright 2019 by Till Tantau
2 %
3 % This file may be distributed and/or modified
4 %
5 % 1. under the LaTeX Project Public License and/or
6 % 2. under the GNU Free Documentation License.
7 %
8 % See the file doc/generic/pgf/licenses/LICENSE for more details.
9
10
11 \section{Spy Library: Magnifying Parts of Pictures}
12 \label{section-library-spy}
13
14 \begin{tikzlibrary}{spy}
15 The package defines options for creating pictures in which some part of the
16 picture is repeated in another area in a magnified way (as if you were
17 looking through a spyglass, hence the name).
18 \end{tikzlibrary}
19
20
21 \subsection{Magnifying a Part of a Picture}
22
23 The idea behind the |spy| library is to make it easy to create high-density
24 pictures in which some important parts are repeated somewhere, but magnified as
25 if you were looking through a spyglass:
26 %
27 \begin{codeexample}[preamble={\usetikzlibrary{decorations.fractals,spy}}]
28 \begin{tikzpicture}
29 [spy using outlines={circle, magnification=4, size=2cm, connect spies}]
30
31 \draw [help lines] (0,0) grid (3,2);
32
33 \draw [decoration=Koch curve type 1]
34 decorate { decorate{ decorate{ decorate{ (0,0) -- (2,0) }}}};
35
36 \spy [red] on (1.6,0.3)
37 in node [left] at (3.5,-1.25);
38
39 \spy [blue, size=1cm] on (1,1)
40 in node [right] at (0,-1.25);
41 \end{tikzpicture}
42 \end{codeexample}
43
44 \begin{codeexample}[preamble={\usetikzlibrary{decorations.fractals,spy}}]
45 \begin{tikzpicture}[spy using overlays={size=12mm}]
46 \draw [decoration=Koch snowflake]
47 decorate { decorate{ decorate{ decorate{ (0,0) -- (2,0) }}}};
48
49 \spy [green,magnification=3] on (0.6,0.1) in node at (-0.3,-1);
50 \spy [blue,magnification=5] on (1,0.5) in node at (1,-1);
51 \spy [red,magnification=10] on (1.6,0.1) in node at (2.3,-1);
52 \end{tikzpicture}
53 \end{codeexample}
54
55 Note that this magnification uses what is called a \emph{canvas transformation}
56 in this manual: Everything is magnified, including line width and text.
57
58 In order for ``spying'' to work, the picture obviously has to be drawn several
59 times: Once at its normal size and then again for each ``magnifying glass''.
60 Several keys and commands work in concert to make this possible:
61 %
62 \begin{itemize}
63 \item You need to make \tikzname\ aware of the fact that a picture (or just
64 a scope) is to be magnified. This is done by adding the special key
65 |spy scope| to a |{scope}| or |{tikzpicture}| (which is also just a
66 scope). Some special keys like |spy using outlines| implicitly set the
67 |spy scope|.
68 \item Inside this scope you may then use the command |\spy|, which is only
69 available inside such scopes (so there is no danger of you
70 inadvertently using this command outside such a scope). This command
71 has a special syntax and will (at some point) create two nodes: One
72 node that shows the magnified picture (called the \emph{spy-in node})
73 and another node showing which part of the original picture is
74 magnified (called the \emph{spy-on} node). The spy-in node is, indeed,
75 a normal node, so it can have any shape or border that you like and you
76 can apply all of \tikzname's advanced features to it. The only
77 difference compared to a normal node is that instead of some ``text''
78 it contains a magnified version of the picture, clipped to the size of
79 the node.
80
81 The |\spy| command does not create the nodes immediately. Rather, the
82 creation of these nodes is postponed till the end of the |spy scope| in
83 which the |\spy| command is used. This is necessary since in order to
84 repeat the whole scope inside the node containing the magnified
85 version, the whole picture needs to be available when this node is
86 created.
87 \end{itemize}
88
89 A basic question any library for ``magnifying things'' has to address is how
90 you specify which part of the picture is to be magnified (the spy-on node) and
91 where this magnified part is to be shown (the spy-in node). There are two
92 possible ways:
93 %
94 \begin{enumerate}
95 \item You specify the size and position of the spy-on node. Then the size
96 of the spy-in node is determined by the size of the spy-on node and the
97 magnification factor -- you can still decide where the spy-in node
98 should be placed, but not its size.
99 \item Alternatively, you specify the size and position of the spy-in node.
100 Then, similarly to the first case, the size of the spy-on node is
101 determined implicitly and you can only decide where the spy-on node
102 should be placed, but not its size.
103 \end{enumerate}
104
105 The |spy| library uses the second method: You specify the size and position of
106 the spy-in nodes, the sizes of the spy-on nodes are then computed
107 automatically.
108
109
110 \subsection{Spy Scopes}
111
112 \begin{key}{/tikz/spy scope=\meta{options} (default \normalfont empty)}
113 This option may be used with a |{scope}| or any environment that creates
114 such a scope internally (like |{tikzpicture}|). It has the following
115 effects:
116 %
117 \begin{itemize}
118 \item It resets a number of graphic state parameters, including the
119 color, line style, and others. This is necessary for technical
120 reasons.
121 \item It tells \tikzname\ that the content of the scope should be saved
122 internally in a special box.
123 \item It defines the command |\spy| so that it can be used inside the
124 scope.
125 \item At the end of the scope, the nodes belonging to the |\spy|
126 commands used inside the scope are created.
127 \item The \meta{options} are saved in an internal style. Each time
128 |\spy| is used, these \meta{options} will be used.
129 \item Three keys are defined that provide useful shortcuts:
130 %
131 \begin{key}{/tikz/size=\meta{dimension}}
132 Inside a |spy scope|, this is a shortcut for |minimum size|.
133 \end{key}
134 %
135 \begin{key}{/tikz/height=\meta{dimension}}
136 Inside a |spy scope|, this is a shortcut for |minimum height|.
137 \end{key}
138 %
139 \begin{key}{/tikz/width=\meta{dimension}}
140 Inside a |spy scope|, this is a shortcut for |minimum width|.
141 \end{key}
142 \end{itemize}
143 %
144 It is permissible to nest |spy scopes|. In this case, all |\spy| commands
145 inside the inner |spy scope| only have an effect on material inside the
146 scope, whereas |\spy| commands outside the inner |spy scope| but inside the
147 outer |spy scope| allow you to ``spy on the spy''.
148 %
149 \begin{codeexample}[preamble={\usetikzlibrary{decorations.fractals,spy}}]
150 \begin{tikzpicture}
151 [spy using outlines={rectangle, red, magnification=5,
152 size=1.5cm, connect spies}]
153
154 \begin{scope}
155 [spy using outlines={circle, blue,
156 magnification=3, size=1.5cm, connect spies}]
157 \draw [help lines] (0,0) grid (3,2);
158
159 \draw [decoration=Koch curve type 1]
160 decorate{ decorate{ decorate{ (0,0) -- (2,0) }}};
161
162 \spy on (1.6,0.3) in node (zoom) [left] at (3.5,-1.25);
163 \end{scope}
164
165 \spy on (zoom.north west) in node [right] at (0,-1.25);
166 \end{tikzpicture}
167 \end{codeexample}
168 %
169 \end{key}
170
171
172 \subsection{The Spy Command}
173
174 \begin{command}{\spy \opt{\oarg{options}} |on| \meta{coordinate} \texttt{in node} \meta{node options}|;|}
175 This command can only be used inside a |spy scope|. Let us start with the
176 syntax:
177 %
178 \begin{itemize}
179 \item The |\spy| command is not a special case of |\path|. Rather, it
180 has a small parser of its own.
181 \item Following the optional \meta{options}, you must write |on|,
182 followed by a coordinate. This coordinate will be the center of the
183 area that is to be magnified.
184 \item Following the \meta{coordinate}, you must write |in node|
185 followed by some \meta{node options}. The syntax for these options
186 is the same as for a normal |node| path command, such as |[left]|
187 or |(foo) [red] at (bar)|. \emph{However}, \meta{node options} are
188 \emph{not} followed by a curly brace. Rather, the \meta{node
189 options} must directly be followed by a semicolon.
190 \end{itemize}
191 %
192 The effect of this command is the following: The \meta{options},
193 \meta{coordinate}, and \meta{node options} are stored internally till the
194 end of the current |spy scope|. This means that, in particular, you can
195 reference any node inside the |spy scope|, even if it is not yet defined
196 when the |\spy| command is given. At the end of the current |spy scope|,
197 two nodes are created, called the \emph{spy-in node} and the \emph{spy-on
198 node}.
199 %
200 \begin{itemize}
201 \item The \emph{spy-in node} is the node that contains a magnified part
202 of the picture (the node \emph{in} which we see on what we spy).
203 This node is, indeed, a normal \tikzname\ node, so you can use all
204 standard options to style this node. In particular, you can specify
205 a shape or a border color or a drop shadow or whatever. The only
206 thing that is special about this node is that instead of containing
207 some normal text, its ``text'' is the magnified picture.
208
209 To be precise, the picture of the |spy scope| is scaled by a
210 certain factor, specified by the |lens| or |magnification| options
211 discussed below, and is shifted in such a way that the
212 \meta{coordinate} lies at the center of the spy-on node.
213 \item The \emph{spy-on node} is a node that is centered on the
214 \meta{coordinate} and whose size reflects exactly the area shown
215 inside the spy-in node (the node containing \emph{on} what we spy).
216 \end{itemize}
217
218 Let us now go over what happens in detail when the two nodes are
219 created:
220 %
221 \begin{enumerate}
222 \item A scope is started. Two sets of options are used with this scope:
223 First, the options passed to the enclosing |spy scope| and then the
224 \meta{options} (which will, thus, overrule the options of the
225 |spy scope|).
226 \item Then, the spy-on node is created. However, we will first discuss
227 the spy-in node.
228 \item The spy-in node is created after the spy-on node (and, hence,
229 will cover the spy-on node in case they overlap). When this node is
230 created, the \meta{node options} are used in addition to the effect
231 caused by the \meta{options} and the options of the |{spy scope}|.
232 Additionally, the following style is used:
233 %
234 \begin{stylekey}{/tikz/every spy in node}
235 This style is used with every spy-in node.
236 \end{stylekey}
237 %
238 The position of the node (the |at| option) is set to the
239 \meta{coordinate} by default, so that it will cover the
240 to-be-magnified area. You can change this by providing the |at|
241 option yourself:
242 %
243 \begin{codeexample}[preamble={\usetikzlibrary{decorations.fractals,spy}}]
244 \begin{tikzpicture}
245 [spy using outlines={circle, magnification=3, size=1cm}]
246
247 \draw [decoration=Koch curve type 1]
248 decorate{ decorate{ decorate{ (0,0) -- (2,0) }}};
249
250 \spy [red] on (1.6,0.3) in node;
251 \spy [blue] on (1,1) in node at (1,-1);
252 \end{tikzpicture}
253 \end{codeexample}
254 %
255 No ``text'' can be specified for the node. Rather, the ``text''
256 shown inside this node is the picture of the current |spy scope|,
257 but canvas-transformed according to the following key:
258 %
259 \begin{key}{/tikz/lens=\meta{options}}
260 The \meta{options} should contain transformation commands like
261 |scale| or |rotate|. These transformations are applied to the
262 picture when it is shown inside the spy-on node.
263 \end{key}
264 %
265 Since the most common transformation is undoubtedly a simple
266 scaling, there is a special style for this:
267 %
268 \begin{key}{/tikz/magnification=\meta{number}}
269 This has the same effect as saying
270 |lens={scale=|\meta{number}|}|.
271 \end{key}
272 %
273 Now, usually the size of a node is determined in such a way that it
274 ``fits'' around the text of the node. For a spy-on node this is not
275 a good approach since the ``text'' of this node would contain ``the
276 whole picture''. Because of this, \tikzname\ acts as if the
277 ``text'' of the node has zero size. You must then use keys like
278 |minimum size| to cause the node to have a certain size. Note that
279 the key |size| is an abbreviation for |minimum size| inside a spy
280 scope.
281
282 You can name the spy-on node in the usual ways. Additionally, the
283 node is (also) always named |tikzspyinnode|. Following the spy
284 scope, you can use this node like any other node:
285 %
286 \begin{codeexample}[preamble={\usetikzlibrary{decorations.fractals,spy}}]
287 \begin{tikzpicture}
288 \begin{scope}
289 [spy using outlines={circle, magnification=3, size=2cm, connect spies}]
290
291 \draw [decoration=Koch curve type 1]
292 decorate{ decorate{ decorate{ (0,0) -- (2,0) }}};
293
294 \spy [red] on (1.6,0.3) in node (a) [left] at (3.5,-1.25);
295
296 \spy [blue, size=1cm] on (1,1) in node (b) [right] at (0,-1.25);
297 \end{scope}
298 \draw [ultra thick, green!50!black] (b) -- (a.north west);
299 \end{tikzpicture}
300 \end{codeexample}
301 %
302 \item Once both nodes have been created, the current value of the
303 following key is used to connect them:
304 %
305 \begin{key}{/tikz/spy connection path=\meta{code} (initially \normalfont empty)}
306 The \meta{code} is executed after the spy-on and spy-in nodes
307 have just been created. Inside this \meta{code}, the two nodes
308 can be accessed as |tikzspyinnode| and |tikzspyonnode|. For
309 example, the key |connect spies| sets this command to
310 %
311 \begin{codeexample}[code only]
312 \draw[thin] (tikzspyonnode) -- (tikzspyinnode);
313 \end{codeexample}
314 \end{key}
315 \end{enumerate}
316 %
317 Returning to the creation of the spy-in node: This node is centered on
318 \meta{coordinate} (more precisely, its anchor is set to |center| and the
319 |at| option is set to \meta{coordinate}). Its size and shape are initially
320 determined in the same way as the size and shape of the spy-on node
321 (unless, of course, you explicitly provide a different shape for, say, the
322 spy-on node locally, which is not really a good idea). Then, additionally,
323 the \emph{inverted} transformation done by the |lens| option is applied,
324 resulting in a node whose size and shape exactly corresponds to the area in
325 the picture that is shown in the spy-on node.
326 %
327 \begin{codeexample}[preamble={\usetikzlibrary{decorations.fractals,spy}}]
328 \begin{tikzpicture}
329 [spy using outlines={lens={scale=3,rotate=20}, size=2cm, connect spies}]
330
331 \draw [decoration=Koch curve type 1]
332 decorate{ decorate{ decorate{ (0,0) -- (2,0) }}};
333
334 \spy [red] on (1.6,0.3) in node at (2.5,-1.25);
335 \end{tikzpicture}
336 \end{codeexample}
337
338 Like for the spy-in node, a style can be used to format the spy-on node:
339 %
340 \begin{stylekey}{/tikz/every spy on node}
341 This style is used with every spy-on node.
342 \end{stylekey}
343 %
344 The spy-on node is named |tikzspyonnode| (but, as always, this node is only
345 available after the spy scope). If you have multiple spy-on nodes and you
346 would like to access all of them, you need to use the |name| key inside the
347 |every spy on node| style.
348
349 The |inner sep| and |outer sep| of both spy-in and spy-on nodes are set to
350 |0pt|.
351 \end{command}
352
353
354 \subsection{Predefined Spy Styles}
355
356 There are some predefined styles that make using the |spy| library easier. The
357 following two styles can be used instead of |spy scope|, they pass their
358 \meta{options} directly to |spy scope|. They additionally set up the graphic
359 styles to be used for the spy-in nodes and the spy-on nodes in some special
360 way.
361
362 \begin{key}{/tikz/spy using outlines=\meta{options} (default \normalfont empty)}
363 This key creates a |spy scope| in which the spy-in node is drawn, but not
364 filled, using a thick line; and the spy-on node is drawn, but not filled,
365 using a very thin line.
366 %
367 \begin{codeexample}[preamble={\usetikzlibrary{decorations.fractals,spy}}]
368 \begin{tikzpicture}
369 [spy using outlines={circle, magnification=3, size=1cm, connect spies}]
370
371 \draw [decoration=Koch curve type 1]
372 decorate{ decorate{ decorate{ (0,0) -- (2,0) }}};
373
374 \spy [red] on (1.6,0.3) in node at (3,1);
375 \end{tikzpicture}
376 \end{codeexample}
377 %
378 \end{key}
379
380 \begin{key}{/tikz/spy using overlays=\meta{options} (default \normalfont empty)}
381 This key creates a |spy scope| in which both the spy-in and spy-on nodes
382 are filled, but with the fill opacity set to 20\%.
383 %
384 \begin{codeexample}[preamble={\usetikzlibrary{decorations.fractals,spy}}]
385 \begin{tikzpicture}
386 [spy using overlays={circle, magnification=3, size=1cm, connect spies}]
387
388 \draw [decoration=Koch curve type 1]
389 decorate{ decorate{ decorate{ (0,0) -- (2,0) }}};
390
391 \spy [green] on (1.6,0.3) in node at (3,1);
392 \end{tikzpicture}
393 \end{codeexample}
394 %
395 \end{key}
396
397 The following style is useful for connecting the spy-in and the spy-on nodes:
398
399 \begin{key}{/tikz/connect spies}
400 Causes the spy-in and the spy-on nodes to be connected by a thin line.
401 %
402 \begin{codeexample}[preamble={\usetikzlibrary{decorations.fractals,spy}}]
403 \begin{tikzpicture}
404 [spy using overlays={circle, magnification=3, size=1cm}]
405
406 \draw [decoration=Koch curve type 2]
407 decorate{ decorate{ decorate{ (0,0) -- (2,0) }}};
408
409 \spy [green] on (1.6,0.1) in node at (3,1);
410 \spy [red,connect spies] on (0.5,0.4) in node at (1,1.5);
411 \end{tikzpicture}
412 \end{codeexample}
413 %
414 \end{key}
415
416
417 \subsection{Examples}
418
419 Usually, the spy-in node and the spy-on node should have the same shape.
420 However, you might also wish to use the |circle| shape for the spy-on node and
421 the |magnifying glass| shape for the spy-in node:
422 %
423 \begin{codeexample}[preamble={\usetikzlibrary{decorations.fractals,shadows,shapes.symbols,spy}}]
424 \tikzset{spy using mag glass/.style={
425 spy scope={
426 every spy on node/.style={
427 circle,
428 fill, fill opacity=0.2, text opacity=1},
429 every spy in node/.style={
430 magnifying glass, circular drop shadow,
431 fill=white, draw, ultra thick, cap=round},
432 #1
433 }}}
434 \begin{tikzpicture}[spy using mag glass={magnification=3, size=1cm}]
435 \draw [decoration=Koch curve type 2]
436 decorate{ decorate{ decorate{ (0,0) -- (2,0) }}};
437
438 \spy [green!50!black] on (1.6,0.1) in node at (2.5,-0.5);
439 \end{tikzpicture}
440 \end{codeexample}
441
442 With the magnifying glass, you can also put it ``on top'' of the picture
443 itself:
444 %
445 \begin{codeexample}[preamble={\usetikzlibrary{decorations.fractals,shadows,shapes.symbols,spy}}]
446 \begin{tikzpicture}
447 [spy scope={magnification=4, size=1cm},
448 every spy in node/.style={
449 magnifying glass, circular drop shadow,
450 fill=white, draw, ultra thick, cap=round}]
451
452 \draw [decoration=Koch curve type 2]
453 decorate{ decorate{ decorate{ (0,0) -- (2,0) }}};
454
455 \spy on (1.6,0.1) in node;
456 \end{tikzpicture}
457 \end{codeexample}
458
459
460 %%% Local Variables:
461 %%% mode: latex
462 %%% TeX-master: "pgfmanual-pdftex-version"
463 %%% End: