summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-decorations.tex
blob: 1600e6f5378c779cfd113f275c5078af7d52260c (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
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
% Copyright 2008 by Mark Wibrow
%
% 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{Decorated Paths}
\label{section-tikz-decorations}

\subsection{Overview}

Decorations are a general concept to make (sub)paths ``more interesting''.
Before we have a look at the details, let us have a look at some examples:
%
\begin{codeexample}[]
\begin{tikzpicture}[thick]
  \draw                                                (0,3)   -- (3,3);
  \draw[decorate,decoration=zigzag]                    (0,2.5) -- (3,2.5);
  \draw[decorate,decoration=brace]                     (0,2)   -- (3,2);
  \draw[decorate,decoration=triangles]                 (0,1.5) -- (3,1.5);
  \draw[decorate,decoration={coil,segment length=4pt}] (0,1)   -- (3,1);
  \draw[decorate,decoration={coil,aspect=0}]           (0,.5)  -- (3,.5);
  \draw[decorate,decoration={expanding waves,angle=7}] (0,0)   -- (3,0);
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[]
\begin{tikzpicture}
  \node [fill=red!20,draw,decorate,decoration={bumps,mirror},
         minimum height=1cm]
  {Bumpy};
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[]
\begin{tikzpicture}
  \filldraw[fill=blue!20]                    (0,3)
  decorate [decoration=saw]             { -- (3,3) }
  decorate [decoration={coil,aspect=0}] { -- (2,1) }
  decorate [decoration=bumps]           { -| (0,3) };
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[]
\begin{tikzpicture}
  \node [fill=yellow!50,draw,thick, minimum height=2cm, minimum width=3cm,
         decorate, decoration={random steps,segment length=3pt,amplitude=1pt}]
    {Saved from trash};
\end{tikzpicture}
\end{codeexample}

The general idea of decorations is the following: First, you construct a path
using the usual path construction commands. The resulting path is, in essence,
a series of straight and curved lines. Instead of directly using this path for
filling or drawing, you can then specify that it should form the basis for a
decoration. In this case, depending on which decoration you use, a new path is
constructed ``along'' the path you specified. For instance, with the |zigzag|
decoration, the new path is a zigzagging line that goes along the old path.

Let us have a look at an example: In the first picture, we see a path that
consists of a line, an arc, and a line. In the second picture, this path has
been used as the basis of a decoration.
%
\begin{codeexample}[]
\tikz \fill
  [fill=blue!20,draw=blue,thick] (0,0) -- (2,1) arc (90:-90:.5) -- cycle;
\end{codeexample}
%
\begin{codeexample}[]
\tikz \fill [decorate,decoration={zigzag}]
  [fill=blue!20,draw=blue,thick] (0,0) -- (2,1) arc (90:-90:.5) -- cycle;
\end{codeexample}

It is also possible to decorate only a subpath (the exact syntax will be
explained later in this section).
%
\begin{codeexample}[]
\tikz \fill [decoration={zigzag}]
  [fill=blue!20,draw=blue,thick] (0,0) -- (2,1)
    decorate { arc (90:-90:.5) } -- cycle;
\end{codeexample}

The |zigzag| decoration will be called a \emph{path morphing} decoration
because it morphs a path into a different, but topologically equivalent path.
Not all decorations are path morphing; rather there are three kinds of
decorations.

\begin{enumerate}
    \item The just-mentioned \emph{path morphing} decorations morph the path in
        the sense that what used to be a straight line might afterwards be a
        squiggly line or might have bumps. However, a line is still and a line
        and path deforming decorations do not change the number of subpaths.

        Examples of such decorations are the |snake| or the |zigzag|
        decoration. Many such decorations are defined in the library
        |decorations.pathmorphing|.

    \item \emph{Path replacing} decorations completely replace the path by a
        different path that is only ``loosely based'' on the original path. For
        instance, the |crosses| decoration replaces a path by a path consisting
        of a sequence of crosses. Note how in the following example filling the
        path has no effect since the path consist only of (numerous)
        unconnected straight line subpaths:
        %
\begin{codeexample}[]
\tikz \fill [decorate,decoration={crosses}]
  [fill=blue!20,draw=blue,thick] (0,0) -- (2,1) arc (90:-90:.5) -- cycle;
\end{codeexample}

        Examples of path replacing decorations are |crosses| or |ticks| or
        |shape backgrounds|. Such decorations are defined in the library
        |decorations.pathreplacing|, but also in |decorations.shapes|.
    \item \emph{Path removing} decorations completely remove the
        to-be-decorated path. Thus, they have no effect on the main path that
        is being constructed. Instead, they typically have numerous \emph{side
        effects}. For instance, they might ``write some text'' along the
        (removed) path or they might place nodes along this path. Note that for
        such decorations the path usage command for the main path have no
        influence on how the decoration looks like.
        %
\begin{codeexample}[]
\tikz \fill [decorate,decoration={text along path,
               text=This is a text along a path. Note how the path is lost.}]
  [fill=blue!20,draw=blue,thick] (0,0) -- (2,1) arc (90:-90:.5) -- cycle;
\end{codeexample}
        %
\end{enumerate}

Decorations are defined in different decoration libraries, see
Section~\ref{section-library-decorations} for details. It is also possible to
define your own decorations, see Section~\ref{section-base-decorations}, but
you need to use the \pgfname\ basic layer and a bit of theory is involved.

Decorations can be used to decorate already decorated paths. In the following
three graphics, we start with a simple path, then decorate it once, and then
decorate the decorated path once more.
%
\begin{codeexample}[]
\tikz \fill [fill=blue!20,draw=blue,thick]
  (0,0) rectangle (3,2);
\end{codeexample}
%
\begin{codeexample}[]
\tikz \fill [fill=blue!20,draw=blue,thick]
  decorate[decoration={zigzag,segment length=10mm,amplitude=2.5mm}]
    { (0,0) rectangle (3,2) };
\end{codeexample}
%
\begin{codeexample}[]
\tikz \fill [fill=blue!20,draw=blue,thick]
  decorate[decoration={crosses,segment length=2mm}] {
    decorate[decoration={zigzag,segment length=10mm,amplitude=2.5mm}] {
      (0,0) rectangle (3,2)
    }
  };
\end{codeexample}

One final word of warning: Decorations can be pretty slow to typeset and they
can be inaccurate. The reason is that \pgfname\ has to a \emph{lot} of rather
difficult computations in the background and \TeX\ is not very good at doing
math. Decorations are fastest when applied to straight line segments, but even
then they are much slower than other alternatives. For instance, the |ticks|
decoration can be simulated by clever use of a dashing pattern and the dashing
pattern will literally be thousands of times faster to typeset. However, for
most decorations there are no real alternatives.

\begin{tikzlibrary}{decorations}
    In order to use decorations, you first have to load a decoration library.
    This |decoration| library defines the basic options described in the
    following, but it does not define any new decorations. This is done by
    libraries like |decorations.text|. Since these more specialized libraries
    include the |decoration| library automatically, you usually do not have to
    bother about it.
\end{tikzlibrary}


\subsection{Decorating a Subpath Using the Decorate Path Command}

The most general way to decorate a (sub)path is the following path command.

\begin{pathoperation}{decorate}{\opt{\oarg{options}}\marg{subpath}}
    This path operation causes the \meta{subpath} to be decorated using the
    current decoration. Depending on the decoration, this may or may not extend
    the current path.
    %
\begin{codeexample}[]
\begin{tikzpicture}
  \draw [help lines] grid (3,2);
  \draw decorate [decoration={name=zigzag}]
         { (0,0) .. controls (0,2) and (3,0) .. (3,2) |- (0,0) };
\end{tikzpicture}
\end{codeexample}
    %
    The path can include straight lines, curves, rectangles, arcs, circles,
    ellipses, and even already decorated paths (that is, you can nest
    applications of the |decorate| path command, see below).

    Due to the limits on the precision in  \TeX, some inaccuracies in
    positioning when crossing input segment boundaries may occasionally be
    found.

    You can use nodes normally inside the \meta{subpath}.
    %
\begin{codeexample}[]
\begin{tikzpicture}
  \draw [help lines] grid (3,2);
  \draw decorate [decoration={name=zigzag}]
    { (0,0) -- (2,2) node (hi) [left,draw=red] {Hi!} arc(90:0:1)};

  \draw [blue] decorate [decoration={crosses}] {(3,0) -- (hi)};
\end{tikzpicture}
\end{codeexample}

    The following key is used to select the decoration and also to select
    further ``rendering options'' for the decoration.

    \begin{key}{/pgf/decoration=\meta{decoration options}}
            \keyalias{tikz}
        This option is used to specify which decoration is used and how it will
        look like. Note that this key will \emph{not} cause any decorations to
        be applied, immediately. It takes the |decorate| path command or the
        |decorate| option to actually decorate a path. The |decoration| option
        is only used to specify which decoration should be used, in principle.
        You can also use this option at the beginning of a picture or a scope
        to specify the decoration to be used with each invocation of the
        |decorate| path command. Naturally, any local options of the |decorate|
        path command override these ``global'' options.
        %
\begin{codeexample}[]
\begin{tikzpicture}[decoration=zigzag]
  \draw       decorate                      {(0,0) -- (3,2)};
  \draw [red] decorate [decoration=crosses] {(0,2) -- (3,0)};
\end{tikzpicture}
\end{codeexample}

        The \meta{decoration options} are special options (which have the path
        prefix |/pgf/decoration/|) that determine the properties of the
        decoration. Which options are appropriate for a decoration strongly
        depend on the decoration, you will have to look up the appropriate
        options in the documentation of the decoration, see
        Section~\ref{section-library-decorations}.

        There is one option (available only in \tikzname) that is special:
        %
        \begin{key}{/pgf/decoration/name=\meta{name} (initially none)}
            Use this key to set which decoration is to be used. The \meta{name}
            can both be a decoration or a meta-decoration (you need to worry
            about the difference only if you wish to define your own
            decorations).

            If you set \meta{name} to |none|, no decorations are added.
            %
\begin{codeexample}[]
\begin{tikzpicture}
  \draw [help lines] grid (3,2);
  \draw decorate [decoration={name=zigzag}]
         { (0,0) .. controls (0,2) and (3,0) .. (3,2) };
\end{tikzpicture}
\end{codeexample}
            %
            Since this option is used so often, you can also leave out the
            |name=| part. Thus, the above example can be rewritten more
            succinctly:
            %
\begin{codeexample}[]
\begin{tikzpicture}
  \draw [help lines] grid (3,2);
  \draw decorate [decoration=zigzag]
         { (0,0) .. controls (0,2) and (3,0) .. (3,2) };
\end{tikzpicture}
\end{codeexample}
            %
            In general, when \meta{decoration options} are parsed, for each
            unknown key it is checked whether that key happens to be a
            (meta-)decoration and, if so, the |name| option is executed for
            this key.
        \end{key}

        Further options allow you to adjust the position of decorations
        relative to the to-be-decorated path. See
        Section~\ref{section-decorations-adjust} below for details.
    \end{key}

    Recall that some decorations actually completely remove the to-be-decorated
    path. In such cases, the construction of the main path is resumed after the
    |decorate| path command ends.
    %
\begin{codeexample}[]
\begin{tikzpicture}[decoration={text along path,text=
      around and around and around and around we go}]

  \draw (0,0) -- (1,1) decorate { -- (2,1) } -- (3,0);
\end{tikzpicture}
\end{codeexample}

    It is permissible to nest |decorate| commands. In this case, the path
    resulting from the first decoration process is used as the to-be-decorated
    path for the second decoration process. This is especially useful for
    drawing fractals. The |Koch snowflake| decoration replaces a straight line
    like \tikz\draw (0,0) -- (1,0); by
    \tikz[decoration=Koch snowflake] \draw decorate{(0,0) -- (1,0)};.
    Repeatedly applying this transformation to a triangle yields a fractal that
    looks a bit like a snowflake, hence the name.
    %
\begin{codeexample}[]
\begin{tikzpicture}[decoration=Koch snowflake,draw=blue,fill=blue!20,thick]
  \filldraw (0,0) -- ++(60:1) -- ++(-60:1) -- cycle ;
  \filldraw decorate{ (0,-1) -- ++(60:1) -- ++(-60:1) -- cycle };
  \filldraw decorate{ decorate{ (0,-2.5) -- ++(60:1) -- ++(-60:1) -- cycle }};
\end{tikzpicture}
\end{codeexample}
    %
\end{pathoperation}


\subsection{Decorating a Complete Path}

You may sometimes wish to decorate a path over whose construction you have no
control. For instance, the path of the background of a node is created without
having a chance to issue a |decorate| path command. In such cases you can use
the following option, which allows you to decorate a path ``after the fact''.

\begin{key}{/tikz/decorate=\opt{\meta{boolean}} (default true)}
    When this key is set, the whole path is decorated after it has been
    finished. The decoration used for decorating the path is set via the
    |decoration| way, in exactly the same way as for the |decorate| path
    command. Indeed, the following two commands have the same effect:
    %
    \begin{enumerate}
        \item |\path decorate[|\meta{options}|] {|\meta{path}|};|
        \item |\path [decorate,|\meta{options}|] |\meta{path}|;|
    \end{enumerate}
    %
    The main use or the |decorate| option is the you can also use it with the
    nodes. It then causes the background path of the node to be decorated. Note
    that you can decorate a background path only once in this manner. That is,
    in contrast to the |decorate| path command you cannot apply this option
    twice (this would just set it to |true|, once more).
    %
\begin{codeexample}[]
\begin{tikzpicture}[decoration=zigzag]
  \draw [help lines] (0,0) grid (3,5);

  \draw [fill=blue!20,decorate] (1.5,4) circle (1cm);

  \node at (1.5,2.5) [fill=red!20,decorate,ellipse] {Ellipse};

  \node at (1.5,1) [inner sep=6mm,fill=red!20,decorate,ellipse,decoration=
    {text along path,text={This is getting silly}}] {Ellipse};
\end{tikzpicture}
\end{codeexample}

    In the last example, the |text along path| decoration removes the path. In
    such cases it is useful to use a pre- or postaction to cause the decoration
    to be applied only before or after the main path has been used.
    Incidentally, this is another application of the |decorate| option that you
    cannot achieve with the decorate path command.
    %
\begin{codeexample}[]
\begin{tikzpicture}[decoration=zigzag]
  \node at (1.5,1) [inner sep=6mm,fill=red!20,ellipse,
    postaction={decorate,decoration=
    {text along path,text={This is getting silly}}}] {Ellipse};
\end{tikzpicture}
\end{codeexample}
    %
    Here is more useful example, where a postaction is used to add the path
    after the main path has been drawn.
    %
% \catcode`\|12 % !?
\begin{codeexample}[]
\begin{tikzpicture}
\draw [help lines] grid (3,2);
\fill [draw=red,fill=red!20,
         postaction={decorate,decoration={raise=2pt,text along path,
           text=around and around and around and around we go}}]
  (0,1) arc (180:-180:1.5cm and 1cm);
\end{tikzpicture}
\end{codeexample}
    %
\end{key}


\subsection{Adjusting Decorations}
\label{section-decorations-adjust}

\subsubsection{Positioning Decorations Relative to the To-Be-Decorate Path}

The following option, which are only available with \tikzname, allow you to
modify the positioning of decorations relative to the to-be-decorated path.

\begin{key}{/pgf/decoration/raise=\meta{dimension} (initially 0pt)}
    The segments of the decoration are raised by \meta{dimension} relative to
    the to-be-decorated path. More precisely, the segments of the path are
    offset by this much ``to the left'' of the path as we travel along the
    path. This raising is done after and in addition to any transformations set
    using the |transform| option (see below).

    A negative \meta{dimension} will offset the decoration ``to the right'' of
    the to-be-decorated path.
    %
\begin{codeexample}[]
\begin{tikzpicture}
  \draw [help lines] (0,0) grid (3,2);

  \draw (0,0) -- (1,1) arc (90:0:2 and 1);
  \draw      decorate [decoration=crosses]
        { (0,0) -- (1,1) arc (90:0:2 and 1) };
  \draw[red] decorate [decoration={crosses,raise=5pt}]
        { (0,0) -- (1,1) arc (90:0:2 and 1) };
\end{tikzpicture}
\end{codeexample}
    %
\end{key}

\begin{key}{/pgf/decoration/mirror=\opt{\meta{boolean}}}
    Causes the segments of the decoration to be mirrored along the
    to-be-decorated path. This is done after and in addition to any
    transformations set using the |transform| and/or |raise| options.
    %
\begin{codeexample}[]
\begin{tikzpicture}
  \node (a)          {A};
  \node (b) at (2,1) {B};
  \draw                                                    (a) -- (b);
  \draw[decorate,decoration=brace]                         (a) -- (b);
  \draw[decorate,decoration={brace,mirror},red]            (a) -- (b);
  \draw[decorate,decoration={brace,mirror,raise=5pt},blue] (a) -- (b);
\end{tikzpicture}
\end{codeexample}
    %
\end{key}

\begin{key}{/pgf/decoration/transform=\meta{transformations}}
    This key allows you to specify general \meta{transformations} to be applied
    to the segments of a decoration. These transformations are applied before
    and independently of |raise| and |mirror| transformations. The
    \meta{transformations} should be normal \tikzname\ transformations like
    |shift| or |rotate|.

    In the following example the |shift only| transformation is used to make
    sure that the crosses are \emph{not} sloped along the path.
    %
\begin{codeexample}[]
\begin{tikzpicture}
  \draw [help lines] (0,0) grid (3,2);

  \draw (0,0) -- (1,1) arc (90:0:2 and 1);
  \draw[red,very thick] decorate [decoration={
               crosses,transform={shift only},shape size=1.5mm}]
        { (0,0) -- (1,1) arc (90:0:2 and 1) };
\end{tikzpicture}
\end{codeexample}
    %
\end{key}


\subsubsection{Starting and Ending Decorations Early or Late}

You sometimes may wish to ``end'' a decoration a bit early on the path. For
instance, you might wish a |snake| decoration to stop 5mm before the end of the
path and to continue in a straight line. There are different ways of achieving
this effect, but the easiest may be the |pre| and |post| options, which only
have an effect in \tikzname. Note, however, that they can only be used with
decorations, not with meta-decorations.

\begin{key}{/pgf/decoration/pre=\meta{decoration} (initially lineto)}
    This key sets a decoration that should be used before the main decoration
    starts. The \meta{decoration} will be used for a length of |pre length|,
    which |0pt| by default. Thus, for the |pre| option to have any effect, you
    also need to set the |pre length| option.
    %
\begin{codeexample}[]
\begin{tikzpicture}
\tikz [decoration={zigzag,pre=lineto,pre length=1cm}]
  \draw [decorate] (0,0) -- (2,1) arc (90:0:1);
\end{tikzpicture}
\end{codeexample}
    %
\begin{codeexample}[]
\begin{tikzpicture}
\tikz [decoration={zigzag,pre=moveto,pre length=1cm}]
  \draw [decorate] (0,0) -- (2,1) arc (90:0:1);
\end{tikzpicture}
\end{codeexample}
    %
\begin{codeexample}[]
\begin{tikzpicture}
\tikz [decoration={zigzag,pre=crosses,pre length=1cm}]
  \draw [decorate] (0,0) -- (2,1) arc (90:0:1);
\end{tikzpicture}
\end{codeexample}

    Note that the default |pre| option is |lineto|, not |curveto|. This means
    that the default |pre| decoration will not follow curves (for efficiency
    reasons). Change the |pre| key to |curveto| if you have a curved path.
    %
\begin{codeexample}[]
\begin{tikzpicture}
\tikz [decoration={zigzag,pre length=3cm}]
  \draw [decorate] (0,0) -- (2,1) arc (90:0:1);
\end{tikzpicture}
\end{codeexample}
    %
\begin{codeexample}[]
\begin{tikzpicture}
\tikz [decoration={zigzag,pre=curveto,pre length=3cm}]
  \draw [decorate] (0,0) -- (2,1) arc (90:0:1);
\end{tikzpicture}
\end{codeexample}
    %
\end{key}

\begin{key}{/pgf/decoration/pre length=\meta{dimension} (initially 0pt)}
    This key sets the distance along which the pre-decoration should be used.
    If you do not need/wish a pre-decoration, set this key to |0pt| (exactly
    this string, not just to something that evaluates to the same things such
    as |0cm|).
\end{key}

\begin{key}{/pgf/decorations/post=\meta{decoration} (initially lineto)}
    Works like |pre|, only for the end of the decoration.
\end{key}

\begin{key}{/pgf/decorations/post length=\meta{dimension} (initially 0pt)}
    Works like |pre length|, only for the end of the decoration.
\end{key}

Here is a typical example that shows how these keys can be used:
%
\begin{codeexample}[]
\begin{tikzpicture}
  [decoration=snake,
   line around/.style={decoration={pre length=#1,post length=#1}}]

  \draw[->,decorate]                  (0,0)    -- ++(3,0);
  \draw[->,decorate,line around=5pt]  (0,-5mm) -- ++(3,0);
  \draw[->,decorate,line around=1cm]  (0,-1cm) -- ++(3,0);
\end{tikzpicture}
\end{codeexample}