diff options
author | Karl Berry <karl@freefriends.org> | 2010-10-29 00:31:31 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2010-10-29 00:31:31 +0000 |
commit | 6bc1f5497cfb2f56d65c80a4c36ea3bad6dc046c (patch) | |
tree | f7751da75030fb1e06653eeb44e579fcee09c65f /Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-spy.tex | |
parent | ed0c7c756e441b2d2ba3633da233fc24361ac0d3 (diff) |
pgf 2.10 (28oct10)
git-svn-id: svn://tug.org/texlive/trunk@20236 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-spy.tex')
-rw-r--r-- | Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-spy.tex | 451 |
1 files changed, 451 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-spy.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-spy.tex new file mode 100644 index 00000000000..dc6f163929f --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-spy.tex @@ -0,0 +1,451 @@ +% Copyright 2006 by Till Tantau +% +% This file may be distributed and/or modified +% +% 1. under the LaTeX Project Public License and/or +% 2. under the GNU Free Documentation License. +% +% See the file doc/generic/pgf/licenses/LICENSE for more details. + + +\section{Spy Library: Magnifying Parts of Pictures} +\label{section-library-spy} + +\begin{tikzlibrary}{spy} + The package defines options for creating pictures in which some part + of the picture is repeated in another area in a magnified way (as if + you were looking through a spyglass, hence the name). +\end{tikzlibrary} + + +\subsection{Magnifying a Part of a Picture} + +The idea behind the |spy| library is to make is easy to create high-density +pictures in which some important parts are repeated somewhere, but +magnified as if you were looking through a spyglass: + +\begin{codeexample}[] +\begin{tikzpicture} + [spy using outlines={circle, magnification=4, size=2cm, connect spies}] + + \draw [help lines] (0,0) grid (3,2); + + \draw [decoration=Koch curve type 1] + decorate { decorate{ decorate{ decorate{ (0,0) -- (2,0) }}}}; + + \spy [red] on (1.6,0.3) + in node [left] at (3.5,-1.25); + + \spy [blue, size=1cm] on (1,1) + in node [right] at (0,-1.25); +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture}[spy using overlays={size=12mm}] + \draw [decoration=Koch snowflake] + decorate { decorate{ decorate{ decorate{ (0,0) -- (2,0) }}}}; + + \spy [green,magnification=3] on (0.6,0.1) in node at (-0.3,-1); + \spy [blue,magnification=5] on (1,0.5) in node at (1,-1); + \spy [red,magnification=10] on (1.6,0.1) in node at (2.3,-1); +\end{tikzpicture} +\end{codeexample} + + +Note that this magnification uses what is called a \emph{canvas + transformation} in this manual: Everything is magnified, including +line width and text. + +In order for ``spying'' to work, the picture obviously has to be drawn +several times: Once at its normal size and then again for each +``magnifying glass.'' Several keys and commands work in concert to +make this possible: +\begin{itemize} +\item You need to make \tikzname\ aware of the fact that a picture (or + just a scope) is to be magnified. This is done by adding the special + key |spy scope| to a |{scope}| or |{tikzpicture}| (which is also + just a scope). Some special keys like |spy using outlines| + implicitly set the |spy scope|. + +\item Inside this scope you may then use the command |\spy|, which is + only available inside such scopes (so there is no danger of your + inadvertently using this command outside such a scope). This command + has a special syntax and will (at some point) create two nodes: One + node that shows the magnified picture (called the \emph{spy-in + node}) and another node showing which part of the original picture + is magnified (called the \emph{spy-on} node). The spy-in node is, + indeed, a normal node, so it can have any shape or border that you + like and you can apply all of \tikzname's advanced features to + it. The only difference compared to a normal node is that instead of + some ``text'' it contains a magnified version of the picture, + clipped to the size of the node. + + The |\spy| command does not create the nodes immediately. Rather, + the creation of these nodes is postponed till the end of the + |spy scope| in which the |\spy| command is used. This is necessary + since in order to repeat the whole scope inside the node containing + the magnified version, the whole picture needs to be available when + this node is created. +\end{itemize} + +A basic question any library for ``magnifying things'' has to address +is how you specify which part of the picture is to be +magnified (the spy-on node) and where this magnified part is to be +shown (the spy-in node). There are two possible ways: +\begin{enumerate} +\item You specify the size and position of the spy-on node. Then the + size of the spy-in node is determined by the size of the spy-on node + and the magnification factor -- you can still decide where the + spy-in node should be placed, but not its size. +\item Alternatively, you specify the size and position of the spy-in + node. Then, similarly to the first case, the size of the spy-on node + is determined implicitly and you can only decide where the + spy-on node should be placed, but not its size. +\end{enumerate} + +The |spy| library uses the second method: You specify the size and +position of the spy-in nodes, the sizes of the spy-on nodes are then +computed automatically. + + + +\subsection{Spy Scopes} + +\begin{key}{/tikz/spy scope=\meta{options} (default \normalfont empty)} + This option may be used with a |{scope}| or any environment that + creates such a scope internally (like |{tikzpicture}|). It has the + following effects: + \begin{itemize} + \item It resets a number of graphic state parameters, including the + color, line style, and other. This is necessary for technical + reasons. + \item It tells \tikzname\ that the content of the scope should be saved + internally in a special box. + \item It defines the command |\spy| so that it can be used inside + the scope. + \item At the end of the scope, the nodes belonging to the |\spy| + commands used inside the scope are created. + \item The \meta{options} are saved in an internal style. Each time + |\spy| is used, these \meta{options} will be used. + \item Three keys are defined that provide useful shortcuts: + \begin{key}{/tikz/size=\meta{dimension}} + Inside a |spy scope|, |size| this is a shortcut for |minimum size|. + \end{key} + \begin{key}{/tikz/height=\meta{dimension}} + Inside a |spy scope|, |height| this is a shortcut for |minimum height|. + \end{key} + \begin{key}{/tikz/width=\meta{dimension}} + Inside a |spy scope|, |width| this is a shortcut for |minimum width|. + \end{key} + \end{itemize} + It is permissible to nest |spy scopes|. In this case, all |\spy| + commands inside the inner |spy scope| only have an effect on + material inside the scope, whereas |\spy| commands outside the inner + |spy scope| but inside the outer |spy scope| allow you to ``spy on + the spy.'' + +\begin{codeexample}[] +\begin{tikzpicture} + [spy using outlines={rectangle, red, magnification=5, + size=1.5cm, connect spies}] + + \begin{scope} + [spy using outlines={circle, blue, + magnification=3, size=1.5cm, connect spies}] + \draw [help lines] (0,0) grid (3,2); + + \draw [decoration=Koch curve type 1] + decorate{ decorate{ decorate{ (0,0) -- (2,0) }}}; + + \spy on (1.6,0.3) in node (zoom) [left] at (3.5,-1.25); + \end{scope} + + \spy on (zoom.north west) in node [right] at (0,-1.25); +\end{tikzpicture} +\end{codeexample} + +\end{key} + + + +\subsection{The Spy Command} + +\begin{command}{\spy \opt{\oarg{options}} |on| \meta{coordinate} + |in node| \meta{node options}|;|} + This command can only be used inside a |spy scope|. Let us start with the syntax: + \begin{itemize} + \item The |\spy| command is not a special case of |\path|. Rather, + it has a small parser of its own. + \item Following the optional \meta{options}, you must write |on|, + followed by a coordinate. This coordinate will be the center of + the area that is to be magnified. + \item Following the \meta{coordinate}, you must write |in node| + followed by some \meta{node options}. The syntax for these options is the same + as for a normal |node| path command, such as |[left]| or + |(foo) [red] at (bar)|. \emph{However}, \meta{node options} are + \emph{not} followed by a curly brace. Rather, the \meta{node + options} must directly be followed by a semicolon. + \end{itemize} + The effect of this command is the following: The \meta{options}, + \meta{coordinate}, and \meta{node options} are stored internally + till the end of the current + |spy scope|. This means that, in particular, you can reference any node + inside the |spy scope|, even if it is not yet defined when the + |\spy| command is given. At the end of the current |spy scope|, two + nodes are created, called the \emph{spy-in node} and the + \emph{spy-on node}. + \begin{itemize} + \item The \emph{spy-in node} is the node that contains a magnified + part of the picture (the node \emph{in} which we see on what we + spy). This node is, indeed, a normal \tikzname\ + node, so you can use all standard options to style this node. In + particular, you can specify a shape or a border color or a drop + shadow or whatever. The only thing that is special about this node + is that instead of containing some normal text, its ``text'' is + the magnified picture. + + To be precise, the picture of the |spy scope| is scaled by a + certain factor, specified by the |lens| or |magnification| options + discussed below, and the shifted in such a way that the + \meta{coordinate} lies at the center of the spy-on node. + \item The \emph{spy-on node} is a node that is centered on the + \meta{coordinate} and whose size reflects exactly the area shown + inside the spy-in node (the node containing \emph{on} what we + spy). + \end{itemize} + + Let us now go over what happens in detail when the two nodes are + created: + \begin{enumerate} + \item A scope is started. Two sets of options are used with this + scope: First, the options passed to the enclosing |spy scope| and + then the \meta{options} (which will, thus, overrule the options of + the |spy scope|). + \item Then, the spy-on node is created. However, we will first + discuss the spy-in node. + \item The spy-in node is created after the spy-on node (and, hence, + will cover the spy-on node in case they overlap). When this node is + created, the \meta{node options} are used in addition to the + effect caused by the \meta{options} and the options of the + |{spy scope}|. Additionally, the following style is used: + \begin{stylekey}{/tikz/every spy in node} + This style is used with every spy in node. + \end{stylekey} + The position of the node (the |at| option) is set to the + \meta{coordinate} by default, so that it will cover the + to-be-magnified area. You can change this by providing the |at| + option yourself: +\begin{codeexample}[] +\begin{tikzpicture} + [spy using outlines={circle, magnification=3, size=1cm}] + + \draw [decoration=Koch curve type 1] + decorate{ decorate{ decorate{ (0,0) -- (2,0) }}}; + + \spy [red] on (1.6,0.3) in node; + \spy [blue] on (1,1) in node at (1,-1); +\end{tikzpicture} +\end{codeexample} + No ``text'' can be specified for the node. Rather, the ``text'' + shown inside this node is the picture of the current |spy scope|, + but canvas-transformed according to the following key: + \begin{key}{/tikz/lens=\meta{options}} + The \meta{options} should contain transformation commands like + |scale| or |rotate|. These transformations are applied to the + picture when it is shown inside the spy-on node. + \end{key} + Since the most common transformation is undoubtedly a simple + scaling, there is a special style for this: + \begin{key}{/tikz/magnification=\meta{number}} + This has the same effect as saying + |lens={scale=|\meta{number}|}|. + \end{key} + Now, usually the size of a node is determined in such a way that + it ``fits'' around the text of the node. For a spy-on node this is + not a good approach since the ``text'' of this node would contain + ``the whole picture.'' Because of this, \tikzname\ acts + as if the ``text'' of the node has zero size. You must then use + keys like |minimum size| to cause the node to have a certain + size. Note that the key |size| is an abbreviation for + |minimum size| inside a spy scope. + + You can name the spy on node in the usual ways. Additionally, the + node is (also) always named |tikzspyinnode|. Following the spy + scope, you can use this node like any other node: +\begin{codeexample}[] +\begin{tikzpicture} + \begin{scope} + [spy using outlines={circle, magnification=3, size=2cm, connect spies}] + + \draw [decoration=Koch curve type 1] + decorate{ decorate{ decorate{ (0,0) -- (2,0) }}}; + + \spy [red] on (1.6,0.3) in node (a) [left] at (3.5,-1.25); + + \spy [blue, size=1cm] on (1,1) in node (b) [right] at (0,-1.25); + \end{scope} + \draw [ultra thick, green!50!black] (b) -- (a.north west); +\end{tikzpicture} +\end{codeexample} + + \item Once both nodes have been created, the current value of the + following key is used to connect them: + \begin{key}{/tikz/spy connection path=\meta{code} (initially + \normalfont empty)} + The \meta{code} is executed after the spy-on and spy-in nodes + have just been created. Inside this \meta{code}, the two nodes + can be accessed as |tikzspyinnode| and |tikzspyonnode|. + For example, the key |connect spies| sets this command to +\begin{codeexample}[code only] +\draw[thin] (tikzspyonnode) -- (tikzspyinnode); +\end{codeexample} + \end{key} + \end{enumerate} + Returning to the creation of the spy-in node: This node is centered on + \meta{coordinate} (more precisely, its anchor is set to |center| and + the |at| option is set to \meta{coordinate}). Its size and shape are + initially determined in the same way as the size and shape of the + spy-on node (unless, of course, you explicitly provide a different + shape for, say, the spy-on node locally, which is not really a good + idea). Then, additionally, the \emph{inverted} transformation done + by the |lens| option is applied, resulting in a node whose size and + shape exactly corresponds to the area in the picture that is shown + in the spy-on node. +\begin{codeexample}[] +\begin{tikzpicture} + [spy using outlines={lens={scale=3,rotate=20}, size=2cm, connect spies}] + + \draw [decoration=Koch curve type 1] + decorate{ decorate{ decorate{ (0,0) -- (2,0) }}}; + + \spy [red] on (1.6,0.3) in node at (2.5,-1.25); +\end{tikzpicture} +\end{codeexample} + + Like for the spy-in node, a style can be used to format the spy-on + node: + \begin{stylekey}{/tikz/every spy on node} + This style is used with every spy on node. + \end{stylekey} + The spy-on node is named |tikzspyonnode| (but, as always, this node + is only available after the spy scope). If you have multiple + spy-on nodes and you would like to access all of them, you need to + use the |name| key inside the |every spy on node| style. + + The |inner sep| and |outer sep| of both spy-in and spy-on nodes are + set to |0pt|. +\end{command} + + + +\subsection{Predefined Spy Styles} + +There are some predefined styles that make using the |spy| library +easier. The following two styles can be used instead of |spy scope|, +they pass their \meta{options} directly to |spy scope|. They +additionally setup the graphic styles to be used for the spy-in nodes +and the spy-on nodes in some special way. + +\begin{key}{/tikz/spy using outlines=\meta{options} (default + \normalfont empty)} + This key creates a |spy scope| in which the spy-in node is drawn, + but not filled, using a thick line; and the spy-on node is drawn, + but not filled, using a very thin line. + +\begin{codeexample}[] +\begin{tikzpicture} + [spy using outlines={circle, magnification=3, size=1cm, connect spies}] + + \draw [decoration=Koch curve type 1] + decorate{ decorate{ decorate{ (0,0) -- (2,0) }}}; + + \spy [red] on (1.6,0.3) in node at (3,1); +\end{tikzpicture} +\end{codeexample} +\end{key} + +\begin{key}{/tikz/spy using overlays=\meta{options} (default + \normalfont empty)} + This key creates a |spy scope| in which both the spy-in and spy-on + nodes are filled, but with the fill opacity set to 20\%. + +\begin{codeexample}[] +\begin{tikzpicture} + [spy using overlays={circle, magnification=3, size=1cm, connect spies}] + + \draw [decoration=Koch curve type 1] + decorate{ decorate{ decorate{ (0,0) -- (2,0) }}}; + + \spy [green] on (1.6,0.3) in node at (3,1); +\end{tikzpicture} +\end{codeexample} +\end{key} + +The following style is useful for connecting the spy-in and the spy-on +nodes: + +\begin{key}{/tikz/connect spies} + Causes the spy-in and the spy-on nodes to be connected by a thin + line. + +\begin{codeexample}[] +\begin{tikzpicture} + [spy using overlays={circle, magnification=3, size=1cm}] + + \draw [decoration=Koch curve type 2] + decorate{ decorate{ decorate{ (0,0) -- (2,0) }}}; + + \spy [green] on (1.6,0.1) in node at (3,1); + \spy [red,connect spies] on (0.5,0.4) in node at (1,1.5); +\end{tikzpicture} +\end{codeexample} +\end{key} + + +\subsection{Examples} + +Usually, the spy-in node and the spy-on node should have the same +shape. However, you might also wish to use the |circle| shape for the +spy-on node and the |magnifying glass| shape for the spy-in node: + +\begin{codeexample}[] +\tikzset{spy using mag glass/.style={ + spy scope={ + every spy on node/.style={ + circle, + fill, fill opacity=0.2, text opacity=1}, + every spy in node/.style={ + magnifying glass, circular drop shadow, + fill=white, draw, ultra thick, cap=round}, + #1 + }}} +\begin{tikzpicture}[spy using mag glass={magnification=3, size=1cm}] + \draw [decoration=Koch curve type 2] + decorate{ decorate{ decorate{ (0,0) -- (2,0) }}}; + + \spy [green!50!black] on (1.6,0.1) in node at (2.5,-0.5); +\end{tikzpicture} +\end{codeexample} + +With the magnifying glass, you can also put it ``on top'' of the +picture itself: + +\begin{codeexample}[] +\begin{tikzpicture} + [spy scope={magnification=4, size=1cm}, + every spy in node/.style={ + magnifying glass, circular drop shadow, + fill=white, draw, ultra thick, cap=round}] + + \draw [decoration=Koch curve type 2] + decorate{ decorate{ decorate{ (0,0) -- (2,0) }}}; + + \spy on (1.6,0.1) in node; +\end{tikzpicture} +\end{codeexample} + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "pgfmanual-pdftex-version" +%%% End: |