Debian Codegraph @

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

raw
1 % Copyright 2019 by Mark Wibrow
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 Public License.
7 %
8 % See the file doc/generic/pgf/licenses/LICENSE for more details.
9
10
11 \section{Lindenmayer System Drawing Library}
12
13 \subsection{Overview}
14
15 Lindenmayer systems (also commonly known as ``L-systems''), were originally
16 developed by Aristid Lindenmayer as a theory of algae growth patterns and then
17 subsequently used to model branching patterns in plants and produce fractal
18 patterns. Typically, an L-system consists of a set of symbols, each of which is
19 associated with some graphical action (such as ``turn left'' or ``move
20 forward'') and a set of rules (``production'' or ``rewrite'' rules). Given a
21 string of symbols, the rewrite rules are applied several times and when the
22 resulting string is processed the action associated with each symbol is
23 executed.
24
25 In \pgfname, L-systems can be used to create simple 2-dimensional fractal
26 patterns\ldots
27 %
28 \begin{codeexample}[
29 preamble={\usetikzlibrary{lindenmayersystems}},
30 pre={\expandafter\let\csname pgf@lsystem@Koch curve\endcsname=\relax},
31 ]
32 \begin{tikzpicture}
33 \pgfdeclarelindenmayersystem{Koch curve}{
34 \rule{F -> F-F++F-F}
35 }
36
37 \shadedraw [top color=white, bottom color=blue!50, draw=blue!50!black]
38 [l-system={Koch curve, step=2pt, angle=60, axiom=F++F++F, order=3}]
39 lindenmayer system -- cycle;
40 \end{tikzpicture}
41 \end{codeexample}
42 %
43 \noindent\ldots and ``plant like'' patterns\ldots
44 %
45 \begin{codeexample}[preamble={\usetikzlibrary{lindenmayersystems}}]
46 \begin{tikzpicture}
47 \draw [green!50!black, rotate=90]
48 [l-system={rule set={F -> FF-[-F+F]+[+F-F]}, axiom=F, order=4, step=2pt,
49 randomize step percent=25, angle=30, randomize angle percent=5}]
50 lindenmayer system;
51 \end{tikzpicture}
52 \end{codeexample}
53 %
54 \noindent \ldots but it is important to bear in mind that even moderately
55 complex L-systems can exceed the available memory of \TeX, and can be very
56 slow. If possible, you are advised to increase the main memory and save stack
57 to their maximum possible values for your particular \TeX{} distribution.
58 However, even by doing this you may find you still run out of memory quite
59 quickly.
60
61 For an excellent introduction to L-systems (containing some ``really cool''
62 pictures -- many of which are sadly not possible in \pgfname) see \emph{The
63 Algorithmic Beauty of Plants} by Przemyslaw Prusinkiewicz and Aristid
64 Lindenmayer (which is freely available via the internet).
65
66 \begin{pgflibrary}{lindenmayersystems}
67 This \pgfname-library provides basic commands for defining and using simple
68 L-systems. The \tikzname-library provides, furthermore, a front end for
69 using L-systems in \tikzname.
70 \end{pgflibrary}
71
72
73 \subsubsection{Declaring L-systems}
74
75 Before an L-system can be used, it must be declared using the following
76 command:
77
78 \begin{command}{\pgfdeclarelindenmayersystem\marg{name}\marg{specification}}
79 This command declares a Lindenmayer system called \meta{name}. The
80 \meta{specification} argument contains a description of the L-system's
81 symbols and rules. Two commands |\symbol| and |\rule| are only defined when
82 the \meta{specification} argument is executed.
83
84 \begin{command}{\symbol\marg{name}\marg{code}}
85 This defines a symbol called \meta{name} for a specific L-system,
86 and associates it with \meta{code}.
87
88 A symbol should consist of a single alpha-numeric character (i.e.,
89 |A|-|Z|, |a|-|z| or |0|-|9|). The symbols |F|, |f|, |+|, |-|, |[| and
90 |]| are available by default so do not need to be defined for each
91 L-system. However, if you are feeling adventurous, they can be
92 redefined for specific L-systems if required. The L-system treats the
93 default symbols as follows (the commands they execute are described
94 below):
95 %
96 \begin{itemize}
97 \item |F| move forward a certain distance, drawing a line. Uses
98 |\pgflsystemdrawforward|.
99 \item |f| move forward a certain distance, without drawing a line.
100 Uses |\pgflsystemmoveforward|.
101 \item |+| turn left by some angle. Uses |\pgflsystemturnleft|.
102 \item |-| turn right by some angle. Uses |\pgflsystemturnright|.
103 \item |[| save the current state (i.e., the position and
104 direction). Uses |\pgflsystemsavestate|.
105 \item |]| restore the last saved state. Uses
106 |\pgflsystemrestorestate|.
107 \end{itemize}
108
109 The symbols |[| and |]| act like a stack: |[| pushes the state of the
110 L-system on to the stack, and |]| pops a state off the stack.
111
112 When \meta{code} is executed, the transformation matrix is set up so
113 that the origin is at the current position and the positive x-axis
114 ``points forward'', so |\pgfpathlineto{\pgfpoint{1cm}{0cm}}| draws a
115 line 1cm forward.
116
117 The following keys can alter the production of an L-system. However,
118 they do not store values in themselves.
119
120 \begin{key}{/pgf/lindenmayer system/step=\meta{length} (initially 5pt)}
121 How far the L-system moves forward if required. This key sets the
122 \TeX{} dimension |\pgflsystemstep|.
123 \end{key}
124
125 \begin{key}{/pgf/lindenmayer system/randomize step percent=\meta{percentage} (initially 0)}
126 If the step is to be randomized, this key specifies by how much.
127 The value is stored in the \TeX{} macro
128 |\pgflsystemrandomizesteppercent|.
129 \end{key}
130
131 \begin{key}{/pgf/lindenmayer system/left angle=\meta{angle} (initially 90)}
132 This key sets the angle through which the L-system turns when it
133 turns left. The value is stored in the \TeX{} macro
134 |\pgflsystemrleftangle|.
135 \end{key}
136
137 \begin{key}{/pgf/lindenmayer system/right angle=\meta{angle} (initially 90)}
138 This key sets the angle through which the L-system turns when it
139 turns right. The value is stored in the \TeX{} macro
140 |\pgflsystemrrightangle|.
141 \end{key}
142
143 \begin{key}{/pgf/lindenmayer system/randomize angle percent=\meta{percentage} (initially 0)}
144 If the angles are to be randomized, this key specifies by how much.
145 The value is stored in the \TeX{} macro
146 |\pgflsystemrandomizeanglepercent|.
147 \end{key}
148
149 For speed and convenience, when the code for a symbol is executed, the
150 following commands are available.
151
152 \begin{command}{\pgflsystemcurrentstep}
153 The current ``step'' of the L-system (i.e., how far the system
154 will move forward if required). This is initially set to the
155 value in the \TeX-dimensions |\pgflsystemstep|, but the actual
156 value may be changed if |\pgflsystemrandomizestep| is used
157 (see below).
158 \end{command}
159
160 \begin{command}{\pgflsystemcurrentleftangle}
161 The angle the L-system will turn when it turns left.
162 The value stored in this macro may be changed if
163 |\pgflsystemrandomizeleftangle| is used.
164 \end{command}
165
166 \begin{command}{\pgflsystemcurrentrightangle}
167 The angle the L-system will turn when it turns right.
168 The value stored in this macro may be changed if
169 |\pgflsystemrandomizerightangle| is used.
170 \end{command}
171
172 The following commands may be useful if you wish to define your own
173 symbols.
174
175 \begin{command}{\pgflsystemrandomizestep}
176 Randomizes the value in |\pgflsystemcurrentstep| according to the
177 current value of the key |randomize step percent|.
178 \end{command}
179
180 \begin{command}{\pgflsystemrandomizeleftangle}
181 Randomizes the value in |\pgflsystemcurrentleftangle| according to
182 the value of the |randomize angle percent| key.
183 \end{command}
184
185 \begin{command}{\pgflsystemrandomizerightangle}
186 Randomizes the value in |\pgflsystemcurrentrightangle| according
187 to the value of the |randomize angle| key.
188 \end{command}
189
190 \begin{command}{\pgflsystemdrawforward}
191 Move forward in the current direction, by |\pgflsystemcurrentstep|,
192 drawing a line in the process. This macro calls
193 |\pgflsystemrandomizestep|. Internally, \pgfname{} simply shifts
194 the transformation matrix in the positive direction of the current
195 (transformed) x-axis by |\pgflsystemstep| and then executes a
196 line-to to the (newly transformed) origin.
197 \end{command}
198
199 \begin{command}{\pgflsystemmoveforward}
200 Move forward in the current direction, by |\pgflsystemcurrentstep|,
201 without drawing a line. This macro calls
202 |\pgflsystemrandomizestep|. \pgfname{} executes a transformation as
203 above, but executes a move-to to the (newly transformed) origin.
204 \end{command}
205
206 \begin{command}{\pgflsystemturnleft}
207 Turn left by |\pgflsystemcurrentleftangle|. Internally, \pgfname{}
208 simply rotates the transformation matrix. This macro calls
209 |\pgflsystemrandomizeleftangle|.
210 \end{command}
211
212 \begin{command}{\pgflsystemturnright}
213 Turn right by |\pgflsystemcurrentrightangle|. Internally,
214 \pgfname{} simply rotates the transformation matrix. This macro
215 calls |\pgflsystemrandomizerightangle|.
216 \end{command}
217
218 \begin{command}{\pgflsystemsavestate}
219 Save the current position and orientation. Internally, \pgfname{}
220 simply starts a new \TeX-group.
221 \end{command}
222
223 \begin{command}{\pgflsystemrestorestate}
224 Restore the last saved position and orientation. Internally,
225 \pgfname{} closes a \TeX-group, restoring the transformation matrix
226 of the outer scope, and a move-to command is executed to the
227 (transformed) origin.
228 \end{command}
229 \end{command}
230
231 \begin{command}{\rule{\ttfamily\char`\{}\meta{head}{\ttfamily->}\meta{body}{\ttfamily\char`\}}}
232 Declare a rule. \meta{head} should consist of a single symbol, which
233 need not have been declared using |\symbol| or exist as a default
234 symbol (in fact, the more interesting L-systems depend on using symbols
235 with no corresponding code, to control the ``growth'' of the system).
236 \meta{body} consists of a string of symbols, which again need not
237 necessarily have any code associated with them.
238 \end{command}
239
240 As an example, the following shows an L-system that uses some of these
241 commands. This example illustrates the point that some symbols, in this
242 case |A| and |B|, do not have to have code associated with them. They
243 simply control the growth of the system.
244 %
245 \begin{codeexample}[
246 preamble={\usetikzlibrary{lindenmayersystems}},
247 pre={\nullfont\expandafter\let\csname pgf@lsystem@Hilbert curve\endcsname=\relax},
248 ]
249 \pgfdeclarelindenmayersystem{Hilbert curve}{
250 \symbol{X}{\pgflsystemdrawforward}
251 \symbol{+}{\pgflsystemturnright} % Explicitly define + and - symbols.
252 \symbol{-}{\pgflsystemturnleft}
253 \rule{A -> +BX-AXA-XB+}
254 \rule{B -> -AX+BXB+XA-}
255 }
256 \tikz\draw[lindenmayer system={Hilbert curve, axiom=A, order=4, angle=90}]
257 lindenmayer system;
258 \end{codeexample}
259 %
260 \end{command}
261
262
263 \subsection{Using Lindenmayer Systems}
264
265 \subsubsection{Using L-Systems in PGF}
266
267 The following command is used to run an L-system in \pgfname:
268 %
269 \begin{command}{\pgflindenmayersystem\marg{name}\marg{axiom}\marg{order}}
270 Runs the L-system called \meta{name} using the input string \meta{axiom}
271 for \meta{order} iterations. In general, prior to calling this command, the
272 transformation matrix should be set appropriately for shifting and
273 rotating, and a move-to to the (transformed) origin should be executed.
274 This origin will be where the L-system starts. In addition, the relevant
275 keys should be set appropriately.
276 %
277 \begin{codeexample}[preamble={\usetikzlibrary{lindenmayersystems}}]
278 \begin{tikzpicture}
279 \draw [help lines] grid (3,2);
280 \pgfset{lindenmayer system/.cd, angle=60, step=2pt}
281 \foreach \x/\y in {0cm/1cm, 1.5cm/1.5cm, 2.5cm/0.5cm, 1cm/0cm}{
282 \pgftransformshift{\pgfqpoint{\x}{\y}}
283 \pgfpathmoveto{\pgfpointorigin}
284 \pgflindenmayersystem{Koch curve}{F++F++F}{2}
285 \pgfusepath{stroke}
286 }
287 \end{tikzpicture}
288 \end{codeexample}
289
290 Note that it is perfectly feasible for an L-system to define special
291 symbols which perform the move-to and use-path operations.
292 %
293 \end{command}
294
295
296 \subsubsection{Using L-Systems in Ti\emph{k}Z}
297
298 In \tikzname, an L-system is created using a path operation. However,
299 \tikzname{} is more flexible regarding the positioning of the L-system and also
300 provides keys to create L-systems ``on-line''.
301
302 \begin{pathoperation}{lindenmayer system}{ \opt{|[|\meta{keys}|]|}}
303 This will run an L-system according to the parameters specified in
304 \meta{keys} (which can also contain normal \tikz{} keys such as |draw| or
305 |thin|). The syntax is flexible regarding the L-system parameters and the
306 following all do the same thing:
307 %
308 \begin{codeexample}[code only]
309 \draw lindenmayer system [lindenmayer system={Hilbert curve, axiom=4, order=3}];
310 \end{codeexample}
311
312 \begin{codeexample}[code only]
313 \draw [lindenmayer system={Hilbert curve, axiom=4, order=3}] lindenmayer system;
314 \end{codeexample}
315
316 \begin{codeexample}[code only]
317 \tikzset{lindenmayer system={Hilbert curve, axiom=4, order=3}}
318 \draw lindenmayer system;
319 \end{codeexample}
320 %
321 \end{pathoperation}
322
323 \begin{pathoperation}{l-system}{ \opt{|[|\meta{keys}|]|}}
324 A more compact version of the |lindenmayer system| path command.
325 \end{pathoperation}
326
327 This library adds some additional keys for specifying L-systems. These keys
328 only work in \tikzname{} and all have the same path, namely, |/pgf/lindenmayer|
329 |system|, but the following keys are provided for convenience, so that you do
330 not have to keep repeating this path:
331
332 \begin{stylekey}{/pgf/lindenmayer system=\marg{keys}}
333 \keyalias{tikz}
334 This key changes the key path to |/pgf/lindenmayer systems| and executes
335 \meta{keys}.
336 \end{stylekey}
337
338 \begin{stylekey}{/pgf/l-system=\marg{keys}}
339 \keyalias{tikz}
340 A more compact version of the previous key.
341 \end{stylekey}
342
343 \begin{key}{/pgf/lindenmayer system/name=\marg{name}}
344 Sets the name for the L-system.
345 \end{key}
346
347 \begin{key}{/pgf/lindenmayer system/axiom=\marg{string}}
348 Sets the axiom (or input string) for the L-system.
349 \end{key}
350
351 \begin{key}{/pgf/lindenmayer system/order=\marg{integer}}
352 Sets the number of iterations the L-system will perform.
353 \end{key}
354
355 \begin{key}{/pgf/lindenmayer system/rule set=\marg{list}}
356 This key allows an (anonymous) L-system to be declared ``on-line''. There
357 is, however, a restriction that only the default symbols can be used for
358 drawing (empty symbols can still be used to control the growth of the
359 system). The rules in \meta{list} should be separated by commas.
360 %
361 \begin{codeexample}[preamble={\usetikzlibrary{lindenmayersystems}}]
362 \tikz[rotate=65]\draw [green!60!black] l-system
363 [l-system={rule set={F -> F[+F]F[-F]}, axiom=F, order=4, angle=25,step=3pt}];
364 \end{codeexample}
365 %
366 \end{key}
367
368 \begin{key}{/pgf/lindenmayer system/anchor=\meta{anchor}}
369 Be default, when this key is not used, the L-system will start from the
370 last specified coordinate. By using this key, the L-system will be placed
371 inside a special (rectangle) node which can be positioned using
372 \meta{anchor}.
373 %
374 \begin{codeexample}[preamble={\usetikzlibrary{lindenmayersystems}}]
375 \begin{tikzpicture}[l-system={step=1.75pt, order=5, angle=60}]
376 \pgfdeclarelindenmayersystem{Sierpinski triangle}{
377 \symbol{X}{\pgflsystemdrawforward}
378 \symbol{Y}{\pgflsystemdrawforward}
379 \rule{X -> Y-X-Y}
380 \rule{Y -> X+Y+X}
381 }
382 \draw [help lines] grid (3,2);
383 \draw [red] (0,0) l-system
384 [l-system={Sierpinski triangle, axiom=+++X, anchor=south west}];
385 \draw [blue] (3,2) l-system
386 [l-system={Sierpinski triangle, axiom=X, anchor=north east}];
387 \end{tikzpicture}
388 \end{codeexample}
389 %
390 \end{key}