1
2
3\startcomponent metafunwelcome
4
5\environment metafunenvironment
6
7\startchapter[reference=sec:welcome,title={Welcome to MetaPost}]
8
9\startintro
10
11In this chapter, we will introduce the most important \METAPOST\ concepts as well
12as demonstrate some drawing primitives and operators. This chapter does not
13replace the \METAFONT\ book or \METAPOST\ manual, both of which provide a lot of
14explanations, examples, and (dirty) tricks.
15
16As its title says, the \METAFONT\ book by Donald.\ E.\ Knuth is about fonts.
17Nevertheless, buying a copy is worth the money, because as a \METAPOST\ user you
18can benefit from the excellent chapters about curves, algebraic expressions, and
19(linear) equations. The following sections are incomplete in many aspects. More
20details on how to define your own macros can be found in both the \METAFONT\ book
21and \METAPOST\ manual, but you will probably only appreciate the nasty details if
22you have written a few simple figures yourself. This chapter will give you a
23start.
24
25A whole section is dedicated to the basic extensions to \METAPOST\ as provided by
26\METAFUN. Most of them are meant to make defining graphics like those shown in
27this document more convenient.
28
29Many of the concepts introduced here will be discussed in more detail in later
30chapters. So, you may consider this chapter to be an appetizer for the following
31chapters. If you want to get started quickly, you can safely skip this chapter
32now.
33
34\stopintro
35
36\startsection[title={Paths}]
37
38\index{paths}
39
40Paths are the building blocks of \METAPOST\ graphics. In its simplest form, a
41path is a single point.
42
43\startuseMPgraphic{axis}
44 tickstep := 1cm ; ticklength := 2mm ;
45 drawticks unitsquare xscaled 4cm yscaled 3cm shifted (-1cm,-1cm) ;
46 tickstep := tickstep2 ; ticklength := ticklength2 ;
47 drawticks unitsquare xscaled 4cm yscaled 3cm shifted (-1cm,-1cm) ;
48\stopuseMPgraphic
49
50\startlinecorrection[blank]
51\startMPcode
52 \includeMPgraphic{axis}
53 drawpoint "1cm,1.5cm" ;
54\stopMPcode
55\stoplinecorrection
56
57Such a point is identified by two numbers, which represent the horizontal and
58vertical position, often referred to as $x$ and $y$, or $(x,y)$. Because there
59are two numbers involved, in \METAPOST\ this point is called a pair. Its related
60datatype is therefore \type {pair}. The following statements assigns the point we
61showed previously to a pair variable.
62
63\starttyping
64pair somepoint ; somepoint := (1cm,1.5cm) ;
65\stoptyping
66
67A pair can be used to identify a point in the two dimensional coordinate space,
68but it can also be used to denote a vector (being a direction or displacement).
69For instance, \type {(0,1)} means \quote {go up}. Looking through math glasses,
70you may consider them vectors, and if you know how to deal with them, \METAPOST\
71may be your friend, since it knows how to manipulate them.
72
73You can connect points and the result is called a path. A path is a straight or
74bent line, and is not necessarily a smooth curve. An example of a simple
75rectangular path is: \footnote {In the next examples we use the debugging
76features discussed in \in {chapter} [sec:debugging] to visualize the points,
77paths and bounding boxes.}
78
79\startuseMPgraphic{path}
80 path p ;
81 p := unitsquare xyscaled (2cm,1cm) shifted (.5cm,.5cm) ;
82\stopuseMPgraphic
83
84\startlinecorrection[blank]
85\startMPcode
86 \includeMPgraphic{axis}
87 \includeMPgraphic{path}
88 drawpath p ;
89\stopMPcode
90\stoplinecorrection
91
92This path is constructed out of four points:
93
94\startlinecorrection[blank]
95\startMPcode
96 \includeMPgraphic{axis}
97 \includeMPgraphic{path}
98 swappointlabels := true ; drawpath p ; drawpoints p ;
99\stopMPcode
100\stoplinecorrection
101
102Such a path has both a beginning and end and runs in a certain direction:
103
104\startlinecorrection[blank]
105\startMPcode
106 \includeMPgraphic{axis}
107 \includeMPgraphic{path}
108 autoarrows := true ;
109 swappointlabels := true ; drawarrowpath p ; drawpoints p ;
110\stopMPcode
111\stoplinecorrection
112
113A path can be open or closed. The previous path is an example of a closed path.
114An open path looks like this:
115
116\startuseMPgraphic{path}
117 path p ; p := (1cm,1cm)..(1.5cm,1.5cm)..(2cm,0cm) ;
118\stopuseMPgraphic
119
120\startlinecorrection[blank]
121\startMPcode
122 \includeMPgraphic{axis}
123 \includeMPgraphic{path}
124 swappointlabels := true ; drawpath p ; drawpoints p ;
125\stopMPcode
126\stoplinecorrection
127
128When we close this path <and in a moment we will see how to do this> the path
129looks like:
130
131\startbuffer
132\startlinecorrection[blank]
133\startMPcode
134 \includeMPgraphic{axis}
135 \includeMPgraphic{path}
136 p := p .. cycle ;
137 swappointlabels := true ; drawpath p ; drawpoints p ;
138\stopMPcode
139\stoplinecorrection
140\stopbuffer
141
142\getbuffer
143
144The open path is defined as:
145
146\starttyping
147(1cm,1cm)..(1.5cm,1.5cm)..(2cm,0cm)
148\stoptyping
149
150The \quote {double period} connector \type {..} tells \METAPOST\ that we want to
151connect the lines by a smooth curve. If you want to connect points with straight
152line segments, you should use \type {}.
153
154Closing the path is done by connecting the first and last point, using the \type
155{cycle} command.
156
157\starttyping
158(1cm,1cm)..(1.5cm,1.5cm)..(2cm,0cm)..cycle
159\stoptyping
160
161Feel free to use \type {..} or \type {} at any point in your path.
162
163\starttyping
164(1cm,1cm)(1.5cm,1.5cm)..(2cm,0cm)..cycle
165\stoptyping
166
167\startuseMPgraphic{path}
168path p ; p := (1cm,1cm)--(1.5cm,1.5cm)..(2cm,0cm)..cycle ;
169\stopuseMPgraphic
170
171This path, when drawn, looks like this:
172
173\getbuffer
174
175As you can see in some of the previous examples, \METAPOST\ is capable of drawing
176a smooth curve through the three points that make up the path. We will now
177examine how this is done.
178
179\startlinecorrection[blank]
180\startMPcode
181 \includeMPgraphic{axis}
182 \includeMPgraphic{path}
183 p := p .. cycle ; swappointlabels := true ;
184 drawpath p ; drawcontrollines p ; drawpoints p ; drawcontrolpoints p ;
185\stopMPcode
186\stoplinecorrection
187
188The six small points are the so called control points. These points pull their
189parent point in a certain direction. The further away such a point is, the
190stronger the pull.
191
192Each point has at most two control points. As you can see in the following
193graphic, the endpoints of a non closed curve have only one control point.
194
195\startuseMPgraphic{path}
196path p ; p := (1.5cm,1.5cm)..(2cm,0cm)..(1cm,1cm) ;
197\stopuseMPgraphic
198
199\startbuffer[path]
200\startlinecorrection[blank]
201\startMPcode
202 \includeMPgraphic{axis}
203 \includeMPgraphic{path}
204 swappointlabels := true ;
205 drawpath p ; drawcontrollines p ; drawpoints p ; drawcontrolpoints p ;
206\stopMPcode
207\stoplinecorrection
208\stopbuffer
209
210\getbuffer[path]
211
212This time we used the path:
213
214\starttyping
215(1.5cm,1.5cm)..(2cm,0cm)..(1cm,1cm)
216\stoptyping
217
218When you connect points by a smooth curve, \METAPOST\ will calculate the control
219points itself, unless you specify one or more of them.
220
221\startuseMPgraphic{path}
222 path p ; p := (1cm,1cm)..(1.5cm,1.5cm)..controls (3cm,2cm)..(2cm,0cm) ;
223\stopuseMPgraphic
224
225\getbuffer[path]
226
227This path is specified as:
228
229\starttyping
230(1cm,1cm)..(1.5cm,1.5cm)..controls (3cm,2cm)..(2cm,0cm)
231\stoptyping
232
233In this path, the second and third point share a control point. Watch how the
234curve is pulled in that direction. It is possible to pull a bit less by choosing
235a different control point:
236
237\starttyping
238(1cm,1cm)..(1.5cm,1.5cm)..controls (2.75cm,1.25cm)..(2cm,0cm)
239\stoptyping
240
241Now we get:
242
243\startuseMPgraphic{path}
244 path p ; p := (1cm,1cm)..(1.5cm,1.5cm)..controls (2.75cm,1.25cm)..(2cm,0cm) ;
245\stopuseMPgraphic
246
247\getbuffer[path]
248
249We can also specify a different control point for each connecting segment.
250
251\startuseMPgraphic{path}
252 path p ; p := (1cm,1cm)..controls (.5cm,2cm) and (2.5cm,2cm)..(2cm,.5cm) ;
253\stopuseMPgraphic
254
255\getbuffer[path]
256
257This path is defined as:
258
259\starttyping
260(1cm,1cm)..controls (.5cm,2cm) and (2.5cm,2cm)..(2cm,.5cm)
261\stoptyping
262
263\stopsection
264
265\startsection[title={Transformations}]
266
267\index{transformations}
268
269We can store a path in a path variable. Before we can use such a variable, we
270have to allocate its memory slot with \type {path}.
271
272\starttyping
273path p ; p := (1cm,1cm)..(1.5cm,2cm)..(2cm,0cm) ;
274\stoptyping
275
276Although we can manipulate any path in the same way, using a variable saves us
277the effort to key in a path more than once.
278
279\startuseMPgraphic{axis}
280 tickstep := 1cm ; ticklength := 2mm ;
281 drawticks unitsquare xscaled 8cm yscaled 4cm ;
282 tickstep := tickstep2 ; ticklength := ticklength2 ;
283 drawticks unitsquare xscaled 8cm yscaled 4cm ;
284\stopuseMPgraphic
285
286\startuseMPgraphic{path}
287 path p ; p := (1cm,1cm)..(1.5cm,2cm)..(2cm,0cm)..cycle ;
288 path q ; q := p shifted (4cm,2cm) ;
289\stopuseMPgraphic
290
291\startbuffer[path]
292\startlinecorrection[blank]
293\startMPcode
294 \includeMPgraphic{axis}
295 \includeMPgraphic{path}
296 swappointlabels := true ;
297 drawpath p ; drawcontrollines p ; drawpoints p ; drawcontrolpoints p ;
298 drawpath q ; drawcontrollines q ; drawpoints q ; drawcontrolpoints q ;
299\stopMPcode
300\stoplinecorrection
301\stopbuffer
302
303\getbuffer[path]
304
305In this graphic, the path stored in \type {p} is drawn twice, once in its
306displaced form. The displacement is defined as:
307
308\starttyping
309p shifted (4cm,2cm)
310\stoptyping
311
312In a similar fashion you can rotate a path. You can even combine shifts and
313rotations. First we rotate the path 15 degrees counterclockwise around the
314origin.
315
316\starttyping
317p rotated 15
318\stoptyping
319
320\startuseMPgraphic{path}
321 path p ; p := (1cm,1cm)..(1.5cm,2cm)..(2cm,0cm)..cycle ;
322 path q ; q := p rotated 15 ;
323\stopuseMPgraphic
324
325\getbuffer[path]
326
327This rotation becomes more visible when we also shift the path to the right by
328saying:
329
330\starttyping
331rotated 15 shifted (4cm,0cm)
332\stoptyping
333
334Now we get:
335
336\startuseMPgraphic{path}
337 path p ; p := (1cm,1cm)..(1.5cm,2cm)..(2cm,0cm)..cycle ;
338 path q ; q := p rotated 15 shifted (4cm,0cm) ;
339\stopuseMPgraphic
340
341\getbuffer[path]
342
343Note that \type {rotated 15} is equivalent to \typ {p rotatedaround (origin,
34415)}.
345
346It may make more sense to rotate the shape around its center. This can easily be
347achieved with the \type {rotatedaround} command. Again, we move the path to the
348right afterwards.
349
350\starttyping
351p rotatedaround(center p, 15) shifted (4cm,0cm)
352\stoptyping
353
354\startuseMPgraphic{axis}
355 tickstep := 1cm ; ticklength := 2mm ;
356 drawticks unitsquare xscaled 10cm yscaled 3cm ;
357 tickstep := tickstep2 ; ticklength := ticklength2 ;
358 drawticks unitsquare xscaled 10cm yscaled 3cm ;
359\stopuseMPgraphic
360
361\startuseMPgraphic{path}
362 path p ; p := (1cm,1cm)..(1.5cm,2cm)..(2cm,0cm)..cycle ;
363 path q ; q := p rotatedaround(center p, 15) shifted (4cm,0cm) ;
364\stopuseMPgraphic
365
366\getbuffer[path]
367
368Yet another transformation is slanting. Just like characters can be upright or
369slanted, a graphic can be:
370
371\starttyping
372p slanted 1.5 shifted (4cm,0cm)
373\stoptyping
374
375\startuseMPgraphic{path}
376 path p ; p := (1cm,1cm)..(1.5cm,2cm)..(2cm,0cm)..cycle ;
377 path q ; q := p slanted 1.5 shifted (4cm,0cm) ;
378\stopuseMPgraphic
379
380\getbuffer[path]
381
382The slant operations main application is in tilting fonts. The $x$coodinates
383are increased by a percentage of their $y$coordinate, so here every $x$ becomes
384$x1.5y$. The $y$coordinate is left untouched. The following table summarizes
385the most important primitive transformations that \METAPOST\ supports.
386
387\starttabulate[lTl]
388\HL
389\NC \METAPOST\ code \NC mathematical equivalent \NC \NR
390\HL
391\NC (x,y) shifted (a,b) \NC $(xa,yb)$ \NC \NR
392\NC (x,y) scaled s \NC $(sx,sy)$ \NC \NR
393\NC (x,y) xscaled s \NC $(sx,y)$ \NC \NR
394\NC (x,y) yscaled s \NC $(x,sy)$ \NC \NR
395\NC (x,y) zscaled (u,v) \NC $(xuyv,xvyu)$ \NC \NR
396\NC (x,y) slanted s \NC $(xsy,y)$ \NC \NR
397\NC (x,y) rotated r \NC $(x\cos(r)y\sin(r),x\sin(r)y\cos(r))$ \NC \NR
398\HL
399\stoptabulate
400
401The previously mentioned \type {rotatedaround} is not a primitive but a macro,
402defined in terms of shifts and rotations. Another transformation macro is
403mirroring, or in \METAPOST\ terminology, \type {reflectedabout}.
404
405\startbuffer[path]
406\startlinecorrection[blank]
407\startMPcode
408 \includeMPgraphic{axis}
409 \includeMPgraphic{path}
410 swappointlabels := true ;
411 drawpath p ; drawpoints p ;
412 drawpath q ; drawpoints q ;
413\stopMPcode
414\stoplinecorrection
415\stopbuffer
416
417\startuseMPgraphic{path}
418 path p ; p := unitsquare scaled 2cm shifted (2cm,.5cm) ;
419 path q ; q := unitsquare scaled 2cm shifted (2cm,.5cm) reflectedabout((2.4cm,-.5),(2.4cm,3cm)) ;
420 draw (2.4cm,-.5cm)--(2.4cm,3cm) ;
421\stopuseMPgraphic
422
423\getbuffer[path]
424
425The reflection axis is specified by a pair of points. For example, in the graphic
426above, we used the following command to reflect the square about a line through
427the given points.
428
429\starttyping
430p reflectedabout((2.4cm,.5),(2.4cm,3cm))
431\stoptyping
432
433The line about which the path is mirrored. Mirroring does not have to be parallel
434to an axis.
435
436\starttyping
437p reflectedabout((2.4cm,.5),(2.6cm,3cm))
438\stoptyping
439
440The rectangle now becomes:
441
442\startuseMPgraphic{path}
443 path p ; p := unitsquare scaled 2cm shifted (2cm,.5cm) ;
444 path q ; q := unitsquare scaled 2cm shifted (2cm,.5cm) reflectedabout((2.4cm,-.5),(2.6cm,3cm)) ;
445 draw (2.4cm,-.5cm)--(2.6cm,3cm) ;
446\stopuseMPgraphic
447
448\getbuffer[path]
449
450\pagereference [zscaled]The table also mentions \type {zscaled}.
451
452\startuseMPgraphic{path}
453path p ; p := unitsquare scaled (1cm) shifted (1cm,.5cm) ;
454path q ; q := unitsquare scaled (1cm) zscaled (2,.5) shifted (1cm,.5cm) ;
455\stopuseMPgraphic
456
457\getbuffer[path]
458
459A \type {zscaled} specification takes a vector as argument:
460
461\starttyping
462p zscaled (2,.5)
463\stoptyping
464
465The result looks like a combination of scaling and rotation, and conforms to the
466formula in the previous table.
467
468Transformations can be defined in terms of a transform matrix. Such a matrix is
469stored in a transform variable. For example:
470
471\starttyping
472transform t ; t := identity scaled 2cm shifted (4cm,1cm) ;
473\stoptyping
474
475We use the associated keyword \type {transformed} to apply this matrix to a path
476or picture.
477
478\starttyping
479p transformed t
480\stoptyping
481
482In this example weve taken the \type {identity} matrix as starting point but you
483can use any predefined transformation. The identity matrix is defined in such a
484way that it scales by a factor of one in both directions and shifts over the
485zerovector.
486
487Transform variables can save quite some typing and may help you to force
488consistency when many similar transformations are to be done. Instead of changing
489the scaling, shifting and other transformations you can then stick to just
490changing the one transform variable.
491
492\stopsection
493
494\startsection[title={Constructing paths}]
495
496\index{paths}
497
498In most cases, a path will have more points than the few shown here. Take for
499instance a so called {\em super ellipse}.
500
501\startlinecorrection[blank]
502\startMPcode
503path p ; p := fullsquare xyscaled (5cm,3cm) superellipsed .85 ;
504drawpath p ; drawpoints p ;
505visualizepaths ; draw p shifted (6cm,0cm) withcolor .625yellow ;
506\stopMPcode
507\stoplinecorrection
508
509These graphics provide a lot of information. In this picture the crosshair in the
510center is the {\em origin} and the dashed rectangle is the {\em bounding box} of
511the super ellipse. The bounding box specifies the position of the graphic in
512relation to the origin as well as its width and height.
513
514In the graphic on the right, you can see the points that make up the closed path
515as well as the control points. Each point has a number with the first point
516numbered zero. Because the path is closed, the first and last point coincide.
517
518\startuseMPgraphic{axis}
519 tickstep := 1cm ; ticklength := 2mm ;
520 drawticks unitsquare xscaled 8cm yscaled 3cm ;
521 tickstep := tickstep2 ; ticklength := ticklength2 ;
522 drawticks unitsquare xscaled 8cm yscaled 3cm ;
523\stopuseMPgraphic
524
525\startbuffer
526\startlinecorrection[blank]
527\startMPcode
528 string tmp ; defaultfont := "\truefontname{Mono}" ;
529 \includeMPgraphic{axis}
530 \includeMPgraphic{points}
531 \includeMPgraphic{path}
532 label.lft(verbatim(tmp),(14.5cm,2.5cm)) ;
533 drawwholepath scantokens(tmp) ;
534\stopMPcode
535\stoplinecorrection
536\stopbuffer
537
538Weve used the commands \type {..} and \type {} as path connecting directives.
539In the next series of examples, we will demonstrate a few more. However, before
540doing that, we define a few points, using the predefined \type {z} variables.
541
542\startuseMPgraphic{points}
543 z0 = (0.5cm,1.5cm) ; z1 = (2.5cm,2.5cm) ;
544 z2 = (6.5cm,0.5cm) ; z3 = (3.0cm,1.5cm) ;
545\stopuseMPgraphic
546
547\starttyping
548z0 = (0.5cm,1.5cm) ; z1 = (2.5cm,2.5cm) ;
549z2 = (6.5cm,0.5cm) ; z3 = (3.0cm,1.5cm) ;
550\stoptyping
551
552Here \type {z1} is a short way of saying \type {(x1,y1)}. When a \type {z}
553variable is called, the corresponding \type {x} and \type {y} variables are
554available too. Later we will discuss \METAPOST\ capability to deal with
555expressions, which are expressed using an \type {=} instead of \type {:=}. In
556this case the expression related to \type {z0} is expanded into:
557
558\starttyping
559z0 = (x0,y0) = (0.5cm,1.5cm) ;
560\stoptyping
561
562But for this moment lets forget about their expressive nature and simply see
563them as points which we will now connect by straight line segments.
564
565\startuseMPgraphic{path}
566 tmp := "z0--z1--z2--z3--cycle" ;
567\stopuseMPgraphic
568
569\getbuffer
570
571The smooth curved connection, using \type {..} looks like:
572
573\startuseMPgraphic{path}
574 tmp := "z0..z1..z2..z3..cycle" ;
575\stopuseMPgraphic
576
577\getbuffer
578
579If we replace the \type {..} by \type {...}, we get a tighter path.
580
581\startuseMPgraphic{path}
582 tmp := "z0...z1...z2...z3...cycle" ;
583\stopuseMPgraphic
584
585\getbuffer
586
587Since there are \type {..}, \type {}, and \type {...}, it will be no surprise
588that there is also \type {}.
589
590\startuseMPgraphic{path}
591 tmp := "z0---z1---z2---z3---cycle" ;
592\stopuseMPgraphic
593
594\getbuffer
595
596If you compare this graphic with the one using \type {} the result is the same,
597but there is a clear difference in control points. As a result, combining \type
598{..} with \type {} or \type {} makes a big difference. Here we get a
599nonsmooth connection between the curves and the straight line.
600
601\startuseMPgraphic{path}
602 tmp := "z0..z1..z2--z3..cycle" ;
603\stopuseMPgraphic
604
605\getbuffer
606
607As you can see in the next graphic, when we use \type {}, we get a smooth
608connection between the straight line and the rest of the curve.
609
610\startuseMPgraphic{path}
611 tmp := "z0..z1..z2---z3..cycle" ;
612\stopuseMPgraphic
613
614\getbuffer
615
616So far, we have joined the four points as one path. Alternatively, we can
617constrict subpaths and connect them using the ampersand symbol, \type {}.
618
619\startuseMPgraphic{path}
620 tmp := "z0..z1..z2 & z2..z3..z0 & cycle" ;
621\stopuseMPgraphic
622
623\getbuffer
624
625So far we have created a closed path. Closing is done by \type {cycle}. The
626following path may look closed but is in fact open.
627
628\startuseMPgraphic{path}
629 tmp := "z0..z1..z2..z3..z0" ;
630\stopuseMPgraphic
631
632\getbuffer
633
634Only a closed path can be filled. The closed alternative looks as follows. We
635will see many examples of filled closed paths later on.
636
637\startuseMPgraphic{path}
638 tmp := "z0..z1..z2..z3..z0..cycle" ;
639\stopuseMPgraphic
640
641\getbuffer
642
643Here the final \type {..} will try to make a smooth connection, but because we
644already are at the starting point, this is not possible. However, the \type
645{cycle} command can automatically connect to the first point. Watch the
646difference between the previous and the next path.
647
648\startuseMPgraphic{path}
649 tmp := "z0..z1..z2..z3..cycle" ;
650\stopuseMPgraphic
651
652\getbuffer
653
654It is also possible to combine two paths into one that dont have common head and
655tails. First we define an open path:
656
657\startuseMPgraphic{path}
658 tmp := "z0..z1..z2" ;
659\stopuseMPgraphic
660
661\getbuffer
662
663The following path is a closed one, and crosses the previously shown path.
664
665\startuseMPgraphic{path}
666 tmp := "z0..z3..z1..cycle" ;
667\stopuseMPgraphic
668
669\getbuffer
670
671With \type {buildcycle} we can combine two paths into one.
672
673\startuseMPgraphic{path}
674 tmp := "buildcycle(z0..z1..z2 , z0..z3..z1..cycle)" ;
675\stopuseMPgraphic
676
677\getbuffer
678
679We would refer readers to the \METAFONT\ book and the \METAPOST\ manual for an
680explanation of the intricacies of the \type {buildcycle} command. It is an
681extremely complicated command, and there is just not enough room here to do it
682justice. We suffice with saying that the paths should cross at least once before
683the \type {buildcycle} command can craft a combined path from two given paths. We
684encourage readers to experiment with this command.
685
686In order to demonstrate another technique of joining paths, we first draw a few
687strange paths. The last of these three graphics demonstrates the use of \type
688{softjoin}.
689
690\startuseMPgraphic{path}
691 tmp := "z0--z1..z2--z3" ;
692\stopuseMPgraphic
693
694\getbuffer
695
696\startuseMPgraphic{path}
697 tmp := "z0..z1..z2--z3" ;
698\stopuseMPgraphic
699
700\getbuffer
701
702Watch how \type {softjoin} removes a point in the process of smoothing a
703connection. The smoothness is accomplished by adapting the control points of the
704neighbouring points in the appropriate way.
705
706\startuseMPgraphic{path}
707 tmp := "z0--z1 softjoin z2--z3" ;
708\stopuseMPgraphic
709
710\getbuffer
711
712Once a path is known, you can cut off a slice of it. We will demonstrate a few
713alternative ways of doing so, but first we show one more time the path that we
714take as starting point.
715
716\startuseMPgraphic{path}
717 tmp := "z0..z1..z2..z3..cycle" ;
718\stopuseMPgraphic
719
720\getbuffer
721
722This path is made up out of five points, where the cycle duplicates the first
723point and connects the loose ends. The first point has number zero.
724
725We can use these points in the \type {subpath} command, which takes two
726arguments, specifying the range of points to cut of the path specified after the
727keyword \type {of}.
728
729\startuseMPgraphic{path}
730 tmp := "subpath(2,4) of (z0..z1..z2..z3..cycle)" ;
731\stopuseMPgraphic
732
733\getbuffer
734
735The new (sub)path is a new path with its own points that start numbering at
736zero. The next graphic shows both the original and the subpath from point 1
737upto3.
738
739\startuseMPgraphic{path}
740 tmp := "(z0..z1..z2..z3..cycle)" ;
741 sub := "subpath(1,3)" ;
742\stopuseMPgraphic
743
744\startbuffer[sub]
745\startlinecorrection[blank]
746\startMPcode
747 string tmp, sub ; defaultfont := "\truefontname{Mono}" ;
748 \includeMPgraphic{axis}
749 \includeMPgraphic{points}
750 \includeMPgraphic{path}
751 label.lft(verbatim(tmp),(14.5cm,2.5cm)) ;
752 label.lft(verbatim(sub),(14.5cm,2.0cm)) ;
753 sub := sub & " of " & tmp ;
754 path p ; p := scantokens(tmp) ;
755 path q ; q := scantokens(sub) ;
756 drawwholepath p ; swappointlabels := true ;
757 drawpath q withcolor .625yellow ;
758 drawpoints q withcolor .625red ;
759 drawpointlabels q ;
760\stopMPcode
761\stoplinecorrection
762\stopbuffer
763
764\getbuffer[sub]
765
766In spite of what you may think, a point is not fixed. This is why in \METAPOST\ a
767point along a path is officially called a time. The next example demonstrates
768that we can specify any time on the path.
769
770\startuseMPgraphic{path}
771 tmp := "(z0..z1..z2..z3..cycle)" ;
772 sub := "subpath(2.45,3.85)" ;
773\stopuseMPgraphic
774
775\getbuffer[sub]
776
777Often we want to take a slice starting at a specific point. This is provided by
778\type {cutafter} and its companion \type {cutbefore}. Watch out, this time we use
779a noncyclic path.
780
781\startuseMPgraphic{path}
782 tmp := "(z0..z1..z2..z3)" ;
783\stopuseMPgraphic
784
785\getbuffer
786
787When you use \type {cutafter} and \type {cutbefore} it really helps if you know
788in what direction the path runs.
789
790\startuseMPgraphic{path}
791 tmp := "(z0..z1..z2..z3) cutafter z2" ;
792\stopuseMPgraphic
793
794\getbuffer
795
796\startuseMPgraphic{path}
797 tmp := "(z0..z1..z2..z3) cutbefore z1" ;
798\stopuseMPgraphic
799
800\getbuffer
801
802Here is a somewhat silly way of accomplishing the same thing, but it is a nice
803introduction to \METAPOSTs \type {point} operation. In order to use this command
804effectively, you need to know how many points make up the path.
805
806\startuseMPgraphic{path}
807 tmp := "(z0..z1..z2..z3) cutbefore point 2 of (z0..z1..z2..z3)" ;
808\stopuseMPgraphic
809
810\getbuffer
811
812As with \type {subpath}, you can use fractions to specify the time on the path,
813although the resulting point is not necessarily positioned linearly along the
814curve.
815
816\startuseMPgraphic{path}
817 tmp := "(z0..z1..z2..z3) cutbefore point 2.5 of (z0..z1..z2..z3)" ;
818\stopuseMPgraphic
819
820\getbuffer
821
822If you really want to know the details of where fraction points are positioned,
823you should read the \METAFONT\ book and study the source of \METAFONT\ and
824\METAPOST, where you will find the complicated formulas that are used to
825calculate smooth curves.
826
827\startuseMPgraphic{path}
828 tmp := "z0..z1..cycle" ;
829\stopuseMPgraphic
830
831\getbuffer
832
833Like any closed path, this path has points where the tangent is horizontal or
834vertical. Early in this chapter we mentioned that a pair (or point) can specify a
835direction or vector. Although any angle is possible, we often use one of four
836predefined directions:
837
838\starttabulate[TlTl]
839\HL
840\NC right \NC ( 1, 0) \NC \NR
841\NC up \NC ( 0, 1) \NC \NR
842\NC left \NC (1, 0) \NC \NR
843\NC down \NC ( 0,1) \NC \NR
844\HL
845\stoptabulate
846
847We can use these predefined directions in combination with \type {directionpoint}
848and \type {cutafter}. The following command locates the first point on the path
849that has a tangent that points vertically upward, and then feeds this point to
850the \type {cutafter} command.
851
852\startuseMPgraphic{path}
853 tmp := "(z0..z1..cycle) cutafter directionpoint up of (z0..z1..cycle)" ;
854\stopuseMPgraphic
855
856\getbuffer
857
858You are not limited to predefined direction vectors. You can provide a pair to
859indicate a direction. In the next example we use the following cyclic path:
860
861\startuseMPgraphic{path}
862 tmp := "z0..z1..cycle" ;
863\stopuseMPgraphic
864
865\getbuffer
866
867Using \type {( )} is not mandatory but makes the expression look less
868complicated.
869
870\startuseMPgraphic{path}
871 tmp := "(z0..z1..cycle) cutafter directionpoint (1,1) of (z0..z1..cycle)" ;
872\stopuseMPgraphic
873
874\getbuffer
875
876We will apply these commands in the next chapters, but first we will finish our
877introduction in \METAPOST. We have seen how a path is constructed and what can be
878done with it. Now it is time to demonstrate how such a path is turned into a
879graphic.
880
881\stopsection
882
883\startsection[title={Angles}]
884
885\index{angles}
886\index{rotation}
887
888You can go from angles to vectors and vice versa using the \type {angle} and
889\type {dir} functions. The next example show both in action.
890
891\startbuffer
892pickup pencircle scaled 2mm ;
893draw (origin dir(45) dir(0) cycle)
894 scaled 3cm withcolor .625red ;
895draw (origin dir(angle(1,1)) dir(angle(1,0)) cycle)
896 scaled 3cm shifted (3.5cm,0) withcolor .625yellow ;
897draw (origin (1,1) (1,0) cycle)
898 scaled 3cm shifted (7cm,0) withcolor .625white ;
899\stopbuffer
900
901\typebuffer
902
903\startlinecorrection[blank]
904\processMPbuffer
905\stoplinecorrection
906
907The \type {dir} command returns an unit vector, which is why the first two shapes
908look different and are smaller than the third one. We can compensate for that by
909an additional scaling:
910
911\startbuffer
912pickup pencircle scaled 2mm ;
913draw (origin dir(45) dir(0) cycle)
914 scaled sqrt(2) scaled 3cm withcolor .625red ;
915draw (origin dir(angle(1,1)) dir(angle(1,0)) cycle)
916 scaled sqrt(2) scaled 3cm shifted (4.5cm,0) withcolor .625yellow ;
917draw (origin (1,1) (1,0) cycle)
918 scaled 3cm shifted (9cm,0) withcolor .625white ;
919\stopbuffer
920
921\typebuffer
922
923\startlinecorrection[blank]
924\processMPbuffer
925\stoplinecorrection
926
927\stopsection
928
929\startsection[title={Drawing pictures}]
930
931\index{drawing}
932
933Once a path is defined, either directly or as a variable, you can turn it into a
934picture. You can draw a path, like we did in the previous examples, or you can
935fill it, but only if it is closed.
936
937\startlinecorrection[blank]
938\startMPcode
939visualizepaths ;
940path p ; p := (0cm,1cm)..(2cm,2cm)..(4cm,0cm)..cycle ;
941draw p withcolor .625red ;
942fill p shifted (7cm,0) withcolor .625white ;
943\stopMPcode
944\stoplinecorrection
945
946Drawing is done by applying the \type {draw} command to a path, as in:
947
948\starttyping
949draw (0cm,1cm)..(2cm,2cm)..(4cm,0cm)..cycle ;
950\stoptyping
951
952The rightmost graphic was made with \type {fill}:
953
954\starttyping
955fill (0cm,1cm)..(2cm,2cm)..(4cm,0cm)..cycle ;
956\stoptyping
957
958If you try to duplicate this drawing, you will notice that you will get black
959lines instead of red and a black fill instead of a gray one. When drawing or
960filling a path, you can give it a color, use all kinds of pens, and achieve
961special effects like dashes or arrows.
962
963\startlinecorrection[blank]
964\startMPcode
965visualizepaths ;
966path p ; p := (0cm,1cm)..(2cm,2cm)..(4cm,0cm)..(2.5cm,1cm)..cycle ;
967drawarrow p withcolor .625red ;
968draw p shifted (7cm,0) dashed withdots withcolor .625yellow ;
969\stopMPcode
970\stoplinecorrection
971
972These two graphics were defined and drawn using the following commands. Later we
973will explain how you can set the line width (or penshape in terms of \METAPOST).
974
975\starttyping
976path p ; p := (0cm,1cm)..(2cm,2cm)..(4cm,0cm)..(2.5cm,1cm)..cycle ;
977drawarrow p withcolor .625red ;
978draw p shifted (7cm,0) dashed withdots withcolor .625yellow ;
979\stoptyping
980
981Once we have drawn one or more paths, we can store them in a picture variable.
982The straightforward way to store a picture is to copy it from the current
983picture:
984
985\starttyping
986picture pic ; pic := currentpicture ;
987\stoptyping
988
989The following command effectively clears the picture memory and allows us to
990start anew.
991
992\starttyping
993currentpicture := nullpicture ;
994\stoptyping
995
996We can shift, rotate and slant the picture stored in \type {pic} as we did with
997paths. We can say:
998
999\starttyping
1000draw pic rotated 45 withcolor red ;
1001\stoptyping
1002
1003A picture can hold multiple paths. You may compare a picture to grouping as
1004provided by drawing applications.
1005
1006\starttyping
1007draw (0cm,0cm)(1cm,1cm) ; draw (1cm,0cm)(0cm,1cm) ;
1008picture pic ; pic := currentpicture ;
1009draw pic shifted (3cm,0cm) ; draw pic shifted (6cm,0cm) ;
1010pic := currentpicture ; draw pic shifted (0cm,2cm) ;
1011\stoptyping
1012
1013We first draw two paths and store the resulting \quote {cross} in a picture
1014variable. Then we draw this picture two times, so that we now have three copies
1015of the cross. We store the accumulated drawing again, so that after duplication,
1016we finally get six crosses.
1017
1018\startlinecorrection[blank]
1019\startMPcode
1020path p ; p := (0cm,0cm)--(1cm,1cm) ;
1021path q ; q := (1cm,0cm)--(0cm,1cm) ;
1022for i=p,q :
1023 drawpath i ; drawcontrollines i ; drawpoints i ; drawcontrolpoints i ;
1024endfor ;
1025picture pic ; pic := currentpicture ;
1026draw pic shifted (3cm,0cm) ;
1027draw pic shifted (6cm,0cm) ;
1028pic := currentpicture ;
1029draw pic shifted (0cm,2cm) ;
1030\stopMPcode
1031\stoplinecorrection
1032
1033You can often follow several routes to reach the same solution. Consider for
1034instance the following graphic.
1035
1036\startbuffer[points]
1037w := 4cm ; h := 2cm ; ww := 1cm ; hh := 1.5cm ;
1038\stopbuffer
1039
1040\startbuffer[common]
1041drawoptions(withcolor .625white) ;
1042\stopbuffer
1043
1044\startbuffer[background]
1045fill (unitsquare xscaled w yscaled h) enlarged 2mm withcolor .625yellow ;
1046\stopbuffer
1047
1048\startbuffer[shape]
1049fill (0,0)(ww,0)(ww,hh)(w,hh)(w,h)(0,h)cycle ;
1050fill (ww,0)(w,0)(w,hh)cycle ;
1051\stopbuffer
1052
1053\typebuffer[shape]
1054
1055\startlinecorrection[blank]
1056\processMPbuffer[common,points,shape]
1057\stoplinecorrection
1058
1059The points that are used to construct the paths are defined using the constants
1060\type {w}, \type {h}, \type {ww} and \type {hh}. These are defined as follows:
1061
1062\typebuffer[points]
1063
1064In this case we draw two shapes that leave part of the rectangle uncovered. If
1065you have a background, this technique allows the background to \quote {show
1066through} the graphic.
1067
1068\startlinecorrection[blank]
1069\processMPbuffer[common,points,background,shape]
1070\stoplinecorrection
1071
1072A not uncommon practice when making complicated graphics is to use unfill
1073operations. Since \METAPOST\ provides one, let us see what happens if we apply
1074this command.
1075
1076\startbuffer[shape]
1077fill (0,0)(w,0)(w,h)(0,h)cycle ;
1078unfill (ww,0)(w,hh)(ww,hh)cycle ;
1079\stopbuffer
1080
1081\typebuffer[shape]
1082
1083\startlinecorrection[blank]
1084\processMPbuffer[common,points,background,shape]
1085\stoplinecorrection
1086
1087This does not always give the desired effect, because \METAPOSTs \type {unfill}
1088is not really an unfill, but a \type {fill} with color \type {background}. Since
1089this color is white by default, we get what we just showed. So, if we set \type
1090{background} to \type {black}, using \typ {background := black}, we get:
1091
1092\startbuffer[back]
1093background := black ;
1094\stopbuffer
1095
1096\startlinecorrection[blank]
1097\processMPbuffer[back,common,points,background,shape]
1098\stoplinecorrection
1099
1100Of course, you can set the variable \type {background} to a different color, but
1101this does not hide the fact that \METAPOST\ lacks a real unfill operation.
1102
1103\startbuffer[shape]
1104fill (0,0)(0,h)(w,h)(w,0)(ww,0)(w,hh)(ww,hh)
1105 (ww,0)cycle ;
1106\stopbuffer
1107
1108\startbuffer[path]
1109autoarrows := true ;
1110path p ; p := (0,0)(0,h)(w,h)(w,0)(ww,0)(w,hh)(ww,hh)
1111 (ww,0)cycle ;
1112draw p withpen pencircle scaled 1mm withcolor .625red;
1113numeric l ; l := length(p)1 ;
1114for i=0 upto l :
1115 drawarrow subpath(i,i1) of p
1116 withpen pencircle scaled 1mm
1117 withcolor (.5.5(il))*red ;
1118endfor ;
1119\stopbuffer
1120
1121\startlinecorrection[blank]
1122\processMPbuffer[common,points,background,shape]
1123\stoplinecorrection
1124
1125Since we dont consider this \type {unfill} a suitable operator, you may wonder
1126how we achieved the above result.
1127
1128\typebuffer[shape]
1129
1130\startlinecorrection[blank]
1131\processMPbuffer[common,points,background,shape,path]
1132\stoplinecorrection
1133
1134This feature depends on the \POSTSCRIPT\ way of filling closed paths, which comes
1135down to filling either the left or the right hand side of a curve. The following
1136alternative works too.
1137
1138\startbuffer[shape]
1139fill (0,0)(0,h)(w,h)(w,hh)(ww,hh)(ww,0)(w,hh)
1140 (w,0)cycle ;
1141\stopbuffer
1142
1143\typebuffer[shape]
1144
1145\startlinecorrection[blank]
1146\processMPbuffer[common,points,background,shape]
1147\stoplinecorrection
1148
1149The next alternative will fail. This has to do with the change in direction at
1150point \type {(0,0)} halfway through the path. Sometimes changing direction can
1151give curious but desirable effects, but here it brings no good.
1152
1153\startbuffer[shape]
1154fill (0,0)(0,h)(w,h)(w,0)(0,0)(ww,0)(ww,hh)
1155 (w,hh)(ww,0)cycle ;
1156\stopbuffer
1157
1158\typebuffer[shape]
1159
1160This path fails because of the way \POSTSCRIPT\ implements its fill operator.
1161More details on how \POSTSCRIPT\ defines fills can be found in the reference
1162manuals.
1163
1164\startlinecorrection[blank]
1165\processMPbuffer[common,points,background,shape]
1166\stoplinecorrection
1167
1168Some of the operations we have seen are hard coded into \METAPOST\ and are called
1169primitives. Others are defined as macros, that is, a sequence of \METAPOST\
1170commands. Since they are used often, you may expect \type {draw} and \type {fill}
1171to be primitives, but they are not. They are macros defined in terms of
1172primitives.
1173
1174Given a path \type {pat}, you can consider a \type {draw} to be defined in terms
1175of:
1176
1177\starttyping
1178addto currentpicture doublepath pat
1179\stoptyping
1180
1181The \type {fill} command on the other hand is defined as:
1182
1183\starttyping
1184addto currentpicture contour pat
1185\stoptyping
1186
1187Both macros are actually a bit more complicated but this is mainly due to the
1188fact that they also have to deal with attributes like the pen and color they draw
1189with.
1190
1191You can use \type {doublepath} and \type {contour} directly, but we will use
1192\type {draw} and \type {fill} whenever possible.
1193
1194Given a picture \type {pic}, the following code is valid:
1195
1196\starttyping
1197addto currentpicture also pic
1198\stoptyping
1199
1200You can add pictures to existing picture variables, where \type {currentpicture}
1201is the picture that is flushed to the output file. Watch the subtle difference
1202between adding a \type {doublepath}, \type {contour} or \type {picture}.
1203
1204\stopsection
1205
1206\startsection[title={Variables}]
1207
1208\index{variables}
1209
1210At this point you may have noted that \METAPOST\ is a programming language.
1211Contrary to some of todays languages, \METAPOST\ is a simple and clean language.
1212Actually, it is a macro language. Although \METAPOST\ and \TEX\ are a couple, the
1213languages differ in many aspects. If you are using both, you will sometimes wish
1214that features present in one would be available in the other. When using both
1215languages, in the end you will understand why the conceptual differences make
1216sense.
1217
1218Being written in \PASCAL, it will be no surprise that \METAPOST\ has some
1219\PASCALlike features, although some may also recognize features from \ALGOL68\
1220in it.
1221
1222First there is the concept of variables and assignments. There are several data
1223types, some of which we already have seen.
1224
1225\starttabulate
1226\HL
1227\NC numeric \NC real number in the range $4096 \ldots 4096$ \NC \NR
1228\NC boolean \NC a variable that takes one of two states: true or false \NC \NR
1229\NC pair \NC point or vector in 2dimensional space \NC \NR
1230\NC path \NC a piecewise collection of curves and line segments \NC \NR
1231\NC picture \NC collection of stroked or filled paths \NC \NR
1232\NC string \NC sequence of characters, like \type {"metapost"} \NC \NR
1233\NC color \NC vector of three (rgb) or four (cmyk) numbers \NC \NR
1234\HL
1235\stoptabulate
1236
1237There are two additional types, \type {transform} and \type {pen}, but we will
1238not discuss these in depth.
1239
1240\starttabulate
1241\HL
1242\NC transform \NC transformation vector with six elements \NC \NR
1243\NC pen \NC pen specification \NC \NR
1244\HL
1245\stoptabulate
1246
1247You can achieve interesting effects by using pens with certain shapes. For the
1248moment you may consider a pen to be a path itself that is applied to the path
1249that is drawn.
1250
1251The \type {numeric} data type is used so often that it is the default type of any
1252non declared variable. This means that
1253
1254\starttyping
1255n := 10 ;
1256\stoptyping
1257
1258is the same as
1259
1260\starttyping
1261numeric n ; n := 10 ;
1262\stoptyping
1263
1264When writing collections of macros, it makes sense to use the second method,
1265because you can never be sure if \type {n} isnt already declared as a picture
1266variable, and assigning a numeric to a picture variable is not permitted.
1267
1268Because we often deal with collections of objects, such as a series of points,
1269all variables can be organized in arrays. For instance:
1270
1271\starttyping
1272numeric n[] ; n[3] := 10 ; n[5] := 13 ;
1273\stoptyping
1274
1275An array is a collection of variables of the same type that are assigned and
1276accessed by indexing the variable name, as in \type {n[3] := 5}.
1277Multidimensional arrays are also supported. Since you need a bit of imagination
1278to find an application for 5dimensional arrays, we restrict ourselves to a
1279twodimensional example.
1280
1281\starttyping
1282numeric n[][] ; n[2][3] := 10 ;
1283\stoptyping
1284
1285A nice feature is that the bounds of such an array needs not to be set
1286beforehand. This also means that each cell that you access is reported as {\em
1287unknown} unless you have assigned it a value.
1288
1289Behind the screens there are not really arrays. Its just a matter of creating
1290hash entries. It might not be obvious, but the following assignments are all
1291equivalent:
1292
1293\startbuffer
1294i111222 := 1cm ;
1295i[111][222] := 1cm ;
1296i[111][222] := 1cm ;
1297draw
1298 image (
1299 draw (0cm,i111222) ;
1300 draw (1cm,i[111][222]) ;
1301 draw (2cm,i[111][222]) ;
1302 )
1303 withpen pencircle scaled 5mm
1304 withcolor .625 red ;
1305\stopbuffer
1306
1307\typebuffer
1308
1309Sometimes \METAPOST\ ways are mysterious:
1310
1311\startlinecorrection[blank]
1312\processMPbuffer
1313\stoplinecorrection
1314
1315\stopsection
1316
1317\startsection[title={Conditions}]
1318
1319\index{conditions}
1320
1321The existence of boolean variables indicates the presence of conditionals.
1322Indeed, the general form of \METAPOSTs conditional follows:
1323
1324\starttyping
1325if n=10 : draw p ; else : draw q ; fi ;
1326\stoptyping
1327
1328Watch the colons after the if and else clause. They may not be omitted. The
1329semicolons on the other hand, are optional and depend on the context. You may
1330say things like:
1331
1332\starttyping
1333draw if n=10 : p ; else : q ; fi ;
1334\stoptyping
1335
1336Here we can omit a few semicolons:
1337
1338\starttyping
1339draw if n=10 : p else : q fi withcolor red ;
1340\stoptyping
1341
1342Adding semicolons after \type {p} and \type {q} will definitely result in an
1343error message, since the semicolon ends the draw operation and \typ {withcolor
1344red} becomes an isolated piece of nonsense.
1345
1346There is no case statement available, but for most purposes, the following
1347extension is adequate:
1348
1349\starttyping
1350draw p withcolor if n<10 : red elseif n=10 : green else : blue fi ;
1351\stoptyping
1352
1353There is a wide repertoire of boolean tests available.
1354
1355\starttyping
1356if picture p :
1357if known n :
1358if odd i :
1359if cycle q :
1360\stoptyping
1361
1362Of course, you can use \type {and}, \type {or}, \type {not}, and \type {( )} to
1363construct very advanced boolean expressions. If you have a bit of programming
1364experience, you will appreciate the extensive support of conditionals in
1365\METAPOST.
1366
1367\stopsection
1368
1369\startsection[title={Loops}]
1370
1371\index{loops}
1372
1373Yet another programming concept present in \METAPOST\ is the loop statement, the
1374familiar \quote {for loop} of all programming languages.
1375
1376\starttyping
1377for i=0 step 2 until 20 :
1378 draw (0,i) ;
1379endfor ;
1380\stoptyping
1381
1382As explained convincingly in Niklaus Wirths book on algorithms and
1383datastructures, the for loop is the natural companion to an array. Given an array
1384of length $n$, you can construct a path out of the points that make up the array.
1385
1386\starttyping
1387draw for i=0 step 1 until n1 : p[i] .. endfor p[n] ;
1388\stoptyping
1389
1390If the step increment is not explicitly stated, it has an assumed value of 1. We
1391can shorten the previous loop construct as follows:
1392
1393\starttyping
1394draw for i=0 upto n1 : p[i] .. endfor p[n] ;
1395\stoptyping
1396
1397After seeing \type {if} in action, the following \type {for} loop will be no
1398surprise:
1399
1400\startbuffer
1401draw origin for i=0 step 10 until 100 : ..{down}(i,0) endfor ;
1402\stopbuffer
1403
1404\typebuffer
1405
1406This gives the zigzag curve:
1407
1408\startlinecorrection[blank]
1409\processMPbuffer
1410\stoplinecorrection
1411
1412You can use a loop to iterate over a list of objects. A simple 3step iteration
1413is:
1414
1415\starttyping
1416for i=p,q,r :
1417 fill i withcolor .8white ;
1418 draw i withcolor red ;
1419endfor ;
1420\stoptyping
1421Using \type {for} in this manner can sometimes save a bit of typing. The list can
1422contain any expression, and may be of different types.
1423
1424In the previous example the \type {i} is an independent variable, local to the
1425for loop. If you want to change the loop variable itself, you need to use \type
1426{forsuffixes}. In the next loop the paths \type {p}, \type {q} and\type {r} are
1427all shifted.
1428
1429\starttyping
1430forsuffixes i = p, q, r :
1431 i := i shifted (3cm,2cm) ;
1432endfor ;
1433\stoptyping
1434
1435Sometimes you may want to loop forever until a specific condition occurs. For
1436this, \METAPOST\ provides a special looping mechanism:
1437
1438\startbuffer[demo]
1439numeric done[][], i, j, n ; n := 0 ;
1440forever :
1441 i := round(uniformdeviate(10)) ; j := round(uniformdeviate(2)) ;
1442 if unknown done[i][j] :
1443 drawdot (i*cm,j*cm) ; n := n 1 ; done[i][j] := n ;
1444 fi ;
1445 exitif n = 10 ;
1446endfor ;
1447\stopbuffer
1448
1449\typebuffer[demo]
1450
1451Here we remain in the loop until we have 10 points placed. We use an array to
1452keep track of placed points. The \METAPOST\ macro \type {uniformdeviate(n)}
1453returns a random number between 0 andn and the \type {round} command is used to
1454move the result toward the nearest integer. The \type {unknown} primitive allows
1455us to test if the array element already exists, otherwise we exit the
1456conditional. This saves a bit of computational time as each point is drawn and
1457indexed only once.
1458
1459\startbuffer[pen]
1460pickup pencircle scaled 2mm ;
1461\stopbuffer
1462
1463\startlinecorrection[blank]
1464\processMPbuffer[pen,demo]
1465\stoplinecorrection
1466
1467The loop terminator \type {exitif} and its companion \type {exitunless} can be
1468used in \type {for}, \type {forsuffixes} and \type {forever}.
1469
1470\stopsection
1471
1472\startsection[title={Macros}]
1473
1474\index{macros}
1475\index{definitions}
1476
1477In the previous section we introduced \type {upto}. Actually this is not part of
1478the built in syntax, but a sort of shortcut, defined by:
1479
1480\starttyping
1481def upto = step 1 until enddef ;
1482\stoptyping
1483
1484You just saw a macro definition where \type {upto} is the name of the macro. The
1485counterpart of \type {upto} is \type {downto}. Whenever you use \type {upto}, it
1486is replaced by \typ {step 1 until}. This replacement is called expansion.
1487
1488There are several types of macros. A primary macro is used to define your own
1489operators. For example:
1490
1491\starttyping
1492primarydef p doublescaled s =
1493 p xscaled (s2) yscaled (s*2)
1494enddef ;
1495\stoptyping
1496
1497Once defined, the \type {doublescaled} macro is implemented as in the following
1498example:
1499
1500\starttyping
1501draw somepath doublescaled 2cm withcolor red ;
1502\stoptyping
1503
1504When this command is executed, the macro is expanded. Thus, the actual content of
1505this command becomes:
1506
1507\starttyping
1508draw somepath xscaled 1cm yscaled 4cm withcolor red ;
1509\stoptyping
1510
1511If in the definition of \type {doublescaled} we had added a semicolon after
1512\type {(s*2)}, we could not have set the color, because the semicolon ends the
1513statement. The \type {draw} expects a path, so the macro can best return one.
1514
1515A macro can take one or more arguments, as in:
1516
1517\starttyping
1518def drawrandomscaledpath (expr p, s) =
1519 draw p xscaled (s2) yscaled (s*2) ;
1520enddef ;
1521\stoptyping
1522
1523When using this macro, it is expected that you will pass it two parameters, the
1524first being a path, the second a numeric scale factor.
1525
1526\starttyping
1527drawrandomscaledpath(fullsquare, 3cm) ;
1528\stoptyping
1529
1530Sometimes we want to return a value from a macro. In that case we must make sure
1531that any calculations dont interfere with the expectations. Consider:
1532
1533\starttyping
1534vardef randomscaledpath(expr p, s) =
1535 numeric r ; r := round(1 uniformdeviate(4)) ;
1536 p xscaled (sr) yscaled (s*r)
1537enddef ;
1538\stoptyping
1539
1540Because we want to use the same value of \type {r} twice, we have to use an
1541intermediate variable. By using a \type {vardef} we hide everything but the last
1542statement. It is important to distinguish \type {def} macros from those defined
1543with \type {vardef}. In the latter case, \type {vardef} macros are not a simple
1544expansion and replacement. Rather, \type {vardef} macros return the value of
1545their last statement. In the case of the \type {randomscaledpath} macro, a path
1546is returned. This macro is used in the following manner:
1547
1548\starttyping
1549path mypath ; mypath := randomscaledpath(unitsquare,4cm) ;
1550\stoptyping
1551
1552Note that we send \type {randomscaledpath} a path (\type {unitsquare}) and a
1553scaling factor (\type {4cm}). The macro returns a scaled path which is then
1554stored in the path variable \type {mypath}.
1555
1556The following argument types are accepted:
1557
1558\starttabulate
1559\HL
1560\NC expr \NC something that can be assigned to a variable \NC \NR
1561\NC text \NC arbitrary \METAPOST\ code ending with a \type {;} \NC \NR
1562\NC suffix \NC a variable bound to another variable \NC \NR
1563\HL
1564\stoptabulate
1565An expression is passed by value. This means that in the body of the macro, a
1566copy is used and the original is left untouched. On the other hand, any change to
1567a variable passed as suffix is also applied to the original.
1568
1569Local variables must be handled in a special manner, since they may conflict with
1570variables used elsewhere. This is because all variables are global by default.
1571The way out of this problem is using grouping in combination with saving
1572variables. The use of grouping is not restricted to macros and may be used
1573anywhere in your code. Variables saved and declared in a group are local to that
1574group. Once the group is exited the variables cease to exist.
1575
1576\starttyping
1577vardef randomscaledpath(expr p, s) =
1578 begingroup ; save r ; numeric r ;
1579 r := round(1 uniformdeviate(4)) ;
1580 p xscaled (sr) yscaled (s*r)
1581 endgroup
1582enddef ;
1583\stoptyping
1584
1585In this particular case, we could have omitted the grouping, since \type {vardef}
1586macros are always grouped automatically. Therefore, we could have defined the
1587macro as:
1588
1589\starttyping
1590vardef randomscaledpath(expr p, s) =
1591 save r ; numeric r ; r := round(1 uniformdeviate(4)) ;
1592 p xscaled (sr) yscaled (s*r)
1593enddef ;
1594\stoptyping
1595
1596The command \type {save r} declares that the variable \type {r} is local to the
1597macro. Thus, any changes to the (new) numeric variable \type {r} are local and
1598will not interfere with a variable \type {r} defined outside the macro. This is
1599important to understand, as variables outside the macro are global and accessible
1600to the code within the body of the macro.
1601
1602Macro definitions may be nested, but since most \METAPOST\ code is relatively
1603simple, it is seldom needed. Nesting is discouraged as it makes your code less
1604readable.
1605
1606Besides \type {def} and \type {vardef}, \METAPOST\ also provides the classifiers
1607\type {primarydef}, \type {secondarydef} and \type {tertiarydef}. You can use
1608these classifiers to define macros like those provided by \METAPOST\ itself:
1609
1610\starttyping
1611primarydef x mod y = ... enddef ;
1612secondarydef p intersectionpoint q = ... enddef ;
1613tertiarydef p softjoin q = ... enddef ;
1614\stoptyping
1615A primary macro acts like the binary operators \type {*} or \type {scaled} and
1616\type {shifted}. Secondary macros are like \type {}, \type {} and logical \type
1617{or}, and take less precedence. The tertiary operators like \type {<} or the path
1618and string concatenation operator \type {} have tertiary macros as companions.
1619More details can be found in the \METAFONT\ book. When it comes to taking
1620precedence, \METAPOST\ tries to be as natural as possible, in the sense that you
1621need to provide as few \type {( )}s as possible. When in doubt, or when
1622surprised by unexpected results, use parentheses.
1623
1624\stopsection
1625
1626\startsection[title={Arguments}]
1627
1628\index{arguments}
1629\index{macrosarguments}
1630
1631The \METAPOST\ macro language is rather flexible in how you feed arguments to
1632macros. If you have only one argument, the following definitions and calls are
1633valid.
1634
1635\starttyping
1636def test expr a = enddef ; test (a) ; test a ;
1637def test (expr a) = enddef ; test (a) ; test a ;
1638\stoptyping
1639
1640A more complex definition is the following. As you can see, you can call the
1641\type {test} macro in your favorite way.
1642
1643\starttyping
1644def test (expr a,b) (expr c,d) = enddef ;
1645
1646test (a) (b) (c) (d) ;
1647test (a,b) (c,d) ;
1648test (a,b,c) (d) ;
1649test (a,b,c,d) ;
1650\stoptyping
1651
1652The type of the arguments is one of \type {expr}, \type {primary} or \type
1653{suffix}. When fetching arguments, \METAPOST\ uses the type to determine how and
1654what to grab. A fourth type is \type {text}. When no parenthesis are used, a
1655\type {text} argument grabs everything upto the next semicolon.
1656
1657\starttyping
1658def test (expr a) text b = enddef ;
1659
1660test (a) ; test (a) b ;
1661\stoptyping
1662
1663You can use a \type {text} to grab arguments like \typ {withpen pencircle scaled
166410 withcolor red}. Because \type {text} is so hungry, you may occasionally need a
1665two stage definition:
1666
1667\starttyping
1668def test expr a = dotext(a) enddef ;
1669def dotest (expr a) text b = ... enddef ;
1670
1671test a ; test a b ;
1672\stoptyping
1673
1674This definition permits arguments without parenthesis, which is something you
1675want with commands like \type {draw}.
1676
1677The \type {vardef} alternative behaves in a similar way. It always provides
1678grouping. You need to generate a return value and as a result may not end with a
1679semicolon.
1680
1681You may consider the whole \type {vardef} to be encapsulated into parenthesis and
1682thereby to be a (self contained) variable. Adding additional parenthesis often
1683does more harm than good:
1684
1685\starttyping
1686vardef test (expr a) =
1687 ( do tricky things with a ; manipulateda )
1688enddef ;
1689\stoptyping
1690
1691Here the tricky things become part of the return value, which quite certainly is
1692something that you dont want.
1693
1694The three operator lookalike macro definitions are less flexible and have the
1695definition scheme:
1696
1697\starttyping
1698primarydef x test y = enddef ;
1699secondarydef x test y = enddef ;
1700tertiarydef x test y = enddef ;
1701\stoptyping
1702
1703When defining macros using this threesome you need to be aware of the associated
1704priorities. When using these definitions, you also have to provide your own
1705grouping.
1706
1707In the plain \METAPOST\ macro collection (\type {plain.mp}) you can find many
1708examples of clever definitions. The following (simplified) version of \type {min}
1709demonstrates how we use the argument handler to isolate the first argument from
1710the provided list, simply by using two arguments.
1711
1712\starttyping
1713vardef min (expr u) (text t) =
1714 save minu ; minu := u ;
1715 for uu = t : if uu<u : minu := uu ; fi endfor
1716 minu
1717enddef ;
1718\stoptyping
1719
1720The special sequence \type {@#} is used to pick up a so called delimited argument:
1721
1722\starttyping
1723vardef TryMe@#(expr x) =
1724
1725enddef ;
1726\stoptyping
1727
1728This feature is used in the definition of \type {z} as used in \type {z1} or
1729\type {z234}:
1730
1731\starttyping
1732vardef z@# = (x@#,y@#) enddef ;
1733\stoptyping
1734
1735Other applications can be found in the label drawing macros where the anchor
1736point is assigned to the obscure variable \type {@#}.
1737
1738\stopsection
1739
1740\startsection[title={Pens}]
1741
1742\index{pens}
1743
1744When drawing, three attributes can be applied to it: a dashpattern, a pen
1745andor a color. You may consider an arrowhead an attribute, but actually it is
1746just an additional drawing, appended to the path.
1747
1748The (predefined) \type {pencircle} attribute looks like:
1749
1750\starttyping
1751withpen pencircle
1752\stoptyping
1753
1754where \type {pencircle} is a special kind of path, stored in a pen variable. Like
1755any path, you can transform it. You can scale it equally in all directions:
1756
1757\starttyping
1758withpen pencircle scaled 1mm
1759\stoptyping
1760
1761You can also provide unequal scales, creating an elliptically shaped and rotated
1762pen.
1763
1764\starttyping
1765withpen pencircle xscaled 2mm yscaled 4mm rotated 30
1766\stoptyping
1767
1768In the following graphic, the circle in the center is drawn without any option,
1769which means that the default pen is used, being a pencircle with a radius of half
1770a base point. The other three circles are drawn with different pen
1771specifications.
1772
1773\startlinecorrection[blank]
1774\startMPcode
1775path p ; p := fullcircle scaled 1cm ;
1776drawoptions (withcolor .625yellow) ;
1777draw p ;
1778drawoptions (withcolor .625red) ;
1779draw p scaled 2 withpen pencircle ;
1780drawoptions (withcolor .625yellow) ;
1781draw p scaled 3 withpen pencircle scaled 1mm ;
1782drawoptions (withcolor .625red) ;
1783draw p scaled 4 withpen pencircle xscaled 2mm yscaled 4mm rotated 30 ;
1784\stopMPcode
1785\stoplinecorrection
1786
1787If you forget about the colors, the \METAPOST\ code to achieve this is as
1788follows.
1789
1790\starttyping
1791path p ; p := fullcircle scaled 1cm ;
1792draw p ;
1793draw p scaled 2 withpen pencircle ;
1794draw p scaled 3 withpen pencircle scaled 1mm ;
1795draw p scaled 4 withpen pencircle xscaled 2mm yscaled 4mm rotated 30 ;
1796\stoptyping
1797
1798If this were the only way of specifying a pen, we would be faced with a
1799considerable amount of typing, particularly in situations where we use pens
1800similar to the fourth specification above. For that reason, \METAPOST\ supports
1801the concept of a current pen. The best way to set this pen is to use the \type
1802{pickup} macro.
1803
1804\starttyping
1805pickup pencircle xscaled 2mm yscaled 4mm rotated 30 ;
1806\stoptyping
1807
1808This macro also stores some characteristics of the pen in variables, so that they
1809can be used in (the more complicated) calculations that are involved in
1810situations like drawing fontlike graphics.
1811
1812If we substitute \type {pencircle} by \type {pensquare}, we get a different kind
1813of shapes. In the non rotated pens, the top, bottom, left and right parts of the
1814curve are thinner.
1815
1816\startlinecorrection[blank]
1817\startMPcode
1818path p ; p := fullcircle scaled 1cm ;
1819drawoptions (withcolor .625yellow) ;
1820draw p ;
1821drawoptions (withcolor .625red) ;
1822draw p scaled 2 withpen pensquare ;
1823drawoptions (withcolor .625yellow) ;
1824draw p scaled 3 withpen pensquare scaled 1mm ;
1825drawoptions (withcolor .625red) ;
1826draw p scaled 4 withpen pensquare xscaled 2mm yscaled 4mm rotated 30 ;
1827\stopMPcode
1828\stoplinecorrection
1829
1830You should look at pens in the way an artist does. He follows a shape and in
1831doing so he or she twists the pen (and thereby the nib) and puts more or less
1832pressure on it.
1833
1834The chance that you have an appropriate pen laying at your desk is not so big,
1835but you can simulate the following \METAPOSTs pen by taking two pencils and
1836holding them together in one hand. If you position them in a 45 degrees angle,
1837and draw a circle, you will get something like:
1838
1839\startlinecorrection[blank]
1840\startMPcode
1841path p ; p := fullcircle xscaled 2cm yscaled 3cm ;
1842drawoptions(withcolor .625red withpen pencircle scaled .5mm);
1843draw p ; draw p shifted (.3cm,.3cm) ;
1844\stopMPcode
1845\stoplinecorrection
1846
1847If you take a calligraphic pen with a thin edge of .5cm, you will get:
1848
1849\startlinecorrection[blank]
1850\startMPcode
1851drawoptions(withcolor .625red);
1852path p ; p := fullcircle xscaled 2cm yscaled 3cm ;
1853draw p withpen makepen ((0,0)--(.3cm,.3cm)) withcolor .625white ;
1854drawoptions(withcolor .625red withpen pencircle scaled .25mm);
1855draw p ; draw p shifted (.3cm,.3cm) ;
1856\stopMPcode
1857\stoplinecorrection
1858
1859You can define such a pen yourself:
1860
1861\starttyping
1862path p ; p := fullcircle xscaled 2cm yscaled 3cm ;
1863pen doublepen ; doublepen := makepen ((0,0)(.3cm,.3cm)) ;
1864pickup doublepen ; draw p ;
1865\stoptyping
1866
1867Here we define a new pen using the \type {pen} command. Then we define a path,
1868and make a pen out of it using the \type {makepen} macro. The path should be a
1869relatively simple one, otherwise \METAPOST\ will complain.
1870
1871You can use \type {makepen} with the previously introduced \type {withpen}:
1872
1873\starttyping
1874draw p withpen makepen ((0,0)(.3cm,.3cm)) ;
1875\stoptyping
1876
1877and \type {pickup}:
1878
1879\starttyping
1880pickup makepen ((0,0)(.3cm,.3cm)) ; draw p ;
1881\stoptyping
1882
1883You can use \type {makepen} and \type {makepath} to convert paths into pens and
1884vice versa.
1885
1886Pens are very important when defining fonts, and \METAFONT\ is meant to be a font
1887creation tool. Since \METAPOST\ has a slightly different audience, it lacks some
1888features in this area, but offers a few others instead. Nevertheless, one can try
1889to design a font using \METAPOST. Of course, pens are among the designers best
1890kept secrets. But even then, not everyO is a nice looking one.
1891
1892\startlinecorrection[blank]
1893\startMPcode
1894path p ; p := fullcircle xscaled 2cm yscaled 3cm ;
1895draw p withpen makepen (unitsquare scaled .4cm superellipsed .85)
1896withcolor .625white ;
1897\stopMPcode
1898\stoplinecorrection
1899
1900\startbuffer[s00]
1901 path p ; p := (1,0) {down} .. {up} (1,0) ;
1902 draw pensilled(p, pensquare scaled (13))
1903 scaled 2cm ;
1904 draw boundingbox image(draw p)
1905 scaled 2cm ;
1906\stopbuffer
1907
1908\startbuffer[s30]
1909 path p ; p := (1,0) {down} .. {up} (1,0) ;
1910 draw pensilled(p, pensquare scaled (13) rotated 30)
1911 scaled 2cm ;
1912 draw boundingbox image(draw p)
1913 scaled 2cm ;
1914\stopbuffer
1915
1916\startbuffer[s45]
1917 path p ; p := (1,0) {down} .. {up} (1,0) ;
1918 draw pensilled(p, pensquare scaled (13) rotated 45)
1919 scaled 2cm ;
1920 draw boundingbox image(draw p)
1921 scaled 2cm ;
1922\stopbuffer
1923
1924\startbuffer[c00]
1925 path p ; p := (1,0) {down} .. {up} (1,0) ;
1926 draw pensilled(p, pencircle scaled (13))
1927 scaled 2cm ;
1928 draw boundingbox image(draw p)
1929 scaled 2cm ;
1930\stopbuffer
1931
1932\startbuffer[c30]
1933 path p ; p := (1,0) {down} .. {up} (1,0) ;
1934 draw pensilled(p, pencircle scaled (13) rotated 30)
1935 scaled 2cm ;
1936 draw boundingbox image(draw p)
1937 scaled 2cm ;
1938\stopbuffer
1939
1940\startbuffer[c45]
1941 path p ; p := (1,0) {down} .. {up} (1,0) ;
1942 draw pensilled(p, pencircle scaled (13) rotated 45)
1943 scaled 2cm ;
1944 draw boundingbox image(draw p)
1945 scaled 2cm ;
1946\stopbuffer
1947
1948\startbuffer[f30]
1949 interim pensilstep := 16 ;
1950 draw pensilled(fullcircle, pencircle xscaled (110) yscaled (210) rotated 30)
1951 scaled 5cm ;
1952 draw boundingbox fullcircle
1953 scaled 5cm ;
1954\stopbuffer
1955
1956The \type {pensilled} macro is a variant on a macro used for testing some border
1957cases in the engine. It provides a nice way to see what actually happens when a
1958pen is applied. \in {Figure} [fig:pensilled] demonstrates this macro. The first
1959row shows a square pen:
1960
1961\typebuffer[s30]
1962
1963and the second row a circular pen:
1964
1965\typebuffer[c30]
1966
1967\startplacefigure[title={How pens are applied.},reference=fig:pensilled]
1968 \startcombination[3*2]
1969 {\processMPbuffer[s00]} {\tttf pensquare rotated 0}
1970 {\processMPbuffer[s30]} {\tttf pensquare rotated 30}
1971 {\processMPbuffer[s45]} {\tttf pensquare rotated 45}
1972 {\processMPbuffer[c00]} {\tttf pencircle rotated 0}
1973 {\processMPbuffer[c30]} {\tttf pencircle rotated 30}
1974 {\processMPbuffer[c45]} {\tttf pencircle rotated 45}
1975 \stopcombination
1976\stopplacefigure
1977
1978The effects of rotation and nonproportional scaling are demonstrated
1979in \in {figure} [fig:pensilled:fullcircle].
1980
1981\typebuffer[f30]
1982
1983\startplacefigure[title={A proportionally scaled and rotated pen.},reference=fig:pensilled:fullcircle]
1984 \processMPbuffer[f30]
1985\stopplacefigure
1986
1987\stopsection
1988
1989\startsection[title={Joining lines}]
1990
1991\index{joining}
1992\index{pathsjoining}
1993
1994The way lines are joined or end is closely related to the way \POSTSCRIPT\
1995handles this. By setting the variables \type {linejoin} and \type {linecap}, you
1996can influence the drawing process. \in {Figure} [fig:joints] demonstrates the
1997alternatives. The gray curves are drawn with both variables set to \type
1998{rounded}.
1999
2000\startnotmode[screen]
2001
2002\def\showMPline#1#2
2003 {\startMPcode
2004 path p ; p := ((0,0)--(.5,1)--(1,0)) xscaled 3cm yscaled 1.5cm ;
2005 pickup pencircle scaled 1cm ;
2006 draw p withcolor .625white ;
2007 interim linejoin := #1 ;
2008 interim linecap := #2 ;
2009 draw p withcolor transparent(1,.5,.625yellow) ;
2010 \stopMPcode}
2011
2012\stopnotmode
2013
2014\startmode[screen]
2015
2016\def\showMPline#1#2
2017 {\startMPcode
2018 path p ; p := ((0,0)--(.5,1)--(1,0)) xscaled 2.5cm yscaled 1.25cm ;
2019 pickup pencircle scaled .75cm ;
2020 draw p withcolor .625white ;
2021 interim linejoin := #1 ;
2022 interim linecap := #2 ;
2023 draw p withcolor transparent(1,.5,.625yellow) ;
2024 \stopMPcode}
2025
2026\stopmode
2027
2028\def\showMPtext#1#2
2029 {linejoin=#1\par linecap=#2}
2030
2031\startbuffer
2032\startcombination[3*3]
2033 {\showMPline{mitered}{butt}} {\showMPtext{mitered}{butt}}
2034 {\showMPline{mitered}{rounded}} {\showMPtext{mitered}{rounded}}
2035 {\showMPline{mitered}{squared}} {\showMPtext{mitered}{squared}}
2036 {\showMPline{rounded}{butt}} {\showMPtext{rounded}{butt}}
2037 {\showMPline{rounded}{rounded}} {\showMPtext{rounded}{rounded}}
2038 {\showMPline{rounded}{squared}} {\showMPtext{rounded}{squared}}
2039 {\showMPline{beveled}{butt}} {\showMPtext{beveled}{butt}}
2040 {\showMPline{beveled}{rounded}} {\showMPtext{beveled}{rounded}}
2041 {\showMPline{beveled}{squared}} {\showMPtext{beveled}{squared}}
2042\stopcombination
2043\stopbuffer
2044
2045\placefigure
2046 [here] [fig:joints]
2047 {The nine ways to end and join lines.}
2048 {\getbuffer}
2049
2050By setting the variable \type {miterlimit}, you can influence the mitering of
2051joints. The next example demonstrates that the value of this variable acts as a
2052trigger.
2053
2054\startbuffer
2055interim linejoin := mitered ;
2056for i :=1 step 1 until 5 :
2057 interim miterlimit := i*pt ;
2058 draw ((0,0)(.5,1)(1,0)) shifted (1.5i,0) scaled 50pt
2059 withpen pencircle scaled 10pt withcolor .625red ;
2060endfor ;
2061\stopbuffer
2062
2063\typebuffer
2064
2065The variables \type {linejoin}, \type {linecap} and \type {miterlimit} are so
2066called {\em internal} variables. When we prefix their assignments by \type
2067{interim}, the setting will be local within groups, like \typ {beginfig ...
2068endfig}.
2069
2070\startlinecorrection[blank]
2071\processMPbuffer
2072\stoplinecorrection
2073
2074\stopsection
2075
2076\startsection[title={Colors}]
2077
2078\index{attributes}
2079\index{color}
2080So far, we have seen some colors in graphics. It must be said that \METAPOST\
2081color model is not that advanced, although playing with colors in the \METAPOST\
2082way can be fun. In later chapters we will discuss some extensions that provide
2083shading.
2084
2085Colors are defined as vectors with three components: a red, green and blue one.
2086Like pens, colors have their \type {with}command:
2087
2088\starttyping
2089withcolor (.4,.5.,6)
2090\stoptyping
2091
2092You can define color variables, like:
2093
2094\starttyping
2095color darkred ; darkred := (.625,0.0) ;
2096\stoptyping
2097
2098You can now use this color as:
2099
2100\starttyping
2101withcolor darkred
2102\stoptyping
2103
2104Given that \type {red} is already defined, we also could have said:
2105
2106\starttyping
2107withcolor .625red
2108\stoptyping
2109
2110Because for \METAPOST\ colors are just vectors, you can do things similar to
2111points. A color halfway red and green is therefore accomplished with:
2112
2113\starttyping
2114withcolor .5[red,green]
2115\stoptyping
2116
2117Since only the \RGB\ color space is supported, this is about all we can tell
2118about colors for this moment. Later we will discuss some nasty details.
2119
2120\stopsection
2121
2122\startsection[title={Dashes}]
2123
2124\index{dashes}
2125
2126A dash pattern is a simple picture that is build out of straight lines. Any
2127slightly more complicated picture will be reduced to straight lines and a real
2128complicated one is rejected, and in this respect \METAPOST\ considers a circle to
2129be a complicated path.
2130
2131The next example demonstrates how to get a dashed line. First we built picture
2132\type {p}, that we apply to a path. Here we use a straight path, but dashing can
2133be applied to any path.
2134
2135\startbuffer
2136picture p ; p := nullpicture ;
2137addto p doublepath ((0,0)(3mm,3mm)) shifted (6mm,6mm) ;
2138draw (0,0)(10cm,0) dashed p withpen pencircle scaled 1mm ;
2139\stopbuffer
2140
2141\typebuffer
2142
2143\startlinecorrection[blank]
2144\processMPbuffer
2145\stoplinecorrection
2146
2147This way of defining a pattern is not that handy, especially if you start
2148wondering why you need to supply a slanted path. Therefore, \METAPOST\ provides a
2149more convenient mechanism to define a pattern.
2150
2151\startbuffer
2152picture p ; p := dashpattern(on 3mm off 3mm) ;
2153draw (0,0)(10cm,0) dashed p withpen pencircle scaled 1mm ;
2154\stopbuffer
2155
2156\typebuffer
2157
2158\startlinecorrection[blank]
2159\processMPbuffer
2160\stoplinecorrection
2161
2162Most dashpatterns can be defined in terms of on and off. This simple onoff
2163dashpattern is predefined as picture \type {evenly}. Because this is a picture,
2164you can (and often need to) scale it.
2165
2166\startbuffer
2167draw (0,0)(10cm,0) dashed (evenly scaled 1mm)
2168 withpen pencircle scaled 1mm ;
2169\stopbuffer
2170
2171\typebuffer
2172
2173\startlinecorrection[blank]
2174\processMPbuffer
2175\stoplinecorrection
2176
2177Opposite to a defaultpen, there is no default color and default dash pattern set.
2178The macro \type {drawoptions} provides you a way to set the default attributes.
2179
2180\starttyping
2181drawoptions(dashed evenly withcolor red) ;
2182\stoptyping
2183
2184Dashes are pretty much bound to the backend in the sense that like line width
2185they are a property that the \POSTSCRIPT\ (or actually nowadays the \PDF)
2186interpreter handles. There is not that much cleverness involved at the \METAPOST\
2187end. Take these examples:
2188
2189\startbuffer
2190 pickup pencircle scaled 2mm ; path p ;
2191
2192 p := (0,0) {dir 25} .. (5cm,0) ;
2193 draw p withcolor darkyellow ;
2194 draw p dashed dashpattern (on 4mm off 3mm) withcolor darkblue ;
2195 drawpoints point 0 of p withcolor white ;
2196
2197 p := ((0,0) {dir 70} .. {up} (5cm,0) .. cycle) yshifted 1cm ;
2198 draw p withcolor darkyellow ;
2199 draw p dashed dashpattern (on 4mm off 3mm) withcolor darkblue ;
2200 drawpoints point 0 of p withcolor white ;
2201\stopbuffer
2202
2203\typebuffer[a]
2204
2205\startlinecorrection[blank]
2206\processMPbuffer
2207\stoplinecorrection
2208
2209In both cases the dash is not evenly spread which for the line results in
2210different begin and end rendering while the closed shape gets some weird looking
2211connection. The next variant uses the \type {withdashes} macro that adapts the
2212dashes to fit nicely to the path.
2213
2214\startbuffer[a]
2215 pickup pencircle scaled 2mm ; path p ;
2216
2217 p := (0,0) {dir 25} .. (5cm,0) ;
2218 draw p withcolor darkyellow ;
2219 draw p withdashes (4mm,3mm) withcolor darkblue ;
2220 drawpoints point 0 of p withcolor white ;
2221
2222 p := ((0,0) {dir 70} .. {up} (5cm,0) .. cycle) yshifted 1cm ;
2223 draw p withcolor darkyellow ;
2224 draw p withdashes (4mm,3mm) withcolor darkblue ;
2225 drawpoints point 0 of p withcolor white ;
2226\stopbuffer
2227
2228\typebuffer
2229
2230\startlinecorrection[blank]
2231\processMPbuffer
2232\stoplinecorrection
2233
2234\stopsection
2235
2236\startsection[reference=sec:text,title={Text}]
2237
2238\index{text}
2239
2240Since \METAFONT\ is meant for designing fonts, the only means for including text
2241are those that permit you to add labels to positions for the sole purpose of
2242documentation.
2243
2244Because \METAPOST\ is derived from \METAFONT\ it provides labels too, but in
2245order to let users add more sophisticated text, like a math formula, to a
2246graphic, it also provides an interface to \TEX.
2247
2248Because we will spend a whole chapter on using text in \METAPOST\ we limit the
2249discussion here to a few fundamentals.
2250
2251\startbuffer[font]
2252defaultfont := "\truefontname{Mono}" ;
2253defaultscale := .8 ;
2254\stopbuffer
2255
2256\startbuffer[label]
2257pair a ; a := (3cm,3cm) ;
2258label.top("top",a) ; label.bot("bot",a) ;
2259label.lft("lft",a) ; label.rt ("rt" ,a) ;
2260\stopbuffer
2261
2262\typebuffer[label]
2263
2264These four labels show up at the position stored in the pair variable \type {a},
2265anchored in the way specified after the period.
2266
2267\startlinecorrection[blank]
2268\processMPbuffer[font,label]
2269\stoplinecorrection
2270
2271The command \type {dotlabel} also typesets the point as a rather visible dot.
2272
2273\startbuffer[label]
2274pair a ; a := (3cm,3cm) ;
2275dotlabel.top("top",a) ; dotlabel.bot("bot",a) ;
2276dotlabel.lft("lft",a) ; dotlabel.rt ("rt" ,a) ;
2277\stopbuffer
2278
2279\typebuffer[label]
2280
2281\startlinecorrection[blank]
2282\processMPbuffer[font,label]
2283\stoplinecorrection
2284
2285The command \type {thelabel} returns the typeset label as picture that you can
2286manipulate or draw afterwards.
2287
2288\startbuffer[label]
2289pair a ; a := (3cm,3cm) ; pickup pencircle scaled 1mm ;
2290drawdot a withcolor .625yellow ;
2291draw thelabel.rt("the right way",a) withcolor .625red ;
2292\stopbuffer
2293
2294\typebuffer[label]
2295
2296You can of course rotate, slant and manipulate such a label picture like any
2297other picture.
2298
2299\startlinecorrection[blank]
2300\processMPbuffer[font,label]
2301\stoplinecorrection
2302
2303The font can be specified in the string \type {defaultfont} and the scale in
2304\type {defaultscale}. Labels are defined using the low level operator \type
2305{infont}. The next statement returns a picture:
2306
2307\startbuffer[mp]
2308draw "this string will become a sequence of glyphs (MP)"
2309 infont defaultfont scaled defaultscale ;
2310\stopbuffer
2311
2312\typebuffer[mp]
2313
2314By default the \type {infont} operator is not that clever and does not apply
2315kerning. Also, typesetting math or accented characters are not supported. The way
2316out of this problem is using \typ {btex ... etex}.
2317
2318\startbuffer[tex]
2319draw btex this string will become a sequence of glyphs (\TeX) etex ;
2320\stopbuffer
2321
2322\typebuffer[tex]
2323
2324The difference between those two methods is shown below. The outcome of \type
2325{infont} depends on the current setting of the variable \type {defaultfont}.
2326
2327\startlinecorrection[blank]
2328\processMPbuffer[mp]
2329\processMPbuffer[tex]
2330\stoplinecorrection
2331
2332When you run inside \CONTEXT\ (as we do here) there is no difference between
2333\type {infont} and the \TEX\ methods. This is because we overload the \type
2334{infont} operator and also pass its content to \TEX. Both \type {infont} and
2335\type {btex} use the macro \type {textext} which is intercepted and redirects the
2336task to \TEX. This happens in the current run so there is no need to pass extra
2337information about fonts.
2338
2339Instead of passing strings to \type {infont}, you can also pass characters, using
2340\type {char}, for example \type {char(73)}. When you use \type {infont} you
2341normally expect the font to be \ASCII\ conforming. If this is not the case, you
2342must make sure that the encoding of the font that you use matches your
2343expectations. However, as we overload this macro it does not really matter since
2344the string is passed to \TEX\ anyway. For instance, \UTF\ encoded text should
2345work fine as \CONTEXT\ itself understands this encoding.
2346
2347\stopsection
2348
2349\startsection[title={Linear equations}]
2350
2351\index{equations}
2352\index{expressions}
2353
2354\startbuffer[a]
2355\defineMPinstance
2356 [solvers]
2357 [format=metafun,
2358 extensions=yes,
2359 initializations=yes]
2360\stopbuffer
2361
2362\startbuffer[b]
2363\startMPdefinitions{solvers}
2364def draw_problem (expr p, q, r, s, show_labels) =
2365 begingroup ; save x, y, a, b, c, d, e, f, g, h ;
2366
2367 z11 = z42 = p ; z21 = z12 = q ; z31 = z22 = r ; z41 = z32 = s ;
2368
2369 a = x12 x11 ; b = y12 y11 ; c = x22 x21 ; d = y22 y21 ;
2370 e = x32 x31 ; f = y32 y31 ; g = x42 x41 ; h = y42 y41 ;
2371
2372 z11 = (x11, y11) ; z12 = (x12, y12) ;
2373 z13 = (x12b, y12a) ; z14 = (x11b, y11a) ;
2374 z21 = (x21, y21) ; z22 = (x22, y22) ;
2375 z23 = (x22d, y22c) ; z24 = (x21d, y21c) ;
2376 z31 = (x31, y31) ; z32 = (x32, y32) ;
2377 z33 = (x32f, y32e) ; z34 = (x31f, y31e) ;
2378 z41 = (x41, y41) ; z42 = (x42, y42) ;
2379 z43 = (x42h, y42g) ; z44 = (x41h, y41g) ;
2380
2381 pickup pencircle scaled .5pt ;
2382
2383 draw z11z12z13z14cycle ; draw z11z13 ; draw z12z14 ;
2384 draw z21z22z23z24cycle ; draw z21z23 ; draw z22z24 ;
2385 draw z31z32z33z34cycle ; draw z31z33 ; draw z32z34 ;
2386 draw z41z42z43z44cycle ; draw z41z43 ; draw z42z44 ;
2387
2388 z1 = 0.5[z11,z13] ; z2 = 0.5[z21,z23] ;
2389 z3 = 0.5[z31,z33] ; z4 = 0.5[z41,z43] ;
2390
2391 draw z1z3 dashed evenly ; draw z2z4 dashed evenly ;
2392
2393 z0 = whatever[z1,z3] = whatever[z2,z4] ;
2394 mark_rt_angle (z1, z0, z2) ;
2395
2396 if show_labels > 0 :
2397 draw_problem_labels ;
2398 fi ;
2399
2400 endgroup ;
2401enddef ;
2402\stopMPdefinitions
2403\stopbuffer
2404
2405\startbuffer[c]
2406\startMPdefinitions{solvers}
2407angle_radius := 10pt ;
2408
2409def mark_rt_angle (expr a, b, c) =
2410 draw ((1,0)--(1,1)--(0,1))
2411 zscaled (angle_radiusunitvector(ab))
2412 shifted b
2413enddef ;
2414\stopMPdefinitions
2415\stopbuffer
2416
2417\startbuffer[d]
2418\startMPdefinitions{solvers}
2419def draw_problem_labels =
2420 pickup pencircle scaled 5pt ;
2421
2422 dotlabel.llft("$Z_{11}$", z11) ; dotlabel.ulft("$Z_{12}$", z12) ;
2423 dotlabel.ulft("$Z_{13}$", z13) ; dotlabel.llft("$Z_{14}$", z14) ;
2424
2425 dotlabel.lrt ("$Z_{21}$", z21) ; dotlabel.llft("$Z_{22}$", z22) ;
2426 dotlabel.urt ("$Z_{23}$", z23) ; dotlabel.ulft("$Z_{24}$", z24) ;
2427
2428 dotlabel.urt ("$Z_{31}$", z31) ; dotlabel.ulft("$Z_{32}$", z32) ;
2429 dotlabel.urt ("$Z_{33}$", z33) ; dotlabel.urt ("$Z_{34}$", z34) ;
2430
2431 dotlabel.lrt ("$Z_{41}$", z41) ; dotlabel.urt ("$Z_{42}$", z42) ;
2432 dotlabel.llft("$Z_{43}$", z43) ; dotlabel.lrt ("$Z_{44}$", z44) ;
2433
2434 dotlabel.urt ("$Z_{0}$", z0) ;
2435 dotlabel.lft ("$Z_{1}$", z1) ; dotlabel.top ("$Z_{2}$", z2) ;
2436 dotlabel.rt ("$Z_{3}$", z3) ; dotlabel.bot ("$Z_{4}$", z4) ;
2437enddef ;
2438\stopMPdefinitions
2439\stopbuffer
2440
2441\startbuffer[e]
2442\startuseMPgraphic{solvers::one}{i,j,s}
2443 draw_problem (
2444 (400pt,400pt), (300pt,600pt),
2445 \MPvar{i}[(300pt,600pt), (550pt,800pt)],
2446 \MPvar{j}[(400pt,400pt), (550pt,500pt)],
2447 \MPvar{s}
2448 ) ;
2449\stopuseMPgraphic
2450\stopbuffer
2451
2452\startbuffer[f]
2453\placefigure
2454 [here][fig:problem]
2455 {The problem.}
2456 {\scale
2457 [width=\textwidth]
2458 {\useMPgraphic{solvers::one}{i=0.6,j=1.0,s=1}}}
2459\stopbuffer
2460
2461In the previous sections, we used the assignment operator \type {:=} to assign a
2462value to a variable. Although for most of the graphics that we will present in
2463later chapters, an assignment is appropriate, specifying a graphic in terms of
2464expressions is not only more flexible, but also more in the spirit of the
2465designers of \METAFONT\ and \METAPOST.
2466
2467The \METAFONT\ book and \METAPOST\ manual provide lots of examples, some of which
2468involve math that we dont consider to belong to everyones repertoire. But, even
2469for non mathematicians using expressions can be a rewarding challenge.
2470
2471The next introduction to linear equations is based on my first experiences with
2472\METAPOST\ and involves a mathematical challenge posed by a friend. I quickly
2473ascertained that a graphical proof was far more easy than some proof with a lot
2474of $\sin (this)$ and $\cos (that)$ and long forgotten formulas.
2475
2476I was expected to prove that the lines connecting the centers of four squares
2477drawn upon the four sides of a quadrilateral were perpendicular (see \in {figure}
2478[fig:problem]).
2479
2480\getbuffer[a,b,c,d,e]
2481
2482\getbuffer[f]
2483
2484This graphic was generated with the following command:
2485
2486\typebuffer[f]
2487
2488We will use this example to introduce a few new concepts, one being instances. In
2489a large document there can be many \METAPOST\ graphics and they might fall in
2490different categories. In this manual we have graphics that are generated as part
2491of the style as wel as examples that show what \METAFUN\ can do. As definitions
2492and variables in \METAPOST\ are global by default, there is a possibility that we
2493end up with clashes. This can be avoided by grouping graphics in instances. Here
2494we create an instance for the example that were about to show.
2495
2496\typebuffer[a]
2497
2498We can now limit the scope of definitions to this specific instance. Lets start
2499with the macro that takes care of drawing the solution to our problem. The macro
2500accepts four pairs of coordinates that determine the central quadrilateral. All
2501of them are expressions.
2502
2503\typebuffer[b]
2504
2505Because we want to call this macro more than once, we first have to save the
2506locally used values. Instead of declaring local variables, one can hide their use
2507from the outside world. In most cases variables behave globally. If we dont save
2508them, subsequent calls will lead to errors due to conflicting equations. We can
2509omit the grouping commands, because we wrap the graphic in a figure, and figures
2510are grouped already.
2511
2512We will use the predefined \type {z} variable, or actually a macro that returns a
2513variable. This variable has two components, an \type {x} and \type {y}
2514coordinate. So, we dont save \type {z}, but the related variables \type {x} and
2515\type {y}.
2516
2517Next we draw four squares and instead of hard coding their corner points, we use
2518\METAPOSTs equation solver. Watch the use of \type {=} which means that we just
2519state dependencies. In languages like \PERL, the equal sign is used in
2520assignments, but in \METAPOST\ it is used to express relations.
2521
2522In a first version, we will just name a lot of simple relations, as we can read
2523them from a sketch drawn on paper. So, we end up with quite some \type {z}
2524related expressions.
2525
2526For those interested in the mathematics behind this code, we add a short
2527explanation. Absolutely key to the construction is the fact that you traverse the
2528original quadrilateral in a clockwise orientation. What is really going on here
2529is vector geometry. You calculate the vector from $z{11}$ to $z{12}$ (the first
2530side of the original quadrilateral) with:
2531
2532\starttyping
2533(a,b) = z12 z11 ;
2534\stoptyping
2535
2536This gives a vector that points from $z{11}$ to $z{12}$. Now, how about an
2537image that shows that the vector $(b,a)$ is a 90 degree rotation in the
2538counterclockwise direction. Thus, the points $z{13}$ and $z{14}$ are easily
2539calculated with vector addition.
2540
2541\starttyping
2542z13 = z12 (b,a) ;
2543z14 = z11 (b,a) ;
2544\stoptyping
2545
2546This pattern continues as you move around the original quadrilateral in a
2547clockwise manner. \footnote {Thanks to David Arnold for this bonus explanation.}
2548
2549The code that calculates the pairs \type {a} through \type {h}, can be written in
2550a more compact way.
2551
2552\starttyping
2553(a,b) = z12 z11 ; (c,d) = z22 z21 ;
2554(e,f) = z32 z31 ; (g,h) = z42 z41 ;
2555\stoptyping
2556
2557The centers of each square can also be calculated by \METAPOST. The next lines
2558define that those points are positioned halfway the extremes.
2559
2560\starttyping
2561z1 = 0.5[z11,z13] ; z2 = 0.5[z21,z23] ;
2562z3 = 0.5[z31,z33] ; z4 = 0.5[z41,z43] ;
2563\stoptyping
2564
2565Once we have defined the relations we can let \METAPOST\ solve the equations.
2566This is triggered when a variable is needed, for instance when we draw the
2567squares and their diagonals. We connect the centers of the squares using a dashed
2568line style.
2569
2570Just to be complete, we add a symbol that marks the right angle. First we
2571determine the common point of the two lines, that lays at {\em whatever} point
2572\METAPOST\ finds suitable.
2573
2574The definition of \type {markrtangle} is copied from the \METAPOST\ manual and
2575shows how compact a definition can be (see \at {page} [zscaled] for an
2576introduction to \type {zscaled}).
2577
2578\typebuffer[c]
2579
2580So far, most equations are rather simple, and in order to solve them, \METAPOST\
2581did not have to work real hard. The only boundary condition is that in order to
2582find a solution, \METAPOST\ must be able to solve all dependencies.
2583
2584The actual value of the \type {whatever} variable is that it saves us from
2585introducing a slew of variables that will never be used again. We could write:
2586
2587\starttyping
2588z0 = A[z1,z3] = B[z2,z4] ;
2589\stoptyping
2590
2591and get the same result, but the \type {whatever} variable saves us the trouble
2592of introducing intermediate variables for which we have no use once the
2593calculation is finished.
2594
2595The macro \type{markrtangle} draws the angle symbol and later we will see how
2596it is defined. First we draw the labels. Unfortunately we cannot package \typ
2597{btex ... etex} into a macro, because it is processed in a rather special way.
2598Each \typ {btex ... etex} occurance is filtered from the source and converted
2599into a snippet of \TEX\ code. When passed through \TEX, each snippet becomes a
2600page, and an auxiliary program converts each page into a \METAPOST\ picture
2601definition, which is loaded by \METAPOST. The limitation lays in the fact that
2602the filtering is done independent from the \METAPOST\ run, which means that loops
2603(and other code) are not seen at all. Later we will introduce the \METAFUN\ way
2604around this.
2605
2606In order to get all the labels typeset, we have to put a lot of code here. The
2607macro \type {dotlabel} draws a dot and places the typeset label.
2608
2609\typebuffer[d]
2610
2611Watch out: as we are in \CONTEXT, we can pass regular \TEX\ code to the label
2612macro. In a standalone \METAPOST\ run youd have to use the \type {btex} variant.
2613
2614We are going to draw a lot of pictures, so we define an extra macro. This time we
2615hardcode some values. The fractions \type {i} and \type {j} are responsible for
2616the visual iteration process, while \type {s} determines the labels. We pass
2617these variables to the graphic using an extra argument. When you define the
2618(useable) graphic you need to tell what variables it can expect.
2619
2620\typebuffer[e]
2621
2622Of course we could have used a loop construct here, but defining auxiliary macros
2623probably takes more time than simply calling the drawing macro directly. The
2624results are shown on a separate page (\in{figure}[fig:solution]).
2625
2626\startbuffer[x]
2627\def\MyTest#1#2
2628 {\scale
2629 [width=.25\textwidth]
2630 {\useMPgraphic{solvers::one}{i=#1,j=#2,s=0}}}
2631\stopbuffer
2632
2633\startbuffer[y]
2634 \startcombination[3*4]
2635 {\MyTest{1.0}{1.0}} {1.0 1.0} {\MyTest{0.8}{1.0}} {0.8 1.0}
2636 {\MyTest{0.6}{1.0}} {0.6 1.0} {\MyTest{0.4}{1.0}} {0.4 1.0}
2637 {\MyTest{0.2}{1.0}} {0.2 1.0} {\MyTest{0.0}{1.0}} {0.0 1.0}
2638 {\MyTest{0.0}{1.0}} {0.0 1.0} {\MyTest{0.0}{0.8}} {0.0 0.8}
2639 {\MyTest{0.0}{0.6}} {0.0 0.6} {\MyTest{0.0}{0.4}} {0.0 0.4}
2640 {\MyTest{0.0}{0.2}} {0.0 0.2} {\MyTest{0.0}{0.0}} {0.0 0.0}
2641 \stopcombination
2642\stopbuffer
2643
2644We will use a helper macro (that saves us typing):
2645
2646\typebuffer[x]
2647
2648We now can say:
2649
2650\typebuffer[y]
2651
2652Watch how we pass the settings to the graphic definition using an extra argument.
2653We force using the \type {solvers} instance by prefixing the name.
2654
2655\startpostponing
2656
2657 \startnotmode[screen]
2658 \placefigure
2659 [here][fig:solution]
2660 {The solution.}
2661 {\getbuffer[x,y]}
2662 \stopnotmode
2663
2664 \startmode[screen]
2665 \placefigure
2666 [here][fig:solution]
2667 {The solution.}
2668 {\getbuffer[x,y]}
2669 \stopmode
2670
2671 \page
2672
2673\stoppostponing
2674
2675It does not need that much imagination to see the four sided problem converge to
2676a three sided one, which itself converges to a two sided one. In the two sided
2677alternative its not that hard to prove that the angle is indeed 90 degrees.
2678
2679As soon as you can see a clear pattern in some code, its time to consider using
2680loops. In the previous code, we used semi indexes, like \type {12} in \type
2681{z12}. In this case \type{12} does reflect something related to square1 and2,
2682but in reality the 12 is just twelve. This does not harm our expressions.
2683
2684A different approach is to use a two dimensional array. In doing so, we can
2685access the variables more easily using loops. If we omit the labels, and angle
2686macro, the previously defined macro can be reduced considerably.
2687
2688\starttyping
2689def drawproblem (expr n, p, q, r, s) =
2690 begingroup ; save x, y ;
2691
2692 z[1][1] = p ; z[2][1] = q ; z[3][1] = r ; z[4][1] = s ;
2693
2694 for i=1 upto 4 :
2695 z[i][1] = (x[i][1],y[i][1]) = z[if i=1: 4 else: i1 fi][2] ;
2696 z[i][2] = (x[i][2],y[i][2]) ;
2697 z[i][3] = (x[i][2]y[i][2]y[i][1], y[i][2]x[i][2]x[i][1]) ;
2698 z[i][4] = (x[i][1]y[i][2]y[i][1], y[i][1]x[i][2]x[i][1]) ;
2699 z[i] = 0.5[z[i][1],z[i][3]] ;
2700 endfor ;
2701
2702 z[0] = whatever[z[1],z[3]] = whatever[z[2],z[4]] ;
2703
2704 pickup pencircle scaled .5pt ;
2705
2706 for i=1 upto 4 :
2707 draw z[i][1]z[i][2]z[i][3]z[i][4]cycle ;
2708 draw z[i][1]z[i][3] ; draw z[i][2]z[i][4] ;
2709 if i<3 : draw z[i]z[i2] dashed evenly fi ;
2710 endfor ;
2711
2712 draw ((1,0)(1,1)(0,1))
2713 zscaled (unitvector(z[1]z[0])*10pt)
2714 shifted z[0] ;
2715
2716 endgroup ;
2717enddef ;
2718\stoptyping
2719
2720I think that we could argue quite some time about the readability of this code.
2721If you start from a sketch, and the series of equations does a good job, there is
2722hardly any need for such improvements to the code. On the other hand, there are
2723situations where the simplified (reduced) case can be extended more easily, for
2724instance to handle 10 points instead of4. It all depends on how you want to
2725spend your free hours.
2726
2727\stopsection
2728
2729\startsection[title={Clipping}]
2730
2731\index{clipping}
2732
2733For applications that do something with a drawing, for instance \TEX\ embedding a
2734graphic in a text flow, it is important to know the dimensions of the graphic.
2735The maximum dimensions of a graphic are specified by its bounding box.
2736
2737\startlinecorrection[blank]
2738\startMPcode
2739path p ; p := fullcircle scaled 3cm ;
2740draw p withpen pencircle scaled 1mm withcolor .625red ;
2741draw boundingbox p withpen pencircle scaled .1mm ;
2742draw llcorner boundingbox p withpen pencircle scaled 2mm withcolor .625yellow ;
2743draw urcorner boundingbox p withpen pencircle scaled 2mm withcolor .625yellow ;
2744\stopMPcode
2745\stoplinecorrection
2746
2747A bounding box is defined by its lower left and upper right corners. If you open
2748the \POSTSCRIPT\ file produced by \METAPOST, you may find lines like:
2749
2750\starttyping
2751
2752\stoptyping
2753
2754or, when supported,
2755
2756\starttyping
2757
2758\stoptyping
2759
2760The first two numbers define the lower left corner and the last two numbers the
2761upper right corner. From these values, you can calculate the width and height of
2762the graphic.
2763
2764A graphic may extend beyond its bounding box. It depends on the application that
2765uses the graphic whether that part of the graphic is shown.
2766
2767In \METAPOST\ you can ask for all four points of the bounding box of a path or
2768picture as well as the center.
2769
2770\starttabulate[lTl]
2771\HL
2772\NC llcorner p \NC lower left corner \NC \NR
2773\NC lrcorner p \NC lower right corner \NC \NR
2774\NC urcorner p \NC upper right corner \NC \NR
2775\NC ulcorner p \NC upper left corner \NC \NR
2776\NC center p \NC the center point \NC \NR
2777\HL
2778\stoptabulate
2779
2780You can construct the bounding box of path\type {p} out of the four points
2781mentioned:
2782
2783\starttyping
2784llcorner p lrcorner p urcorner p ulcorner p cycle
2785\stoptyping
2786
2787You can set the bounding box of a picture, which can be handy if you want to
2788build a picture in steps and show the intermediate results using the same
2789dimensions as the final picture, or when you want to show only a small piece.
2790
2791\startbuffer
2792fill fullcircle scaled 2cm withcolor .625yellow ;
2793setbounds currentpicture to unitsquare scaled 1cm ;
2794draw unitsquare scaled 1cm withcolor .625red ;
2795\stopbuffer
2796
2797\typebuffer
2798
2799Here, we set the bounding box with the command \type {setbounds}, which takes a
2800path.
2801
2802\startlinecorrection[blank]
2803\processMPbuffer
2804\stoplinecorrection
2805
2806The graphic extends beyond the bounding box, but the bounding box determines the
2807placement and therefore the spacing around the graphic. We can get rid of the
2808artwork outside the bounding box by clipping it.
2809
2810\startbuffer
2811fill fullcircle scaled 2cm withcolor .625yellow ;
2812clip currentpicture to unitsquare scaled 1cm ;
2813\stopbuffer
2814
2815\typebuffer
2816
2817The resulting picture is just as large but shows less of the picture.
2818
2819\startlinecorrection[blank]
2820\processMPbuffer
2821\stoplinecorrection
2822
2823\stopsection
2824
2825\startsection[title={Some extensions}]
2826
2827We will now encounter a couple of transformations that can make your life easy
2828when you use \METAPOST\ for making graphics like the ones demonstrated in this
2829document. These transformations are not part of standard \METAPOST, but come with
2830\METAFUN.
2831
2832A very handy extension is \type {enlarged}. Although you can feed it with any
2833path, it will return a rectangle larger or smaller than the boundingbox of that
2834path. You can specify a pair or a numeric.
2835
2836\startbuffer
2837path p ; p := fullsquare scaled 2cm ;
2838drawpath p ; drawpoints p ;
2839p := (p shifted (3cm,0)) enlarged (.5cm,.25cm) ;
2840drawpath p ; drawpoints p ;
2841\stopbuffer
2842
2843\typebuffer
2844
2845\startlinecorrection[blank] \processMPbuffer \stoplinecorrection
2846
2847There are a few more alternatives, like \type {bottomenlarged}, \type
2848{rightenlarged}, \type {topenlarged} and \type {leftenlarged}.
2849
2850The \type {cornered} operator will replace sharp corners by rounded ones (we
2851could not use \type {rounded} because this is already in use).
2852
2853\startbuffer
2854path p ; p := ((1,0)(2,0)(2,2)(1,2)(0,1)cycle)
2855 xysized (4cm,2cm) ;
2856drawpath p ; drawpoints p ;
2857p := (p shifted (5cm,0)) cornered .5cm ;
2858drawpath p ; drawpoints p ;
2859\stopbuffer
2860
2861\typebuffer
2862
2863\startlinecorrection[blank] \processMPbuffer \stoplinecorrection
2864
2865The \type {smoothed} operation is a less subtle one, since it operates on the
2866bounding box and thereby can result in a different shape.
2867
2868\startbuffer
2869path p ; p := ((1,0)(2,0)(2,2)cycle) xysized (4cm,2cm) ;
2870drawpath p ; drawpoints p ;
2871p := (p shifted (5cm,0)) smoothed .5cm ;
2872drawpath p ; drawpoints p ;
2873\stopbuffer
2874
2875\typebuffer
2876
2877\startlinecorrection[blank] \processMPbuffer \stoplinecorrection
2878
2879The next one, \type {simplified}, can be applied to paths that are constructed
2880automatically. Instead of testing for duplicate points during construction, you
2881can clean up the path afterwards.
2882
2883\startbuffer
2884path p ; p :=
2885 ((0,0)(1,0)(2,0)(2,1)(2,2)(1,2)(0,2)(0,1)cycle)
2886 xysized (4cm,2cm) ;
2887drawpath p ; drawpoints p ;
2888p := simplified (p shifted (5cm,0)) ;
2889drawpath p ; drawpoints p ;
2890\stopbuffer
2891
2892\typebuffer
2893
2894\startlinecorrection[blank] \processMPbuffer \stoplinecorrection
2895
2896A cousin of the previous operation is \type {unspiked}. This one removes ugly
2897leftovers. It works well for the average case.
2898
2899\startbuffer
2900path p ; p :=
2901 ((0,0)(2,0)(3,1)(2,0)(2,2)(1,2)(1,3)(1,2)(0,1)cycle)
2902 xysized (4cm,2cm) ;
2903drawpath p ; drawpoints p ;
2904p := unspiked (p shifted (5cm,0)) ;
2905drawpath p ; drawpoints p ;
2906\stopbuffer
2907
2908\typebuffer
2909
2910\startlinecorrection[blank] \processMPbuffer \stoplinecorrection
2911
2912There are a couple of operations that manipulate the path in more drastic ways.
2913Take \type {randomized}.
2914
2915\startbuffer
2916path p ; p := fullsquare scaled 2cm ;
2917drawpath p ; drawpoints p ;
2918p := (p shifted (5cm,0)) randomized .5cm ;
2919drawpath p ; drawpoints p ;
2920\stopbuffer
2921
2922\typebuffer
2923
2924\startlinecorrection[blank] \processMPbuffer \stoplinecorrection
2925
2926Or how about \type {squeezed}:
2927
2928\startbuffer
2929path p ; p := fullsquare scaled 2cm randomized .5cm ;
2930drawpath p ; drawpoints p ;
2931p := (p shifted (5cm,0)) squeezed .5cm ;
2932drawpath p ; drawpoints p ;
2933\stopbuffer
2934
2935\typebuffer
2936
2937\startlinecorrection[blank] \processMPbuffer \stoplinecorrection
2938
2939A \type {punked} path is, like a punked font, a font with less smooth curves (in
2940our case, only straight lines).
2941
2942\startbuffer
2943path p ; p := fullcircle scaled 2cm randomized .5cm ;
2944drawpath p ; drawpoints p ;
2945p := punked (p shifted (5cm,0)) ;
2946drawpath p ; drawpoints p ;
2947\stopbuffer
2948
2949\typebuffer
2950
2951\startlinecorrection[blank] \processMPbuffer \stoplinecorrection
2952
2953A \type {curved} path on the other hand has smooth connections. Where in many
2954cases a punked path becomes smaller, a curved path will be larger.
2955
2956\startbuffer
2957path p ; p := fullsquare scaled 2cm randomized .5cm ;
2958drawpath p ; drawpoints p ;
2959p := curved (p shifted (5cm,0)) ;
2960drawpath p ; drawpoints p ;
2961\stopbuffer
2962
2963\typebuffer
2964
2965\startlinecorrection[blank] \processMPbuffer \stoplinecorrection
2966
2967Probably less usefull (although we use it in one of the \OPENTYPE\ visualizers)
2968is \type {laddered}:
2969
2970\startbuffer
2971path p ; p := fullcircle scaled 3cm ;
2972drawpath p ; drawpoints p ;
2973p := laddered (p shifted (5cm,0)) ;
2974drawpath p ; drawpoints p ;
2975\stopbuffer
2976
2977\typebuffer
2978
2979\startlinecorrection[blank] \processMPbuffer \stoplinecorrection
2980
2981When writing \PPCHTEX\ (that can be used to draw chemical structure formulas) I
2982needed a parallelizing macro, so here it is:
2983
2984\startbuffer
2985path p ; p := fullcircle scaled 3cm ;
2986drawpath p ; drawpoints p ;
2987p := p paralleled 1cm ;
2988drawpath p ; drawpoints p ;
2989\stopbuffer
2990
2991\typebuffer
2992
2993\startlinecorrection[blank] \processMPbuffer \stoplinecorrection
2994
2995If you use a negative argument (like \type {1cm}) the parallel line will be
2996drawn at the other side.
2997
2998The \type {blownup} operation scales the path but keeps the center in the same
2999place.
3000
3001\startbuffer
3002path p ; p := fullsquare xyscaled (4cm,1cm) randomized .5cm ;
3003drawpath p ; drawpoints p ;
3004p := p blownup .5cm ;
3005drawpath p ; drawpoints p ;
3006\stopbuffer
3007
3008\typebuffer
3009
3010\startlinecorrection[blank] \processMPbuffer \stoplinecorrection
3011
3012The \type {shortened} operation also scales the path but only makes it longer or
3013shorter. This macro only works on straight paths.
3014
3015\startbuffer
3016path p ; p := (0,0) (2cm,3cm) ;
3017drawpath p ; drawpoints p ;
3018p := p shortened 1cm ;
3019drawpath p ; drawpoints p ;
3020p := p shortened 1cm ;
3021drawpath p ; drawpoints p ;
3022\stopbuffer
3023
3024\typebuffer
3025
3026\startlinecorrection[blank] \processMPbuffer \stoplinecorrection
3027
3028Here are a few more drawing helpers. Even if you dont need them you might at
3029some point take a look at their definitions to see what happens there. First we
3030give a square round corners with \type {roundedsquare}:
3031
3032\startbuffer
3033path p ; p := roundedsquare(2cm,4cm,.25cm) ;
3034drawpath p ; drawpoints p ;
3035\stopbuffer
3036
3037\typebuffer
3038
3039\startlinecorrection[blank] \processMPbuffer \stoplinecorrection
3040
3041Next we draw a squarelike circle (or circlelike square) using \type
3042{tensecircle}:
3043
3044\startbuffer
3045path p ; p := tensecircle(2cm,4cm,.25cm) ;
3046drawpath p ; drawpoints p ;
3047\stopbuffer
3048
3049\typebuffer
3050
3051\startlinecorrection[blank] \processMPbuffer \stoplinecorrection
3052
3053Often I make such helpers in the process of writing larger drawing systems. Take
3054\type {crossed}:
3055
3056\startbuffer
3057path p ; p := origin crossed 1cm ;
3058drawpath p ; drawpoints p ;
3059p := (origin crossed fullcircle scaled 2cm crossed .5cm) shifted (3cm,0) ;
3060drawpath p ; drawpoints p ;
3061\stopbuffer
3062
3063\typebuffer
3064
3065These examples demonstrate that a path is made up out of points (something that
3066you probably already knew by now). The \METAPOST\ operator \type {of} can be used
3067to \quote {access} a certain point at a curve.
3068
3069\startbuffer
3070path p ; p := fullsquare xyscaled (3cm,2cm) randomized .5cm ;
3071drawpath p ; drawpoints p ; drawpointlabels p ;
3072draw point 2.25 of p withpen pencircle scaled 5mm withcolor .625red ;
3073\stopbuffer
3074
3075\typebuffer
3076
3077\startlinecorrection[blank] \processMPbuffer \stoplinecorrection
3078
3079To this we add two more operators: \type {on} and \type {along}. With \type {on}
3080you get the point at the supplied distance from point0; with \type {along} you
3081get the point at the fraction of the length of the path.
3082
3083\startbuffer
3084path p, q, r ;
3085p := fullsquare xyscaled (2cm,2cm) randomized .5cm ;
3086q := p shifted (3cm,0) ; r := q shifted (3cm,0) ;
3087drawpath p ; drawpoints p ; drawpointlabels p ;
3088drawpath q ; drawpoints q ; drawpointlabels q ;
3089drawpath r ; drawpoints r ; drawpointlabels r ;
3090pickup pencircle scaled 5mm ;
3091draw point 2.25 of p withcolor .625red ;
3092draw point 2.50cm on q withcolor .625yellow ;
3093draw point .45 along r withcolor .625white ;
3094\stopbuffer
3095
3096\typebuffer
3097
3098Beware: the \type {length} of a path is the number of points minus one. The
3099shapes below are constructed from 5points and a length of4. If you want the
3100length as dimension, you should use \type {arclength}.
3101
3102\startlinecorrection[blank] \processMPbuffer \stoplinecorrection
3103
3104We will now play a bit with simple lines. With \type {cutends}, you can (indeed)
3105cut off the ends of a curve. The specification is a dimension.
3106
3107\startbuffer
3108path p ; p := (0cm,0cm) (4cm,1cm) ;
3109path q ; q := (5cm,0cm){right} .. (9cm,1cm) ;
3110drawpath p ; drawpoints p ; drawpath q ; drawpoints q ;
3111p := p cutends .5cm ; q := q cutends .5cm ;
3112drawpathoptions (withpen pencircle scaled 5pt withcolor .625yellow) ;
3113drawpointoptions(withpen pencircle scaled 4pt withcolor .625red) ;
3114drawpath p ; drawpoints p ; drawpath q ; drawpoints q ;
3115resetdrawoptions ;
3116\stopbuffer
3117
3118\typebuffer
3119
3120\startlinecorrection[blank] \processMPbuffer \stoplinecorrection
3121
3122As with more operators, \type {cutends} accepts a numeric or a pair. Watch the
3123subtle difference between the next and the previous use of \type {cutends}.
3124
3125\startbuffer
3126path p ; p := (0cm,0) .. (4cm,0) .. (8cm,0) .. (4cm,0) .. cycle ;
3127drawpath p ; drawpoints p ; p := p cutends (2cm,1cm) ;
3128drawpathoptions (withpen pencircle scaled 5pt withcolor .625yellow) ;
3129drawpointoptions(withpen pencircle scaled 4pt withcolor .625red) ;
3130drawpath p ; drawpoints p ;
3131resetdrawoptions ;
3132\stopbuffer
3133
3134\typebuffer
3135
3136\startlinecorrection[blank] \processMPbuffer \stoplinecorrection
3137
3138When \type {stretched} is applied to a path, it is scaled but the starting point
3139(point0) keeps its location. The specification is a scale.
3140
3141\startbuffer
3142path p ; p := (0cm,0) .. (3cm,1cm) .. (4cm,0) .. (5cm,1cm) ;
3143drawpath p ; drawpoints p ; p := p stretched 1.1 ;
3144drawpathoptions (withpen pencircle scaled 2.5pt withcolor .625yellow) ;
3145drawpointoptions(withpen pencircle scaled 4.0pt withcolor .625red) ;
3146drawpath p ; drawpoints p ; resetdrawoptions ;
3147\stopbuffer
3148
3149\typebuffer
3150
3151\startlinecorrection[blank] \processMPbuffer \stoplinecorrection
3152
3153We can scale in two directions independently or even in one direction by
3154providing a zero value. In the next example we apply the stretch two times.
3155
3156\startbuffer
3157path p ; p := (0cm,0) .. (3cm,1cm) .. (4cm,0) .. (5cm,1cm) ;
3158drawpath p ; drawpoints p ; p := p stretched (.75,1.25) ;
3159drawpathoptions (withpen pencircle scaled 2.5pt withcolor .625yellow) ;
3160drawpointoptions(withpen pencircle scaled 4.0pt withcolor .625red) ;
3161drawpath p ; drawpoints p ; p := p stretched (0,1.5) ;
3162drawpathoptions (withpen pencircle scaled 4.0pt withcolor .625red) ;
3163drawpointoptions(withpen pencircle scaled 2.5pt withcolor .625yellow) ;
3164drawpath p ; drawpoints p ; resetdrawoptions ;
3165\stopbuffer
3166
3167\typebuffer
3168
3169\startlinecorrection[blank] \processMPbuffer \stoplinecorrection
3170
3171We already met the \type {randomize} operator. This one is the chameleon under
3172the operators.
3173
3174\startbuffer
3175draw fullsquare xyscaled (4cm,2cm)
3176 randomized .25cm
3177 shifted origin randomized (1cm, 2cm)
3178 withcolor red randomized (.625, .850)
3179 withpen pencircle scaled (5pt randomized 1pt) ;
3180\stopbuffer
3181
3182\typebuffer
3183
3184So, \type {randomized} can handle a numeric, pair, path and color, and its
3185specification can be a numeric, pair or color, depending on what were dealing
3186with.
3187
3188\startlinecorrection[blank] \processMPbuffer \stoplinecorrection
3189
3190In the previous example we also see \type {xyscaled} in action. Opposite to \type
3191{scaled}, \type {xscaled} and \type {yscaled}, this is not one of \METAPOST\
3192build in features. The same is true for the \type {.sized} operators.
3193
3194\startbuffer[a]
3195picture p ; p := image
3196 ( draw fullsquare
3197 xyscaled (300,800)
3198 withpen pencircle scaled 50
3199 withcolor .625 yellow ; ) ;
3200draw p xysized (3cm,2cm) shifted (bbwidth(currentpicture).5cm,0) ;
3201draw p xysized 2cm shifted (bbwidth(currentpicture).5cm,0) ;
3202draw p xsized 1cm shifted (bbwidth(currentpicture).5cm,0) ;
3203draw p ysized 2cm shifted (bbwidth(currentpicture).5cm,0) ;
3204\stopbuffer
3205
3206\typebuffer[a]
3207
3208\startlinecorrection[blank] \processMPbuffer[a] \stoplinecorrection
3209
3210Here, the \type {image} macro creates an (actually rather large) picture. The
3211last four lines actually draw this picture, but at the given dimensions. Watch
3212how the line width scales accordingly. If you dont want this, you can add the
3213following line:
3214
3215\startbuffer[b]
3216redraw currentpicture withpen pencircle scaled 2pt ;
3217draw boundingbox currentpicture withpen pencircle scaled .5mm ;
3218\stopbuffer
3219
3220\typebuffer[b]
3221
3222Watch how the boundingbox is not affected:
3223
3224\startlinecorrection[blank] \processMPbuffer[a,b] \stoplinecorrection
3225
3226In this example we also used \type {bbwidth} (which has a companion macro \type
3227{bbheight}). You can apply this macro to a path or a picture.
3228
3229In fact you dont always need to follow this complex route if you want to simply
3230redraw a path with another pen or color.
3231
3232\startbuffer
3233draw fullcircle scaled 1cm
3234 withcolor .625red withpen pencircle scaled 1mm ;
3235draw currentpicture
3236 withcolor .625yellow withpen pencircle scaled 3mm ;
3237draw boundingbox currentpicture
3238 withpen pencircle scaled .5mm ;
3239\stopbuffer
3240
3241\typebuffer
3242
3243This is what you will get from this:
3244
3245\startlinecorrection[blank] \processMPbuffer \stoplinecorrection
3246
3247If you want to add a background color to a picture you can do that afterwards.
3248This can be handy when you dont know in advance what size the picture will have.
3249
3250\startbuffer
3251fill fullcircle scaled 1cm withcolor .625red ;
3252addbackground withcolor .625 yellow ;
3253\stopbuffer
3254
3255\typebuffer
3256
3257The background is just a filled rectangle that gets the same size as the current
3258picture, that is put on top of it.
3259
3260\startlinecorrection[blank] \processMPbuffer \stoplinecorrection
3261
3262\stopsection
3263
3264\startsection[title={Cutting and pasting}]
3265
3266\index{pathscutting}
3267\index{cutting}
3268
3269When enhancing or building a graphic, often parts of already constructed paths
3270are needed. The \type {subpath}, \type {cutbefore} and \type {cutafter} operators
3271can be used to split paths in smaller pieces. In order to do so, we must know
3272where we are on the path that is involved. For this we use points on the path.
3273Unfortunately we can only use these points when we know where they are located.
3274In this section we will combine some techniques discussed in previous sections.
3275We will define a few macros, manipulate some paths and draw curves and points.
3276
3277\startbuffer
3278path p ; p := fullcircle yscaled 3cm xscaled .9TextWidth ;
3279drawpath p ; drawpoints p withcolor .625red ; drawpointlabels p ;
3280\stopbuffer
3281
3282\startlinecorrection[blank]
3283\processMPbuffer
3284\stoplinecorrection
3285
3286This circle is drawn by scaling the predefined path \type {fullcircle}. This path
3287is constructed using 8points. As you can see, these points are not distributed
3288equally along the path. In the following graphic, the second and third point of
3289the curve are colored red, and point 2.5 is colored yellow. Point0 is marked in
3290black. This point is positioned halfway between point2 and3.
3291
3292\startbuffer
3293path p ; p := fullcircle scaled 3cm xscaled 2 ;
3294pickup pencircle scaled 5mm ; autoarrows := true ;
3295drawarrow p withcolor .625white ;
3296draw point 0.0 of p ;
3297draw point 2.0 of p withcolor .625red ;
3298draw point 2.5 of p withcolor .625yellow ;
3299draw point 3.0 of p withcolor .625red ;
3300\stopbuffer
3301
3302\startlinecorrection[blank]
3303\processMPbuffer
3304\stoplinecorrection
3305
3306It is clear that, unless you know exactly how the path is constructed, other
3307methods should be available. A specific point on a path is accessed by \typ
3308{point ... of}, but the next example demonstrates two more alternatives.
3309
3310\startbuffer
3311path p ; p := fullcircle scaled 3cm xscaled 2 ;
3312pickup pencircle scaled 5mm ;
3313draw p withcolor .625white ;
3314draw point 3 of p withcolor .625red ;
3315draw point .6 along p withcolor .625yellow ;
3316draw point 3cm on p ;
3317\stopbuffer
3318
3319\typebuffer
3320
3321So, in addition to \type {on} to specify a point by number (in \METAPOST\
3322terminology called time), we have \type {along} to specify a point as fraction of
3323the path, and \type {on} to specify the position in a dimension.
3324
3325\startlinecorrection[blank]
3326\processMPbuffer
3327\stoplinecorrection
3328
3329The \type {on} and \type {along} operators are macros and can be defined as:
3330
3331\starttyping
3332primarydef len on pat =
3333 (arctime len of pat) of pat
3334enddef ;
3335
3336primarydef pct along pat =
3337 (arctime (pct * (arclength pat)) of pat) of pat
3338enddef ;
3339\stoptyping
3340
3341These macros introduce two new primitives, \type {arctime} and \type {arclength}.
3342While \type {arctime} returns a number denoting the time of the point on the
3343path, \type {arclength} returns a dimension.
3344
3345\quotation {When mathematicians draw parametric curves, they frequently need to
3346indicate the direction of motion. I often have need of a little macro that will
3347put an arrow of requested length, anchored at a point on the curve, and bending
3348with the curve in the direction of motion.}
3349
3350When David Arnold asked me how this could be achieved, the fact that a length was
3351requested meant that the solution should be sought in using the primitives and
3352macros we introduced a few paragraphs before. Say that we want to call for such
3353an arrow as follows.
3354
3355\startbuffer[a]
3356path p ; p := fullcircle scaled 3cm ;
3357pair q ; q := point .4 along p ;
3358pickup pencircle scaled 2mm ;
3359draw p withcolor .625white ;
3360drawarrow somearrow(p,q,2cm) withcolor .625red ;
3361draw q withcolor .625yellow ;
3362\stopbuffer
3363
3364\typebuffer[a]
3365
3366Because we want to follow the path, we need to construct the arrow from this
3367path. Therefore, we first reduce the path by cutting off the part before the
3368given point. Next we cut off the end of the resulting path so that we keep a
3369slice that has the length that was asked for. Since we can only cut at points, we
3370determine this point using the \type {arctime} primitive.
3371
3372\startbuffer[b]
3373vardef somearrow (expr pat, loc, len) =
3374 save p ; path p ; p := pat cutbefore loc ;
3375 (p cutafter point (arctime len of p) of p)
3376enddef ;
3377\stopbuffer
3378
3379\typebuffer[b]
3380
3381By using a \type {vardef} we hide the intermediate assignments. Such \type
3382{vardef} is automatically surrounded by \type {begingroup} and \type {endgroup},
3383so the \type {save} is local to this macro. When processed, this code produces
3384the following graphic:
3385
3386\startbuffer[c]
3387autoarrows := true ;
3388\stopbuffer
3389
3390\startlinecorrection[blank]
3391\processMPbuffer[c,b,a]
3392\stoplinecorrection
3393
3394This graphic shows that we need a bit more control over the exact position of the
3395arrow. It would be nice if we could start the arrow at the point, or end there,
3396or center the arrow around the point. Therefore, the real implementation is a bit
3397more advanced.
3398
3399\startbuffer
3400vardef pointarrow (expr pat, loc, len, off) =
3401 save l, r, s, t ; path l, r ; numeric s ; pair t ;
3402 t := if pair loc : loc else : point loc along pat fi ;
3403 s := len2 off ; if s<=0 : s := 0 elseif s>len : s := len fi ;
3404 r := pat cutbefore t ;
3405 r := (r cutafter point (arctime s of r) of r) ;
3406 s := len2 off ; if s<=0 : s := 0 elseif s>len : s := len fi ;
3407 l := reverse (pat cutafter t) ;
3408 l := (reverse (l cutafter point (arctime s of l) of l)) ;
3409 (l..r)
3410enddef ;
3411\stopbuffer
3412
3413\typebuffer
3414
3415This code fragment also demonstrates how we can treat the \type {loc} argument as
3416pair (coordinates) or fraction of the path. We calculate the piece of path before
3417and after the given point separately and paste them afterwards as \type {(l..r)}.
3418By adding braces we can manipulate the path in expressions without the danger of
3419handling \type {r} alone.
3420
3421We can now implement left, center and right arrows by providing this macro the
3422right parameters. The offset (the fourth parameter), is responsible for a
3423backward displacement. This may seem strange, but negative values would be even
3424more confusing.
3425
3426\startbuffer
3427def rightarrow (expr p,t,l) = pointarrow(p,t,l,l) enddef ;
3428def leftarrow (expr p,t,l) = pointarrow(p,t,l,l) enddef ;
3429def centerarrow(expr p,t,l) = pointarrow(p,t,l, 0) enddef ;
3430\stopbuffer
3431
3432\typebuffer
3433
3434We can now apply this macro as follows:
3435
3436\startbuffer[a]
3437path p ; p := fullcircle scaled 3cm ;
3438pickup pencircle scaled 2mm ;
3439draw p withcolor .625white ;
3440drawarrow leftarrow (p, .4 ,2cm) withcolor .625red ;
3441drawarrow centerarrow(p,point 5 of p,2cm) withcolor .625yellow ;
3442draw point .4 along p withcolor .625yellow ;
3443draw point 5 of p withcolor .625red ;
3444\stopbuffer
3445
3446\typebuffer[a]
3447
3448\startlinecorrection[blank]
3449\processMPbuffer[a]
3450\stoplinecorrection
3451
3452Watch how we can pass a point (\typ {point 5 of p}) as well as a fraction (\type
3453{.4}). The following graphic demonstrates a few more alternatives.
3454
3455\startbuffer[a]
3456pickup pencircle scaled 2mm; autoarrows := true ;
3457
3458path p ; p := fullcircle yscaled 3cm xscaled .9TextWidth ;
3459
3460draw p withcolor .5white;
3461
3462for i=1, 2, 3 :
3463 drawdot point i of p withpen pencircle scaled 5mm withcolor .625white ;
3464endfor ;
3465for i=.60, .75, .90 :
3466 drawdot point i along p withpen pencircle scaled 5mm withcolor .625white ;
3467endfor ;
3468\stopbuffer
3469
3470\startbuffer[b]
3471drawarrow leftarrow (p,point 1 of p,2cm) withcolor red ;
3472drawarrow centerarrow (p,point 2 of p,2cm) withcolor blue ;
3473drawarrow rightarrow (p,point 3 of p,2cm) withcolor green ;
3474drawarrow pointarrow (p,.60,4cm,.5cm) withcolor yellow ;
3475drawarrow pointarrow (p,.75,3cm,.5cm) withcolor cyan ;
3476drawarrow centerarrow (p,.90,3cm) withcolor magenta ;
3477\stopbuffer
3478
3479\startlinecorrection[blank]
3480\processMPbuffer[a,b]
3481\stoplinecorrection
3482
3483The arrows are drawn using the previously defined macros. Watch the positive and
3484negative offsets in call to \type {pointarrow}.
3485
3486\typebuffer[b]
3487
3488\stopsection
3489
3490\startsection[title={Current picture}]
3491
3492\index {pictures}
3493
3494When you draw paths, texts andor pictures they are added to the so called
3495current picture. You can manipulate this current picture as is demonstrated in
3496this manual. Lets show a few current picture related tricks.
3497
3498\startbuffer
3499 draw fullcircle scaled 1cm withpen pencircle scaled 1mm withcolor .625red ;
3500\stopbuffer
3501
3502\typebuffer \startlinecorrection[blank] \processMPbuffer \stoplinecorrection
3503
3504We can manipulate the picture as a whole:
3505
3506\startbuffer
3507 draw fullcircle scaled 1cm withpen pencircle scaled 1mm withcolor .625red ;
3508 currentpicture := currentpicture slanted .5 ;
3509\stopbuffer
3510
3511\typebuffer \startlinecorrection[blank] \processMPbuffer \stoplinecorrection
3512
3513Sometimes its handy to temporarily set aside the current picture.
3514
3515\startbuffer
3516 draw fullcircle scaled 1cm withpen pencircle scaled 1mm withcolor .625red ;
3517 currentpicture := currentpicture slanted .5 ;
3518 pushcurrentpicture ;
3519 draw fullcircle scaled 1cm withpen pencircle scaled 1mm withcolor .625yellow ;
3520 currentpicture := currentpicture slanted .5 ;
3521 popcurrentpicture ;
3522\stopbuffer
3523
3524\typebuffer \startlinecorrection[blank] \processMPbuffer \stoplinecorrection
3525
3526These are \METAFUN\ commands but \METAPOST\ itself comes with a variant, \type
3527{image}, and you explicitly have to draw this picture (or otherwise add it to the
3528currentpicture).
3529
3530\startbuffer
3531 draw fullcircle scaled 1cm withpen pencircle scaled 1mm withcolor .625red ;
3532 currentpicture := currentpicture slanted .5 ;
3533 draw image (
3534 draw fullcircle scaled 1cm
3535 withpen pencircle scaled 1mm withcolor .625yellow ;
3536 currentpicture := currentpicture slanted .5 ;
3537 ) ;
3538\stopbuffer
3539
3540\typebuffer \startlinecorrection[blank] \processMPbuffer \stoplinecorrection
3541
3542Each graphic starts fresh with an empty current picture. In \METAFUN\ we make
3543sure that we also reset some otherwise global variables, like color, pen and some
3544line properties.
3545
3546\stopsection
3547
3548\startsection[title={\UTF8}]
3549
3550The \METAPOST\ library used in \LUATEX\ and \LUAMETATEX\ supports \UTF8\ input.
3551Actually there is not much magic needed to do this because all the engine in
3552interested in is bytes and some just have a special meaning (like parenthesis,
3553symbols that have a meaning in formulas etc).
3554
3555\startbuffer
3556save p ; pen p ; p := currentpen ;
3557pickup pencircle scaled .05;
3558
3559picture ○ ; ○ := image (draw fullcircle) ;
3560picture ◎ ; ◎ := image (draw fullcircle ; draw fullcircle scaled .5) ;
3561
3562draw ◎ ysized 2cm withcolor darkblue ;
3563draw ○ xsized 2cm shifted (3cm,0) withcolor darkgreen ;
3564draw ○ xysized (3cm,2cm) shifted (7cm,0) withcolor darkred ;
3565\stopbuffer
3566
3567\typebuffer
3568
3569Here we use a \UTF8\ encoded character as macro name and the next image
3570demonstrate that it does work indeed:
3571
3572\startlinecorrection[blank] \processMPbuffer \stoplinecorrection
3573
3574You can do crazy things like use emoji for special operators
3575
3576\startbuffer
3577def ✏ = withpen pencircle enddef ;
3578def ✖️ = scaled enddef ;
3579fill fullsquare ✖️ 1cm ✏ ✖️ 1mm withcolor darkgray ;
3580draw fullsquare ✖️ 1cm ✏ ✖️ 1mm withcolor darkblue ;
3581\stopbuffer
3582
3583\typebuffer
3584
3585But do we really want to go there?
3586
3587\startlinecorrection[blank] \processMPbuffer \stoplinecorrection
3588
3589Normally using \UTF8\ makes more sense in text or regular macro names, so if you
3590want to use accented characters it is possible:
3591
3592\startbuffer
3593def rændömîzèd = randomized 110 enddef ;
3594
3595draw textext ("\strut rændömîzèd") ;
3596draw boundingbox currentpicture rændömîzèd
3597 enlarged 2mm
3598 withpen pencircle scaled 1mm
3599 withcolor darkgreen ;
3600\stopbuffer
3601
3602\typebuffer
3603
3604\page[preference]
3605
3606it really does work:
3607
3608\startlinecorrection[blank] \processMPbuffer \stoplinecorrection
3609
3610\stopsection
3611
3612\stopchapter
3613
3614\stopcomponent
3615 |