Debian Codegraph @

texmf-dist/doc/generic/pgf/pgfmanual-en-library-patterns.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{Pattern Library}
12 \label{section-library-patterns}
13
14 \begin{pgflibrary}{patterns}
15 The package defines patterns for filling areas.
16 \end{pgflibrary}
17
18
19 \newcommand\patternindex[1]{%
20 \index{#1@\protect\texttt{#1} pattern}%
21 \index{Patterns!#1@\protect\texttt{#1}}%
22 \texttt{#1}&
23 \begin{tikzpicture}[baseline=.5ex]
24
25 % Background
26 \pattern [path fading=west,pattern=checkerboard light gray]
27 (0,0) rectangle (5cm,2em);
28
29 \pattern [pattern=#1,pattern color=black] (0,0) rectangle +(1.5cm,2em);
30 \pattern [pattern=#1,pattern color=blue] (1.75,0) rectangle +(1.5cm,2em);
31 \pattern [pattern=#1,pattern color=red] (3.5,0) rectangle +(1.5cm,2em);
32 \end{tikzpicture} \\[1ex]
33 }
34
35 \newcommand\patternindexinherentlycolored[1]{%
36 \index{#1@\protect\texttt{#1} pattern}%
37 \index{Patterns!#1@\protect\texttt{#1}}%
38 \texttt{#1}&
39 \begin{tikzpicture}[baseline=.5ex]
40
41 % Background
42 \pattern [path fading=west,pattern=checkerboard light gray]
43 (0,0) rectangle (5cm,2em);
44
45 \pattern [pattern=#1,pattern color=blue] (0,0) rectangle +(5cm,2em);
46 \end{tikzpicture} \\[1ex]
47 }
48
49
50 \subsection{Form-Only Patterns}
51
52 \begin{tabular}{ll}
53 \emph{Pattern name}
54 & \emph{Example (pattern in black, blue, and red on faded checkerboard)} \\
55 \patternindex{horizontal lines}
56 \patternindex{vertical lines}
57 \patternindex{north east lines}
58 \patternindex{north west lines}
59 \patternindex{grid}
60 \patternindex{crosshatch}
61 \patternindex{dots}
62 \patternindex{crosshatch dots}
63 \patternindex{fivepointed stars}
64 \patternindex{sixpointed stars}
65 \patternindex{bricks}
66 \patternindex{checkerboard}
67 \end{tabular}
68
69
70 \subsection{Inherently Colored Patterns}
71
72 \begin{tabular}{ll}
73 \emph{Pattern name} & \emph{Example} \\
74 \patternindexinherentlycolored{checkerboard light gray}
75 \patternindexinherentlycolored{horizontal lines light gray}
76 \patternindexinherentlycolored{horizontal lines gray}
77 \patternindexinherentlycolored{horizontal lines dark gray}
78 \patternindexinherentlycolored{horizontal lines light blue}
79 \patternindexinherentlycolored{horizontal lines dark blue}
80 \patternindexinherentlycolored{crosshatch dots gray}
81 \patternindexinherentlycolored{crosshatch dots light steel blue}
82 \end{tabular}
83
84
85 \subsection{User-Defined Patterns}
86 \label{section-library-patterns-meta}
87
88 \noindent\emph{by Mark Wibrow}
89
90 \begin{pgflibrary}{patterns.meta}
91 Define your own patterns with a syntax similar to |arrows.meta|.
92 \end{pgflibrary}
93
94 \emph{Caveat:} This library is currently experimental and might change without
95 notice. There are some known shortcomings that will hopefully be fixed in the
96 future.
97
98 \begin{command}{\pgfdeclarepattern\marg{config}}
99 This command is used to declare a new pattern. In contrast to the normal
100 patterns and in the spirit of |arrows.meta| this command takes a list of
101 keys and values to define the pattern. The following keys are available:
102 %
103 \begin{key}{/pgf/patterns/name=\meta{name}}
104 The name of the pattern by which it can be used later on.
105 \end{key}
106 %
107 \begin{key}{/pgf/patterns/type=\meta{type} (default uncolored)}
108 The type of the pattern maps to what was called ``form only'' and
109 ``inherently colored'' in the language of the normal patterns. The
110 available choices are:
111 %
112 \begin{itemize}
113 \item |uncolored| the pattern will obey the surrounding color.
114 \item |colored| the pattern will have an intrinsic color.
115 \item |form only| synonym for |uncolored|
116 \item |inherently colored| synonym for |colored|
117 \end{itemize}
118 \end{key}
119 %
120 \begin{key}{/pgf/patterns/x=\meta{dimension} (default 1cm)}
121 Unit vector of the coordinate system in the $x$-direction.
122 \end{key}
123 %
124 \begin{key}{/pgf/patterns/y=\meta{dimension} (default 1cm)}
125 Unit vector of the coordinate system in the $y$-direction.
126 \end{key}
127 %
128 \begin{key}{/pgf/patterns/parameters=\meta{comma separated list} (default empty)}
129 A list of parameters that are passed to the pattern. This is usually a
130 list of \TeX\ macros. It is very important that these macros are fully
131 expandable because the values they hold are being used for
132 deduplication in the PDF file.
133 \end{key}
134 %
135 \begin{key}{/pgf/patterns/defaults=\meta{comma separated list} (default empty)}
136 This list holds default assignments to the parameters passed to the
137 pattern. The default keys can then be found under the
138 |/pgf/pattern keys/| prefix.
139 \end{key}
140 %
141 \begin{key}{/pgf/patterns/bottom left=\meta{pgfpoint}}
142 Bottom left corner of the pattern's bounding box, e.g.\
143 |\pgfqpoint{-.1pt}{-.1pt}|.
144 \end{key}
145 %
146 \begin{key}{/pgf/patterns/top right=\meta{pgfpoint}}
147 Top right corner of the pattern's bounding box, e.g.\
148 |\pgfqpoint{3.1pt}{3.1pt}|.
149 \end{key}
150 %
151 \begin{key}{/pgf/patterns/tile size=\meta{pgfpoint}}
152 Width and height of a single of the pattern as a \pgfname\ point
153 specification, i.e.\ the $x$ coordinate is the width and the $y$
154 coordinate is the height, e.g.\ |\pgfqpoint{3pt}{3pt}|.
155 \end{key}
156 %
157 \begin{key}{/pgf/patterns/tile transformation=\meta{pgftransformation} (default empty)}
158 A \pgfname\ transformation, e.g.\ |\pgftransformrotate{30}|.
159 \end{key}
160 %
161 \begin{key}{/pgf/patterns/code=\meta{code}}
162 The code should be \pgfname\ code that can be protocolled. It should not
163 contain any color code or nodes.
164 \end{key}
165 %
166 \begin{key}{/pgf/patterns/set up code=\meta{code} (default empty)}
167 This code can be set if parameters have to be preprocessed before the
168 actual pattern code can be run.
169 \end{key}
170 \end{command}
171
172 \begin{codeexample}[preamble={\usetikzlibrary{patterns.meta}}]
173 \pgfdeclarepattern{
174 name=hatch,
175 parameters={\hatchsize,\hatchangle,\hatchlinewidth},
176 bottom left={\pgfpoint{-.1pt}{-.1pt}},
177 top right={\pgfpoint{\hatchsize+.1pt}{\hatchsize+.1pt}},
178 tile size={\pgfpoint{\hatchsize}{\hatchsize}},
179 tile transformation={\pgftransformrotate{\hatchangle}},
180 code={
181 \pgfsetlinewidth{\hatchlinewidth}
182 \pgfpathmoveto{\pgfpoint{-.1pt}{-.1pt}}
183 \pgfpathlineto{\pgfpoint{\hatchsize+.1pt}{\hatchsize+.1pt}}
184 \pgfpathmoveto{\pgfpoint{-.1pt}{\hatchsize+.1pt}}
185 \pgfpathlineto{\pgfpoint{\hatchsize+.1pt}{-.1pt}}
186 \pgfusepath{stroke}
187 }
188 }
189
190 \tikzset{
191 hatch size/.store in=\hatchsize,
192 hatch angle/.store in=\hatchangle,
193 hatch line width/.store in=\hatchlinewidth,
194 hatch size=5pt,
195 hatch angle=0pt,
196 hatch line width=.5pt,
197 }
198
199 \begin{tikzpicture}
200 \foreach \r in {1,...,4}
201 \draw [pattern=hatch, pattern color=red]
202 (\r*3,0) rectangle ++(2,2);
203
204 \foreach \r in {1,...,4}
205 \draw [pattern=hatch, pattern color=green, hatch size=2pt]
206 (\r*3,3) rectangle ++(2,2);
207
208 \foreach \r in {1,...,4}
209 \draw [pattern=hatch, pattern color=blue, hatch size=10pt, hatch angle=21]
210 (\r*3,6) rectangle ++(2,2);
211
212 \foreach \r in {1,...,4}
213 \draw [pattern=hatch, pattern color=orange, hatch line width=2pt]
214 (\r*3,9) rectangle ++(2,2);
215 \end{tikzpicture}
216 \end{codeexample}
217
218 There are a couple of predefined \pgfname\ patterns which are similar
219 to their normal counterparts. For all of these the |xshift| and |yshift| are
220 applied \emph{before} the rotation. If you want to rotate before shifting,
221 just rotate in the drawing code.
222
223 \begin{pattern}{Lines}
224 The |Lines| pattern replaces four patterns: |horizontal lines|,
225 |vertical lines|, |north east lines|, and |north west lines|.
226 Unfortunately, due to
227 the way the old patterns are constructed, namely that they are not simply
228 related to each other by rotation, the |Lines| pattern cannot be used as a
229 drop-in replacement.
230
231 However, the pattern options can be tuned to resemble the other versions
232 closely. The available parameters are:
233 %
234 \begin{key}{/pgf/pattern keys/distance (initially 3pt)}
235 Distance between lines.
236 \end{key}
237 %
238 \begin{key}{/pgf/pattern keys/angle (initially 0)}
239 By default the lines are horizontal. The whole pattern is rotated by
240 this angle. The rotation angle is measured in the mathematically
241 positive sense.
242 \end{key}
243 %
244 \begin{key}{/pgf/pattern keys/xshift (initially 0pt)}
245 Shifts the whole pattern in $x$-direction (before applying the
246 rotation).
247 \end{key}
248 %
249 \begin{key}{/pgf/pattern keys/yshift (initially 0pt)}
250 Shifts the whole pattern in $y$-direction (before applying the
251 rotation).
252 \end{key}
253 %
254 \begin{key}{/pgf/pattern keys/line width (initially \string\the\string\pgflinewidth)}
255 Thickness of the lines.
256 \end{key}
257 %
258 The following settings can be used to reproduce the other |... lines|
259 patterns.
260 %
261 \begin{codeexample}[preamble={\usetikzlibrary{patterns,patterns.meta}}]
262 \begin{tikzpicture}
263 \draw[pattern={horizontal lines},pattern color=orange]
264 (0,0) rectangle +(1,1);
265 \draw[pattern={Lines[yshift=.5pt]},pattern color=blue]
266 (0,0) rectangle +(1,1);
267
268 \draw[pattern={vertical lines},pattern color=orange]
269 (1,0) rectangle +(1,1);
270 \draw[pattern={Lines[angle=90,yshift=-.5pt]},pattern color=blue]
271 (1,0) rectangle +(1,1);
272
273 \draw[pattern={north east lines},pattern color=orange]
274 (0,1) rectangle +(1,1);
275 \draw[pattern={Lines[angle=45,distance={3pt/sqrt(2)}]},pattern color=blue]
276 (0,1) rectangle +(1,1);
277
278 \draw[pattern={north west lines},pattern color=orange]
279 (1,1) rectangle +(1,1);
280 \draw[pattern={Lines[angle=-45,distance={3pt/sqrt(2)}]},pattern color=blue]
281 (1,1) rectangle +(1,1);
282 \end{tikzpicture}
283 \end{codeexample}
284 %
285 \end{pattern}
286
287 \begin{pattern}{Hatch}
288 The |Hatch| pattern replaces the |grid| and |crosshatch| patterns.
289 The |Hatch| pattern without options is a drop-in replacement for the
290 |grid| pattern.
291 %
292 \begin{key}{/pgf/pattern keys/distance (initially 3pt)}
293 Distance between crosses.
294 \end{key}
295 %
296 \begin{key}{/pgf/pattern keys/angle (initially 0)}
297 By default the lines are horizontal and vertical. The whole pattern is
298 rotated by this angle. The rotation angle is measured in the
299 mathematically positive sense.
300 \end{key}
301 %
302 \begin{key}{/pgf/pattern keys/xshift (initially 0pt)}
303 Shifts the whole pattern in $x$-direction (before applying the
304 rotation).
305 \end{key}
306 %
307 \begin{key}{/pgf/pattern keys/yshift (initially 0pt)}
308 Shifts the whole pattern in $y$-direction (before applying the
309 rotation).
310 \end{key}
311 %
312 \begin{key}{/pgf/pattern keys/line width (initially \string\the\string\pgflinewidth)}
313 Thickness of the lines.
314 \end{key}
315 %
316 The following settings can be used to reproduce the |grid| and
317 |crosshatch| patterns.
318 %
319 \begin{codeexample}[preamble={\usetikzlibrary{patterns,patterns.meta}}]
320 \begin{tikzpicture}
321 \draw[pattern={grid},pattern color=orange]
322 (0,0) rectangle +(1,1);
323 \draw[pattern={Hatch},pattern color=blue]
324 (0,0) rectangle +(1,1);
325
326 \draw[pattern={crosshatch},pattern color=orange]
327 (1,0) rectangle +(1,1);
328 \draw[pattern={Hatch[angle=45,distance={3pt/sqrt(2)},xshift=.1pt]},
329 pattern color=blue] (1,0) rectangle +(1,1);
330 \end{tikzpicture}
331 \end{codeexample}
332 %
333 \end{pattern}
334
335 \begin{pattern}{Dots}
336 The |Dots| pattern replaces the |dots| and |crosshatch dots| patterns. The
337 |Dots| pattern without options is a drop-in replacement for the |dots|
338 pattern.
339 %
340 \begin{key}{/pgf/pattern keys/distance (initially 3pt)}
341 Distance between dots.
342 \end{key}
343 %
344 \begin{key}{/pgf/pattern keys/angle (initially 0)}
345 By default the lines are arranged on a regular grid. The whole pattern
346 is rotated by this angle. The rotation angle is measured in the
347 mathematically positive sense.
348 \end{key}
349 %
350 \begin{key}{/pgf/pattern keys/xshift (initially 0pt)}
351 Shifts the whole pattern in $x$-direction (before applying the
352 rotation).
353 \end{key}
354 %
355 \begin{key}{/pgf/pattern keys/yshift (initially 0pt)}
356 Shifts the whole pattern in $y$-direction (before applying the
357 rotation).
358 \end{key}
359 %
360 \begin{key}{/pgf/pattern keys/radius (initially 0.5pt)}
361 Radius of the dots.
362 \end{key}
363 %
364 The following settings can be used to reproduce the |dots| and
365 |crosshatch dots| patterns.
366 %
367 \begin{codeexample}[preamble={\usetikzlibrary{patterns,patterns.meta}}]
368 \begin{tikzpicture}
369 \draw[pattern={dots},pattern color=orange]
370 (0,0) rectangle +(1,1);
371 \draw[pattern={Dots},pattern color=blue]
372 (0,0) rectangle +(1,1);
373
374 \draw[pattern={crosshatch dots},pattern color=orange]
375 (1,0) rectangle +(1,1);
376 \draw[pattern={Dots[angle=45,distance={3pt/sqrt(2)}]},
377 pattern color=blue] (1,0) rectangle +(1,1);
378 \end{tikzpicture}
379 \end{codeexample}
380 %
381 \end{pattern}
382
383 \begin{pattern}{Stars}
384 The |Stars| pattern replaces the |fivepointed stars| and |sixpointed stars|
385 patterns. However, the stars of the |Stars| pattern are constructed in a
386 fundamentally different fashion, so it can't be used as a drop-in
387 replacement.
388 %
389 \begin{key}{/pgf/pattern keys/distance (initially 3mm)}
390 Distance between stars.
391 \end{key}
392 %
393 \begin{key}{/pgf/pattern keys/angle (initially 0)}
394 By default the stars are arranged on a regular grid. The whole pattern
395 is rotated by this angle. The rotation angle is measured in the
396 mathematically positive sense.
397 \end{key}
398 %
399 \begin{key}{/pgf/pattern keys/xshift (initially 0pt)}
400 Shifts the whole pattern in $x$-direction (before applying the
401 rotation).
402 \end{key}
403 %
404 \begin{key}{/pgf/pattern keys/yshift (initially 0pt)}
405 Shifts the whole pattern in $y$-direction (before applying the
406 rotation).
407 \end{key}
408 %
409 \begin{key}{/pgf/pattern keys/radius (initially 1mm)}
410 Outer radius of the enclosing circle of the stars.
411 \end{key}
412 %
413 \begin{key}{/pgf/pattern keys/points (initially 5)}
414 Number of pointy ends of the stars.
415 \end{key}
416 %
417 \begin{codeexample}[preamble={\usetikzlibrary{patterns,patterns.meta}}]
418 \begin{tikzpicture}
419 \draw[pattern={fivepointed stars},pattern color=orange]
420 (0,0) rectangle +(1,1);
421 \draw[pattern={Stars},pattern color=blue]
422 (0,0) rectangle +(1,1);
423
424 \draw[pattern={sixpointed stars},pattern color=orange]
425 (1,0) rectangle +(1,1);
426 \draw[pattern={Stars[points=6]},pattern color=blue]
427 (1,0) rectangle +(1,1);
428 \end{tikzpicture}
429 \end{codeexample}
430 %
431 \end{pattern}
432
433
434 \begin{command}{\tikzdeclarepattern\marg{config}}
435 A pattern declared with |\pgfdeclarepattern| can only execute \pgfname\
436 code. This command extends the functionality to also allow \tikzname\
437 code. All the same keys of |\pgfdeclarepattern| are valid, but some of
438 them have been overloaded to give a more natural \tikzname\ syntax.
439 %
440 \begin{key}{/tikz/patterns/bottom left=\meta{point}}
441 Instead of a \pgfname\ name point, this key takes a \tikzname\ point,
442 e.g.\ |(-.1,-.1)|.
443 \end{key}
444 %
445 \begin{key}{/tikz/patterns/top right=\meta{point}}
446 Instead of a \pgfname\ name point, this key takes a \tikzname\ point,
447 e.g.\ |(3.1,3.1)|.
448 \end{key}
449 %
450 \begin{key}{/tikz/patterns/tile size=\meta{point}}
451 Instead of a \pgfname\ name point, this key takes a \tikzname\ point,
452 e.g.\ |(3,3)|.
453 \end{key}
454 %
455 \begin{key}{/tikz/patterns/tile transformation=\meta{transformation}}
456 Instead of a \pgfname\ transformation, this key takes a list of keys
457 and value and extracts the resulting transformation from them, e.g.\
458 |rotate=30|.
459 \end{key}
460
461 In addition to the overloaded keys, some new keys have been added.
462 %
463 \begin{key}{/tikz/patterns/bounding box=\meta{point} and \meta{point}}
464 This is a shorthand to set the bounding box. It will assign the first
465 point to |bottom left| and the second point to |top right|.
466 \end{key}
467 %
468 \begin{key}{/tikz/patterns/infer tile bounding box=\meta{dimension} (default 0pt)}
469 Instead of specifying the bounding box by hand, you can ask \tikzname\
470 to infer the size of the bounding box for you. The \meta{dimension}
471 parameter is padding that is added around the bounding box.
472 \end{key}
473 \end{command}
474
475 \begin{codeexample}[preamble={\usetikzlibrary{patterns.meta}}]
476 \tikzdeclarepattern{
477 name=flower,
478 type=colored,
479 bottom left={(-.1pt,-.1pt)},
480 top right={(10.1pt,10.1pt)},
481 tile size={(10pt,10pt)},
482 code={
483 \tikzset{x=1pt,y=1pt}
484 \path [draw=green] (5,2.5) -- (5, 7.5);
485 \foreach \i in {0,60,...,300}
486 \path [fill=pink, shift={(5,7.5)}, rotate=-\i]
487 (0,0) .. controls ++(120:4) and ++(60:4) .. (0,0);
488 \path [fill=red] (5,7.5) circle [radius=1];
489 \foreach \i in {-45,45}
490 \path [fill=green, shift={(5,2.5)}, rotate=-\i]
491 (0,0) .. controls ++(120:4) and ++(60:4) .. (0,0);
492 }
493 }
494
495 \tikz\draw [pattern=flower] circle [radius=1];
496 \end{codeexample}
497
498 \begin{codeexample}[preamble={\usetikzlibrary{patterns.meta}}]
499 \tikzdeclarepattern{
500 name=mystars,
501 type=uncolored,
502 bounding box={(-5pt,-5pt) and (5pt,5pt)},
503 tile size={(\tikztilesize,\tikztilesize)},
504 parameters={\tikzstarpoints,\tikzstarradius,\tikzstarrotate,\tikztilesize},
505 tile transformation={rotate=\tikzstarrotate},
506 defaults={
507 points/.store in=\tikzstarpoints,points=5,
508 radius/.store in=\tikzstarradius,radius=3pt,
509 rotate/.store in=\tikzstarrotate,rotate=0,
510 tile size/.store in=\tikztilesize,tile size=10pt,
511 },
512 code={
513 \pgfmathparse{180/\tikzstarpoints}\let\a=\pgfmathresult
514 \fill (90:\tikzstarradius) \foreach \i in {1,...,\tikzstarpoints}{
515 -- (90+2*\i*\a-\a:\tikzstarradius/2) -- (90+2*\i*\a:\tikzstarradius)
516 } -- cycle;
517 }
518 }
519
520 \begin{tikzpicture}
521 \draw[pattern=mystars,pattern color=blue] (0,0) rectangle +(2,2);
522 \draw[pattern={mystars[points=7,tile size=15pt]}] (2,0) rectangle +(2,2);
523 \draw[pattern={mystars[rotate=45]},pattern color=red] (0,2) rectangle +(2,2);
524 \draw[pattern={mystars[rotate=30,points=4,radius=5pt]}] (2,2) rectangle +(2,2);
525 \end{tikzpicture}
526 \end{codeexample}
527
528 Instead of macros you can also use \pgfname\ keys as parameters, if that is
529 what you prefer.
530 %
531 \begin{codeexample}[preamble={\usetikzlibrary{patterns.meta}}]
532 \tikzdeclarepattern{
533 name=mylines,
534 parameters={
535 \pgfkeysvalueof{/pgf/pattern keys/size},
536 \pgfkeysvalueof{/pgf/pattern keys/angle},
537 \pgfkeysvalueof{/pgf/pattern keys/line width},
538 },
539 bounding box={
540 (0,-0.5*\pgfkeysvalueof{/pgf/pattern keys/line width}) and
541 (\pgfkeysvalueof{/pgf/pattern keys/size},
542 0.5*\pgfkeysvalueof{/pgf/pattern keys/line width})},
543 tile size={(\pgfkeysvalueof{/pgf/pattern keys/size},
544 \pgfkeysvalueof{/pgf/pattern keys/size})},
545 tile transformation={rotate=\pgfkeysvalueof{/pgf/pattern keys/angle}},
546 defaults={
547 size/.initial=5pt,
548 angle/.initial=45,
549 line width/.initial=.4pt,
550 },
551 code={
552 \draw [line width=\pgfkeysvalueof{/pgf/pattern keys/line width}]
553 (0,0) -- (\pgfkeysvalueof{/pgf/pattern keys/size},0);
554 },
555 }
556
557 \begin{tikzpicture}
558 \draw[pattern={mylines[size=10pt,line width=.8pt,angle=10]},
559 pattern color=red] (0,0) rectangle ++(2,2);
560 \draw[pattern={mylines[size= 5pt,line width=.8pt,angle=40]},
561 pattern color=blue] (2,0) rectangle ++(2,2);
562 \draw[pattern={mylines[size=10pt,line width=.4pt,angle=90]},
563 pattern color=green] (0,2) rectangle ++(2,2);
564 \draw[pattern={mylines[size= 2pt,line width= 1pt,angle=70]},
565 pattern color=orange] (2,2) rectangle ++(2,2);
566 \end{tikzpicture}
567 \end{codeexample}
568
569 %%% Local Variables:
570 %%% mode: latex
571 %%% TeX-master: "pgfmanual-pdftex-version"
572 %%% End: