% language=us runpath=texruns:manuals/metafun \startcomponent metafun-basics \environment metafun-environment \startchapter[title={A few more details}] \startintro In this chapter we will see how to define a \METAPOST\ graphic, and how to include it in a document. Since the exact dimensions of graphics play an important role in the placement of a graphic, we will explore the way a bounding box is constructed. We will also pay attention to the usage of units and the side effects of scaling and shifting, since they can contradict our expectations in unexpected ways. Furthermore we will explore a few obscure areas. \stopintro \startsection[title={Making graphics}] \index{graphics} In this manual we will use \METAPOST\ in a rather straightforward way, and we will try to avoid complicated math as much as possible. We will do a bit of drawing, clipping, and moving around. Occasionally we will see some more complicated manipulations. When defined as stand||alone graphic, a \METAPOST\ file looks like this: \starttyping % Let's draw a circle. beginfig (7) ; draw fullcircle scaled 3cm withpen pencircle scaled 1cm ; endfig ; end . \stoptyping The main structuring components in such a file are the \type {beginfig} and \type {endfig} macros. Like in a big story, the file has many sub||sentences, where each sub||sentence ends with a semi||colon. Although the \type {end} command at the end of the file concludes the story, putting a period there is a finishing touch. Actually, after the \type {end} command you can put whatever text you wish, your comments, your grocery list, whatever. Comments in \METAPOST, prefixed by a percent sign, as in \typ {% Let's draw a circle}, are ignored by the interpreter, but useful reminders for the programmer. Traditionally, if the file is saved as \type {yourfile.mp}, then the file is processed by \METAPOST\ by issuing the following command: \starttyping mpost yourfile \stoptyping after which you will have a graphic called \type {yourfile.7}, which contains a series of \POSTSCRIPT\ commands. Because \METAPOST\ does all the work, this file is efficient and compact. The number of distinct \POSTSCRIPT\ operators used is limited, which has the advantage that we can postprocess this file rather easily. Alternatively \METAPOST\ can generate \SVG\ output. It does when you say \starttyping outputformat := "svg" ; \stoptyping Here we will not go into details about this format. Even \POSTSCRIPT\ is not covered in detail as we use \METAPOST\ mostly in embedded form. We can view this file in a \POSTSCRIPT\ viewer like \GHOSTVIEW\ or convert the graphic to \PDF\ (using \type {mptopdf}) and view the result in a suitable \PDF\ viewer like \ACROBAT. Of course, you can embed such a file in a \CONTEXT\ document, using a command like: \starttyping \externalfigure[yourfile.7] \stoptyping We will go in more detail about embedding graphics in \in {chapter} [sec:embedding]. If you have installed \CONTEXT, somewhere on your system there resides a file \type {mp-tool.mp}. If you make a stand||alone graphic, it's best to put the following line at the top of your file: \starttyping input metafun ; \stoptyping By loading this file, the resulting graphic will provide a high resolution bounding box, which enables more accurate placement. The file also sets the \typ {prologues := 1} so that viewers like \GHOSTVIEW\ can refresh the file when it is changed. {\bf However!} When you use \METAPOST\ in \CONTEXT, you will not run the mentioned program at all: you embed your graphic in the document and we will discuss this later. You can still use separate files but then you process them as follows: \starttyping mtxrun --script metapost somefile.mp \stoptyping Alternatively you can wrap the individual pictures in a \TEX\ file, say \type {yourfile.tex}: \starttyping \starttext \startMPpage % code \stopMPpage \startMPpage % code \stopMPpage \stoptext \stoptyping and then run: \starttyping context somefile.tex \stoptyping after which you can use the resulting \PDF\ file (if it has more pages you just filter the page from that file). Next we will introduce some more \METAPOST\ commands. From now on, we will omit the encapsulating \type {beginfig} and \type {endfig} macros. If you want to process these examples yourself, you should add those commands yourself, or if you use \CONTEXT\ you don't need them at all. You can for instance wrap them in a \type {\startMPpage} \unknown\ \type {\stopMPpage} environment if you want to play around. \startbuffer pickup pencircle scaled .5cm ; draw unitsquare xscaled 8cm yscaled 1cm withcolor .625white ; draw origin withcolor .625yellow ; pickup pencircle scaled 1pt ; draw bbox currentpicture withcolor .625red ; \stopbuffer \typebuffer In this example we see a mixture of so called primitives as well as macros. A primitive is something hard coded, a built||in command, while a macro is a collection of such primitives, packaged in a way that they can be recalled easily. Where \type {scaled} is a primitive and \type {draw} a macro, \type {unitsquare} is a path variable, an abbreviation for: \starttyping unitsquare = (0,0) -- (1,0) -- (1,1) -- (0,1) -- cycle ; \stoptyping The double dash (\type {--}) is also a macro, used to connect two points with a straight line segment. However, \type {cycle} is a primitive, which connects the last point of the unitsquare to the first on unitsquare's path. Path variables must first be declared, as in: \starttyping path unitsquare ; \stoptyping A large collection of such macros is available when you launch \METAPOST. Consult the \METAPOST\ manual for details. \startlinecorrection[blank] \processMPbuffer \stoplinecorrection In the first line of our example, we set the drawing pen to \type {.5cm}. You can also specify such a dimension in other units, like points (\type {pt}). When no unit is provided, \METAPOST\ will use a big point (\type {bp}) , the \POSTSCRIPT\ approximation of a point. The second line does just as it says: it draws a rectangle of certain dimensions in a certain color. In the third line we draw a colored dot at the origin of the coordinate system in which we are drawing. Finally, we set up a smaller pen and draw the bounding box of the current picture, using the variable \type {currentpicture}. Normally, all drawn shapes end up in this picture variable. \stopsection \startsection[title={Bounding boxes}] \index{boundingbox} If you take a close look at the last picture in the previous section, you will notice that the bounding box is larger than the picture. This is one of the nasty side effects of \METAPOST's \type {bbox} macro. This macro draws a box, but with a certain offset. The next example shows how we can manipulate this offset. Personally I never use the \type {bbox} macro because this offset is rather annoying. Also, the \type {boundingbox} operator combined with \type {enlarged} can provide any offset you want. \startbuffer pickup pencircle scaled .5cm ; draw unitsquare xscaled 8cm yscaled 1cm withcolor .625white ; path bb ; bboxmargin := 0pt ; bb := bbox currentpicture ; draw bb withpen pencircle scaled 1pt withcolor .625red ; draw origin withpen pencircle scaled 5pt withcolor .625yellow ; \stopbuffer \typebuffer In the third line we define a path variable. We assign the current bounding box to this variable, but first we set the offset to zero. The last line demonstrates how to draw such a path. Instead of setting the pen as we did in the first line, we pass the dimensions directly. \startlinecorrection[blank] \processMPbuffer \stoplinecorrection Where \type {draw} draws a path, the \type {fill} macro fills one. In order to be filled, a path should be closed, which is accomplished by the \type {cycle} primitive, as we saw in constructing the \type {unitsquare} path. \startbuffer pickup pencircle scaled .5cm ; fill unitsquare xscaled 8cm yscaled 1cm withcolor .625white ; path bb ; bboxmargin := 0pt ; bb := bbox currentpicture ; draw bb withpen pencircle scaled 1pt withcolor .625red ; draw origin withpen pencircle scaled 5pt withcolor .625yellow ; \stopbuffer \typebuffer This example demonstrates that when we fill the path, the resulting graphic is smaller. Where \type {draw} follows the center of a path, \type {fill} stays inside the path. \startlinecorrection[blank] \processMPbuffer \stoplinecorrection A third alternative is the \type {filldraw} macro. From the previous examples, we would expect a bounding box that matches the one of the drawn path. \startbuffer pickup pencircle scaled .5cm ; filldraw unitsquare xscaled 8cm yscaled 1cm withcolor .625white ; path bb ; bboxmargin := 0pt ; bb := bbox currentpicture ; draw bb withpen pencircle scaled 1pt withcolor .625red ; draw origin withpen pencircle scaled 5pt withcolor .625yellow ; \stopbuffer \typebuffer % The resulting graphic has the bounding box of the fill. Note % how the path, because it is stroked with a .5cm pen, extends % beyond the border of the bounding box. The way this image % shows up depends on the viewer (settings) you use to render % the graphic. For example, in \GHOSTVIEW, if you disable % clipping to the bounding box, only the positive quadrant of % the graphic is shown. Further, if you enable clipping to the % bounding box, this image will look exactly like the previous % image created with the fill command. In many cases, it may % be best to avoid the \type {filldraw} command. The resulting graphic has the bounding box of the fill. Note how the path, because it is stroked with a .5cm pen, extends beyond the border of the previous bounding box. The way this image shows up depends on the viewer (settings) you use to render the graphic. For example, in \GHOSTVIEW, if you disable clipping to the bounding box, only the positive quadrant of the graphic is shown. \footnote {Old versions of \METAPOST\ calculated the boundingbox differently for a \type {filldraw}: through the middle of the penpath.} \startlinecorrection[blank] \processMPbuffer \stoplinecorrection From the previous examples, you can conclude that the following alternative results in a proper bounding box: \startbuffer pickup pencircle scaled .5cm ; path p ; p := unitsquare xscaled 8cm yscaled 1cm ; fill p withcolor .625white ; draw p withcolor .625white ; path bb ; bboxmargin := 0pt ; bb := bbox currentpicture ; draw bb withpen pencircle scaled 1pt withcolor .625red ; draw origin withpen pencircle scaled 5pt withcolor .625yellow ; \stopbuffer \typebuffer \startlinecorrection[blank] \processMPbuffer \stoplinecorrection The \CONTEXT\ distribution comes with a set of \METAPOST\ modules, one of which contains the \type {drawfill} macro, which provides the outer bounding box. \footnote {Starting from version 1.0 \METAPOST\ calculates the boundingbox differently and the distinction between \type {drawfill} and \type {filldraw} is gone. We keep them around both for compatibility.} Next we demonstrate its use in another, more complicated example. \startbuffer picture finalpicture ; finalpicture := nullpicture ; numeric n ; n := 0 ; bboxmargin := 0pt ; pickup pencircle scaled .5cm ; def shape = unitsquare scaled 2cm withcolor .625white ; draw bbox currentpicture withpen pencircle scaled .5mm withcolor .625red ; addto finalpicture also currentpicture shifted(n*3cm,0) ; currentpicture := nullpicture ; n := n+1 ; enddef ; fill shape ; draw shape ; filldraw shape ; drawfill shape ; currentpicture := finalpicture ; \stopbuffer \typebuffer Here we introduce a macro definition, \type {shape}. In \METAPOST, the start of a macro definition is indicated with the keyword \type {def}. Thereafter, you can insert other variables and commands, even other macro definitions. The keyword \type {enddef} signals the end of the macro definition. The result is shown in \in {figure} [fig:draws and fills]; watch the bounding boxes. Close reading of the macro will reveal that the \type {fill}, \type {draw}, \type {filldraw} and \type {drawfill} macros are applied to the first \type {unitsquare} path in the macro. \placefigure [here] [fig:draws and fills] {A \type {fill}, \type {draw}, \type {filldraw} and \type {drawfill} applied to the same square.} {\processMPbuffer} In this macro, \type {bbox} calls a macro that returns the enlarged bounding box of a path. By setting \type {bboxmargin} we can influence how much the bounding box is enlarged. Since this is an existing variable, we don't have to allocate it, like we do with~\type{numeric n}. Unless you take special precautions, variables are global by nature and persistent outside macros. \starttyping picture finalpicture ; finalpicture := nullpicture ; \stoptyping Just as \type {numeric} allocates an integer variable, the \type {picture} primitive allocates a picture data structure. We explicitly have to set this picture to nothing using the built||in primitive \type {nullpicture}. Later on, we will add the drawn paths as accumulated in \type {currentpicture} to this \type {finalpicture} in the following manner. \starttyping addto finalpicture also currentpicture shifted(n*3cm,0) ; \stoptyping Since we want to add a few more and don't want them to overlap, we shift them. Therefore we have to erase the current picture as well as increment the shift counter. \starttyping currentpicture := nullpicture ; n := n+1 ; \stoptyping The \type {drawfill} macro is one of the \METAFUN\ macros. Another handy macro is \type {boundingbox}. When used instead of \type {bbox}, you don't have to set the margin to zero. \startbuffer drawoptions (withcolor .625white) ; path p ; p := unitsquare scaled 2cm ; fill p shifted (3cm,0) ; pickup pencircle scaled .5cm ; fill p shifted (6cm,0) ; fill p shifted (9cm,0) withpen pencircle scaled .5cm ; \stopbuffer \placefigure [here] [fig:more draws and fills] {The influence of pens on \type {fill}.} {\processMPbuffer} There is a subtle point in filling a shape. In \in {figure} [fig:more draws and fills] you see the influence of the pen on a \type {fill} operation. An indirect specification has no influence, and results in a filled rectangle with sharp corners. The third rectangle is drawn with a direct pen specification which results in a larger shape with rounds corners. However, the bounding box is the same in all three cases. The graphic is defined as follows. This time we don't use a (complicated) macro. \typebuffer When a graphic is constructed, its components end up in an internal data structure in a more or less layered way. This means that as long as a graphic is not flushed, you may consider it to be a stack of paths and texts with the paths being drawn or filled shapes or acting as clipping paths or bounding boxes. When you ask for the dimensions of a graphic the lower left and upper right corner are calculated using this stack. Because you can explicitly set bounding boxes, you can lie about the dimensions of a graphic. This is a very useful feature. In the rare case that you want to know the truth and nothing but the truth, you can tweak the \type {truecorners} numeric variable. We will demonstrate this with a few examples. \startbuffer fill fullcircle scaled 1cm withcolor .625yellow ; \stopbuffer \typebuffer \startlinecorrection[blank]\ruledhbox{\processMPbuffer}\stoplinecorrection \startbuffer fill fullcircle scaled 1cm withcolor .625yellow ; setbounds currentpicture to boundingbox currentpicture enlarged 2mm ; \stopbuffer \typebuffer \startlinecorrection[blank]\ruledhbox{\processMPbuffer}\stoplinecorrection \startbuffer fill fullcircle scaled 1cm withcolor .625yellow ; setbounds currentpicture to boundingbox currentpicture enlarged 2mm ; interim truecorners := 1 ; \stopbuffer \typebuffer \startlinecorrection[blank]\ruledhbox{\processMPbuffer}\stoplinecorrection \startbuffer fill fullcircle scaled 1cm withcolor .625yellow ; interim truecorners := 1 ; setbounds currentpicture to boundingbox currentpicture enlarged 2mm ; \stopbuffer \typebuffer \startlinecorrection[blank]\ruledhbox{\processMPbuffer}\stoplinecorrection As you can see here, as soon as we set \type {truecorners} to~1, the bounding box settings are ignored. \footnote {Normally you will use grouping to keep the interim local. In \METAFUN\ each figure restores this variable at the beginning.} There are two related macros: \type {bbwidth} and \type {bbheight} that you can apply to a path. \startbuffer fill unitcircle xscaled 4cm yscaled 2cm withpen pencircle scaled 1mm withcolor .625red ; draw origin -- (bbwidth(currentpicture),0) withpen pencircle scaled 1mm withcolor .625yellow ; draw origin -- (0,bbheight(currentpicture)) withpen pencircle scaled 1mm withcolor .625white ; \stopbuffer \typebuffer \startlinecorrection[blank]\processMPbuffer\stoplinecorrection \stopsection Yet another helper is \type {boundingcircle}. Its effect can best be demonstrated with a few examples: \startbuffer[a] path p ; p := fullsquare scaled 2cm ; draw p withpen pencircle scaled 3mm withcolor .625white ; draw center p withpen pencircle scaled 3mm withcolor .625white ; draw boundingbox p withpen pencircle scaled 1mm withcolor .625red ; draw boundingcircle p withpen pencircle scaled 1mm withcolor .625yellow ; \stopbuffer \startbuffer[b] path p ; p := fullcircle scaled 2cm ; draw p withpen pencircle scaled 3mm withcolor .625white ; draw center p withpen pencircle scaled 3mm withcolor .625white ; draw boundingbox p withpen pencircle scaled 1mm withcolor .625red ; draw boundingcircle p withpen pencircle scaled 1mm withcolor .625yellow ; \stopbuffer \startbuffer[c] path p ; p := fulltriangle scaled 2cm ; draw p withpen pencircle scaled 3mm withcolor .625white ; draw center p withpen pencircle scaled 3mm withcolor .625white ; draw boundingbox p withpen pencircle scaled 1mm withcolor .625red ; draw boundingcircle p withpen pencircle scaled 1mm withcolor .625yellow ; \stopbuffer \typebuffer[a,b,c] You can consider the \type {boundingcircle} to be a round boundingbox. \startlinecorrection[blank] \startcombination[nx=3,ny=1,location=middle] {\processMPbuffer[a]} {square} {\processMPbuffer[b]} {circle} {\processMPbuffer[c]} {triangle} \stopcombination \stoplinecorrection \startsection[title={Units}] \index{units} Like \TEX, \METAPOST\ supports multiple units of length. In \TEX, these units are hard coded and handled by the parser, where the internal unit of length is the scaled point (\type {sp}), something on the nanometer range. Because \METAPOST\ is focused on \POSTSCRIPT\ output, its internal unit is the big point (\type {bp}). All other units are derived from this unit and available as numeric instead of hard coded. \starttyping mm = 2.83464 ; pt = 0.99626 ; dd = 1.06601 ; bp := 1 ; cm = 28.34645 ; pc = 11.95517 ; cc = 12.79213 ; in := 72 ; \stoptyping Careful reading reveals that only the \type {bp} and \type {in} are fixed, while the rest of the dimensions are scalar multiples of \type {bp}. Since we are dealing with graphics, the most commonly used dimensions are \type {pt}, \type {bp}, \type {mm}, \type {cm} and~\type {in}. \startuseMPgraphic{pt} fill fullsquare scaled 72.27pt withcolor .625yellow ; fill fullcircle scaled 72.27pt withcolor white ; label("72.27pt", center currentpicture) ; \stopuseMPgraphic \startuseMPgraphic{bp} fill fullsquare scaled 72bp withcolor .625yellow ; fill fullcircle scaled 72bp withcolor white ; label("72bp", center currentpicture) ; \stopuseMPgraphic \startuseMPgraphic{mm} fill fullsquare scaled 25.4mm withcolor .625yellow ; fill fullcircle scaled 25.4mm withcolor white ; label("25.4mm", center currentpicture) ; \stopuseMPgraphic \startuseMPgraphic{cm} fill fullsquare scaled 2.54cm withcolor .625yellow ; fill fullcircle scaled 2.54cm withcolor white ; label("2.54cm", center currentpicture) ; \stopuseMPgraphic \startuseMPgraphic{in} fill fullsquare scaled 1in withcolor .625yellow ; fill fullcircle scaled 1in withcolor white ; label("1in", center currentpicture) ; \stopuseMPgraphic \startlinecorrection[blank] \hbox to \hsize {\useMPgraphic{pt}\hss \useMPgraphic{bp}\hss \useMPgraphic{mm}\hss \useMPgraphic{cm}\hss \useMPgraphic{in}} \stoplinecorrection The text in the center of the leftmost graphic is typeset by \METAPOST\ as a label. \starttyping fill fullsquare scaled 72.27pt withcolor .625yellow ; fill fullcircle scaled 72.27pt withcolor white ; label("72.27pt", center currentpicture) ; \stoptyping In \METAPOST\ the following lines are identical: \starttyping draw fullcircle scaled 100 ; draw fullcircle scaled 100bp ; \stoptyping You might be tempted to omit the unit, but this can be confusing, particularly if you also program in a language like \METAFONT, where the \type {pt} is the base unit. This means that a circle scaled to 100 in \METAPOST\ is not the same as a circle scaled to 100 in \METAFONT. Consider the next definition: \startbuffer pickup pencircle scaled 0 ; fill unitsquare xscaled 400pt yscaled -.5cm withcolor .625red ; fill unitsquare xscaled 400bp yscaled +.5cm withcolor .625yellow ; drawoptions(withcolor white) ; label.rt("400 pt", origin shifted (0, -.25cm)) ; label.rt("400 bp", origin shifted (0, +.25cm)) ; \stopbuffer \typebuffer When processed, the difference between a \type {pt} and \type {bp} shows rather well. Watch how we use \type {.rt} to move the label to the right; you can compare this with \TEX's macro \type {\rlap}. You might want to experiment with \type {.lft}, \type {.top}, \type {.bot}, \type {.ulft}, \type {.urt}, \type {.llft} and \type {.lrt}. The difference between both bars is exactly \scratchdimen = 400 bp \advance\scratchdimen by -400 pt \the \scratchdimen \space (as calculated by \TEX). \startlinecorrection[blank] \processMPbuffer \stoplinecorrection Where \TEX\ is anchored in tradition, and therefore more or less uses the \type {pt} as the default unit, \METAPOST, much like \POSTSCRIPT, has its roots in the computer sciences. There, to simplify calculations, an inch is divided in 72 big points, and .72pt is sacrificed. When you consider that \POSTSCRIPT\ is a high end graphic programming language, you may wonder why this sacrifice was made. Although the difference between \type {1bp} and \type {1pt} is miniscule, this difference is the source of much (unknown) confusion. When \TEX\ users talk about a \type {10pt} font, a desktop publisher hears \type {10bp}. In a similar vein, when we define a papersize having a width of \type {600pt} and a height of \type {450pt}, which is papersize \type {S6} in \CONTEXT, a \POSTSCRIPT\ or \PDF\ viewer will report slightly smaller values as page dimensions. This is because those programs claim the \type {pt} to be a \type {bp}. [This confusion can lead to interesting discussions with desktop publishers when they have to use \TEX. They often think that their demand of a baseline distance of \type {13.4} is met when we set it to \type {13.4pt}, while actually they were thinking of \type {13.4bp}, which of course in other programs is specified using a \type {pt} suffix.] Therefore, when embedding graphics in \CONTEXT, we strongly recommend that you use \type {pt} as the base unit instead. The main reason why we spend so many words on this issue is that, when neglected, large graphics may look inaccurate. Actually, when taken care of, it is one of the (many) reasons why \TEX\ documents always look so accurate. Given that the eye is sensitive to distortions of far less than \type {1pt}, you can be puzzled by the fact that many drawing programs only provide a bounding box in rounded units. Thereby, they round to the next position, to prevent unwanted cropping. For some reason this low resolution has made it into the high end \POSTSCRIPT\ standard. In \CONTEXT\ we try to deal with these issues as well as possible. \stopsection \startsection[title={Scaling and shifting}] \index{scaling} \index{shifting} When we draw a shape, \METAPOST\ will adapt the bounding box accordingly. This means that a graphic has its natural dimensions, unless of course we adapt the bounding box manually. When you limit your graphic to a simple shape, say a rectangle, shifting it to some place can get obscured by this fact. Therefore, the following series of shapes appear to be the same. \startbuffer draw unitsquare xscaled 6cm yscaled 1.5cm withpen pencircle scaled 2mm withcolor .625red ; \stopbuffer \typebuffer \startlinecorrection[blank]\processMPbuffer\stoplinecorrection \startbuffer draw unitsquare shifted (.5,.5) xscaled 6cm yscaled 1.5cm withpen pencircle scaled 2mm withcolor .625red ; \stopbuffer \typebuffer \startlinecorrection[blank]\processMPbuffer\stoplinecorrection \startbuffer draw unitsquare shifted (-.5,-.5) xscaled 6cm yscaled 1.5cm withpen pencircle scaled 2mm withcolor .625red ; \stopbuffer \typebuffer \startlinecorrection[blank]\processMPbuffer\stoplinecorrection \startbuffer draw unitsquare xscaled 6cm yscaled 1.5cm shifted (1cm,1cm) withpen pencircle scaled 2mm withcolor .625red ; \stopbuffer \typebuffer \startlinecorrection[blank]\processMPbuffer\stoplinecorrection \startbuffer draw unitsquare xscaled 6cm yscaled 1.5cm shifted (1.5cm,1cm) withpen pencircle scaled 2mm withcolor .625red ; \stopbuffer \typebuffer \startlinecorrection[blank]\processMPbuffer\stoplinecorrection However, when we combine such graphics into one, we will see in what respect the scaling and shifting actually takes place. \startbuffer draw unitsquare xscaled 6cm yscaled 2cm withpen pencircle scaled 3.0mm withcolor .625yellow ; draw unitsquare shifted (.5,.5) xscaled 6cm yscaled 2cm withpen pencircle scaled 3.0mm withcolor .625red ; draw unitsquare xscaled 6cm yscaled 2cm shifted (1cm,1cm) withpen pencircle scaled 3.0mm withcolor .625white ; draw unitsquare xscaled 6cm yscaled 2cm shifted (1.5cm,1cm) withpen pencircle scaled 1.5mm withcolor white ; draw unitsquare shifted (-.5,-.5) xscaled 6cm yscaled 2cm withpen pencircle scaled 1mm withcolor black ; draw origin withpen pencircle scaled 1mm ; \stopbuffer \typebuffer \startlinecorrection[blank]\processMPbuffer\stoplinecorrection As you can see, the transformations are applied in series. Sometimes this is not what we want, in which case we can use parentheses to force the desired behaviour. The lesson learned is that {\em scaling and shifting} is not always the same as {\em shifting and scaling}. \startbuffer draw origin -- origin shifted ((4cm,0cm) shifted (4cm,0cm)) withpen pencircle scaled 1cm withcolor .625white ; draw origin -- origin shifted (4cm,0cm) shifted (4cm,0cm) withpen pencircle scaled 8mm withcolor .625yellow ; draw (origin -- origin shifted (4cm,0cm)) shifted (4cm,0cm) withpen pencircle scaled 6mm withcolor .625red ; draw origin -- (origin shifted (4cm,0cm) shifted (4cm,0cm)) withpen pencircle scaled 4mm withcolor white ; \stopbuffer \typebuffer \startlinecorrection[blank]\processMPbuffer\stoplinecorrection Especially when a path results from a call to a macro, using parentheses around a path may help, as in the following example. \startbuffer def unitslant = origin -- origin shifted (1,1) enddef ; draw unitslant xscaled 5cm yscaled 1cm withpen pencircle scaled 1cm withcolor .625red ; draw (unitslant) xscaled 5cm yscaled 1cm withpen pencircle scaled 5mm withcolor .625yellow ; \stopbuffer \typebuffer \startlinecorrection[blank]\processMPbuffer\stoplinecorrection The next definition of \type {unitslant} is therefore better. \startbuffer def unitslant = (origin -- origin shifted (1,1)) enddef ; draw unitslant xscaled 5cm yscaled 1cm withpen pencircle scaled 5mm withcolor .625red ; \stopbuffer \typebuffer \startlinecorrection[blank]\processMPbuffer\stoplinecorrection An even better alternative is: \startbuffer path unitslant ; unitslant = origin -- origin shifted (1,1) ; draw unitslant xscaled 5cm yscaled 1cm withpen pencircle scaled 5mm withcolor .625yellow ; \stopbuffer \typebuffer \startlinecorrection[blank] \processMPbuffer \stoplinecorrection \stopsection \startsection[title={Curve construction}] \index{curves} \doifmodeelse{screen} {\def\Xcom{3}\def\Ycom{2}\def\Zcom{\the\textheight}} {\def\Xcom{2}\def\Ycom{3}\def\Zcom{\the\textwidth }} Chapter 3 of the \METAFONT\ book explains the mathematics behind the construction of curves. Both \METAFONT\ and \METAPOST\ implement Bézier curves. The fact that these curves are named after Pierre Bézier obscures the fact that the math behind them originates with Sergeĭ Bernshteĭn. The points on the curve are determined by the following formula: \placeformula[-] \startformula z(t) = (1-t)^3 z_1 + 3 (1-t)^2 t z_2 + 3 (1-t) t^2 z_3 + t^3 z_4 \stopformula Here, the parameter $t$ runs from $[0,1]$. As you can see, we are dealing with four points. In practice this means that when we construct a curve from multiple points, we act on two points and the two control points in between. So, the segment that goes from $z_1$ to $z_4$ is calculated using these two points and the points that \METAFONT|/|\METAPOST\ calls post control point and pre control point. \startbuffer[a] vardef dodrawmidpoints (expr a, b, c, d, n, col, m) = save e, f, g, h, i, j ; pair e, f, g, h, i, j ; e := .5[a,b] ; f := .5[b,c] ; g := .5[c,d] ; h := .5[e,f] ; i := .5[f,g] ; j := .5[h,i] ; if m= 0 : drawpoints j elseif m= 1 : draw a--b--c--d elseif m= 2 : draw e--f--g elseif m= 3 : draw h--i elseif m= 4 : draw a--e--h--j elseif m= 5 : draw j--i--g--d elseif m=11 : drawpoints a--b--c--d elseif m=12 : drawpoints e--f--g elseif m=13 : drawpoints h--i elseif m=14 : drawpoints a--e--h--j elseif m=15 : drawpoints j--i--g--d fi withcolor col ; if n>1 : dodrawmidpoints(a, e, h, j, n-1, col, m) ; dodrawmidpoints(j, i, g, d, n-1, col, m) ; fi ; enddef ; vardef drawmidpoints (expr p, n, col, m) = save a, b, c, d ; pair a, b, c, d ; for x=0 upto length(p)-1 : a := point x of p ; b := postcontrol x of p ; d := point x+1 of p ; c := precontrol x+1 of p ; dodrawmidpoints(a,b,c,d,n,col,m) ; endfor ; enddef ; \stopbuffer \startbuffer[b] path p ; p := (4cm,4cm)..(6cm,0cm)..(1cm,2cm) ; \stopbuffer \startbuffer[c] drawpath p ; drawcontrollines p withcolor .625yellow ; drawcontrolpoints p withcolor .625red ; drawpoints p withcolor .625red ; freelabel(btex $z_1$ etex, point 0 of p, center p) ; freelabel(btex $z_2$ etex, postcontrol 0 of p, center p) ; freelabel(btex $z_3$ etex, precontrol 1 of p, center p) ; freelabel(btex $z_4$ etex, point 1 of p, center p) ; freelabel(btex $z_5$ etex, postcontrol 1 of p, center p) ; freelabel(btex $z_6$ etex, precontrol 2 of p, center p) ; freelabel(btex $z_7$ etex, point 2 of p, center p) ; \stopbuffer \startbuffer[x] draw boundingbox p enlarged 1cm ; setbounds currentpicture to boundingbox p enlarged 1cm ; currentpicture := currentpicture xsized (.45*\Zcom) ; \stopbuffer \startlinecorrection[blank] \processMPbuffer[a,b,c,x] \stoplinecorrection The previous curve is constructed from the three points $z_1$, $z_4$ and $z_7$. The curve is drawn in \METAPOST\ by \type {z1..z4..z7} and is made up out of two segments. The first segment is determined by the following points: \startitemize[packed,n] \item point $z_1$ of the curve \item the postcontrol point $z_2$ of $z_1$ \item the precontrol point $z_3$ of $z_4$ \item point $z_4$ of the curve \stopitemize On the next pages we will see how the whole curve is constructed from these quadruples of points. The process comes down to connecting the mid points of the straight lines to the points mentioned. We do this three times, which is why these curves are classified as third order approximations. The first series of graphics demonstrates the process of determining the mid points. The third order midpoint is positioned on the final curve. The second series focuses on the results: new sets of four points that will be used in a next stage. The last series only shows the third order midpoints. As you can see, after some six iterations we have already reached a rather good fit of the final curve. The exact number of iterations depends on the resolution needed. You will notice that the construction speed (density) differs per segment. \startpostponing % cc .. hh in order to avoid conflicts with c-... \startbuffer[cc] drawpath p ; drawpoints p ; drawcontrolpoints p ; \stopbuffer \startbuffer[dd] drawmidpoints(p,1,.625red, 11) ; drawmidpoints(p,1,.625yellow, 1) ; \stopbuffer \startbuffer[ee] drawmidpoints(p,1,.625red, 12) ; drawmidpoints(p,1,.625yellow, 2) ; \stopbuffer \startbuffer[ff] drawmidpoints(p,1,.625red, 13) ; drawmidpoints(p,1,.625yellow, 3) ; \stopbuffer \startbuffer[gg] drawmidpoints(p,1,.625red, 14) ; drawmidpoints(p,1,.625yellow, 4) ; \stopbuffer \startbuffer[hh] drawmidpoints(p,1,.625red, 15) ; drawmidpoints(p,1,.625yellow, 5) ; \stopbuffer \startbuffer \startcombination[\Xcom*\Ycom] {\processMPbuffer[a,b,cc,x]} {points} {\processMPbuffer[a,b,cc,dd,x]} {first order curve} {\processMPbuffer[a,b,cc,dd,ee,x]} {second order curve} {\processMPbuffer[a,b,cc,dd,ee,ff,x]} {third order curve} {\processMPbuffer[a,b,cc,dd,ee,gg,x]} {left side curves} {\processMPbuffer[a,b,cc,dd,ee,hh,x]} {right side curves} \stopcombination \stopbuffer \getbuffer \page \startbuffer[dd] drawmidpoints(p,1,.625red, 11) ; drawmidpoints(p,1,.625yellow, 1) ; \stopbuffer \startbuffer[ee] for i=11, 12 : drawmidpoints(p,1,.625red, i) ; endfor ; drawmidpoints(p,1,.625yellow, 2) ; \stopbuffer \startbuffer[ff] for i=11, 12, 13 : drawmidpoints(p,1,.625red, i) ; endfor ; drawmidpoints(p,1,.625yellow, 3) ; \stopbuffer \startbuffer[gg] for i=11,12,13,14 : drawmidpoints(p,1,.625red, i) ; endfor ; drawmidpoints(p,1,.625yellow, 4) ; \stopbuffer \startbuffer[hh] for i=11, 12, 13, 14, 15 : drawmidpoints(p,1,.625red, i) ; endfor ; drawmidpoints(p,1,.625yellow, 5) ; \stopbuffer \startbuffer \startcombination[\Xcom*\Ycom] {\processMPbuffer[a,b,cc,x]} {points} {\processMPbuffer[a,b,cc,dd,x]} {first order points} {\processMPbuffer[a,b,cc,ee,x]} {second order points} {\processMPbuffer[a,b,cc,ff,x]} {third order points} {\processMPbuffer[a,b,cc,gg,x]} {left side points} {\processMPbuffer[a,b,cc,hh,x]} {right side points} \stopcombination \stopbuffer \getbuffer \page \startbuffer[cc] drawpath p ; drawmidpoints (p,1,.625yellow, 0) ; \stopbuffer \startbuffer[dd] drawpath p ; drawmidpoints (p,2,.625yellow, 0) ; \stopbuffer \startbuffer[ee] drawpath p ; drawmidpoints (p,3,.625yellow, 0) ; \stopbuffer \startbuffer[ff] drawpath p ; drawmidpoints (p,4,.625yellow, 0) ; \stopbuffer \startbuffer[gg] drawpath p ; drawmidpoints (p,5,.625yellow, 0) ; \stopbuffer \startbuffer[hh] drawpath p ; drawmidpoints (p,6,.625yellow, 0) ; \stopbuffer \startbuffer \startcombination[\Xcom*\Ycom] {\processMPbuffer[a,b,cc,x]} {first iteration} {\processMPbuffer[a,b,cc,dd,x]} {second iteration} {\processMPbuffer[a,b,cc,dd,ee,x]} {third iteration} {\processMPbuffer[a,b,cc,dd,ee,ff,x]} {fourth iteration} {\processMPbuffer[a,b,cc,dd,ee,ff,gg,x]} {fifth iteration} {\processMPbuffer[a,b,cc,dd,ee,ff,gg,hh,x]} {sixths iteration} \stopcombination \stopbuffer \getbuffer \page \stoppostponing % here we pick up the thread, if we would not flush the % pages before the next text, the reader could become % confused The path in these examples is defined as follows: \typebuffer[b] If you are playing with graphics like this, the \METAFUN\ macro \type {randomize} may come in handy: \startbuffer[bb] p := p randomized (1cm,.5cm) ; \stopbuffer \typebuffer[bb] If we apply this operation a couple of times we can see how the (control) points vary. (Using the randomizer saves us the troubles of finding nice example values.) The angle between the tangent as well as the distance from the parent point determine the curve. \startbuffer[xx] currentpicture := currentpicture scaled .5 ; \stopbuffer \startlinecorrection[blank] \hbox to \hsize {\processMPbuffer[a,b,bb,c,x,xx]\hss \processMPbuffer[a,b,bb,c,x,xx]\hss \processMPbuffer[a,b,bb,c,x,xx]\hss \processMPbuffer[a,b,bb,c,x,xx]} \stoplinecorrection % new thread Just in case you are interested in how such graphical simulations can be organized, we show simplified versions of the macros used here. (In the previous examples we minimized the complexity of the code by using buffers, but describing this mechanism is out of the scope of this section.) \startbuffer[demo] vardef dodrawmidpoints (expr a, b, c, d, n) = save e, f, g, h, i, j ; pair e, f, g, h, i, j ; e := .5[a,b] ; f := .5[b,c] ; g := .5[c,d] ; h := .5[e,f] ; i := .5[f,g] ; j := .5[h,i] ; draw j ; if n>1 : dodrawmidpoints(a, e, h, j, n-1) ; dodrawmidpoints(j, i, g, d, n-1) ; fi ; enddef ; vardef drawmidpoints (expr p, n) = save a, b, c, d ; pair a, b, c, d ; for x=0 upto length(p)-1 : a := point x of p ; b := postcontrol x of p ; d := point x+1 of p ; c := precontrol x+1 of p ; dodrawmidpoints(a, b, c, d, n) ; endfor ; enddef ; \stopbuffer We need to loop over all segments of a curve, where for each segment the left and right side sub curves are handled recursively, upto the requested depth (denoted as \type {n}). For this we define the following macros. \typebuffer[demo] \startbuffer[zero] drawoptions (withpen pencircle scaled 5pt withcolor .625red); \stopbuffer \startbuffer[extra] drawoptions (withpen pencircle scaled 5pt withcolor .625yellow); \stopbuffer We apply this macro to a simple shape: \startbuffer[one] drawmidpoints (fullcircle xscaled 300pt yscaled 50pt, 1) ; \stopbuffer \typebuffer[one] When drawn, this results in the points that makes up the curve: \startlinecorrection[blank] \processMPbuffer[demo,zero,one] \stoplinecorrection We now add an extra iteration (resulting in the yellow points): \startbuffer[two] drawmidpoints (fullcircle xscaled 300pt yscaled 50pt, 2) ; \stopbuffer \typebuffer[two] and get: \startlinecorrection[blank] \processMPbuffer[demo,zero,two,extra,one] \stoplinecorrection We don't even need that much iterations to get a good result. The depth needed to get a good result depends on the size of the pen and the resolution of the device on which the curve is visualized. \startbuffer[zero] drawoptions (withpen pencircle scaled 2pt withcolor .625red) ; \stopbuffer \startbuffer[three] for i=1 upto 7 : drawmidpoints (fullcircle xscaled (300pt+i*10pt) yscaled (50pt+i*10pt), i) ; endfor ; \stopbuffer \typebuffer[three] Here we show 7 iterations in one graphic. \startlinecorrection[blank] \processMPbuffer[demo,zero,three] \stoplinecorrection In practice it is not that trivial to determine the depth needed. The next example demonstrates how the resolution of the result depends on the length and nature of the segment. \startbuffer[four] drawmidpoints (fullsquare xscaled 300pt yscaled 50pt randomized (20pt,10pt), 5) ; \stopbuffer \typebuffer[four] \startlinecorrection[blank] \processMPbuffer[demo,zero,four] \stoplinecorrection \stopsection \startsection[title={Inflection, tension and curl}] \index{inflection} \index{tension} \index{curl} The \METAPOST\ manual describes the meaning of \type {...} as \quotation {choose an inflection||free path between these points unless the endpoint directions make this impossible}. To use the words of David Arnold: a point of inflection is where a path switches concavity, from concave up to concave down, for example. It is surprisingly difficult to find nice examples that demonstrate the difference between \type {..} and \type {...}, as it is often \quote {impossible} to honour the request for less inflection. We will demonstrate this with a few graphics. In the four figures on the next pages, you will see that \type {...} is not really suited for taming wild curves. If you really want to make sure that a curve stays within certain bounds, you have to specify it as such using control or intermediate points. In the figures that follow, the gray curves draw the random path using \type {..} on top of yellow curves that use the \type {...} connection. As you can see, in only a few occasions do the yellow \quote {inflection} free curves show up. For those who asked for the code that produces these pictures, we now include it here. We use a macro \type {sample} which we define as a usable graphic (nearly all examples in this manual are coded in the document source). \startbuffer \startuseMPgraphic{sample} def sample (expr rx, ry) = path p, q ; numeric n, m, r, a, b ; color c ; c := \MPcolor{lightgray} ; a := 3mm ; b := 2mm ; r := 2cm ; n := 7 ; m := 5 ; q := unitsquare scaled r xyscaled (n,m) shifted (.5r,.5r) ; draw q withpen pencircle scaled (b/4) withcolor .625yellow; for i=1 upto n : for j=1 upto m : p := (fullcircle scaled r randomized (r/rx,r/ry)) shifted ((i,j) scaled r) ; pickup pencircle scaled a ; draw for k=0 upto length(p) : point k of p .. endfor cycle withcolor c ; draw for k=0 upto length(p) : point k of p ... endfor cycle withcolor c ; pickup pencircle scaled b ; draw for k=0 upto length(p) : point k of p .. endfor cycle withcolor .625yellow ; draw for k=0 upto length(p) : point k of p ... endfor cycle withcolor .625white ; for k=0 upto length(p) : draw point k of p withcolor .625red ; endfor ; endfor ; endfor ; setbounds currentpicture to q ; enddef ; \stopuseMPgraphic \stopbuffer \typebuffer \getbuffer As you see, not so much code is needed. The graphics themselves were produced with a couple of commands like: \startbuffer \placefigure {Circles with minimized inflection and 25\% randomized points.} {\startMPcode \includeMPgraphic{sample} ; sample(4,4) ; \stopMPcode} \stopbuffer \typebuffer \startpostponing \placefigure {Circles with minimized inflection and 25\% randomized points.} {\startMPcode\includeMPgraphic{sample} ; sample(4,4) ; \stopMPcode} \placefigure {Circles with minimized inflection and 33\% randomized points.} {\startMPcode\includeMPgraphic{sample} ; sample(3,3) ; \stopMPcode} \page \placefigure {Circles with minimized inflection and 50\% randomized points.} {\startMPcode\includeMPgraphic{sample} ; sample(2,2) ; \stopMPcode} \placefigure {Circles with minimized inflection and 100\% randomized points.} {\startMPcode\includeMPgraphic{sample} ; sample(1,1) ; \stopMPcode} \page \stoppostponing The tension specifier can be used to influence the curvature. To quote the \METAPOST\ manual once more: \quotation {The tension parameter can be less than one, but it must be at least $3/4$}. The following paths are the same: \starttyping z1 .. z2 z1 .. tension 1 .. z2 z1 .. tension 1 and 1 .. z2 \stoptyping The triple dot command \type {...} is actually a macro that makes the following commands equivalent. Both commands will draw identical paths. \starttyping z1 ... z2 z1 .. tension atleast 1 .. z2 \stoptyping The \type {atleast} directive tells \METAPOST\ to do some magic behind the screens. Both the $3/4$ and the \type {atleast} lead directly to the question: \quotation {What, exactly, is the influence of the tension directive?} We will try to demystify the \type {tension} specifier through a sequence of graphics. \startbuffer u := 1cm ; z1 = (0,0) ; z2 = (2u,4u) ; z3 = (4u,0) ; def sample (expr p, c) = draw p withpen pencircle scaled 2.5mm withcolor white ; draw p withpen pencircle scaled 2.0mm withcolor c ; enddef ; for i=.75 step .05 until 1 : sample (z1 .. tension i .. z2 .. z3, .625red) ; endfor ; for i=1 step .05 until 2 : sample (z1 .. tension i .. z2 .. z3, .625yellow) ; endfor ; sample (z1 .. z2 .. z3, .625white) ; sample (z1 ... z2 ... z3, .625white) ; \stopbuffer \typebuffer Indeed values less than .75 give an error message, but large values are okay. As you can see, the two gray curves are the same. Here, \type {atleast 1} means~1, even if larger values are useful. \startlinecorrection[blank] \processMPbuffer \stoplinecorrection \startbuffer u := 1cm ; z1 = (0,0) ; z2 = (2u,4u) ; z3 = (4u,0) ; def sample (expr p, c) = draw p withpen pencircle scaled 2.5mm withcolor white ; draw p withpen pencircle scaled 2.0mm withcolor c ; enddef ; for i=.75 step .05 until 1 : sample (z1 .. tension i and 2i .. z2 .. z3, .625red) ; endfor ; for i=1 step .05 until 2 : sample (z1 .. tension i and 2i .. z2 .. z3, .625yellow) ; endfor ; sample (z1 .. z2 .. z3, .625white) ; sample (z1 ... z2 ... z3, .625white) ; \stopbuffer Curves finally are made up out of points, and each point has two control points. Since the \type {tension} specifier finally becomes a control point, it is not surprising that you may specify two tension values. If we replace the tension in the previous example by \starttyping .. tension i and 2i .. \stoptyping we get the following graphic: \startlinecorrection[blank] \processMPbuffer \stoplinecorrection \startbuffer u := 1cm ; z1 = (0,0) ; z2 = (2u,4u) ; z3 = (4u,0) ; def sample (expr p, c) = draw p withpen pencircle scaled 2.5mm withcolor white ; draw p withpen pencircle scaled 2.0mm withcolor c ; enddef ; for i=.75 step .05 until 1 : sample (z1 .. tension 2i and i .. z2 .. z3, .625red) ; endfor ; for i=1 step .05 until 2 : sample (z1 .. tension 2i and i .. z2 .. z3, .625yellow) ; endfor ; sample (z1 .. z2 .. z3, .625white) ; sample (z1 ... z2 ... z3, .625white) ; \stopbuffer If we swap both values (\type {.. tension 2i and i ..}) we get: \startlinecorrection[blank] \processMPbuffer \stoplinecorrection \startbuffer[a] u := 1cm ; z1 = (0,0) ; z2 = (2u,4u) ; z3 = (4u,0) ; def sample (expr p, c) = drawpath p withpen pencircle scaled 2.5mm withcolor c ; drawcontrollines p withcolor c ; drawpoints p ; drawcontrolpoints p ; enddef ; \stopbuffer We mentioned control points. We will now draw a few extreme tensions and show the control points as \METAPOST\ calculates them. \startbuffer[b] sample (z1 .. tension 0.75 .. z2 .. z3, .625red) ; sample (z1 .. tension 2.00 .. z2 .. z3, .625yellow) ; sample (z1 .. z2 .. z3, .625white) ; \stopbuffer \typebuffer[b] First we will show the symmetrical tensions. \startlinecorrection[blank] \processMPbuffer[a,b] \stoplinecorrection The asymetrical tensions are less prominent. We use the following values: \startbuffer[b] sample (z1 .. tension .75 and 10 .. z2 .. z3, .625red) ; sample (z1 .. tension 10 and .75 .. z2 .. z3, .625yellow) ; sample (z1 .. z2 .. z3, .625white) ; \stopbuffer \typebuffer[b] \startlinecorrection[blank] \processMPbuffer[a,b] \stoplinecorrection What happens when you use the \METAPOST\ maximum value of \type {infinity} instead of 10? Playing with this kind of graphic can be fun, especially when we apply a few tricks. \startbuffer def sample (expr p, c) = draw p withpen pencircle scaled 2.5mm withcolor white ; draw p withpen pencircle scaled 2.0mm withcolor c ; enddef; u := 1cm ; z1 = (0,0) ; z2 = (2u,4u) ; z3 = (4u,0) ; for i=0 step .05 until 1 : sample(z1 .. tension (.75+i) .. z2 .. z3, i[.625red,.625yellow]) ; endfor; \stopbuffer \typebuffer Here we change the color along with the tension. This clearly demonstrates that we're dealing with a non linear phenomena. \startlinecorrection[blank] \processMPbuffer \stoplinecorrection We can (misuse) transparant colors to illustrate how the effect becomes less with growing tension. \startbuffer def sample (expr p) (text c)= draw p withpen pencircle scaled 2.0mm withcolor c ; enddef; u := 1cm ; z1 = (0,0) ; z2 = (2u,4u) ; z3 = (4u,0) ; for i=0 step .05 until 1 : sample(z1 .. tension (.75+i) .. z2 .. z3, transparent(1,1-i,.625red)) ; endfor; \stopbuffer \typebuffer \startlinecorrection[blank] \processMPbuffer \stoplinecorrection A third magic directive is \type {curl}. The curl is attached to a point between \type {{ }}, like \type {{curl 2}}. Anything between curly braces is a direction specifier, so instead of a \type {curl} you may specify a vector, like \type {{(2,3)}}, a pair of numbers, as in \type {{2,3}}, or a direction, like \type {{dir 30}}. Because vectors and angles are straightforward, we will focus a bit on \type {curl}. \starttyping z0 .. z1 .. z2 z0 {curl 1} .. z1 .. {curl 1} z2 \stoptyping So, a \type {curl} of~1 is the default. When set to~1, the begin and|/|or end points are approached. Given the following definitions: \startbuffer[a] u := 1cm ; z1 = (0,0) ; z2 = (2u,4u) ; z3 = (4u,0) ; def sample (expr p, c) = draw p withpen pencircle scaled 2.5mm withcolor white ; draw p withpen pencircle scaled 2.0mm withcolor c ; enddef ; \stopbuffer \typebuffer[a] We can draw three curved paths. \startbuffer[b] sample (z1 {curl 0} .. z2 .. {curl 0} z3, .625red) ; sample (z1 {curl 2} .. z2 .. {curl 2} z3, .625yellow) ; sample (z1 {curl 1} .. z2 .. {curl 1} z3, .625white) ; \stopbuffer \typebuffer[b] The third (gray) curve is the default situation, so we could have left the \type {curl} specifier out of the expression. \startlinecorrection[blank] \processMPbuffer[a,b] \stoplinecorrection \startbuffer[b] sample (z1 {curl 0} .. z2 .. {curl 0} z3, .625red) ; sample (z1 {curl infinity} .. z2 .. {curl infinity} z3, .625yellow) ; sample (z1 {curl 1} .. z2 .. {curl 1} z3, .625white) ; \stopbuffer The curly specs have a lower bound of zero and no upper bound. When we use \METAPOST\ maximum value of \type {infinity} instead of~2, we get: \startlinecorrection[blank] \processMPbuffer[a,b] \stoplinecorrection These curves were defined as: \typebuffer[b] It may sound strange, but internally \METAPOST\ can handle larger values than \type {infinity}. \startbuffer[b] sample (z1 {curl infinity} .. z2 .. {curl infinity} z3, .625red) ; sample (z1 {curl 4infinity} .. z2 .. {curl 4infinity} z3, .625yellow) ; sample (z1 {curl 8infinity} .. z2 .. {curl 8infinity} z3, .625white) ; \stopbuffer \typebuffer[b] Although this is quite certainly undefined behaviour, interesting effects can be achieved. When you turn off \METAPOST's first stage overflow catcher by setting \type {warningcheck} to zero, you can go upto 8 times \type {infinity}, which, being some $2^{15}$, is still far from what today's infinity is supposed to be. \startlinecorrection[blank] \processMPbuffer[a,b] \stoplinecorrection As the built||in \METAPOST\ command \type {..} accepts the \type {curl} and \type {tension} directives as described in this section, you will now probably understand the following plain \METAPOST\ definitions: \starttyping def -- = {curl 1} .. {curl 1} enddef ; def --- = .. tension infinity .. enddef ; def ... = .. tension atleast 1 .. enddef ; \stoptyping These definitions also point out why you cannot add directives to the left or right side of \type {--}, \type {---} and \type {...}: they are directives themselves! \stopsection \startsection[title={Transformations}] \index{transformations} A \type {transform} is a vector that is used in what is called an affine transformation. To quote the \METAPOST\ manual: \startquotation If $p=(p_x,p_y)$ is a pair and $T$ is a transform, then \type {p transform T} is a pair of the form: \startformula (t_x + t_{xx} p_x + t_{xy} p_y, t_y + t_{yx} p_x + t_{yy} p_y) \stopformula where the six numeric quantities $(t_x, t_y, t_{xx}, t_{xy}, t_{yx}, t_{yy})$ determine T. \stopquotation In literature concerning \POSTSCRIPT\ and \PDF\ you will find many references to such transformation matrices. A matrix of $(s_x,0,0,s_y,0,0)$ is scaling by $s_x$ in the horizontal direction and $s_y$ in the vertical direction, while $(1,0,t_x,1,0,t_y)$ is a shift over $t_x,t_y$. Of course combinations are also possible. Although these descriptions seem in conflict with each other in the nature and order of the transform components in the vectors, the concepts are the same. You normally populate transformation matrices using \type {scaled}, \type {shifted}, \type {rotated}. \starttyping transform t ; t := identity shifted (a,b) rotated c scaled d ; path p ; p := fullcircle transformed t ; \stoptyping The previous lines of code are equivalent to: \starttyping path p ; p := fullcircle shifted (a,b) rotated c scaled d ; \stoptyping You always need a starting point, in this case the identity matrix \type {identity}: $(0,0,1,0,0,1)$. By the way, in \POSTSCRIPT\ the zero vector is $(1,0,0,1,0,0)$. So, unless you want to extract the components using \type {xpart}, \type {xypart}, \type {xxpart}, \type {ypart}, \type {yxpart} and|/|or \ \type {yypart}, you may as well forget about the internal representation. You can invert a transformation using the \type {inverse} macro, which is defined as follows, using an equation: \starttyping vardef inverse primary T = transform T_ ; T_ transformed T = identity ; T_ enddef ; \stoptyping Using transform matrices makes sense when similar transformations need to be applied on many paths, pictures, pens, or other transforms. However, in most cases you will use the predefined commands \type {scaled}, \type {shifted}, \type {rotated} and alike. We will now demonstrate the most common transformations in a text example. \startbuffer[a] draw btex \bfd MetaFun etex ; draw boundingbox currentpicture withcolor .625yellow ; \stopbuffer \typebuffer[a] Before an independent \METAPOST\ run, the \typ {btex ... etex}'s are filtered from the file and passed on to \TEX. After that, the \DVI\ file is converted to a list of pictures, which is consulted by \METAPOST. This is no longer the case in \LUATEX\ where we use \MPLIB, so users don't have to worry about these issues: just ignore what is mentioned in the official \METAPOST\ manual. We can manipulate the pictures representing text like any graphic as well as draw it with \type {draw}. \startlinecorrection[blank] \processMPbuffer[a] \stoplinecorrection We show the transformations in relation to the origin and make the origin stand out a bit more by painting it a bit larger in white first. \startbuffer[c] draw origin withpen pencircle scaled 1.5mm withcolor white ; draw origin withpen pencircle scaled 1mm withcolor .625red \stopbuffer \typebuffer[c] The origin is in the lower left corner of the picture. \startlinecorrection[blank] \processMPbuffer[a,c] \stoplinecorrection Because the transformation keywords are proper english, we let the pictures speak for themselves. % shifted \startbuffer[b] currentpicture := currentpicture shifted (0,-1cm) ; \stopbuffer \page[preference] \typebuffer[b] \page[no] \startlinecorrection[blank] \processMPbuffer[a,b,c] \stoplinecorrection % rotated \startbuffer[b] currentpicture := currentpicture rotated 180 ; \stopbuffer \page[preference] \typebuffer[b] \page[no] \startlinecorrection[blank] \processMPbuffer[a,b,c] \stoplinecorrection % rotatedaround \startbuffer[b] currentpicture := currentpicture rotatedaround(origin,30) ; \stopbuffer \page[preference] \typebuffer[b] \page[no] \startlinecorrection[blank] \processMPbuffer[a,b,c] \stoplinecorrection % scaled \startbuffer[b] currentpicture := currentpicture scaled 1.75 ; \stopbuffer \page[preference] \typebuffer[b] \page[no] \startlinecorrection[blank] \processMPbuffer[a,b,c] \stoplinecorrection % scaled \startbuffer[b] currentpicture := currentpicture scaled -1 ; \stopbuffer \page[preference] \typebuffer[b] \page[no] \startlinecorrection[blank] \processMPbuffer[a,b,c] \stoplinecorrection % xscaled \startbuffer[b] currentpicture := currentpicture xscaled 3.50 ; \stopbuffer \page[preference] \typebuffer[b] \page[no] \startlinecorrection[blank] \processMPbuffer[a,b,c] \stoplinecorrection % xscaled \startbuffer[b] currentpicture := currentpicture xscaled -1 ; \stopbuffer \page[preference] \typebuffer[b] \page[no] \startlinecorrection[blank] \processMPbuffer[a,b,c] \stoplinecorrection % yscaled \startbuffer[b] currentpicture := currentpicture yscaled .5 ; \stopbuffer \page[preference] \typebuffer[b] \page[no] \startlinecorrection[blank] \processMPbuffer[a,b,c] \stoplinecorrection % yscaled \startbuffer[b] currentpicture := currentpicture yscaled -1 ; \stopbuffer \page[preference] \typebuffer[b] \page[no] \startlinecorrection[blank] \processMPbuffer[a,b,c] \stoplinecorrection % slanted \startbuffer[b] currentpicture := currentpicture slanted .5 ; \stopbuffer \page[preference] \typebuffer[b] \page[no] \startlinecorrection[blank] \processMPbuffer[a,b,c] \stoplinecorrection % slanted \startbuffer[b] currentpicture := currentpicture slanted -.5 ; \stopbuffer \page[preference] \typebuffer[b] \page[no] \startlinecorrection[blank] \processMPbuffer[a,b,c] \stoplinecorrection % zscaled \startbuffer[b] currentpicture := currentpicture zscaled (.75,.25) ; \stopbuffer \page[preference] \typebuffer[b] \page[no] \startlinecorrection[blank] \processMPbuffer[a,b,c] \stoplinecorrection % reflectedabout \startbuffer[b] currentpicture := currentpicture reflectedabout(llcorner currentpicture,urcorner currentpicture) ; \stopbuffer \page[preference] \typebuffer[b] \page[no] \startlinecorrection[blank] \processMPbuffer[a,b,c] \stoplinecorrection % reverse counterclockwise turningnumber A path has a certain direction. When the \type {turningnumber} of a path is larger than zero, it runs in clockwise direction. The \METAPOST\ primitive \type {reverse} changes the direction, while the macro \type {counterclockwise} can be used to get a path running in a well defined direction. \startbuffer drawoptions(withpen pencircle scaled 2pt withcolor .625red) ; path p ; p := fullcircle scaled 1cm ; drawarrow p ; drawarrow reverse p shifted (2cm,0) ; drawarrow counterclockwise p shifted (4cm,0) ; drawarrow counterclockwise reverse p shifted (6cm,0) ; drawarrow reverse counterclockwise p shifted (8cm,0) ; \stopbuffer \typebuffer \startlinecorrection[blank] \processMPbuffer \stoplinecorrection \stopsection \startsection[title={Only this far}] When you take a close look at the definitions of the Computer Modern Roman fonts, defined in the \METAFONT\ book, you will notice a high level of abstraction. Instead of hard coded points you will find points defined in terms of \quote {being the same as this point} or \quote {touching that point}. In this section we will spend some time on this touchy aspect. \startbuffer[a] pickup pencircle scaled 2mm ; path p ; p := fullsquare scaled 2cm ; draw p withcolor .625white ; \stopbuffer \startlinecorrection[blank] \processMPbuffer[a] \stoplinecorrection This rectangle is a scaled instance of the predefined \METAFUN\ path \type {fullsquare} which is centered around the origin. \typebuffer[a] On this path, halfway between two of its corners, we define a point \type {q}: \startbuffer[b] pair q ; q := .5[llcorner p, lrcorner p] ; \stopbuffer \typebuffer[b] We draw this point in red, using: \startbuffer[c] draw q withcolor .625red ; \stopbuffer \typebuffer[c] As you can see, this point is drawn on top of the path. \startlinecorrection[blank] \processMPbuffer[a,b,c] \stoplinecorrection There are four of those midpoints, and when we connect them, we get: \startbuffer[c] draw q -- q rotated 90 -- q rotated 180 -- q rotated 270 -- cycle withcolor .625red ; \stopbuffer \startlinecorrection[blank] \processMPbuffer[a,b,c] \stoplinecorrection Because path \type {p} is centered around the origin, we can simply rotate point \type {q} a few times. \typebuffer[c] There are situations, where you don't want the red path to be drawn inside another path, or more general: where you want points to touch instead of being overlayed. \startlinecorrection[blank] \processMPbuffer[a,b,c] \stoplinecorrection We can achieve this by defining point \type {q} to be located on top of the midpoint. \startbuffer[b] pair q ; q := top .5[llcorner p, lrcorner p] ; \stopbuffer \typebuffer[b] The predefined macro \type {top} moves the point over the distance similar to the current pen width. \startlinecorrection[blank] \processMPbuffer[a,b,c] \stoplinecorrection Because we are dealing with two drawing operations, and since the path inside is drawn through the center of points, we need to repeat this move in order to draw the red path really inside the other one. \startbuffer[b] pair q ; q := top top .5[llcorner p, lrcorner p] ; \stopbuffer \typebuffer[b] Operations like \type {top} and its relatives \type {bot}, \type {lft} and \type {rt} can be applied sequentally. \startlinecorrection[blank] \processMPbuffer[a,b,c] \stoplinecorrection We already showed that \type {q} was defined as a series of rotations. \typebuffer[c] As an intermezzo we will show an alternative definition of \type {q}. Because each point is rotated 90 degrees more, we can define a macro that expands into the point and rotates afterwards. Because each consecutive point on the path is rotated an additional 90 degrees, we use the \METAPOST\ macro \type {hide} to isolate the assignment. The \type {hide} command executes the hidden command and afterwards continues as if it were never there. You must not confuse this with grouping, since the hidden commands are visible to their surroundings. \startbuffer[c] def qq = q hide(q := q rotated 90) enddef ; draw qq -- qq -- qq -- qq -- cycle withcolor .625red ; \stopbuffer \typebuffer[c] The macro \type {top} uses the characteristics of the current pen to determine the displacement. However, for the more complicated pen shapes we need a different trick to get an inside path. Let's start by defining an elliptical path. \startbuffer[a] pickup pencircle xscaled 3mm yscaled 5mm rotated 30 ; path p ; p := fullcircle xscaled 6cm yscaled 3cm ; draw p withcolor .625white ; \stopbuffer \typebuffer[a] We draw this path using a non standard pen. In the \METAFONT\ manual you will find methods to draw shapes with similar pens, where the pen is also turning, as it does in real calligraphy. Here we stick to a more simple one. \startlinecorrection[blank] \processMPbuffer[a] \stoplinecorrection We construct the inner path from the points that make up the curve. Watch how we use a for loop to compose the new path. When used this way, no semi colon may be used to end the loop, since it would isolate the color directive. \startbuffer[b] draw point 0 of p for i=1 upto length(p) : -- point (i) of p endfor withcolor .625red ; \stopbuffer \typebuffer[b] The points are still located on the original path. \startlinecorrection[blank] \processMPbuffer[a,b] \stoplinecorrection We can move the points to the inside by shifting them over the penwidth in the direction perpendicular to the point. Because we use this transformation more than once, we wrap it into a macro. This also keeps the code readable. \startbuffer[b] vardef inside expr pnt of p = (point pnt of p shifted -(penoffset direction pnt of p of currentpen)) enddef ; draw inside 0 of p for i=1 upto length(p) : -- inside i of p endfor withcolor .625red ; \stopbuffer \typebuffer[b] Whenever you define a pen, \METAPOST\ stores its characteristics in some private variables which are used in the \type {top} and alike directives. The \type {penoffset} is a built in primitive and is defined as the \quotation {point on the pen furthest to the right of the given direction}. Deep down in \METAPOST\ pens are actually simple paths and therefore \METAPOST\ has a notion of a point on the penpath. In the \METAFONT\ book and \METAPOST\ manual you can find in depth discussions on pens. \startlinecorrection[blank] \processMPbuffer[a,b] \stoplinecorrection We're still not there. Like in a previous example, we need to shift over twice the pen width. To get good results, we should determine the width of the pen at that particular point, which is not trivial. The more general solution, which permits us to specify the amount of shifting, is as follows. \startbuffer[b] vardef penpoint expr pnt of p = save n, d ; numeric n, d ; (n,d) = if pair pnt : pnt else : (pnt,1) fi ; (point n of p shifted ((penoffset direction n of p of currentpen) scaled d)) enddef ; \stopbuffer \typebuffer[b] When the point specification is extended with a distance, in which case we have a pair expression, the point and distance are derived from this specification. First we demonstrate the simple case: \startbuffer[c] draw penpoint 0 of p for i=1 upto length(p)-1 : .. penpoint i of p endfor .. cycle withcolor .625red ; \stopbuffer \typebuffer[c] \startlinecorrection[blank] \processMPbuffer[a,b,c] \stoplinecorrection In the next graphic, we draw both an inner and and outer path. \startbuffer[c] draw penpoint (0,-2) of p for i=1 upto length(p)-1 : .. penpoint (i,-2) of p endfor .. cycle withcolor .625red ; draw penpoint (0,+2) of p for i=1 upto length(p)-1 : .. penpoint (i,+2) of p endfor .. cycle withcolor .625yellow ; \stopbuffer \typebuffer[c] \startlinecorrection[blank] \processMPbuffer[a,b,c] \stoplinecorrection \startbuffer[a] path p, q, r ; p := fullcircle scaled 3cm ; q := p shifted (7cm,0cm) ; r := center p -- center q ; \stopbuffer \startbuffer[b] pair pr, qr ; pr := p intersectionpoint r ; qr := q intersectionpoint r ; r := r cutbefore pr cutafter qr ; \stopbuffer \startbuffer[c] r := r cutbefore (point 5pt on r) ; r := r cutafter (point -5pt on r) ; \stopbuffer \startbuffer[cc] r := r cutends 5pt ; \stopbuffer \startbuffer[d] draw p withpen pencircle scaled 10pt withcolor .625red ; draw q withpen pencircle scaled 10pt withcolor .625yellow ; draw r withpen pencircle scaled 20pt withcolor .625white ; \stopbuffer \startbuffer[dd] draw r withpen pencircle scaled 20pt withcolor .625white ; draw p withpen pencircle scaled 10pt withcolor .625red ; draw q withpen pencircle scaled 10pt withcolor .625yellow ; \stopbuffer Another case when \type {top} and friends cannot be applied in a general way is the following. Consider the three paths: \typebuffer[a] We draw these paths with: \typebuffer[d] The line is drawn from center to center and since the line has a non zero width and a round line cap, it extends beyond this point. \startlinecorrection[blank] \processMPbuffer[a,d] \stoplinecorrection If we want the line to stop at the circular paths, we can cut off the pieces that extend beyond those paths. \typebuffer[b] This time we get: \startlinecorrection[blank] \processMPbuffer[a,b,d] \stoplinecorrection Due to the thicker line width used when drawing the straight line, part of that line is still visible inside the circles. So, we need to clip off a bit more. \typebuffer[c] The \type {point ... on} operation is a \METAFUN\ macro that takes a dimension. \startlinecorrection[blank] \processMPbuffer[a,b,c,d] \stoplinecorrection In order to save you some typing, \METAFUN\ provides a macro \type {cutends} that does the same job: \typebuffer[cc] This time we draw the path in a different order: \typebuffer[dd] That way we hide the still remaining overlapping part of the line. \startlinecorrection[blank] \processMPbuffer[a,b,cc,dd] \stoplinecorrection \stopsection \startsection[title={Directions}] \index{directions} Quite often you have to tell \METAPOST\ in what direction a line should be drawn. A direction is specified as a vector. There are four predefined vectors: \type {up}, \type {down}, \type {left}, \type {right}. These are defined as follows: \starttyping pair up, down, left, right ; up = -down = (0,1) ; right = -left = (1,0) ; \stoptyping We can use these predefined pairs as specifications and in calculations. \startbuffer dotlabel.top("up" , up * 1cm) ; dotlabel.bot("down" , down * 1cm) ; dotlabel.lft("left" , left * 1cm) ; dotlabel.rt ("right", right * 1cm) ; drawoptions (withpen pencircle scaled .25mm withcolor .625 red) ; drawarrow origin -- up * 1cm ; drawarrow origin -- down * 1cm ; drawarrow origin -- left * 1cm ; drawarrow origin -- right * 1cm ; \stopbuffer \typebuffer \startlinecorrection[blank] \processMPbuffer \stoplinecorrection This graphic can also be defined in a more efficient (but probably more cryptic) way. The next definition demonstrates a few nice tricks. Instead of looping over the four directions, we loop over their names. Inside the loop we convert these names, or strings, into a pair by scanning the string using \type {scantokens}. The \type {freedotlabel} macro is part of \METAFUN\ and takes three arguments: a label string (or alternatively a picture), a point (location), and the \quote {center of gravity}. The label is positioned in the direction opposite to this center of gravity. \startbuffer pair destination ; for whereto = "up", "down", "left", "right" : destination := scantokens(whereto) * 1cm ; freedotlabel(whereto, destination, origin) ; drawarrow origin -- destination withpen pencircle scaled .25mm withcolor .625 red ; endfor ; \stopbuffer \typebuffer So, in this code fragment, we use the string as string and (by means of \type {scantokens}) as a point or vector. \startlinecorrection[blank] \processMPbuffer \stoplinecorrection The previous definition is a stepping stone to the next one. This time we don't use points, but the \type {dir} command. This command converts an angle into an unitvector. \startbuffer pair destination ; for whereto = 0 step 30 until 330 : destination := dir(whereto) * 1.5cm ; freedotlabel(decimal whereto, destination, origin) ; drawarrow origin -- destination withpen pencircle scaled .25mm withcolor .625 red ; endfor ; \stopbuffer \typebuffer In \METAPOST\ the angles go counter clockwise, which is not that illogical if you look at it from the point of view of vector algebra. \startlinecorrection[blank] \processMPbuffer \stoplinecorrection \stopsection \startsection[title={Analyzing pictures}] \index{pictures+analyzing} {\em Unless you really want to know all details, you can safely skip this section. The \METAPOST\ features discussed here are mainly of importance when you write (advanced) macros.} % Later we will discuss in detail how you can use either \METAPOST\ or \TEX\ to % typeset text (\in {section} [sec:text] and \in {chapter} [sec:typesetting]), so % here we limit our exploration to a quick introduction. The most direct way of % processing text in \METAPOST\ is using the \type {infont} operator. % % \startbuffer[mp] % draw "this string will become a sequence of glyphs (MP)" % infont defaultfont scaled defaultscale ; % \stopbuffer % % \typebuffer[mp] % % The text between \type {"} is passed to \TEX, and the resulting \DVI\ will be % converted into a picture with textual components. So, we get: % % \startlinecorrection[blank] % \midaligned{\processMPbuffer[mp]} % \stoplinecorrection % % The same string typeset by \TEX\ shows up as: % % \blank % \midaligned{this string will become a sequence of glyphs (\TeX)} % \blank % % The following \METAPOST\ features are not covered by the \METAPOST\ manual, but % most of them are discussed in the appendix of the \type {graph} package written % by John Hobby. % %It is possible to disassemble a picture by means of a special for loop using the %\type {within} specifier. The following code walks over a picture and draws the %components with their bounding boxes. % % \startbuffer[show] % for i within currentpicture : % draw boundingbox i withcolor .625yellow ; % endfor ; % \stopbuffer % % \typebuffer[show] % % We can use the disassemble loop feature to look into the previously shown % example text. % % \startlinecorrection[blank] % \processMPbuffer[mp,show] % \stoplinecorrection % % The second line is typeset by \TEX. The resulting \DVI\ code is converted into a % series of pictures, which \METAPOST\ pastes into one picture. You may also notice % that in the set of pictures that originate in \TEX, the space is replaced by a % shift (this is because \TEX\ knows no space). % % An interesting aspect of this \quote {loop over a picture} feature, is that it % can provide insight in how \TEX\ is composing a paragraph. % % \startbuffer % draw btex \framed[width=fit,align=middle]{\input tufte \relax} etex ; % for i within currentpicture : % draw boundingbox i withpen pencircle scaled .2pt withcolor .625yellow ; % endfor ; % \stopbuffer % % \startlinecorrection[blank] % \processMPbuffer % \stoplinecorrection % % You may also notice, that rules produced by \TEX\ are converted to straight line % segments. Because the line extends 50\% of its linewidth beyond a point, there is % a slight overshoot. This picture was defined in a few lines: % % \typebuffer % % If we use a Times Roman instead of a Palatino, we get quite % different results. % % \startlinecorrection[blank] % \startMPenvironment % %\let\fontclass\empty % \usetypescript[times][texnansi] % \switchtobodyfont[times,10pt] % \stopMPenvironment % \processMPbuffer % \stoplinecorrection % % In \CONTEXT, you can easily change the body font for % \METAPOST\ graphics with directives like: % % \starttyping % \startMPenvironment % \usetypescript[times][texnansi] % \switchtobodyfont[times,10pt] % \stopMPenvironment % \stoptyping % % This font has far less kerning. Even more interesting is the Lucida Bright % Handwriting font, which is defined in such a way that no kerning is needed at % all. % % \startlinecorrection[blank] % \resetMPenvironment % \startMPenvironment % %\let\fontclass\empty % \usetypescript[lucida][texnansi] % \switchtobodyfont[lucida,hw,10pt] % \stopMPenvironment % \processMPbuffer % \stoplinecorrection % % You can ask for the number of components with \type {length}. A component can be % a stroked or filled path, or a text resulting from an \type {infont} operation. % If the (last) path is a clip path, or when the whole picture has a forced % boundingbox, the picture is treated as a whole. We will demonstrate this later. We can decompose \METAPOST\ pictures using a \type {within} loop. You may wonder if such a \type {within} loop construct has any real application, and as you can expect, it has. In \in {section} [sec:color circles] a macro is defined that draws a colored circle. If you want the inverted alternative, you can pass the inverted color specification, but wouldn't it be more convenient if there was an operator that did this for you automatically? Unfortunately there isn't one so we have to define one ourselves in a macro. \startbuffer colorcircle(4cm,(.4,.6,.8),(.4,.8,.6),(.6,.4,.8)) ; addto currentpicture also inverted currentpicture shifted (5cm,0) ; \stopbuffer \startlinecorrection[blank] \processMPbuffer \stoplinecorrection These circles were drawn using: \typebuffer When we \type {draw} a path, or stroke a path, as it is called officially, we actually perform an addition: \starttyping addto currentpicture doublepath somepath \stoptyping The \type {fill} command is actually: \starttyping addto currentpicture contour somepath \stoptyping We will need both \type {doublepath} and \type {contour} operations in the definition of \type {inverted}. When \METAPOST\ has digested a path into a picture, it keeps track of some characteristics. We can ask for them using \type {part...} operators. The following operators can be applied to a transform vector (one of \METAPOST's data types), but also to a picture. Say that we have drawn a circle: \startbuffer[a] draw fullcircle xscaled 3cm yscaled 2cm dashed dashpattern(on 3mm off 3mm) withpen pencircle scaled 1mm withcolor .625red ; picture p ; p := currentpicture ; \stopbuffer \typebuffer[a] This circle looks like: \startlinecorrection[blank] \processMPbuffer[a] \stoplinecorrection We can now ask for some of the characteristics of \type {currentpicture}, like its color. We could write the values to the log file, but it is more convenient to put them on paper. \startbuffer[b] label.rt("redpart: " & decimal redpart p, (4cm,+.5cm)) ; label.rt("greenpart: " & decimal greenpart p, (4cm, 0cm)) ; label.rt("bluepart: " & decimal bluepart p, (4cm,-.5cm)) ; \stopbuffer \typebuffer[b] Here the \type {&} glues strings together, while the decimal operator converts a number into a string. The result has no typographic beauty |<|keep in mind that here we use \METAPOST\ to typeset the text|>|but the result serves its purpose. \startlinecorrection[blank] \processMPbuffer[a,b] \stoplinecorrection We can also ask for the path itself (\type {pathpart}), the pen (\type {penpart}) and the dashpattern (\type {dashpart}), but these can only be assigned to variables of the corresponding type. A path can be stroked or filled, in which case it is a cyclic path. It can have a non natural bounding box, be a clip path, consist of line segments or contain text. All these characteristics can be tested. \startbuffer[b] label.rt("filled: " & condition filled p, (4cm,+1.25cm)) ; label.rt("stroked: " & condition stroked p, (4cm,+0.75cm)) ; label.rt("textual: " & condition textual p, (4cm,+0.25cm)) ; label.rt("clipped: " & condition clipped p, (4cm,-0.25cm)) ; label.rt("bounded: " & condition bounded p, (4cm,-0.75cm)) ; label.rt("cycle: " & condition cycle pathpart p, (4cm,-1.25cm)) ; \stopbuffer \typebuffer[b] \startlinecorrection[blank] \processMPbuffer[a,b] \stoplinecorrection In this code snippet, \type {condition} is a macro that takes care of translating a boolean value into a string (like \type {decimal} does with a numeric value). \starttyping def condition primary b = if b : "true" else : "false" fi enddef ; \stoptyping Clip paths and bounding boxes are kind of special in the sense that they can obscure components. The following examples demonstrate this. In case of a clip path or bounding box, the \type {pathpart} operator returns this path. In any case that asking for a value does not make sense |<|a clipping path for instance has no color|>| a zero (null) value is returned. \startbuffer[b] n := 1 ; for i within currentpicture : n := n + 1 ; label("n: " & decimal n & " / " & "length: " & decimal length i & " / " & "stroked: " & condition stroked i & " / " & "clipped: " & condition clipped i & " / " & "bounded: " & condition bounded i , (0,-n*.5cm)) ; endfor ; \stopbuffer \startbuffer[c] \startlinecorrection[blank] \framed[offset=overlay,frame=off,background=color,backgroundcolor=gray]{\processMPbuffer[a,b]} \stoplinecorrection \stopbuffer \startbuffer[a] draw fullcircle withpen pencircle scaled 6mm ; clip currentpicture to fullcircle ; setbounds currentpicture to fullcircle ; \stopbuffer \typebuffer[a] \getbuffer[c] \startbuffer[a] draw fullcircle withpen pencircle scaled 6mm ; setbounds currentpicture to fullcircle ; clip currentpicture to fullcircle ; \stopbuffer \typebuffer[a] \getbuffer[c] \startbuffer[a] clip currentpicture to fullcircle ; draw fullcircle withpen pencircle scaled 6mm ; setbounds currentpicture to fullcircle ; \stopbuffer \typebuffer[a] \getbuffer[c] \startbuffer[a] clip currentpicture to fullcircle ; setbounds currentpicture to fullcircle ; draw fullcircle withpen pencircle scaled 6mm ; \stopbuffer \typebuffer[a] \getbuffer[c] \startbuffer[a] setbounds currentpicture to fullcircle ; clip currentpicture to fullcircle ; draw fullcircle withpen pencircle scaled 6mm ; \stopbuffer \typebuffer[a] \getbuffer[c] \startbuffer[a] setbounds currentpicture to fullcircle ; draw fullcircle withpen pencircle scaled 6mm ; clip currentpicture to fullcircle ; \stopbuffer \typebuffer[a] \getbuffer[c] The description lines were generated by the following loop: \typebuffer[b] % % The following is no longer valid in MetaFun: % % If we have a textual picture, we can also ask for the text and font. Take the % following picture: % % \startbuffer[a] % picture p ; % p := "MetaFun" normalinfont "rm-lmr10" scaled 2 rotated 30 slanted .5 ; % p := p shifted (0,-ypart center p) ; % currentpicture := p ; % \stopbuffer % % \typebuffer[a] % % Here we can ask for: % % \startbuffer[b] % label.rt("textpart: " & textpart p, (4cm,+0.25cm)) ; % label.rt("fontpart: " & fontpart p, (4cm,-0.25cm)) ; % \stopbuffer % % \typebuffer[b] % % and get: % % \startlinecorrection[blank] % \processMPbuffer[a,b] % \stoplinecorrection % % We use \type {normalinfont} instead of \type {infont} because in \METAFUN\ this % operator is overloaded and follows another route for including text. % % If we're dealing with a path, the transformations have ended up in the path % specification. If we have a text picture, we can explicitly ask for the transform % components. % % \startbuffer[b] % label.rt("xpart: " & decimal xpart p, (4cm,+1.25cm)) ; % label.rt("ypart: " & decimal ypart p, (4cm,+0.75cm)) ; % label.rt("xxpart: " & decimal xxpart p, (4cm,+0.25cm)) ; % label.rt("xypart: " & decimal xypart p, (4cm,-0.25cm)) ; % label.rt("yxpart: " & decimal yxpart p, (4cm,-0.75cm)) ; % label.rt("yypart: " & decimal yypart p, (4cm,-1.25cm)) ; % \stopbuffer % % \typebuffer[b] % % \startlinecorrection[blank] % \processMPbuffer[a,b] % \stoplinecorrection % % We will now define the \type {inverted} macro using these primitives. Because we % have to return a picture, we cannot use \type {draw} and \type {fill} but need to % use the low level operators. Because a picture can consist of more than one path, % we need a temporary picture \type {pp}. % % \starttyping % vardef inverted expr p = % save pp ; picture pp ; pp := nullpicture ; % for i within p : % addto pp % if stroked i or filled i : % if filled i : contour else : doublepath fi pathpart i % dashed dashpart i withpen penpart i % else : % also i % fi % withcolor white-(redpart i, greenpart i, bluepart i) ; % endfor ; % pp % enddef ; % \stoptyping % % We probably need to handle a few more border cases, but for general purposes, % this macro works as expected. The textual capabilities built in \METAPOST\ are rather limited but in \CONTEXT\ we have overloaded the relevant operators. There we hook into the normal font handler. The native text related operators are: \starttyping draw "MetaFun" infont "somefont" scaled 2 rotated 30 slanted .5 ; draw btex MetaFun etex scaled 2 rotated 30 slanted .5 ; \stoptyping The \type {infont} operator directly calls for a font and in stock \METAPOST\ is limited to (eight bit) \TYPEONE\ fonts. In \CONTEXT\ you can do this: \startbuffer[a] draw "MetaFun" infont "SerifBold*default" xscaled 5 rotated 5 slanted .5 ; \stopbuffer \typebuffer[a] The specification is a regular \CONTEXT\ font specification. \startlinecorrection[blank] \processMPbuffer[a] \stoplinecorrection The \type {btex ... etex} variant in normal \METAPOST\ delegates to \TEX\ and in \MKII\ indeed we filter them and process them between runs (or at runtime). In \MKIV\ they are also handled by \TEX\ but in an even more integrated and immediate way. The two primitives \type {textpart} and \type {fontpart} that can be used to disassemble a picture don't apply to \METAFUN\ as contrary to \METAPOST\ we don't convert the result to a picture. In later chapters we will discuss text in more detail. From the previous examples it may be clear that each picture has some associated data stored with it. From the \type {bounded} boolean test we can conclude that the bounding box is part of this data. Internally \METAPOST\ keeps track of two bounding boxes: the natural one, and the forced one. The forced one is actually a component of the picture which applies to all previously added graphics. You can calculate the bounding box from the \type {llcorner} and \type {urcorner} or if you like \type {ulcorner} and \type {lrcorner} and the \METAFUN\ command \type {boundingbox} does so. The four corners that make up the bounding box are either the natural ones, or the ones forced by \type {setbounds}. You can force \METAPOST\ to report the natural ones by setting \type {truecorners} to~1. The next example demonstrates this feature. \startbuffer pickup pencircle scaled 2mm ; path p, q ; draw fullcircle scaled 4cm slanted .5 withcolor .625white ; setbounds currentpicture to boundingbox currentpicture enlarged -5mm ; interim truecorners := 0 ; p := boundingbox currentpicture ; interim truecorners := 1 ; q := boundingbox currentpicture ; pickup pencircle scaled 1mm ; draw p withcolor .625red ; draw q withcolor .625yellow ; \stopbuffer \typebuffer We use \type {interim} because \type {truecorners} is an internal \METAPOST\ variable. \startlinecorrection[blank] \processMPbuffer \stoplinecorrection % % we already redefined infont so it's kind of dangerous to provide this example % % Since \METAPOST\ can handle fonts (it can even generate font metric files) it is % no surprise that we can also ask for the natural size of a font. For this we use % \type {fontsize}. However, you should beware of the fact that the size reported % is in base points. Since this is \METAPOST's native unit, this is no problem in % calculations, but it may look confusing when you \type {show} this size on your % terminal and get less that 10 reported for a \type {cmr10} font. % % \starttyping % show fontsize "cmr10" ; % \stoptyping % % In order to demonstrate that \type {fontsize} is useful, we extend the \type % {infont} command. In the process we show a few macro definition tricks. What we % want is a \TEX\ like specification of a font size: % % \startbuffer[txt] % draw "MetaFun" infont defaultfont at 20pt ; % \stopbuffer % % \typebuffer[txt] % % We can store the current meaning of a primitive or macro in a new macro. We do so % with \type {infont}: % % \startbuffer[a] % let normalinfont = infont ; % \stopbuffer % % \typebuffer[a] % % We can only know the size if we know the name of the font, so we have to redefine % \type {infont} to pick up this name. % % \startbuffer[b] % numeric lastfontsize ; lastfontsize = fontsize defaultfont ; % \stopbuffer % % \startbuffer[c] % primarydef infont primary name = % patched: def should work too % hide(lastfontsize := fontsize name) % normalinfont name % enddef ; % \stopbuffer % % \typebuffer[c] % % Because we are replacing an operator, and since \METAPOST\ expects one, we have % to use \type {def} instead of \type {vardef} (which is actually a kind of % variable). For the same reason, we have to pick up a \type {primary}. If we would % use a \typ {expr name}, we would end up in an unwanted look ahead. The \type % {hide} macro hides the assignment and makes this macro behave like a \type % {vardef} with respect to hiding expressions. We may not put a semi colon after % the \type {)} because it would stop \METAPOST\ from reading on, and thereby % invoke an error message. % % We can now define \type {at}. This macro picks up an expression (which can be % more than just a number) and return a scale transform that normalizes the given % size to the design size. % % \startbuffer[d] % def at expr size = % scaled (size/lastfontsize) % enddef ; % \stopbuffer % % \typebuffer[d] % % Because this macro is defined global, and therefore can be used apart from \type % {infont}, we predefine the size: % % \typebuffer[b] % % When defined this way \type {at} a comfortable 20 points, the string \type % {MetaFun} comes out as follows: % % \startlinecorrection[blank] % \processMPbuffer[a,b,c,d,txt] % \stoplinecorrection \stopsection \startsection[title={Filling}] \index{filling} \index{reversing} In most cases a path ends up being drawn or filled. When filling a path, it doesn't matter in what direction the path runs, as long as it's closed you're fine. You can however change the direction any time along the path. Here is an example of what happens when you fill a path that is partially reversed. \startbuffer fill fullsquare rotated 45 scaled 2cm withcolor .625 red ; fill fullcircle scaled 2cm -- reverse fullcircle scaled 1cm -- cycle withcolor .625 yellow ; \stopbuffer \typebuffer You'll notice that the inner circle is not filled: \startlinecorrection[blank] \processMPbuffer \stoplinecorrection Now watch the following: \startbuffer fill fullsquare rotated 45 scaled 2cm -- fullcircle scaled 2cm -- cycle withcolor .625 red ; \stopbuffer \typebuffer This results in: \startlinecorrection[blank] \processMPbuffer \stoplinecorrection Compare this with: \startbuffer fill fullsquare rotated 45 scaled 2cm -- reverse fullcircle scaled 2cm -- cycle -- cycle withcolor .625 red ; \stopbuffer \typebuffer giving: \startlinecorrection[blank] \processMPbuffer \stoplinecorrection The normal filling happens according to the non||zero winding rule. An alternative is the odd||even rule. There we don't need the reverse trick: \startbuffer eofill fullsquare rotated 45 scaled 2cm -- fullcircle scaled 2cm -- cycle withcolor .625 red ; \stopbuffer \typebuffer The \type {eofill} is a \METAFUN\ extension. Hopefully the next explains a bit how this works (you can find explanations on the Internet). \startlinecorrection[blank] \processMPbuffer \stoplinecorrection \startuseMPgraphic{demo} def DrawIt(text how) = path p ; p := ((0,0) .. (1,0) .. (1,1) .. (0,1) .. (1,0) .. (2,1) .. cycle) scaled 2cm ; how p withcolor .625 yellow ; draw p withcolor .625 red ; for i=0 step 0.05 until 1 : fill arrowheadonpath (p,i) withcolor .625 red ; endfor ; draw (0.5,0.5) scaled 2cm withpen pencircle scaled .5mm withcolor .375 white ; draw ((0.5,0.5) scaled 2cm -- llcorner p) withpen pencircle scaled .5mm withcolor .375 white ; draw (1.5,1.5) scaled 2cm withpen pencircle scaled .5mm withcolor .375 white ; draw ((1.5,1.5) scaled 2cm -- urcorner p) withpen pencircle scaled .5mm withcolor .375 white ; enddef ; \stopuseMPgraphic \startlinecorrection[blank] \startcombination[distance=4em] {\startMPcode \includeMPgraphic{demo} DrawIt(eofill) \stopMPcode} {\type{eofill}} {\startMPcode \includeMPgraphic{demo} DrawIt(fill) \stopMPcode} {\type{fill}} \stopcombination \stoplinecorrection In the case of a normal fill, the non||zero winding rule is applied: a winding number is calculated by subtracting 1 each time the line (from inside an area to someplace outside) is crossed clockwise while 1 is added each time we cross anti||clockwise. When the total is non zero the area is filled. Here we run in one direction and therefore we always get a fill. In the previous example where we used a reverse, an anti||clockwise crossing was nilled by a clockwise one. The leftmost shape uses \type {eofill} and therefore the odd||even rule gets applied. This time we follow the line and when it gets crossed en even number of times the area will not be filled. Here is another example: \startbuffer eofill for i=1 upto 12: fullcircle scaled ((i/12)*cm) -- endfor cycle ; \stopbuffer \typebuffer The successive larger circle are unfilled and basically form one path: \startlinecorrection[blank] \processMPbuffer \stoplinecorrection A glyph is often constructed from more than one path and eventually the shape is filled with an odd||even fill (\type {eofill}) operation. Take the following sequence: \startbuffer pickup pencircle scaled 1mm ; draw fullsquare scaled 2cm ; draw fullsquare scaled 2cm shifted (1cm,0) ; draw fullsquare scaled 2cm shifted (0,1cm) ; \stopbuffer \typebuffer \startlinecorrection[blank] \processMPbuffer \stoplinecorrection We can use a sequence of \type {nofill} ending with a \type {eofill} to create a combined shape. This is not done in \METAPOST\ but in the backend. \startbuffer nofill fullsquare scaled 2cm ; nofill fullsquare scaled 2cm shifted (1cm,0) ; eofill fullsquare scaled 2cm shifted (0,1cm) ; \stopbuffer \typebuffer \startlinecorrection[blank] \processMPbuffer \stoplinecorrection As this is used for glyphs, we demonstrate this mechanism with a simple \type {O} shape: \startbuffer nofill fullcircle xyscaled (2cm,3cm) ; eofill fullcircle xyscaled (1cm,2cm) ; \stopbuffer \typebuffer \startlinecorrection[blank] \processMPbuffer \stoplinecorrection Another backend related feature is \type {fillup}. This is just a combination of a fill and a draw in one go. It can save some bytes in the output file. \startbuffer draw image ( pickup pencircle scaled 5mm ; fill fullsquare scaled 2cm ; draw fullsquare scaled 2cm ; fillup fullsquare scaled 2cm shifted (4cm,0) ; ) withcolor .625red ; \stopbuffer \typebuffer \startlinecorrection[blank] \processMPbuffer \stoplinecorrection \stopsection \startsection[title={Pitfalls}] When writing macros, you need to be careful in what operations apply to what object. There is for instance a difference between the following code: \startbuffer pickup pencircle scaled 2pt ; draw (0,0)--(0,1)--(1,1) scaled 1cm withcolor .625 red ; draw ((0,0)--(0,1)--(1,1)) scaled 2cm withcolor .625 yellow ; \stopbuffer \typebuffer \startlinecorrection[blank] \processMPbuffer \stoplinecorrection The \type {scaled} operates on the previous expression which in the first case is the point \type {(1,1)} and in the second case the whole path. \startbuffer pickup pencircle scaled 2pt ; draw (0,0)--(0,1)--(1,1)--cycle scaled 1cm withcolor .625 red ; draw ((0,0)--(0,1)--(1,1)--cycle) scaled 2cm withcolor .625 yellow ; \stopbuffer \typebuffer \startlinecorrection[blank] \processMPbuffer \stoplinecorrection Here the last element in the first case is not the cycle, and the next alternative does not help us much in discovering what is going on. (Well, at least something {\em is} going on, because the result seems to have some dimensions.) \startbuffer pickup pencircle scaled 2pt ; draw (1,1)--cycle scaled 1cm withcolor .625 red ; draw ((1,1)--cycle) scaled 1cm withcolor .625 yellow ; \stopbuffer \typebuffer \startlinecorrection[blank] \processMPbuffer \stoplinecorrection The next lines demonstrate that we're dealing with the dark sides of \METAPOST, and from that we may conclude that in case of doubt it's best to add parenthesis when such fuzzy situations threaten to occur. \startbuffer pickup pencircle scaled 2pt ; draw (0,1)--(1,1)--cycle scaled 1cm withcolor .625 red ; draw ((0,1)--(1,1)--cycle) scaled 1cm withcolor .625 yellow ; \stopbuffer \typebuffer \startlinecorrection[blank] \processMPbuffer \stoplinecorrection There are more cases where the result may surprise you. Take the following code: \startbuffer drawarrow ((0,0)--(10,0)) withpen pencircle scaled 2pt withcolor red randomized (.4,.9) ; currentpicture := currentpicture scaled 8 ; \stopbuffer \typebuffer \startlinecorrection[blank] \processMPbuffer \stoplinecorrection The arrow is made up out of two pieces and each piece gets a different shade of red. This is because the attributes are collected and applied to each of the components that make up the arrow. Because for each component the attribute code is expanded again, we get two random colors. One way around this is to apply the color afterwards. \startbuffer draw image (drawarrow ((0,0)--(10,0)) withpen pencircle scaled 2pt) scaled 8 withcolor red randomized (.4,.9) ; \stopbuffer \typebuffer \startlinecorrection[blank] \processMPbuffer \stoplinecorrection Here the \type {image} macro creates a picture and as you can see, this provides a way to draw within a draw operation. Once you see the benefits of \type {image}, you will use it frequently. Another handy (at first sight strange) macro is \type {hide}. You can use this in situations where you don't want code to interfere. \starttyping def mydraw text t = boolean error ; error := false ; def withpencil expr p = hide (error := true) enddef ; draw t ; if error : message "pencils are not supported here" fi ; enddef ; mydraw fullcircle scaled 10cm withpencil sharp ; \stoptyping Here, setting the boolean normally interferes with the draw operation, but by hiding the assignment, this code becomes valid. This code will bring the message to your terminal and log file. Once you start using expressions you have a good chance of encountering messages with regard to redundant expressions. The following code is for instance a recipe for problems: \starttyping z1 = (1,0) ; z1 = (2,0) ; \stoptyping Changing the \type {=} into \type {:=} helps, but this may not be what you want. Because the \type {z}||variables are used frequently, they are reset each figure. You can also reset them yourself, using the \type {clearxy} macro. The \METAFUN\ version clears all \type {z}||variables, unless you explictly specify what variables to reset. \footnote {This version resulted from a discussion on the \METAFONT\ discussion list and is due to Bogus\l{}aw Jackowski.} If you want to play with this macro, see what happens when you run the following code: \starttyping show x0 ; z0 = (10,10) ; show x0 ; x0 := whatever ; y0 := whatever ; show x0 ; z0 = (20,20) ; show x0 ; clearxy 0 ; show x0 ; z0 = (30,30) ; \stoptyping So, the following calls are all legal: \starttyping clearxy ; clearxy 1 ; clearxy 1, 8, 10 ; \stoptyping Keep in mind that for each figure a full clear is done anyway. You should not confuse this command with \type {clearit}, which clears \type {currentpicture}. \stopsection \startsection[title={\TeX\ versus \MetaPost}] If you are defining your own \TEX\ and \METAPOST\ macros, you will notice that there are a couple of essential differences between the two macro languages. In \TEX\ the following code is invalid. \footnote {In \ETEX\ the calculation can be done in less lines using a \type {\numexpr}.} \starttyping \def\fancyplied#1% {\ifnum#1=0 \message{zero argument}% \fi \count0=#1 \multiply \count0 by \count0 \count2=#1 \multiply \count2 by 2 \count4=#1 \divide \count4 by 2 \advance \count0 by \count2 \advance \count0 by \count4 \count4 } \hskip \fancyplied{3} pt \stoptyping This is because \TEX\ is very strict in what tokens it expects next. In \METAPOST\ however, you can use \type {vardef}'d macros to hide nasty intermediate calculations. \starttyping vardef fancyplied expr x = if x=0 : message "x is zero" ; (x*x+2x+x/2) enddef ; a := a shifted (fancyplied 3pt,0) ; \stoptyping Hiding intermediate calculations and manipulations is a very strong point of \METAPOST. Another important difference between both languages is the way grouping is implemented. Because \TEX\ is dealing with a flow of information, strong grouping is a must and therefore part of the language. Occasionally you run into situations where you wished that you could reach over a group (for instance in order to pass a value). In \METAPOST\ grouping behaves quite different. First of all, it provides the mechanism that hides processing from the current flow. The previously mentioned \type {vardef} is implicitly grouped. Contrary to \TEX, in \METAPOST\ all assignments are global by default, even in a group. If you assign a variable inside a group it is persistent unless you first save the variable (or macro) using the \type {save} operator. So, in the next code snippet, the value of \type {\value} inside the box is {\em no} but after the box is typeset, it will be {\em yes} again. \starttyping \def\value{yes} \hbox{\def\value{no}\value} \value \stoptyping To make a value local in \METAPOST, the following code is needed. \starttyping string value ; value := "yes" ; def intermezzo begingroup ; save value ; string value ; value := "no" ; endgroup ; enddef ; \stoptyping Once you start writing your own \METAPOST\ macros, you will appreciate this \quote {always global} behaviour. As with other differences between the two languages, they make sense if you look at what the programs are supposed to do. \stopsection \startsection[title={Internals and Interims}] \index{internals} \index{interims} Related to grouping is the internal numeric datatype. When numeric variables are defined as interim, you can quickly overload them inside a group. \starttyping newinternal mynumber ; mynumber := 1 ; begingroup ; ... interim mynumber := 0 ; ... ; endgroup ; \stoptyping You can only \type {interim} a variable if it is already defined using \type {newinternal}. Among the \METAPOST\ macros is one called \type {drawdot}. This macro is kind of redundant because, at least at first sight, you can use draw to achieve the same result. There is however a very subtle difference: a dot is slightly larger than a drawn point. We guess that it's about the device pixel, so you may not even notice it. It may even be due to differences in accuracy of the methods to render them. \startbuffer pickup pencircle scaled 50pt ; drawdot origin shifted (-120pt,0) ; draw origin shifted (-60pt,0) ; drawdot origin ; draw origin withcolor white ; setbounds currentpicture to boundingbox currentpicture enlarged 1pt ; \stopbuffer \typebuffer \startlinecorrection[blank] \processMPbuffer \stoplinecorrection \stopsection \startsection[title=Named colors] The \type {withcolor} operator accepts a color expression but in \METAFUN\ it also accepts a string indicating a color defined at the \TEX\ end. Most helpers that deal with colors are able to deal with named colors as well. Here are some examples. First we define a few colors: \startbuffer \definecolor[MyColor1][r=.5] \definecolor[MyColor2][g=.5] \definecolor[MyColor3][b=.5] \definecolor[MyColor4][s=.8] \stopbuffer \typebuffer \getbuffer Here we access them: \startbuffer fill fullcircle scaled 12 withcolor "MyColor1" ; fill fullcircle scaled 10 withcolor "MyColor2" ; fill fullcircle scaled 8 withcolor complementary "MyColor3" ; fill fullcircle scaled 6 withcolor complemented "MyColor3" ; fill fullcircle scaled 4 withcolor "MyColor4" randomized 2 ; fill fullcircle scaled 2 withcolor "MyColor4" randomized 2 ; addbackground withcolor .5[resolvedcolor("MyColor4"),resolvedcolor("MyColor2")] ; currentpicture := currentpicture ysized 4cm ; \stopbuffer \typebuffer And get: \startlinecorrection[blank] \processMPbuffer \stoplinecorrection \stopsection \startsection[title=Formatted text] Text support in \METAFUN\ has evolved quite a bit over years. For compatibility reasons we keep old methods around but in practice one can probably do all with the following: \starttabulate[|T|p|] \NC textext[.anchor](str) \NC position a text relative to the origin \NC \NR \NC thetextext[.anchor](str,pos) \NC position a text relative to the given position \NC \NR \NC rawtextext[.anchor](str,pos) \NC idem but with less checking \NC \NR \stoptabulate If needed all functionality could be combined in one call (textext) but we keep it this way. You need to keep in mind that text in \METAPOST\ is not a first class object but something virtual that is known to \METAFUN\ as something with path like properties but is actually dealt with in the backend. This means that timing is important. \starttyping \startMPinitializations picture p ; p := image(draw textext("Foo");); \stopMPinitializations \startMPcode picture q ; q := image(draw textext("Bar");); picture r ; r := image(draw textext("Gnu");); draw p ; draw q shifted (2cm,0) ; draw r shifted (4cm,0) ; \stopMPcode \stoptyping This will work out well because an initialization is part of a figure, but this will fail: \starttyping \startMPinclusions picture p ; p := image(draw textext("Foo");); \stopMPinclusions \stoptyping because inclusions happen before the local textexts get initialized and due to the multipass implementation are not seeN a second time. The order of processing is: \starttabulate[|l|c|c|] \BC action \BC first pass \BC second pass \NC \NR \NC definitions \NC yes \NC \NC \NR \NC extensions \NC yes \NC \NC \NR \NC inclusions \NC yes \NC \NC \NR \NC begin figure \NC yes \NC yes \NC \NR \NC initializations \NC yes \NC yes \NC \NR \NC metapost code \NC yes \NC yes \NC \NR \NC end figure \NC yes \NC yes \NC \NR \stoptabulate The graph package (that comes with \METAPOST) has some pseudo typesetting on board needed to format numbers. Because we don't want to interfere with the definitions of macros used in that package we provide another set of macros for formatting: \type {fmttext}, \type {thefmttext} and \type {rawfmttext}. \startbuffer \startMPcode draw thefmttext("\bf@3.2f done",123.45678) withcolor darkred ; \stopMPcode \stopbuffer \typebuffer Here we pass one variable to the format but there can be more: \inlinebuffer. In \LUA\ the \type {%} is used as format directive but that does not work well in \TEX\ and \LUA\ which is why we use \type {@} instead. The formatting is done with the formatters subsystem which is an extension to the regular \LUA\ \type {format} function. More information can be found in \type {clf-mkiv.pdf} but one extension is not mentioned there: \type {%!texexp!}. This directive takes one argument by default but optionally can take one or two extra arguments: the format of the base number and one for the exponent. The following code demonstrates this: \startbuffer \startMPcode{doublefun} draw image ( draw thefmttext.rt("@!texexp!", 10.4698E30, (0,-1LineHeight)) ; draw thefmttext.rt("@1!texexp!",10.4698E30, (0,-2LineHeight)) ; draw thefmttext.rt("@2!texexp!",10.4698E30,"@2.3f", (0,-3LineHeight)) ; draw thefmttext.rt("@3!texexp!",10.4698E30,false,"@2i", (0,-4LineHeight)) ; draw thefmttext.rt("@3!texexp!",10.4698E30,"@2.3f","@2i",(0,-5LineHeight)) ; ) withcolor darkblue ; \stopMPcode \stopbuffer \typebuffer We switch to double mode because we use large numbers. \startlinecorrection[blank] \getbuffer \stoplinecorrection Of course this extra formatter is also supported in the \type {context} command: \startbuffer \startluacode context("%!texexp!, ", 10.4698E30) context("%1!texexp!, ", 10.4698E30) context("%2!texexp!, ", 10.4698E30,"@2.3f") context("%3!texexp! and ",10.4698E30,false,"@2i") context("%3!texexp!", 10.4698E30,"@2.3f","@2i") \stopluacode \stopbuffer \typebuffer This gives: \inlinebuffer . In \in {figure} [fig:formatters] we see some more formatters. \startbuffer for i=1 upto 12 : draw thefmttext("\letterpercent 3!date!","month,space,year",2019,i) shifted (0,i *cm / 2); draw thefmttext("@3!date!","month,space,year",2019,i) shifted (4cm,i *cm / 2); endfor ; for i=1 upto 20 : draw thefmttext(decimal i) shifted (1cm,-i/2*cm); draw thefmttext("@!month!",i) shifted (4cm,-i/2*cm); draw thefmttext("@!weekday!",i) shifted (7cm,-i/2*cm); draw thefmttext("@!monthshort!",i) shifted (10cm,-i/2*cm); draw thefmttext("@3!dayoftheweek!",i,1,2018) shifted (13cm,-i/2*cm); endfor ; \stopbuffer \typebuffer \startplacefigure[title=formatters,reference=fig:formatters] \framed{\scale[width=.8\textwidth]{\processMPbuffer}} \stopplacefigure \stopsection \startsection[title=Lists (aka suffixed variables)] Sometimes graphics are constructed using lists. There are a few helpers (and maybe there will be some more) that can make things a bit easier. Say that we do this: \startbuffer pair a[] ; a[1] := (0,0) ; a[2] := (1,0) ; a[3] := (1,1) ; a[4] := (0,1) ; a[5] := (1,1) ; a[6] := (2,0) ; draw topath(a,--) ysized 2cm withpen pencircle scaled 1mm withcolor .625red ; \stopbuffer \typebuffer \startlinecorrection[blank] \processMPbuffer \stoplinecorrection The \type {topath} macro converts the list into a path, in this case an ugly one. Say that we want to get rid of the sixth entry. For that we can use the \type {dispose} macro. You can use the dispose for any type (except a macro). \startbuffer dispose(a[6]) ; draw topath(a,--) ysized 2cm withpen pencircle scaled 1mm withcolor .625yellow ; \stopbuffer \typebuffer \startlinecorrection[blank] \processMPbuffer \stoplinecorrection We still have some duplicate entries here: \startbuffer dispose(a[6]) ; drawpoints topath(a,--) ysized 2cm withpen pencircle scaled 1mm withcolor .625red ; drawpointlabels topath(a,--) ysized 2cm ; \stopbuffer \typebuffer \startlinecorrection[blank] \processMPbuffer \stoplinecorrection These can be removed with: \startbuffer uniquelist(a) ; draw topath(a,--) ysized 2cm withpen pencircle scaled 1mm withcolor .625yellow ; drawpoints topath(a,--) ysized 2cm withpen pencircle scaled 1mm withcolor .625red ; drawpointlabels topath(a,--) ysized 2cm ; \stopbuffer \typebuffer \startlinecorrection[blank] \processMPbuffer \stoplinecorrection Sometimes a list needs to be sorted and here is the solution: \startbuffer sortlist(a,nothing) ; draw topath(a,--) ysized 2cm withpen pencircle scaled 1mm withcolor .625red ; \stopbuffer \typebuffer \startlinecorrection[blank] \processMPbuffer \stoplinecorrection The second argument can be an operator that takes a pair variable: \startbuffer sortlist(a,xpart) ; draw topath(a,--) ysized 2cm withpen pencircle scaled 3mm withcolor .625red ; sortlist(a,ypart) ; draw topath(a,--) ysized 2cm withpen pencircle scaled 2mm withcolor .625yellow ; \stopbuffer \typebuffer \startlinecorrection[blank] \processMPbuffer \stoplinecorrection Constructing a list can be sped up with the \type {tolist} macro. \startbuffer pair a[], b[], c[], d[] ; tolist(a,1,(0,0),(1,0),(1,1),(0,1)--(1,1)--(2,2)) ; tolist(b,0,(0,0),(1,0),(1,1),(0,1)--(1,1)--(2,2)) ; tolist(c,(0,0),(1,0),(1,1),(0,1)--(1,1)--(2,2)) ; tolist(d,(0,0),(1,0),(1,1)) ; draw image ( draw topath(a,--) shifted (0,0) ; draw topath(b,--) shifted (3,0) ; draw topath(c,--) shifted (6,0) ; draw topath(d,--) shifted (9,0) ; ) ysized 2cm withpen pencircle scaled 1mm withcolor .625red ; \stopbuffer \typebuffer \startlinecorrection[blank] \processMPbuffer \stoplinecorrection \stopsection \startsection[title=Segmented paths] \index {segmented paths}There are all kind of helpers in \METAFUN\ and some are discussed here. In \in {figure} [fig:segmentedpaths] we see a few macros that return a (smooth) path made from segments. You can for instance use these to do things that use the points on a path, like anchoring text. \startbuffer def DrawSomePath(text t) = drawpath t withcolor .625red ; drawpoints t withcolor white ; drawpointlabels t ; enddef ; DrawSomePath(circularpath(5) scaled 12cm) ; DrawSomePath(squarepath (5) scaled 8cm) ; DrawSomePath(linearpath (5) scaled 4cm) ; \stopbuffer \typebuffer \startplacefigure[title={A few segmented paths.},reference=fig:segmentedpaths] \processMPbuffer \stopplacefigure \index {crossing paths}The following examples demonstrates two mechanisms. In the image two paths are drawn on top of each other but one of them has holes where the other one crosses. The \type {crossingunder} macro was written by Alan Braslau as part of the node based diagram builder. In the process the arrow drawing code was adapted to accept a picture. \startbuffer[a] drawarrow image ( draw ((fullcircle scaled 2.25cm) crossingunder (fullsquare scaled 2cm)) withpen pencircle scaled 1mm withcolor .625green ; draw (fullsquare scaled 2cm) withpen pencircle scaled 1mm withcolor .625blue ; ) ; drawarrow image ( draw (fullsquare scaled 4cm) withpen pencircle scaled 1mm withcolor .625red ; draw ((fullcircle scaled 5cm) crossingunder (fullsquare scaled 4cm)) withpen pencircle scaled 1mm withcolor .625yellow ; ) ; \stopbuffer \startbuffer[b] drawarrow image ( draw ((fullsquare scaled 2cm) crossingunder (fullcircle scaled 2.25cm)) withpen pencircle scaled 1mm withcolor .625blue ; draw (fullcircle scaled 2.25cm) withpen pencircle scaled 1mm withcolor .625green ; ) ; drawarrow image ( draw (fullcircle scaled 5cm) withpen pencircle scaled 1mm withcolor .625yellow ; draw ((fullsquare scaled 4cm) crossingunder (fullcircle scaled 5cm)) withpen pencircle scaled 1mm withcolor .625red ; ) ; \stopbuffer \typebuffer[a] The next variant uses a different order: \typebuffer[b] The results are shown in \in {figure} [fig:crossingunder]. The internal variable \type {crossingscale} can be used to make the gap wider or narrower. The gap has a default value of 20. \startplacefigure[title=Crossing paths without touching,reference=fig:crossingunder] \startcombination {\processMPbuffer[a]} {} {\processMPbuffer[b]} {} \stopcombination \stopplacefigure \stopsection \startsection[title=Grouping] The grouping model in \METAPOST\ is kind of special. Basically anything that happens in a group is processed in some nested action and doesn't interfere with the outside. However, the last value put (back) into the input is picked up after the group. A \type {vardef} acts that way: \startbuffer vardef foo (expr i, j) = save ii, jj ; ii := 2*i ; jj :=j/2 ; (i, j) -- (ii,jj) enddef ; draw (foo(1,2) .. foo(5,1) .. foo(12,3)) ysized 1cm withpen pencircle scaled 2mm withcolor darkred ; draw boundingbox currentpicture withcolor darkyellow ; \stopbuffer \typebuffer This weird shape comes out: \startlinecorrection[blank] \processMPbuffer \stoplinecorrection We save two variables, and then give new local numerics with their names some values. Then we \quote {return} a path. A \type {vardef} automatically starts with a \type {begingroup} and ends with an \type {endgroup}. The next example shows how we can use that grouping trick directly. The \type {--} has to come before the \type {begingroup}. \startbuffer vardef turtle expr p = save a ; pair a ; a := point 0 of p ; a for i = 1 upto length(p) if cycle p : - 1 fi : -- begingroup a := a shifted point i of p ; a endgroup endfor if cycle p : -- cycle fi enddef ; draw ((0, 0) -- (10, 0) -- (100, 10) -- (-5,20) -- cycle) withpen pencircle scaled 2 withcolor darkred ; draw turtle ((0, 0) -- (10, 0) -- (100, 10) -- (-5,20) -- cycle) withpen pencircle scaled 2 withcolor darkyellow ; \stopbuffer \typebuffer Turtle graphics use relative positions. Actually they use one number and switch direction but the above is okay too. Effectively we loop over the path and use each point as a relative move, so we recalculate it. \startlinecorrection[blank] \processMPbuffer \stoplinecorrection We could have said \type {-- hide(a := a shifted point i of p) a} because the \type {hide} macro does that the grouping trick. \stopsection \startsection[title=External files] You can put code in an external file and load that one when needed. The low level command is \type {input}: \starttyping input myfile ; input myfile.mp ; input myfile.mpiv ; input myfile.mpxl ; input "myfile.mpxl" ; \stoptyping In \CONTEXT\ we have modules and their name starts with \type {mp-} and the suffix can depend on what version you use (\type {mpii}, \type {mpiv}, \type {mpxl}) but that will be dealt with automatically. \starttyping loadmodule("mine") ; \stoptyping This will locate \type {mp-mine} with the proper suffix and often a module will be set up to be loaded only once. For loading files \LUAMETAFUN\ provides: \starttyping loadfile("somefile.mp") ; \stoptyping Which is a bit more robust than the \type {input} commands that is kind of fuzzy because it takes a sequence of tokens or a string. When you embed code in a document source there are some environments that permit loading of definitions and extensions. \starttyping \startMPdefinitions % code passed to the library directly \stopMPdefinitions \startMPextensions % code passed to the library but via tex (expansion step) \stopMPextensions \stoptyping \stopsection \startsection[title=Instances] The library supports several numbering models. The default is \type {scaled} that uses integers that represent a (relatively small) float. Although you can go up to 32K it's wise to stay below 4096. The \type {double} number model supports 64 bit floating point and the \type {decimal} model arbitrary precision. In \LUATEX\ there is also \type {binary} for arbitrary precision but in \LUAMETATEX\ that model is not provided. You can use different models and instances alongside. In \MKIV\ and \LMTX\ we have a few predefined. The \type {metafun} instance is the default. Here we show the ones that use \METAFUN: \starttyping[style=\ttx] \defineMPinstance[metafun] [format=metafun,extensions=yes,initializations=yes] \defineMPinstance[minifun] [format=minifun,extensions=yes,initializations=yes] \defineMPinstance[extrafun] [format=metafun,extensions=yes,initializations=yes] \defineMPinstance[lessfun] [format=metafun] \defineMPinstance[doublefun] [format=metafun,extensions=yes,initializations=yes,method=double] \defineMPinstance[decimalfun][format=metafun,extensions=yes,initializations=yes,method=decimal] \defineMPinstance[mprun] [format=metafun,extensions=yes,initializations=yes] \defineMPinstance[simplefun] [format=metafun,method=double] % for internal usage \stoptyping All instances will load additional definitions btu extensions (expanded definitions) and initializations (before each graphic) are optional. \starttyping \startMPdefinitions \stopMPdefinitions \startMPextensions \stopMPextensions \startMPinitializations \stopMPinitializations \stoptyping You can search the sources of manuals and test suite for examples of usage, but here are some: \startbuffer \defineMPinstance[foo][definitions=yes] \defineMPinstance[bar][definitions=yes] \startMPdefinitions{foo} vardef p = image ( draw fullsquare scaled 1cm withcolor "darkgreen" ; draw textext("1") ; ) enddef ; \stopMPdefinitions \startMPdefinitions{bar} vardef p = image ( draw (fullsquare rotated 45) scaled 1cm withcolor "darkyellow" ; draw textext("2") ; ) enddef ; \stopMPdefinitions \stopbuffer \typebuffer \getbuffer We use both as: \startbuffer[demo-1] \startMPcode{foo} draw p ; draw image ( draw fullcircle scaled 1cm withcolor "darkblue" ; draw textext("3") withcolor "darkred" ; ) ; draw p ; \stopMPcode \stopbuffer \startbuffer[demo-2] \startMPcode{bar} draw p ; draw image ( draw fullcircle scaled 1cm withcolor "darkblue" ; draw textext("4") withcolor "darkred" ; ) ; \stopMPcode \stopbuffer \typebuffer[demo-1,demo-2] \startlinecorrection \startcombination[nx=2,ny=1] {\getbuffer[demo-1]} {foo} {\getbuffer[demo-2]} {bar} \stopcombination \stoplinecorrection \stopsection \stopchapter \stopcomponent