path: root/doc/context/sources/general/manuals/metafun/metafun-basics.tex

% language=uk
%
% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa

\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.

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 mp-tool ; % or 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.

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.

\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
\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\'ezier curves. The fact
that these curves are named after Pierre B\'ezier obscures the fact that the math
behind them originates with Serge\u{\i} Bernshte\u{\i}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 its 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 zon 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.

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 .

\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

\stopchapter

\stopcomponent