% language=us

\startcomponent metafun-welcome

\environment metafun-environment

\startchapter[reference=sec:welcome,title={Welcome to MetaPost}]

\startintro

In this chapter, we will introduce the most important \METAPOST\ concepts as well
as demonstrate some drawing primitives and operators. This chapter does not
replace the \METAFONT\ book or \METAPOST\ manual, both of which provide a lot of
explanations, examples, and (dirty) tricks.

As its title says, the \METAFONT\ book by Donald.\ E.\ Knuth is about fonts.
Nevertheless, buying a copy is worth the money, because as a \METAPOST\ user you
can benefit from the excellent chapters about curves, algebraic expressions, and
(linear) equations. The following sections are incomplete in many aspects. More
details on how to define your own macros can be found in both the \METAFONT\ book
and \METAPOST\ manual, but you will probably only appreciate the nasty details if
you have written a few simple figures yourself. This chapter will give you a
start.

A whole section is dedicated to the basic extensions to \METAPOST\ as provided by
\METAFUN. Most of them are meant to make defining graphics like those shown in
this document more convenient.

Many of the concepts introduced here will be discussed in more detail in later
chapters. So, you may consider this chapter to be an appetizer for the following
chapters. If you want to get started quickly, you can safely skip this chapter
now.

\stopintro

\startsection[title={Paths}]

\index{paths}

Paths are the building blocks of \METAPOST\ graphics. In its simplest form, a
path is a single point.

\startuseMPgraphic{axis}
  tickstep := 1cm ; ticklength := 2mm ;
  drawticks unitsquare xscaled 4cm yscaled 3cm shifted (-1cm,-1cm) ;
  tickstep := tickstep/2 ; ticklength := ticklength/2 ;
  drawticks unitsquare xscaled 4cm yscaled 3cm shifted (-1cm,-1cm) ;
\stopuseMPgraphic

\startlinecorrection[blank]
\startMPcode
  \includeMPgraphic{axis}
  drawpoint "1cm,1.5cm" ;
\stopMPcode
\stoplinecorrection

Such a point is identified by two numbers, which represent the horizontal and
vertical position, often referred to as $x$ and $y$, or $(x,y)$. Because there
are two numbers involved, in \METAPOST\ this point is called a pair. Its related
datatype is therefore \type {pair}. The following statements assigns the point we
showed previously to a pair variable.

\starttyping
pair somepoint ; somepoint := (1cm,1.5cm) ;
\stoptyping

A pair can be used to identify a point in the two dimensional coordinate space,
but it can also be used to denote a vector (being a direction or displacement).
For instance, \type {(0,1)} means \quote {go up}. Looking through math glasses,
you may consider them vectors, and if you know how to deal with them, \METAPOST\
may be your friend, since it knows how to manipulate them.

You can connect points and the result is called a path. A path is a straight or
bent line, and is not necessarily a smooth curve. An example of a simple
rectangular path is: \footnote {In the next examples we use the debugging
features discussed in \in {chapter} [sec:debugging] to visualize the points,
paths and bounding boxes.}

\startuseMPgraphic{path}
  path p ;
  p := unitsquare xyscaled (2cm,1cm) shifted (.5cm,.5cm) ;
\stopuseMPgraphic

\startlinecorrection[blank]
\startMPcode
  \includeMPgraphic{axis}
  \includeMPgraphic{path}
  drawpath p ;
\stopMPcode
\stoplinecorrection

This path is constructed out of four points:

\startlinecorrection[blank]
\startMPcode
  \includeMPgraphic{axis}
  \includeMPgraphic{path}
  swappointlabels := true ; drawpath p ; drawpoints p ;
\stopMPcode
\stoplinecorrection

Such a path has both a beginning and end and runs in a certain direction:

\startlinecorrection[blank]
\startMPcode
  \includeMPgraphic{axis}
  \includeMPgraphic{path}
  autoarrows := true ;
  swappointlabels := true ; drawarrowpath p ; drawpoints p ;
\stopMPcode
\stoplinecorrection

A path can be open or closed. The previous path is an example of a closed path.
An open path looks like this:

\startuseMPgraphic{path}
  path p ; p := (1cm,1cm)..(1.5cm,1.5cm)..(2cm,0cm) ;
\stopuseMPgraphic

\startlinecorrection[blank]
\startMPcode
  \includeMPgraphic{axis}
  \includeMPgraphic{path}
  swappointlabels := true ; drawpath p ; drawpoints p ;
\stopMPcode
\stoplinecorrection

When we close this path |<|and in a moment we will see how to do this|>| the path
looks like:

\startbuffer
\startlinecorrection[blank]
\startMPcode
  \includeMPgraphic{axis}
  \includeMPgraphic{path}
  p := p .. cycle ;
  swappointlabels := true ; drawpath p ; drawpoints p ;
\stopMPcode
\stoplinecorrection
\stopbuffer

\getbuffer

The open path is defined as:

\starttyping
(1cm,1cm)..(1.5cm,1.5cm)..(2cm,0cm)
\stoptyping

The \quote {double period} connector \type {..} tells \METAPOST\ that we want to
connect the lines by a smooth curve. If you want to connect points with straight
line segments, you should use \type {--}.

Closing the path is done by connecting the first and last point, using the \type
{cycle} command.

\starttyping
(1cm,1cm)..(1.5cm,1.5cm)..(2cm,0cm)..cycle
\stoptyping

Feel free to use \type {..} or \type {--} at any point in your path.

\starttyping
(1cm,1cm)--(1.5cm,1.5cm)..(2cm,0cm)..cycle
\stoptyping

\startuseMPgraphic{path}
path p ; p := (1cm,1cm)--(1.5cm,1.5cm)..(2cm,0cm)..cycle ;
\stopuseMPgraphic

This path, when drawn, looks like this:

\getbuffer

As you can see in some of the previous examples, \METAPOST\ is capable of drawing
a smooth curve through the three points that make up the path. We will now
examine how this is done.

\startlinecorrection[blank]
\startMPcode
  \includeMPgraphic{axis}
  \includeMPgraphic{path}
  p := p .. cycle ; swappointlabels := true ;
  drawpath p ; drawcontrollines p ; drawpoints p ; drawcontrolpoints p ;
\stopMPcode
\stoplinecorrection

The six small points are the so called control points. These points pull their
parent point in a certain direction. The further away such a point is, the
stronger the pull.

Each point has at most two control points. As you can see in the following
graphic, the endpoints of a non closed curve have only one control point.

\startuseMPgraphic{path}
path p ; p := (1.5cm,1.5cm)..(2cm,0cm)..(1cm,1cm) ;
\stopuseMPgraphic

\startbuffer[path]
\startlinecorrection[blank]
\startMPcode
  \includeMPgraphic{axis}
  \includeMPgraphic{path}
  swappointlabels := true ;
  drawpath p ; drawcontrollines p ; drawpoints p ; drawcontrolpoints p ;
\stopMPcode
\stoplinecorrection
\stopbuffer

\getbuffer[path]

This time we used the path:

\starttyping
(1.5cm,1.5cm)..(2cm,0cm)..(1cm,1cm)
\stoptyping

When you connect points by a smooth curve, \METAPOST\ will calculate the control
points itself, unless you specify one or more of them.

\startuseMPgraphic{path}
  path p ; p := (1cm,1cm)..(1.5cm,1.5cm)..controls (3cm,2cm)..(2cm,0cm) ;
\stopuseMPgraphic

\getbuffer[path]

This path is specified as:

\starttyping
(1cm,1cm)..(1.5cm,1.5cm)..controls (3cm,2cm)..(2cm,0cm)
\stoptyping

In this path, the second and third point share a control point. Watch how the
curve is pulled in that direction. It is possible to pull a bit less by choosing
a different control point:

\starttyping
(1cm,1cm)..(1.5cm,1.5cm)..controls (2.75cm,1.25cm)..(2cm,0cm)
\stoptyping

Now we get:

\startuseMPgraphic{path}
  path p ; p := (1cm,1cm)..(1.5cm,1.5cm)..controls (2.75cm,1.25cm)..(2cm,0cm) ;
\stopuseMPgraphic

\getbuffer[path]

We can also specify a different control point for each connecting segment.

\startuseMPgraphic{path}
  path p ; p := (1cm,1cm)..controls (.5cm,2cm) and (2.5cm,2cm)..(2cm,.5cm) ;
\stopuseMPgraphic

\getbuffer[path]

This path is defined as:

\starttyping
(1cm,1cm)..controls (.5cm,2cm) and (2.5cm,2cm)..(2cm,.5cm)
\stoptyping

\stopsection

\startsection[title={Transformations}]

\index{transformations}

We can store a path in a path variable. Before we can use such a variable, we
have to allocate its memory slot with \type {path}.

\starttyping
path p ; p := (1cm,1cm)..(1.5cm,2cm)..(2cm,0cm) ;
\stoptyping

Although we can manipulate any path in the same way, using a variable saves us
the effort to key in a path more than once.

\startuseMPgraphic{axis}
  tickstep := 1cm ; ticklength := 2mm ;
  drawticks unitsquare xscaled 8cm yscaled 4cm ;
  tickstep := tickstep/2 ; ticklength := ticklength/2 ;
  drawticks unitsquare xscaled 8cm yscaled 4cm ;
\stopuseMPgraphic

\startuseMPgraphic{path}
  path p ; p := (1cm,1cm)..(1.5cm,2cm)..(2cm,0cm)..cycle ;
  path q ; q := p shifted (4cm,2cm) ;
\stopuseMPgraphic

\startbuffer[path]
\startlinecorrection[blank]
\startMPcode
  \includeMPgraphic{axis}
  \includeMPgraphic{path}
  swappointlabels := true ;
  drawpath p ; drawcontrollines p ; drawpoints p ; drawcontrolpoints p ;
  drawpath q ; drawcontrollines q ; drawpoints q ; drawcontrolpoints q ;
\stopMPcode
\stoplinecorrection
\stopbuffer

\getbuffer[path]

In this graphic, the path stored in \type {p} is drawn twice, once in its
displaced form. The displacement is defined as:

\starttyping
p shifted (4cm,2cm)
\stoptyping

In a similar fashion you can rotate a path. You can even combine shifts and
rotations. First we rotate the path 15 degrees counter||clockwise around the
origin.

\starttyping
p rotated 15
\stoptyping

\startuseMPgraphic{path}
  path p ; p := (1cm,1cm)..(1.5cm,2cm)..(2cm,0cm)..cycle ;
  path q ; q := p rotated 15 ;
\stopuseMPgraphic

\getbuffer[path]

This rotation becomes more visible when we also shift the path to the right by
saying:

\starttyping
rotated 15 shifted (4cm,0cm)
\stoptyping

Now we get:

\startuseMPgraphic{path}
  path p ; p := (1cm,1cm)..(1.5cm,2cm)..(2cm,0cm)..cycle ;
  path q ; q := p rotated 15 shifted (4cm,0cm) ;
\stopuseMPgraphic

\getbuffer[path]

Note that \type {rotated 15} is equivalent to \typ {p rotatedaround (origin,
15)}.

It may make more sense to rotate the shape around its center. This can easily be
achieved with the \type {rotatedaround} command. Again, we move the path to the
right afterwards.

\starttyping
p rotatedaround(center p, 15) shifted (4cm,0cm)
\stoptyping

\startuseMPgraphic{axis}
  tickstep := 1cm ; ticklength := 2mm ;
  drawticks unitsquare xscaled 10cm yscaled 3cm ;
  tickstep := tickstep/2 ; ticklength := ticklength/2 ;
  drawticks unitsquare xscaled 10cm yscaled 3cm ;
\stopuseMPgraphic

\startuseMPgraphic{path}
  path p ; p := (1cm,1cm)..(1.5cm,2cm)..(2cm,0cm)..cycle ;
  path q ; q := p rotatedaround(center p, 15) shifted (4cm,0cm) ;
\stopuseMPgraphic

\getbuffer[path]

Yet another transformation is slanting. Just like characters can be upright or
slanted, a graphic can be:

\starttyping
p slanted 1.5 shifted (4cm,0cm)
\stoptyping

\startuseMPgraphic{path}
  path p ; p := (1cm,1cm)..(1.5cm,2cm)..(2cm,0cm)..cycle ;
  path q ; q := p slanted 1.5 shifted (4cm,0cm) ;
\stopuseMPgraphic

\getbuffer[path]

The slant operation's main application is in tilting fonts. The $x$||coodinates
are increased by a percentage of their $y$||coordinate, so here every $x$ becomes
$x+1.5y$. The $y$||coordinate is left untouched. The following table summarizes
the most important primitive transformations that \METAPOST\ supports.

\starttabulate[|lT|l|]
\HL
\NC \METAPOST\ code     \NC mathematical equivalent \NC \NR
\HL
\NC (x,y) shifted (a,b) \NC $(x+a,y+b)$     \NC \NR
\NC (x,y) scaled  s     \NC $(sx,sy)$       \NC \NR
\NC (x,y) xscaled s     \NC $(sx,y)$        \NC \NR
\NC (x,y) yscaled s     \NC $(x,sy)$        \NC \NR
\NC (x,y) zscaled (u,v) \NC $(xu-yv,xv+yu)$ \NC \NR
\NC (x,y) slanted s     \NC $(x+sy,y)$      \NC \NR
\NC (x,y) rotated r     \NC $(x\cos(r)-y\sin(r),x\sin(r)+y\cos(r))$ \NC \NR
\HL
\stoptabulate

The previously mentioned \type {rotatedaround} is not a primitive but a macro,
defined in terms of shifts and rotations. Another transformation macro is
mirroring, or in \METAPOST\ terminology, \type {reflectedabout}.

\startbuffer[path]
\startlinecorrection[blank]
\startMPcode
  \includeMPgraphic{axis}
  \includeMPgraphic{path}
  swappointlabels := true ;
  drawpath p ; drawpoints p ;
  drawpath q ; drawpoints q ;
\stopMPcode
\stoplinecorrection
\stopbuffer

\startuseMPgraphic{path}
  path p ; p := unitsquare scaled 2cm shifted (2cm,.5cm) ;
  path q ; q := unitsquare scaled 2cm shifted (2cm,.5cm) reflectedabout((2.4cm,-.5),(2.4cm,3cm)) ;
  draw (2.4cm,-.5cm)--(2.4cm,3cm) ;
\stopuseMPgraphic

\getbuffer[path]

The reflection axis is specified by a pair of points. For example, in the graphic
above, we used the following command to reflect the square about a line through
the given points.

\starttyping
p reflectedabout((2.4cm,-.5),(2.4cm,3cm))
\stoptyping

The line about which the path is mirrored. Mirroring does not have to be parallel
to an axis.

\starttyping
p reflectedabout((2.4cm,-.5),(2.6cm,3cm))
\stoptyping

The rectangle now becomes:

\startuseMPgraphic{path}
  path p ; p := unitsquare scaled 2cm shifted (2cm,.5cm) ;
  path q ; q := unitsquare scaled 2cm shifted (2cm,.5cm) reflectedabout((2.4cm,-.5),(2.6cm,3cm)) ;
  draw (2.4cm,-.5cm)--(2.6cm,3cm) ;
\stopuseMPgraphic

\getbuffer[path]

\pagereference [zscaled]The table also mentions \type {zscaled}.

\startuseMPgraphic{path}
path p ; p := unitsquare scaled (1cm)                shifted (1cm,.5cm) ;
path q ; q := unitsquare scaled (1cm) zscaled (2,.5) shifted (1cm,.5cm) ;
\stopuseMPgraphic

\getbuffer[path]

A \type {zscaled} specification takes a vector as argument:

\starttyping
p zscaled (2,.5)
\stoptyping

The result looks like a combination of scaling and rotation, and conforms to the
formula in the previous table.

Transformations can be defined in terms of a transform matrix. Such a matrix is
stored in a transform variable. For example:

\starttyping
transform t ; t := identity scaled 2cm shifted (4cm,1cm) ;
\stoptyping

We use the associated keyword \type {transformed} to apply this matrix to a path
or picture.

\starttyping
p transformed t
\stoptyping

In this example we've taken the \type {identity} matrix as starting point but you
can use any predefined transformation. The identity matrix is defined in such a
way that it scales by a factor of one in both directions and shifts over the
zero||vector.

Transform variables can save quite some typing and may help you to force
consistency when many similar transformations are to be done. Instead of changing
the scaling, shifting and other transformations you can then stick to just
changing the one transform variable.

\stopsection

\startsection[title={Constructing paths}]

\index{paths}

In most cases, a path will have more points than the few shown here. Take for
instance a so called {\em super ellipse}.

\startlinecorrection[blank]
\startMPcode
path p ; p := fullsquare xyscaled (5cm,3cm) superellipsed .85 ;
drawpath p ; drawpoints p ;
visualizepaths ; draw p shifted (6cm,0cm) withcolor .625yellow ;
\stopMPcode
\stoplinecorrection

These graphics provide a lot of information. In this picture the crosshair in the
center is the {\em origin} and the dashed rectangle is the {\em bounding box} of
the super ellipse. The bounding box specifies the position of the graphic in
relation to the origin as well as its width and height.

In the graphic on the right, you can see the points that make up the closed path
as well as the control points. Each point has a number with the first point
numbered zero. Because the path is closed, the first and last point coincide.

\startuseMPgraphic{axis}
  tickstep := 1cm ; ticklength := 2mm ;
  drawticks unitsquare xscaled 8cm yscaled 3cm ;
  tickstep := tickstep/2 ; ticklength := ticklength/2 ;
  drawticks unitsquare xscaled 8cm yscaled 3cm ;
\stopuseMPgraphic

\startbuffer
\startlinecorrection[blank]
\startMPcode
  string tmp ; defaultfont := "\truefontname{Mono}" ;
  \includeMPgraphic{axis}
  \includeMPgraphic{points}
  \includeMPgraphic{path}
  label.lft(verbatim(tmp),(14.5cm,2.5cm)) ;
  drawwholepath scantokens(tmp) ;
\stopMPcode
\stoplinecorrection
\stopbuffer

We've used the commands \type {..} and \type {--} as path connecting directives.
In the next series of examples, we will demonstrate a few more. However, before
doing that, we define a few points, using the predefined \type {z} variables.

\startuseMPgraphic{points}
  z0 = (0.5cm,1.5cm) ; z1 = (2.5cm,2.5cm) ;
  z2 = (6.5cm,0.5cm) ; z3 = (3.0cm,1.5cm) ;
\stopuseMPgraphic

\starttyping
z0 = (0.5cm,1.5cm) ; z1 = (2.5cm,2.5cm) ;
z2 = (6.5cm,0.5cm) ; z3 = (3.0cm,1.5cm) ;
\stoptyping

Here \type {z1} is a short way of saying \type {(x1,y1)}. When a \type {z}
variable is called, the corresponding \type {x} and \type {y} variables are
available too. Later we will discuss \METAPOST\ capability to deal with
expressions, which are expressed using an \type {=} instead of \type {:=}. In
this case the expression related to \type {z0} is expanded into:

\starttyping
z0 = (x0,y0) = (0.5cm,1.5cm) ;
\stoptyping

But for this moment let's forget about their expressive nature and simply see
them as points which we will now connect by straight line segments.

\startuseMPgraphic{path}
  tmp := "z0--z1--z2--z3--cycle" ;
\stopuseMPgraphic

\getbuffer

The smooth curved connection, using \type {..} looks like:

\startuseMPgraphic{path}
  tmp := "z0..z1..z2..z3..cycle" ;
\stopuseMPgraphic

\getbuffer

If we replace the \type {..} by \type {...}, we get a tighter path.

\startuseMPgraphic{path}
  tmp := "z0...z1...z2...z3...cycle" ;
\stopuseMPgraphic

\getbuffer

Since there are \type {..}, \type {--}, and \type {...}, it will be no surprise
that there is also \type {---}.

\startuseMPgraphic{path}
  tmp := "z0---z1---z2---z3---cycle" ;
\stopuseMPgraphic

\getbuffer

If you compare this graphic with the one using \type {--} the result is the same,
but there is a clear difference in control points. As a result, combining \type
{..} with \type {--} or \type {---} makes a big difference. Here we get a
non||smooth connection between the curves and the straight line.

\startuseMPgraphic{path}
  tmp := "z0..z1..z2--z3..cycle" ;
\stopuseMPgraphic

\getbuffer

As you can see in the next graphic, when we use \type {---}, we get a smooth
connection between the straight line and the rest of the curve.

\startuseMPgraphic{path}
  tmp := "z0..z1..z2---z3..cycle" ;
\stopuseMPgraphic

\getbuffer

So far, we have joined the four points as one path. Alternatively, we can
constrict subpaths and connect them using the ampersand symbol, \type {&}.

\startuseMPgraphic{path}
  tmp := "z0..z1..z2 & z2..z3..z0 & cycle" ;
\stopuseMPgraphic

\getbuffer

So far we have created a closed path. Closing is done by \type {cycle}. The
following path may look closed but is in fact open.

\startuseMPgraphic{path}
  tmp := "z0..z1..z2..z3..z0" ;
\stopuseMPgraphic

\getbuffer

Only a closed path can be filled. The closed alternative looks as follows. We
will see many examples of filled closed paths later on.

\startuseMPgraphic{path}
  tmp := "z0..z1..z2..z3..z0..cycle" ;
\stopuseMPgraphic

\getbuffer

Here the final \type {..} will try to make a smooth connection, but because we
already are at the starting point, this is not possible. However, the \type
{cycle} command can automatically connect to the first point. Watch the
difference between the previous and the next path.

\startuseMPgraphic{path}
  tmp := "z0..z1..z2..z3..cycle" ;
\stopuseMPgraphic

\getbuffer

It is also possible to combine two paths into one that don't have common head and
tails. First we define an open path:

\startuseMPgraphic{path}
  tmp := "z0..z1..z2" ;
\stopuseMPgraphic

\getbuffer

The following path is a closed one, and crosses the previously shown path.

\startuseMPgraphic{path}
  tmp := "z0..z3..z1..cycle" ;
\stopuseMPgraphic

\getbuffer

With \type {buildcycle} we can combine two paths into one.

\startuseMPgraphic{path}
  tmp := "buildcycle(z0..z1..z2 , z0..z3..z1..cycle)" ;
\stopuseMPgraphic

\getbuffer

We would refer readers to the \METAFONT\ book and the \METAPOST\ manual for an
explanation of the intricacies of the \type {buildcycle} command. It is an
extremely complicated command, and there is just not enough room here to do it
justice. We suffice with saying that the paths should cross at least once before
the \type {buildcycle} command can craft a combined path from two given paths. We
encourage readers to experiment with this command.

In order to demonstrate another technique of joining paths, we first draw a few
strange paths. The last of these three graphics demonstrates the use of \type
{softjoin}.

\startuseMPgraphic{path}
  tmp := "z0--z1..z2--z3" ;
\stopuseMPgraphic

\getbuffer

\startuseMPgraphic{path}
  tmp := "z0..z1..z2--z3" ;
\stopuseMPgraphic

\getbuffer

Watch how \type {softjoin} removes a point in the process of smoothing a
connection. The smoothness is accomplished by adapting the control points of the
neighbouring points in the appropriate way.

\startuseMPgraphic{path}
  tmp := "z0--z1 softjoin z2--z3" ;
\stopuseMPgraphic

\getbuffer

Once a path is known, you can cut off a slice of it. We will demonstrate a few
alternative ways of doing so, but first we show one more time the path that we
take as starting point.

\startuseMPgraphic{path}
  tmp := "z0..z1..z2..z3..cycle" ;
\stopuseMPgraphic

\getbuffer

This path is made up out of five points, where the cycle duplicates the first
point and connects the loose ends. The first point has number zero.

We can use these points in the \type {subpath} command, which takes two
arguments, specifying the range of points to cut of the path specified after the
keyword \type {of}.

\startuseMPgraphic{path}
  tmp := "subpath(2,4) of (z0..z1..z2..z3..cycle)" ;
\stopuseMPgraphic

\getbuffer

The new (sub|)|path is a new path with its own points that start numbering at
zero. The next graphic shows both the original and the subpath from point 1
upto~3.

\startuseMPgraphic{path}
  tmp := "(z0..z1..z2..z3..cycle)" ;
  sub := "subpath(1,3)" ;
\stopuseMPgraphic

\startbuffer[sub]
\startlinecorrection[blank]
\startMPcode
  string tmp, sub ; defaultfont := "\truefontname{Mono}" ;
  \includeMPgraphic{axis}
  \includeMPgraphic{points}
  \includeMPgraphic{path}
  label.lft(verbatim(tmp),(14.5cm,2.5cm)) ;
  label.lft(verbatim(sub),(14.5cm,2.0cm)) ;
  sub := sub & " of " & tmp ;
  path p ; p := scantokens(tmp) ;
  path q ; q := scantokens(sub) ;
  drawwholepath p ; swappointlabels := true ;
  drawpath q withcolor .625yellow ;
  drawpoints q withcolor .625red ;
  drawpointlabels q ;
\stopMPcode
\stoplinecorrection
\stopbuffer

\getbuffer[sub]

In spite of what you may think, a point is not fixed. This is why in \METAPOST\ a
point along a path is officially called a time. The next example demonstrates
that we can specify any time on the path.

\startuseMPgraphic{path}
  tmp := "(z0..z1..z2..z3..cycle)" ;
  sub := "subpath(2.45,3.85)" ;
\stopuseMPgraphic

\getbuffer[sub]

Often we want to take a slice starting at a specific point. This is provided by
\type {cutafter} and its companion \type {cutbefore}. Watch out, this time we use
a non||cyclic path.

\startuseMPgraphic{path}
  tmp := "(z0..z1..z2..z3)" ;
\stopuseMPgraphic

\getbuffer

When you use \type {cutafter} and \type {cutbefore} it really helps if you know
in what direction the path runs.

\startuseMPgraphic{path}
  tmp := "(z0..z1..z2..z3) cutafter z2" ;
\stopuseMPgraphic

\getbuffer

\startuseMPgraphic{path}
  tmp := "(z0..z1..z2..z3) cutbefore z1" ;
\stopuseMPgraphic

\getbuffer

Here is a somewhat silly way of accomplishing the same thing, but it is a nice
introduction to \METAPOST's \type {point} operation. In order to use this command
effectively, you need to know how many points make up the path.

\startuseMPgraphic{path}
  tmp := "(z0..z1..z2..z3) cutbefore point 2 of (z0..z1..z2..z3)" ;
\stopuseMPgraphic

\getbuffer

As with \type {subpath}, you can use fractions to specify the time on the path,
although the resulting point is not necessarily positioned linearly along the
curve.

\startuseMPgraphic{path}
  tmp := "(z0..z1..z2..z3) cutbefore point 2.5 of (z0..z1..z2..z3)" ;
\stopuseMPgraphic

\getbuffer

If you really want to know the details of where fraction points are positioned,
you should read the \METAFONT\ book and study the source of \METAFONT\ and
\METAPOST, where you will find the complicated formulas that are used to
calculate smooth curves.

\startuseMPgraphic{path}
  tmp := "z0..z1..cycle" ;
\stopuseMPgraphic

\getbuffer

Like any closed path, this path has points where the tangent is horizontal or
vertical. Early in this chapter we mentioned that a pair (or point) can specify a
direction or vector. Although any angle is possible, we often use one of four
predefined directions:

\starttabulate[|Tl|Tl|]
\HL
\NC right \NC ( 1, 0) \NC \NR
\NC up    \NC ( 0, 1) \NC \NR
\NC left  \NC (-1, 0) \NC \NR
\NC down  \NC ( 0,-1) \NC \NR
\HL
\stoptabulate

We can use these predefined directions in combination with \type {directionpoint}
and \type {cutafter}. The following command locates the first point on the path
that has a tangent that points vertically upward, and then feeds this point to
the \type {cutafter} command.

\startuseMPgraphic{path}
  tmp := "(z0..z1..cycle) cutafter directionpoint up of (z0..z1..cycle)" ;
\stopuseMPgraphic

\getbuffer

You are not limited to predefined direction vectors. You can provide a pair to
indicate a direction. In the next example we use the following cyclic path:

\startuseMPgraphic{path}
  tmp := "z0..z1..cycle" ;
\stopuseMPgraphic

\getbuffer

Using \type {( )} is not mandatory but makes the expression look less
complicated.

\startuseMPgraphic{path}
  tmp := "(z0..z1..cycle) cutafter directionpoint (1,1) of (z0..z1..cycle)" ;
\stopuseMPgraphic

\getbuffer

We will apply these commands in the next chapters, but first we will finish our
introduction in \METAPOST. We have seen how a path is constructed and what can be
done with it. Now it is time to demonstrate how such a path is turned into a
graphic.

\stopsection

\startsection[title={Angles}]

\index{angles}
\index{rotation}

You can go from angles to vectors and vice versa using the \type {angle} and
\type {dir} functions. The next example show both in action.

\startbuffer
pickup pencircle scaled 2mm ;
draw (origin -- dir(45) -- dir(0) -- cycle)
  scaled 3cm                   withcolor .625red ;
draw (origin -- dir(angle(1,1)) -- dir(angle(1,0)) -- cycle)
  scaled 3cm shifted (3.5cm,0) withcolor .625yellow ;
draw (origin -- (1,1) -- (1,0) -- cycle)
  scaled 3cm shifted (7cm,0)   withcolor .625white ;
\stopbuffer

\typebuffer

\startlinecorrection[blank]
\processMPbuffer
\stoplinecorrection

The \type {dir} command returns an unit vector, which is why the first two shapes
look different and are smaller than the third one. We can compensate for that by
an additional scaling:

\startbuffer
pickup pencircle scaled 2mm ;
draw (origin -- dir(45) -- dir(0) -- cycle)
  scaled sqrt(2) scaled 3cm                   withcolor .625red ;
draw (origin -- dir(angle(1,1)) -- dir(angle(1,0)) -- cycle)
  scaled sqrt(2) scaled 3cm shifted (4.5cm,0) withcolor .625yellow ;
draw (origin -- (1,1) -- (1,0) -- cycle)
                 scaled 3cm shifted (9cm,0)   withcolor .625white ;
\stopbuffer

\typebuffer

\startlinecorrection[blank]
\processMPbuffer
\stoplinecorrection

\stopsection

\startsection[title={Drawing pictures}]

\index{drawing}

Once a path is defined, either directly or as a variable, you can turn it into a
picture. You can draw a path, like we did in the previous examples, or you can
fill it, but only if it is closed.

\startlinecorrection[blank]
\startMPcode
visualizepaths ;
path p ; p := (0cm,1cm)..(2cm,2cm)..(4cm,0cm)..cycle ;
draw p withcolor .625red ;
fill p shifted (7cm,0) withcolor .625white ;
\stopMPcode
\stoplinecorrection

Drawing is done by applying the \type {draw} command to a path, as in:

\starttyping
draw (0cm,1cm)..(2cm,2cm)..(4cm,0cm)..cycle ;
\stoptyping

The rightmost graphic was made with \type {fill}:

\starttyping
fill (0cm,1cm)..(2cm,2cm)..(4cm,0cm)..cycle ;
\stoptyping

If you try to duplicate this drawing, you will notice that you will get black
lines instead of red and a black fill instead of a gray one. When drawing or
filling a path, you can give it a color, use all kinds of pens, and achieve
special effects like dashes or arrows.

\startlinecorrection[blank]
\startMPcode
visualizepaths ;
path p ; p := (0cm,1cm)..(2cm,2cm)..(4cm,0cm)..(2.5cm,1cm)..cycle ;
drawarrow p withcolor .625red ;
draw p shifted (7cm,0) dashed withdots withcolor .625yellow ;
\stopMPcode
\stoplinecorrection

These two graphics were defined and drawn using the following commands. Later we
will explain how you can set the line width (or penshape in terms of \METAPOST).

\starttyping
path p ; p := (0cm,1cm)..(2cm,2cm)..(4cm,0cm)..(2.5cm,1cm)..cycle ;
drawarrow p withcolor .625red ;
draw p shifted (7cm,0) dashed withdots withcolor .625yellow ;
\stoptyping

Once we have drawn one or more paths, we can store them in a picture variable.
The straightforward way to store a picture is to copy it from the current
picture:

\starttyping
picture pic ; pic := currentpicture ;
\stoptyping

The following command effectively clears the picture memory and allows us to
start anew.

\starttyping
currentpicture := nullpicture ;
\stoptyping

We can shift, rotate and slant the picture stored in \type {pic} as we did with
paths. We can say:

\starttyping
draw pic rotated 45 withcolor red ;
\stoptyping

A picture can hold multiple paths. You may compare a picture to grouping as
provided by drawing applications.

\starttyping
draw (0cm,0cm)--(1cm,1cm) ; draw (1cm,0cm)--(0cm,1cm) ;
picture pic ; pic := currentpicture ;
draw pic shifted (3cm,0cm) ; draw pic shifted (6cm,0cm) ;
pic := currentpicture ; draw pic shifted (0cm,2cm) ;
\stoptyping

We first draw two paths and store the resulting \quote {cross} in a picture
variable. Then we draw this picture two times, so that we now have three copies
of the cross. We store the accumulated drawing again, so that after duplication,
we finally get six crosses.

\startlinecorrection[blank]
\startMPcode
path p ; p := (0cm,0cm)--(1cm,1cm) ;
path q ; q := (1cm,0cm)--(0cm,1cm) ;
for i=p,q :
  drawpath i ; drawcontrollines i ; drawpoints i ; drawcontrolpoints i ;
endfor ;
picture pic ; pic := currentpicture ;
draw pic shifted (3cm,0cm) ;
draw pic shifted (6cm,0cm) ;
pic := currentpicture ;
draw pic shifted (0cm,2cm) ;
\stopMPcode
\stoplinecorrection

You can often follow several routes to reach the same solution. Consider for
instance the following graphic.

\startbuffer[points]
w := 4cm ; h := 2cm ; ww := 1cm ; hh := 1.5cm ;
\stopbuffer

\startbuffer[common]
drawoptions(withcolor .625white) ;
\stopbuffer

\startbuffer[background]
fill (unitsquare xscaled w yscaled h) enlarged 2mm withcolor .625yellow ;
\stopbuffer

\startbuffer[shape]
fill (0,0)--(ww,0)--(ww,hh)--(w,hh)--(w,h)--(0,h)--cycle ;
fill (ww,0)--(w,0)--(w,hh)--cycle ;
\stopbuffer

\typebuffer[shape]

\startlinecorrection[blank]
\processMPbuffer[common,points,shape]
\stoplinecorrection

The points that are used to construct the paths are defined using the constants
\type {w}, \type {h}, \type {ww} and \type {hh}. These are defined as follows:

\typebuffer[points]

In this case we draw two shapes that leave part of the rectangle uncovered. If
you have a background, this technique allows the background to \quote {show
through} the graphic.

\startlinecorrection[blank]
\processMPbuffer[common,points,background,shape]
\stoplinecorrection

A not uncommon practice when making complicated graphics is to use unfill
operations. Since \METAPOST\ provides one, let us see what happens if we apply
this command.

\startbuffer[shape]
fill (0,0)--(w,0)--(w,h)--(0,h)--cycle ;
unfill (ww,0)--(w,hh)--(ww,hh)--cycle ;
\stopbuffer

\typebuffer[shape]

\startlinecorrection[blank]
\processMPbuffer[common,points,background,shape]
\stoplinecorrection

This does not always give the desired effect, because \METAPOST's \type {unfill}
is not really an unfill, but a \type {fill} with color \type {background}. Since
this color is white by default, we get what we just showed. So, if we set \type
{background} to \type {black}, using \typ {background := black}, we get:

\startbuffer[back]
background := black ;
\stopbuffer

\startlinecorrection[blank]
\processMPbuffer[back,common,points,background,shape]
\stoplinecorrection

Of course, you can set the variable \type {background} to a different color, but
this does not hide the fact that \METAPOST\ lacks a real unfill operation.

\startbuffer[shape]
fill (0,0)--(0,h)--(w,h)--(w,0)--(ww,0)--(w,hh)--(ww,hh)--
     (ww,0)--cycle ;
\stopbuffer

\startbuffer[path]
autoarrows := true ;
path p ; p := (0,0)--(0,h)--(w,h)--(w,0)--(ww,0)--(w,hh)--(ww,hh)--
  (ww,0)--cycle ;
draw p withpen pencircle scaled 1mm withcolor .625red;
numeric l ; l := length(p)-1 ;
for i=0 upto l :
 drawarrow subpath(i,i+1) of p
   withpen pencircle scaled 1mm
   withcolor (.5+.5(i/l))*red ;
endfor ;
\stopbuffer

\startlinecorrection[blank]
\processMPbuffer[common,points,background,shape]
\stoplinecorrection

Since we don't consider this \type {unfill} a suitable operator, you may wonder
how we achieved the above result.

\typebuffer[shape]

\startlinecorrection[blank]
\processMPbuffer[common,points,background,shape,path]
\stoplinecorrection

This feature depends on the \POSTSCRIPT\ way of filling closed paths, which comes
down to filling either the left or the right hand side of a curve. The following
alternative works too.

\startbuffer[shape]
fill (0,0)--(0,h)--(w,h)--(w,hh)--(ww,hh)--(ww,0)--(w,hh)--
     (w,0)--cycle ;
\stopbuffer

\typebuffer[shape]

\startlinecorrection[blank]
\processMPbuffer[common,points,background,shape]
\stoplinecorrection

The next alternative will fail. This has to do with the change in direction at
point \type {(0,0)} halfway through the path. Sometimes changing direction can
give curious but desirable effects, but here it brings no good.

\startbuffer[shape]
fill (0,0)--(0,h)--(w,h)--(w,0)--(0,0)--(ww,0)--(ww,hh)--
     (w,hh)--(ww,0)--cycle ;
\stopbuffer

\typebuffer[shape]

This path fails because of the way \POSTSCRIPT\ implements its fill operator.
More details on how \POSTSCRIPT\ defines fills can be found in the reference
manuals.

\startlinecorrection[blank]
\processMPbuffer[common,points,background,shape]
\stoplinecorrection

Some of the operations we have seen are hard coded into \METAPOST\ and are called
primitives. Others are defined as macros, that is, a sequence of \METAPOST\
commands. Since they are used often, you may expect \type {draw} and \type {fill}
to be primitives, but they are not. They are macros defined in terms of
primitives.

Given a path \type {pat}, you can consider a \type {draw} to be defined in terms
of:

\starttyping
addto currentpicture doublepath pat
\stoptyping

The \type {fill} command on the other hand is defined as:

\starttyping
addto currentpicture contour pat
\stoptyping

Both macros are actually a bit more complicated but this is mainly due to the
fact that they also have to deal with attributes like the pen and color they draw
with.

You can use \type {doublepath} and \type {contour} directly, but we will use
\type {draw} and \type {fill} whenever possible.

Given a picture \type {pic}, the following code is valid:

\starttyping
addto currentpicture also pic
\stoptyping

You can add pictures to existing picture variables, where \type {currentpicture}
is the picture that is flushed to the output file. Watch the subtle difference
between adding a \type {doublepath}, \type {contour} or \type {picture}.

\stopsection

\startsection[title={Variables}]

\index{variables}

At this point you may have noted that \METAPOST\ is a programming language.
Contrary to some of today's languages, \METAPOST\ is a simple and clean language.
Actually, it is a macro language. Although \METAPOST\ and \TEX\ are a couple, the
languages differ in many aspects. If you are using both, you will sometimes wish
that features present in one would be available in the other. When using both
languages, in the end you will understand why the conceptual differences make
sense.

Being written in \PASCAL, it will be no surprise that \METAPOST\ has some
\PASCAL||like features, although some may also recognize features from \ALGOL68\
in it.

First there is the concept of variables and assignments. There are several data
types, some of which we already have seen.

\starttabulate
\HL
\NC numeric \NC real number in the range $-4096 \ldots +4096$          \NC \NR
\NC boolean \NC a variable that takes one of two states: true or false \NC \NR
\NC pair    \NC point or vector in 2||dimensional space                \NC \NR
\NC path    \NC a piecewise collection of curves and line segments     \NC \NR
\NC picture \NC collection of stroked or filled paths                  \NC \NR
\NC string  \NC sequence of characters, like \type {"metapost"}        \NC \NR
\NC color   \NC vector of three (rgb) or four (cmyk) numbers           \NC \NR
\HL
\stoptabulate

There are two additional types, \type {transform} and \type {pen}, but we will
not discuss these in depth.

\starttabulate
\HL
\NC transform \NC transformation vector with six elements \NC \NR
\NC pen       \NC pen specification                       \NC \NR
\HL
\stoptabulate

You can achieve interesting effects by using pens with certain shapes. For the
moment you may consider a pen to be a path itself that is applied to the path
that is drawn.

The \type {numeric} data type is used so often that it is the default type of any
non declared variable. This means that

\starttyping
n := 10 ;
\stoptyping

is the same as

\starttyping
numeric n ; n := 10 ;
\stoptyping

When writing collections of macros, it makes sense to use the second method,
because you can never be sure if \type {n} isn't already declared as a picture
variable, and assigning a numeric to a picture variable is not permitted.

Because we often deal with collections of objects, such as a series of points,
all variables can be organized in arrays. For instance:

\starttyping
numeric n[] ; n[3] := 10 ; n[5] := 13 ;
\stoptyping

An array is a collection of variables of the same type that are assigned and
accessed by indexing the variable name, as in \type {n[3] := 5}.
Multi||dimensional arrays are also supported. Since you need a bit of imagination
to find an application for 5||dimensional arrays, we restrict ourselves to a
two||dimensional example.

\starttyping
numeric n[][] ; n[2][3] := 10 ;
\stoptyping

A nice feature is that the bounds of such an array needs not to be set
beforehand. This also means that each cell that you access is reported as {\em
unknown} unless you have assigned it a value.

Behind the screens there are not really arrays. It's just a matter of creating
hash entries. It might not be obvious, but the following assignments are all
equivalent:

\startbuffer
i_111_222     := 1cm ;
i_[111]_[222] := 1cm ;
i_[111][222]  := 1cm ;
draw
    image (
        draw (0cm,i_111_222) ;
        draw (1cm,i_[111]_[222]) ;
        draw (2cm,i_[111][222]) ;
    )
    withpen pencircle scaled 5mm
    withcolor .625 red ;
\stopbuffer

\typebuffer

Sometimes \METAPOST\ ways are mysterious:

\startlinecorrection[blank]
\processMPbuffer
\stoplinecorrection

\stopsection

\startsection[title={Conditions}]

\index{conditions}

The existence of boolean variables indicates the presence of conditionals.
Indeed, the general form of \METAPOST's conditional follows:

\starttyping
if n=10 : draw p ; else : draw q ; fi ;
\stoptyping

Watch the colons after the if and else clause. They may not be omitted. The
semi||colons on the other hand, are optional and depend on the context. You may
say things like:

\starttyping
draw if n=10 : p ; else : q ; fi ;
\stoptyping

Here we can omit a few semi||colons:

\starttyping
draw if n=10 : p else : q fi withcolor red ;
\stoptyping

Adding semi||colons after \type {p} and \type {q} will definitely result in an
error message, since the semi||colon ends the draw operation and \typ {withcolor
red} becomes an isolated piece of nonsense.

There is no case statement available, but for most purposes, the following
extension is adequate:

\starttyping
draw p withcolor if n<10 : red elseif n=10 : green else : blue fi ;
\stoptyping

There is a wide repertoire of boolean tests available.

\starttyping
if picture p :
if known   n :
if odd     i :
if cycle   q :
\stoptyping

Of course, you can use \type {and}, \type {or}, \type {not}, and \type {( )} to
construct very advanced boolean expressions. If you have a bit of programming
experience, you will appreciate the extensive support of conditionals in
\METAPOST.

\stopsection

\startsection[title={Loops}]

\index{loops}

Yet another programming concept present in \METAPOST\ is the loop statement, the
familiar \quote {for loop} of all programming languages.

\starttyping
for i=0 step 2 until 20 :
  draw (0,i) ;
endfor ;
\stoptyping

As explained convincingly in Niklaus Wirth's book on algorithms and
datastructures, the for loop is the natural companion to an array. Given an array
of length $n$, you can construct a path out of the points that make up the array.

\starttyping
draw for i=0 step 1 until n-1 : p[i] .. endfor p[n] ;
\stoptyping

If the step increment is not explicitly stated, it has an assumed value of 1. We
can shorten the previous loop construct as follows:

\starttyping
draw for i=0 upto n-1 : p[i] .. endfor p[n] ;
\stoptyping

After seeing \type {if} in action, the following \type {for} loop will be no
surprise:

\startbuffer
draw origin for i=0 step 10 until 100 : ..{down}(i,0) endfor ;
\stopbuffer

\typebuffer

This gives the zig||zag curve:

\startlinecorrection[blank]
\processMPbuffer
\stoplinecorrection

You can use a loop to iterate over a list of objects. A simple 3||step iteration
is:

\starttyping
for i=p,q,r :
  fill i withcolor .8white ;
  draw i withcolor red ;
endfor ;
\stoptyping
Using \type {for} in this manner can sometimes save a bit of typing. The list can
contain any expression, and may be of different types.

In the previous example the \type {i} is an independent variable, local to the
for loop. If you want to change the loop variable itself, you need to use \type
{forsuffixes}. In the next loop the paths \type {p}, \type {q} and~\type {r} are
all shifted.

\starttyping
forsuffixes i = p, q, r :
  i := i shifted (3cm,2cm) ;
endfor ;
\stoptyping

Sometimes you may want to loop forever until a specific condition occurs. For
this, \METAPOST\ provides a special looping mechanism:

\startbuffer[demo]
numeric done[][], i, j, n ; n := 0 ;
forever :
  i := round(uniformdeviate(10)) ; j := round(uniformdeviate(2)) ;
  if unknown done[i][j] :
    drawdot (i*cm,j*cm) ; n := n + 1 ; done[i][j] := n ;
  fi ;
  exitif n = 10 ;
endfor ;
\stopbuffer

\typebuffer[demo]

Here we remain in the loop until we have 10 points placed. We use an array to
keep track of placed points. The \METAPOST\ macro \type {uniformdeviate(n)}
returns a random number between 0 and~n and the \type {round} command is used to
move the result toward the nearest integer. The \type {unknown} primitive allows
us to test if the array element already exists, otherwise we exit the
conditional. This saves a bit of computational time as each point is drawn and
indexed only once.

\startbuffer[pen]
pickup pencircle scaled 2mm ;
\stopbuffer

\startlinecorrection[blank]
\processMPbuffer[pen,demo]
\stoplinecorrection

The loop terminator \type {exitif} and its companion \type {exitunless} can be
used in \type {for}, \type {forsuffixes} and \type {forever}.

\stopsection

\startsection[title={Macros}]

\index{macros}
\index{definitions}

In the previous section we introduced \type {upto}. Actually this is not part of
the built in syntax, but a sort of shortcut, defined by:

\starttyping
def upto = step 1 until enddef ;
\stoptyping

You just saw a macro definition where \type {upto} is the name of the macro. The
counterpart of \type {upto} is \type {downto}. Whenever you use \type {upto}, it
is replaced by \typ {step 1 until}. This replacement is called expansion.

There are several types of macros. A primary macro is used to define your own
operators. For example:

\starttyping
primarydef p doublescaled s =
  p xscaled (s/2) yscaled (s*2)
enddef ;
\stoptyping

Once defined, the \type {doublescaled} macro is implemented as in the following
example:

\starttyping
draw somepath doublescaled 2cm withcolor red ;
\stoptyping

When this command is executed, the macro is expanded. Thus, the actual content of
this command becomes:

\starttyping
draw somepath xscaled 1cm yscaled 4cm withcolor red ;
\stoptyping

If in the definition of \type {doublescaled} we had added a semi||colon after
\type {(s*2)}, we could not have set the color, because the semicolon ends the
statement. The \type {draw} expects a path, so the macro can best return one.

A macro can take one or more arguments, as in:

\starttyping
def drawrandomscaledpath (expr p, s) =
  draw p xscaled (s/2) yscaled (s*2) ;
enddef ;
\stoptyping

When using this macro, it is expected that you will pass it two parameters, the
first being a path, the second a numeric scale factor.

\starttyping
drawrandomscaledpath(fullsquare, 3cm) ;
\stoptyping

Sometimes we want to return a value from a macro. In that case we must make sure
that any calculations don't interfere with the expectations. Consider:

\starttyping
vardef randomscaledpath(expr p, s) =
  numeric r ; r := round(1 + uniformdeviate(4)) ;
  p xscaled (s/r) yscaled (s*r)
enddef ;
\stoptyping

Because we want to use the same value of \type {r} twice, we have to use an
intermediate variable. By using a \type {vardef} we hide everything but the last
statement. It is important to distinguish \type {def} macros from those defined
with \type {vardef}. In the latter case, \type {vardef} macros are not a simple
expansion and replacement. Rather, \type {vardef} macros return the value of
their last statement. In the case of the \type {randomscaledpath} macro, a path
is returned. This macro is used in the following manner:

\starttyping
path mypath ; mypath := randomscaledpath(unitsquare,4cm) ;
\stoptyping

Note that we send \type {randomscaledpath} a path (\type {unitsquare}) and a
scaling factor (\type {4cm}). The macro returns a scaled path which is then
stored in the path variable \type {mypath}.

The following argument types are accepted:

\starttabulate
\HL
\NC expr   \NC something that can be assigned to a variable      \NC \NR
\NC text   \NC arbitrary \METAPOST\ code ending with a \type {;} \NC \NR
\NC suffix \NC a variable bound to another variable              \NC \NR
\HL
\stoptabulate
An expression is passed by value. This means that in the body of the macro, a
copy is used and the original is left untouched. On the other hand, any change to
a variable passed as suffix is also applied to the original.

Local variables must be handled in a special manner, since they may conflict with
variables used elsewhere. This is because all variables are global by default.
The way out of this problem is using grouping in combination with saving
variables. The use of grouping is not restricted to macros and may be used
anywhere in your code. Variables saved and declared in a group are local to that
group. Once the group is exited the variables cease to exist.

\starttyping
vardef randomscaledpath(expr p, s) =
  begingroup ; save r ; numeric r ;
    r := round(1 + uniformdeviate(4)) ;
    p xscaled (s/r) yscaled (s*r)
  endgroup
enddef ;
\stoptyping

In this particular case, we could have omitted the grouping, since \type {vardef}
macros are always grouped automatically. Therefore, we could have defined the
macro as:

\starttyping
vardef randomscaledpath(expr p, s) =
  save r ; numeric r ; r := round(1 + uniformdeviate(4)) ;
  p xscaled (s/r) yscaled (s*r)
enddef ;
\stoptyping

The command \type {save r} declares that the variable \type {r} is local to the
macro. Thus, any changes to the (new) numeric variable \type {r} are local and
will not interfere with a variable \type {r} defined outside the macro. This is
important to understand, as variables outside the macro are global and accessible
to the code within the body of the macro.

Macro definitions may be nested, but since most \METAPOST\ code is relatively
simple, it is seldom needed. Nesting is discouraged as it makes your code less
readable.

Besides \type {def} and \type {vardef}, \METAPOST\ also provides the classifiers
\type {primarydef}, \type {secondarydef} and \type {tertiarydef}. You can use
these classifiers to define macros like those provided by \METAPOST\ itself:

\starttyping
primarydef   x mod               y = ... enddef ;
secondarydef p intersectionpoint q = ... enddef ;
tertiarydef  p softjoin          q = ... enddef ;
\stoptyping
A primary macro acts like the binary operators \type {*} or \type {scaled} and
\type {shifted}. Secondary macros are like \type {+}, \type {-} and logical \type
{or}, and take less precedence. The tertiary operators like \type {<} or the path
and string concatenation operator \type {&} have tertiary macros as companions.
More details can be found in the \METAFONT\ book. When it comes to taking
precedence, \METAPOST\ tries to be as natural as possible, in the sense that you
need to provide as few \type {( )}'s as possible. When in doubt, or when
surprised by unexpected results, use parentheses.

\stopsection

\startsection[title={Arguments}]

\index{arguments}
\index{macros+arguments}

The \METAPOST\ macro language is rather flexible in how you feed arguments to
macros. If you have only one argument, the following definitions and calls are
valid.

\starttyping
def test  expr a  = enddef ; test (a) ; test a ;
def test (expr a) = enddef ; test (a) ; test a ;
\stoptyping

A more complex definition is the following. As you can see, you can call the
\type {test} macro in your favorite way.

\starttyping
def test (expr a,b) (expr c,d) = enddef ;

test (a) (b) (c) (d) ;
test (a,b) (c,d) ;
test (a,b,c) (d) ;
test (a,b,c,d) ;
\stoptyping

The type of the arguments is one of \type {expr}, \type {primary} or \type
{suffix}. When fetching arguments, \METAPOST\ uses the type to determine how and
what to grab. A fourth type is \type {text}. When no parenthesis are used, a
\type {text} argument grabs everything upto the next semicolon.

\starttyping
def test (expr a) text b = enddef ;

test (a) ; test (a) b ;
\stoptyping

You can use a \type {text} to grab arguments like \typ {withpen pencircle scaled
10 withcolor red}. Because \type {text} is so hungry, you may occasionally need a
two stage definition:

\starttyping
def test    expr a         = dotext(a) enddef ;
def dotest (expr a) text b = ...       enddef ;

test a ; test a b ;
\stoptyping

This definition permits arguments without parenthesis, which is something you
want with commands like \type {draw}.

The \type {vardef} alternative behaves in a similar way. It always provides
grouping. You need to generate a return value and as a result may not end with a
semicolon.

You may consider the whole \type {vardef} to be encapsulated into parenthesis and
thereby to be a (self contained) variable. Adding additional parenthesis often
does more harm than good:

\starttyping
vardef test (expr a) =
  ( do tricky things with a ; manipulated_a )
enddef ;
\stoptyping

Here the tricky things become part of the return value, which quite certainly is
something that you don't want.

The three operator look||alike macro definitions are less flexible and have the
definition scheme:

\starttyping
primarydef   x test y = enddef ;
secondarydef x test y = enddef ;
tertiarydef  x test y = enddef ;
\stoptyping

When defining macros using this threesome you need to be aware of the associated
priorities. When using these definitions, you also have to provide your own
grouping.

In the plain \METAPOST\ macro collection (\type {plain.mp}) you can find many
examples of clever definitions. The following (simplified) version of \type {min}
demonstrates how we use the argument handler to isolate the first argument from
the provided list, simply by using two arguments.

\starttyping
vardef min (expr u) (text t) =
  save min_u ; min_u := u ;
  for uu = t : if uu<u : min_u := uu ; fi endfor
  min_u
enddef ;
\stoptyping

The special sequence \type {@#} is used to pick up a so called delimited argument:

\starttyping
vardef TryMe@#(expr x) =
  % we can now use @#, which is just text
enddef ;
\stoptyping

This feature is used in the definition of \type {z} as used in \type {z1} or
\type {z234}:

\starttyping
vardef z@# = (x@#,y@#) enddef ;
\stoptyping

Other applications can be found in the label drawing macros where the anchor
point is assigned to the obscure variable \type {@#}.

\stopsection

\startsection[title={Pens}]

\index{pens}

When drawing, three attributes can be applied to it: a dashpattern, a pen
and|/|or a color. You may consider an arrowhead an attribute, but actually it is
just an additional drawing, appended to the path.

The (predefined) \type {pencircle} attribute looks like:

\starttyping
withpen pencircle
\stoptyping

where \type {pencircle} is a special kind of path, stored in a pen variable. Like
any path, you can transform it. You can scale it equally in all directions:

\starttyping
withpen pencircle scaled 1mm
\stoptyping

You can also provide unequal scales, creating an elliptically shaped and rotated
pen.

\starttyping
withpen pencircle xscaled 2mm yscaled 4mm rotated 30
\stoptyping

In the following graphic, the circle in the center is drawn without any option,
which means that the default pen is used, being a pencircle with a radius of half
a base point. The other three circles are drawn with different pen
specifications.

\startlinecorrection[blank]
\startMPcode
path p ; p := fullcircle scaled 1cm ;
drawoptions (withcolor .625yellow) ;
draw p ;
drawoptions (withcolor .625red) ;
draw p scaled 2 withpen pencircle ;
drawoptions (withcolor .625yellow) ;
draw p scaled 3 withpen pencircle scaled 1mm ;
drawoptions (withcolor .625red) ;
draw p scaled 4 withpen pencircle xscaled 2mm yscaled 4mm rotated 30 ;
\stopMPcode
\stoplinecorrection

If you forget about the colors, the \METAPOST\ code to achieve this is as
follows.

\starttyping
path p ; p := fullcircle scaled 1cm ;
draw p ;
draw p scaled 2 withpen pencircle ;
draw p scaled 3 withpen pencircle scaled 1mm ;
draw p scaled 4 withpen pencircle xscaled 2mm yscaled 4mm rotated 30 ;
\stoptyping

If this were the only way of specifying a pen, we would be faced with a
considerable amount of typing, particularly in situations where we use pens
similar to the fourth specification above. For that reason, \METAPOST\ supports
the concept of a current pen. The best way to set this pen is to use the \type
{pickup} macro.

\starttyping
pickup pencircle xscaled 2mm yscaled 4mm rotated 30 ;
\stoptyping

This macro also stores some characteristics of the pen in variables, so that they
can be used in (the more complicated) calculations that are involved in
situations like drawing font||like graphics.

If we substitute \type {pencircle} by \type {pensquare}, we get a different kind
of shapes. In the non rotated pens, the top, bottom, left and right parts of the
curve are thinner.

\startlinecorrection[blank]
\startMPcode
path p ; p := fullcircle scaled 1cm ;
drawoptions (withcolor .625yellow) ;
draw p ;
drawoptions (withcolor .625red) ;
draw p scaled 2 withpen pensquare ;
drawoptions (withcolor .625yellow) ;
draw p scaled 3 withpen pensquare scaled 1mm ;
drawoptions (withcolor .625red) ;
draw p scaled 4 withpen pensquare xscaled 2mm yscaled 4mm rotated 30 ;
\stopMPcode
\stoplinecorrection

You should look at pens in the way an artist does. He follows a shape and in
doing so he or she twists the pen (and thereby the nib) and puts more or less
pressure on it.

The chance that you have an appropriate pen laying at your desk is not so big,
but you can simulate the following \METAPOST's pen by taking two pencils and
holding them together in one hand. If you position them in a 45 degrees angle,
and draw a circle, you will get something like:

\startlinecorrection[blank]
\startMPcode
path p ; p := fullcircle xscaled 2cm yscaled 3cm ;
drawoptions(withcolor .625red withpen pencircle scaled .5mm);
draw p ; draw p shifted (.3cm,.3cm) ;
\stopMPcode
\stoplinecorrection

If you take a calligraphic pen with a thin edge of .5cm, you will get:

\startlinecorrection[blank]
\startMPcode
drawoptions(withcolor .625red);
path p ; p := fullcircle xscaled 2cm yscaled 3cm ;
draw p withpen makepen ((0,0)--(.3cm,.3cm)) withcolor .625white ;
drawoptions(withcolor .625red withpen pencircle scaled .25mm);
draw p ; draw p shifted (.3cm,.3cm) ;
\stopMPcode
\stoplinecorrection

You can define such a pen yourself:

\starttyping
path p ; p := fullcircle xscaled 2cm yscaled 3cm ;
pen doublepen ; doublepen := makepen ((0,0)--(.3cm,.3cm)) ;
pickup doublepen ; draw p ;
\stoptyping

Here we define a new pen using the \type {pen} command. Then we define a path,
and make a pen out of it using the \type {makepen} macro. The path should be a
relatively simple one, otherwise \METAPOST\ will complain.

You can use \type {makepen} with the previously introduced \type {withpen}:

\starttyping
draw p withpen makepen ((0,0)--(.3cm,.3cm)) ;
\stoptyping

and \type {pickup}:

\starttyping
pickup makepen ((0,0)--(.3cm,.3cm)) ; draw p ;
\stoptyping

You can use \type {makepen} and \type {makepath} to convert paths into pens and
vice versa.

Pens are very important when defining fonts, and \METAFONT\ is meant to be a font
creation tool. Since \METAPOST\ has a slightly different audience, it lacks some
features in this area, but offers a few others instead. Nevertheless, one can try
to design a font using \METAPOST. Of course, pens are among the designers best
kept secrets. But even then, not every~O is a nice looking one.

\startlinecorrection[blank]
\startMPcode
path p ; p := fullcircle xscaled 2cm yscaled 3cm ;
draw p withpen makepen (unitsquare scaled .4cm superellipsed .85)
withcolor .625white  ;
\stopMPcode
\stoplinecorrection

\startbuffer[s00]
    path p ; p := (-1,0) {down} .. {up} (1,0) ;
    draw pensilled(p, pensquare scaled (1/3))
        scaled 2cm ;
    draw boundingbox image(draw p)
        scaled 2cm ;
\stopbuffer

\startbuffer[s30]
    path p ; p := (-1,0) {down} .. {up} (1,0) ;
    draw pensilled(p, pensquare scaled (1/3) rotated 30)
        scaled 2cm ;
    draw boundingbox image(draw p)
        scaled 2cm ;
\stopbuffer

\startbuffer[s45]
    path p ; p := (-1,0) {down} .. {up} (1,0) ;
    draw pensilled(p, pensquare scaled (1/3) rotated 45)
        scaled 2cm ;
    draw boundingbox image(draw p)
        scaled 2cm ;
\stopbuffer

\startbuffer[c00]
    path p ; p := (-1,0) {down} .. {up} (1,0) ;
    draw pensilled(p, pencircle scaled (1/3))
        scaled 2cm ;
    draw boundingbox image(draw p)
        scaled 2cm ;
\stopbuffer

\startbuffer[c30]
    path p ; p := (-1,0) {down} .. {up} (1,0) ;
    draw pensilled(p, pencircle scaled (1/3) rotated 30)
        scaled 2cm ;
    draw boundingbox image(draw p)
        scaled 2cm ;
\stopbuffer

\startbuffer[c45]
    path p ; p := (-1,0) {down} .. {up} (1,0) ;
    draw pensilled(p, pencircle scaled (1/3) rotated 45)
        scaled 2cm ;
    draw boundingbox image(draw p)
        scaled 2cm ;
\stopbuffer

\startbuffer[f30]
    interim pensilstep := 1/6 ;
    draw pensilled(fullcircle, pencircle xscaled (1/10) yscaled (2/10) rotated 30)
        scaled 5cm ;
    draw boundingbox fullcircle
        scaled 5cm ;
\stopbuffer

The \type {pensilled} macro is a variant on a macro used for testing some border
cases in the engine. It provides a nice way to see what actually happens when a
pen is applied. \in {Figure} [fig:pensilled] demonstrates this macro. The first
row shows a square pen:

\typebuffer[s30]

and the second row a circular pen:

\typebuffer[c30]

\startplacefigure[title={How pens are applied.},reference=fig:pensilled]
    \startcombination[3*2]
        {\processMPbuffer[s00]} {\tttf pensquare rotated 0}
        {\processMPbuffer[s30]} {\tttf pensquare rotated 30}
        {\processMPbuffer[s45]} {\tttf pensquare rotated 45}
        {\processMPbuffer[c00]} {\tttf pencircle rotated 0}
        {\processMPbuffer[c30]} {\tttf pencircle rotated 30}
        {\processMPbuffer[c45]} {\tttf pencircle rotated 45}
    \stopcombination
\stopplacefigure

The effects of rotation and non|-|proportional scaling are demonstrated
in \in {figure} [fig:pensilled:fullcircle].

\typebuffer[f30]

\startplacefigure[title={A proportionally scaled and rotated pen.},reference=fig:pensilled:fullcircle]
    \processMPbuffer[f30]
\stopplacefigure

\stopsection

\startsection[title={Joining lines}]

\index{joining}
\index{paths+joining}

The way lines are joined or end is closely related to the way \POSTSCRIPT\
handles this. By setting the variables \type {linejoin} and \type {linecap}, you
can influence the drawing process. \in {Figure} [fig:joints] demonstrates the
alternatives. The gray curves are drawn with both variables set to \type
{rounded}.

\startnotmode[screen]

\def\showMPline#1#2%
  {\startMPcode
     path p ; p := ((0,0)--(.5,1)--(1,0)) xscaled 3cm yscaled 1.5cm ;
     pickup pencircle scaled 1cm ;
     draw p withcolor .625white ;
     interim linejoin := #1 ;
     interim linecap  := #2 ;
     draw p withcolor transparent(1,.5,.625yellow) ;
   \stopMPcode}

\stopnotmode

\startmode[screen]

\def\showMPline#1#2%
  {\startMPcode
     path p ; p := ((0,0)--(.5,1)--(1,0)) xscaled 2.5cm yscaled 1.25cm ;
     pickup pencircle scaled .75cm ;
     draw p withcolor .625white ;
     interim linejoin := #1 ;
     interim linecap  := #2 ;
     draw p withcolor transparent(1,.5,.625yellow) ;
   \stopMPcode}

\stopmode

\def\showMPtext#1#2%
  {linejoin=#1\par linecap=#2}

\startbuffer
\startcombination[3*3]
  {\showMPline{mitered}{butt}}    {\showMPtext{mitered}{butt}}
  {\showMPline{mitered}{rounded}} {\showMPtext{mitered}{rounded}}
  {\showMPline{mitered}{squared}} {\showMPtext{mitered}{squared}}
  {\showMPline{rounded}{butt}}    {\showMPtext{rounded}{butt}}
  {\showMPline{rounded}{rounded}} {\showMPtext{rounded}{rounded}}
  {\showMPline{rounded}{squared}} {\showMPtext{rounded}{squared}}
  {\showMPline{beveled}{butt}}    {\showMPtext{beveled}{butt}}
  {\showMPline{beveled}{rounded}} {\showMPtext{beveled}{rounded}}
  {\showMPline{beveled}{squared}} {\showMPtext{beveled}{squared}}
\stopcombination
\stopbuffer

\placefigure
  [here] [fig:joints]
  {The nine ways to end and join lines.}
  {\getbuffer}

By setting the variable \type {miterlimit}, you can influence the mitering of
joints. The next example demonstrates that the value of this variable acts as a
trigger.

\startbuffer
interim linejoin := mitered ;
for i :=1 step 1 until 5 :
  interim miterlimit := i*pt ;
  draw ((0,0)--(.5,1)--(1,0)) shifted (1.5i,0) scaled 50pt
    withpen pencircle scaled 10pt withcolor .625red ;
endfor ;
\stopbuffer

\typebuffer

The variables \type {linejoin}, \type {linecap} and \type {miterlimit} are so
called {\em internal} variables. When we prefix their assignments by \type
{interim}, the setting will be local within groups, like \typ {beginfig ...
endfig}.

\startlinecorrection[blank]
\processMPbuffer
\stoplinecorrection

\stopsection

\startsection[title={Colors}]

\index{attributes}
\index{color}
So far, we have seen some colors in graphics. It must be said that \METAPOST\
color model is not that advanced, although playing with colors in the \METAPOST\
way can be fun. In later chapters we will discuss some extensions that provide
shading.

Colors are defined as vectors with three components: a red, green and blue one.
Like pens, colors have their \type {with}||command:

\starttyping
withcolor (.4,.5.,6)
\stoptyping

You can define color variables, like:

\starttyping
color darkred ; darkred := (.625,0.0) ;
\stoptyping

You can now use this color as:

\starttyping
withcolor darkred
\stoptyping

Given that \type {red} is already defined, we also could have said:

\starttyping
withcolor .625red
\stoptyping

Because for \METAPOST\ colors are just vectors, you can do things similar to
points. A color halfway red and green is therefore accomplished with:

\starttyping
withcolor .5[red,green]
\stoptyping

Since only the \RGB\ color space is supported, this is about all we can tell
about colors for this moment. Later we will discuss some nasty details.

\stopsection

\startsection[title={Dashes}]

\index{dashes}

A dash pattern is a simple picture that is build out of straight lines. Any
slightly more complicated picture will be reduced to straight lines and a real
complicated one is rejected, and in this respect \METAPOST\ considers a circle to
be a complicated path.

The next example demonstrates how to get a dashed line. First we built picture
\type {p}, that we apply to a path. Here we use a straight path, but dashing can
be applied to any path.

\startbuffer
picture p ; p := nullpicture ;
addto p doublepath ((0,0)--(3mm,3mm)) shifted (6mm,6mm) ;
draw (0,0)--(10cm,0) dashed p withpen pencircle scaled 1mm ;
\stopbuffer

\typebuffer

\startlinecorrection[blank]
\processMPbuffer
\stoplinecorrection

This way of defining a pattern is not that handy, especially if you start
wondering why you need to supply a slanted path. Therefore, \METAPOST\ provides a
more convenient mechanism to define a pattern.

\startbuffer
picture p ; p := dashpattern(on 3mm off 3mm) ;
draw (0,0)--(10cm,0) dashed p withpen pencircle scaled 1mm ;
\stopbuffer

\typebuffer

\startlinecorrection[blank]
\processMPbuffer
\stoplinecorrection

Most dashpatterns can be defined in terms of on and off. This simple on||off
dashpattern is predefined as picture \type {evenly}. Because this is a picture,
you can (and often need to) scale it.

\startbuffer
draw (0,0)--(10cm,0) dashed (evenly scaled 1mm)
  withpen pencircle scaled 1mm ;
\stopbuffer

\typebuffer

\startlinecorrection[blank]
\processMPbuffer
\stoplinecorrection

Opposite to a defaultpen, there is no default color and default dash pattern set.
The macro \type {drawoptions} provides you a way to set the default attributes.

\starttyping
drawoptions(dashed evenly withcolor red) ;
\stoptyping

Dashes are pretty much bound to the backend in the sense that like line width
they are a property that the \POSTSCRIPT\ (or actually nowadays the \PDF)
interpreter handles. There is not that much cleverness involved at the \METAPOST\
end. Take these examples:

\startbuffer
  pickup pencircle scaled 2mm ; path p ;

  p := (0,0) {dir 25} .. (5cm,0) ;
  draw p withcolor darkyellow ;
  draw p dashed dashpattern (on 4mm off 3mm) withcolor darkblue ;
  drawpoints point 0 of p withcolor white ;

  p := ((0,0) {dir 70} .. {up} (5cm,0) .. cycle) yshifted -1cm ;
  draw p withcolor darkyellow ;
  draw p dashed dashpattern (on 4mm off 3mm) withcolor darkblue ;
  drawpoints point 0 of p withcolor white ;
\stopbuffer

\typebuffer[a]

\startlinecorrection[blank]
\processMPbuffer
\stoplinecorrection

In both cases the dash is not evenly spread which for the line results in
different begin and end rendering while the closed shape gets some weird looking
connection. The next variant uses the \type {withdashes} macro that adapts the
dashes to fit nicely to the path.

\startbuffer[a]
  pickup pencircle scaled 2mm ; path p ;

  p := (0,0) {dir 25} .. (5cm,0) ;
  draw p withcolor darkyellow ;
  draw p withdashes (4mm,3mm) withcolor darkblue ;
  drawpoints point 0 of p withcolor white ;

  p := ((0,0) {dir 70} .. {up} (5cm,0) .. cycle) yshifted -1cm ;
  draw p withcolor darkyellow ;
  draw p withdashes (4mm,3mm) withcolor darkblue ;
  drawpoints point 0 of p withcolor white ;
\stopbuffer

\typebuffer

\startlinecorrection[blank]
\processMPbuffer
\stoplinecorrection

\stopsection

\startsection[reference=sec:text,title={Text}]

\index{text}

Since \METAFONT\ is meant for designing fonts, the only means for including text
are those that permit you to add labels to positions for the sole purpose of
documentation.

Because \METAPOST\ is derived from \METAFONT\ it provides labels too, but in
order to let users add more sophisticated text, like a math formula, to a
graphic, it also provides an interface to \TEX.

Because we will spend a whole chapter on using text in \METAPOST\ we limit the
discussion here to a few fundamentals.

\startbuffer[font]
defaultfont  := "\truefontname{Mono}" ;
defaultscale := .8 ;
\stopbuffer

\startbuffer[label]
pair a ; a := (3cm,3cm) ;
label.top("top",a) ; label.bot("bot",a) ;
label.lft("lft",a) ; label.rt ("rt" ,a) ;
\stopbuffer

\typebuffer[label]

These four labels show up at the position stored in the pair variable \type {a},
anchored in the way specified after the period.

\startlinecorrection[blank]
\processMPbuffer[font,label]
\stoplinecorrection

The command \type {dotlabel} also typesets the point as a rather visible dot.

\startbuffer[label]
pair a ; a := (3cm,3cm) ;
dotlabel.top("top",a) ; dotlabel.bot("bot",a) ;
dotlabel.lft("lft",a) ; dotlabel.rt ("rt" ,a) ;
\stopbuffer

\typebuffer[label]

\startlinecorrection[blank]
\processMPbuffer[font,label]
\stoplinecorrection

The command \type {thelabel} returns the typeset label as picture that you can
manipulate or draw afterwards.

\startbuffer[label]
pair a ; a := (3cm,3cm) ; pickup pencircle scaled 1mm ;
drawdot a withcolor .625yellow ;
draw thelabel.rt("the right way",a) withcolor .625red ;
\stopbuffer

\typebuffer[label]

You can of course rotate, slant and manipulate such a label picture like any
other picture.

\startlinecorrection[blank]
\processMPbuffer[font,label]
\stoplinecorrection

The font can be specified in the string \type {defaultfont} and the scale in
\type {defaultscale}. Labels are defined using the low level operator \type
{infont}. The next statement returns a picture:

\startbuffer[mp]
draw "this string will become a sequence of glyphs (MP)"
  infont defaultfont scaled defaultscale ;
\stopbuffer

\typebuffer[mp]

By default the \type {infont} operator is not that clever and does not apply
kerning. Also, typesetting math or accented characters are not supported. The way
out of this problem is using \typ {btex ... etex}.

\startbuffer[tex]
draw btex this string will become a sequence of glyphs (\TeX) etex ;
\stopbuffer

\typebuffer[tex]

The difference between those two methods is shown below. The outcome of \type
{infont} depends on the current setting of the variable \type {defaultfont}.

\startlinecorrection[blank]
\processMPbuffer[mp]
\processMPbuffer[tex]
\stoplinecorrection

When you run inside \CONTEXT\ (as we do here) there is no difference between
\type {infont} and the \TEX\ methods. This is because we overload the \type
{infont} operator and also pass its content to \TEX. Both \type {infont} and
\type {btex} use the macro \type {textext} which is intercepted and redirects the
task to \TEX. This happens in the current run so there is no need to pass extra
information about fonts.

Instead of passing strings to \type {infont}, you can also pass characters, using
\type {char}, for example \type {char(73)}. When you use \type {infont} you
normally expect the font to be \ASCII\ conforming. If this is not the case, you
must make sure that the encoding of the font that you use matches your
expectations. However, as we overload this macro it does not really matter since
the string is passed to \TEX\ anyway. For instance, \UTF\ encoded text should
work fine as \CONTEXT\ itself understands this encoding.

\stopsection

\startsection[title={Linear equations}]

\index{equations}
\index{expressions}

\startbuffer[a]
\defineMPinstance
  [solvers]
  [format=metafun,
   extensions=yes,
   initializations=yes]
\stopbuffer

\startbuffer[b]
\startMPdefinitions{solvers}
def draw_problem (expr p, q, r, s, show_labels) =
  begingroup ; save x, y, a, b, c, d, e, f, g, h ;

  z11 = z42 = p ; z21 = z12 = q ; z31 = z22 = r ; z41 = z32 = s ;

  a = x12 - x11 ; b = y12 - y11 ; c = x22 - x21 ; d = y22 - y21 ;
  e = x32 - x31 ; f = y32 - y31 ; g = x42 - x41 ; h = y42 - y41 ;

  z11 = (x11,   y11)   ; z12 = (x12,   y12)   ;
  z13 = (x12-b, y12+a) ; z14 = (x11-b, y11+a) ;
  z21 = (x21,   y21)   ; z22 = (x22,   y22)   ;
  z23 = (x22-d, y22+c) ; z24 = (x21-d, y21+c) ;
  z31 = (x31,   y31)   ; z32 = (x32,   y32)   ;
  z33 = (x32-f, y32+e) ; z34 = (x31-f, y31+e) ;
  z41 = (x41,   y41)   ; z42 = (x42,   y42)   ;
  z43 = (x42-h, y42+g) ; z44 = (x41-h, y41+g) ;

  pickup pencircle scaled .5pt ;

  draw z11--z12--z13--z14--cycle ; draw z11--z13 ; draw z12--z14 ;
  draw z21--z22--z23--z24--cycle ; draw z21--z23 ; draw z22--z24 ;
  draw z31--z32--z33--z34--cycle ; draw z31--z33 ; draw z32--z34 ;
  draw z41--z42--z43--z44--cycle ; draw z41--z43 ; draw z42--z44 ;

  z1 = 0.5[z11,z13] ; z2 = 0.5[z21,z23] ;
  z3 = 0.5[z31,z33] ; z4 = 0.5[z41,z43] ;

  draw z1--z3 dashed evenly ; draw z2--z4 dashed evenly ;

  z0 = whatever[z1,z3] = whatever[z2,z4] ;
  mark_rt_angle (z1, z0, z2) ; % z2 is not used at all

  if show_labels > 0 :
    draw_problem_labels ;
  fi ;

  endgroup ;
enddef ;
\stopMPdefinitions
\stopbuffer

\startbuffer[c]
\startMPdefinitions{solvers}
angle_radius := 10pt ;

def mark_rt_angle (expr a, b, c) =
  draw ((1,0)--(1,1)--(0,1))
    zscaled (angle_radius*unitvector(a-b))
    shifted b
enddef ;
\stopMPdefinitions
\stopbuffer

\startbuffer[d]
\startMPdefinitions{solvers}
def draw_problem_labels =
    pickup pencircle scaled 5pt ;

    dotlabel.llft("$Z_{11}$", z11) ; dotlabel.ulft("$Z_{12}$", z12) ;
    dotlabel.ulft("$Z_{13}$", z13) ; dotlabel.llft("$Z_{14}$", z14) ;

    dotlabel.lrt ("$Z_{21}$", z21) ; dotlabel.llft("$Z_{22}$", z22) ;
    dotlabel.urt ("$Z_{23}$", z23) ; dotlabel.ulft("$Z_{24}$", z24) ;

    dotlabel.urt ("$Z_{31}$", z31) ; dotlabel.ulft("$Z_{32}$", z32) ;
    dotlabel.urt ("$Z_{33}$", z33) ; dotlabel.urt ("$Z_{34}$", z34) ;

    dotlabel.lrt ("$Z_{41}$", z41) ; dotlabel.urt ("$Z_{42}$", z42) ;
    dotlabel.llft("$Z_{43}$", z43) ; dotlabel.lrt ("$Z_{44}$", z44) ;

    dotlabel.urt ("$Z_{0}$", z0) ;
    dotlabel.lft ("$Z_{1}$", z1) ; dotlabel.top ("$Z_{2}$", z2) ;
    dotlabel.rt  ("$Z_{3}$", z3) ; dotlabel.bot ("$Z_{4}$", z4) ;
enddef ;
\stopMPdefinitions
\stopbuffer

\startbuffer[e]
\startuseMPgraphic{solvers::one}{i,j,s}
  draw_problem (
              (400pt,400pt), (300pt,600pt),
    \MPvar{i}[(300pt,600pt), (550pt,800pt)],
    \MPvar{j}[(400pt,400pt), (550pt,500pt)],
    \MPvar{s}
 ) ;
\stopuseMPgraphic
\stopbuffer

\startbuffer[f]
\placefigure
  [here][fig:problem]
  {The problem.}
  {\scale
     [width=\textwidth]
     {\useMPgraphic{solvers::one}{i=0.6,j=1.0,s=1}}}
\stopbuffer

In the previous sections, we used the assignment operator \type {:=} to assign a
value to a variable. Although for most of the graphics that we will present in
later chapters, an assignment is appropriate, specifying a graphic in terms of
expressions is not only more flexible, but also more in the spirit of the
designers of \METAFONT\ and \METAPOST.

The \METAFONT\ book and \METAPOST\ manual provide lots of examples, some of which
involve math that we don't consider to belong to everyones repertoire. But, even
for non mathematicians using expressions can be a rewarding challenge.

The next introduction to linear equations is based on my first experiences with
\METAPOST\ and involves a mathematical challenge posed by a friend. I quickly
ascertained that a graphical proof was far more easy than some proof with a lot
of $\sin (this)$ and $\cos (that)$ and long forgotten formulas.

I was expected to prove that the lines connecting the centers of four squares
drawn upon the four sides of a quadrilateral were perpendicular (see \in {figure}
[fig:problem]).

\getbuffer[a,b,c,d,e]

\getbuffer[f]

This graphic was generated with the following command:

\typebuffer[f]

We will use this example to introduce a few new concepts, one being instances. In
a large document there can be many \METAPOST\ graphics and they might fall in
different categories. In this manual we have graphics that are generated as part
of the style as wel as examples that show what \METAFUN\ can do. As definitions
and variables in \METAPOST\ are global by default, there is a possibility that we
end up with clashes. This can be avoided by grouping graphics in instances. Here
we create an instance for the example that we're about to show.

\typebuffer[a]

We can now limit the scope of definitions to this specific instance. Let's start
with the macro that takes care of drawing the solution to our problem. The macro
accepts four pairs of coordinates that determine the central quadrilateral. All
of them are expressions.

\typebuffer[b]

Because we want to call this macro more than once, we first have to save the
locally used values. Instead of declaring local variables, one can hide their use
from the outside world. In most cases variables behave globally. If we don't save
them, subsequent calls will lead to errors due to conflicting equations. We can
omit the grouping commands, because we wrap the graphic in a figure, and figures
are grouped already.

We will use the predefined \type {z} variable, or actually a macro that returns a
variable. This variable has two components, an \type {x} and \type {y}
coordinate. So, we don't save \type {z}, but the related variables \type {x} and
\type {y}.

Next we draw four squares and instead of hard coding their corner points, we use
\METAPOST's equation solver. Watch the use of \type {=} which means that we just
state dependencies. In languages like \PERL, the equal sign is used in
assignments, but in \METAPOST\ it is used to express relations.

In a first version, we will just name a lot of simple relations, as we can read
them from a sketch drawn on paper. So, we end up with quite some \type {z}
related expressions.

For those interested in the mathematics behind this code, we add a short
explanation. Absolutely key to the construction is the fact that you traverse the
original quadrilateral in a clockwise orientation. What is really going on here
is vector geometry. You calculate the vector from $z_{11}$ to $z_{12}$ (the first
side of the original quadrilateral) with:

\starttyping
(a,b) = z12 - z11 ;
\stoptyping

This gives a vector that points from $z_{11}$ to $z_{12}$. Now, how about an
image that shows that the vector $(-b,a)$ is a 90 degree rotation in the
counterclockwise direction. Thus, the points $z_{13}$ and $z_{14}$ are easily
calculated with vector addition.

\starttyping
z13 = z12 + (-b,a) ;
z14 = z11 + (-b,a) ;
\stoptyping

This pattern continues as you move around the original quadrilateral in a
clockwise manner. \footnote {Thanks to David Arnold for this bonus explanation.}

The code that calculates the pairs \type {a} through \type {h}, can be written in
a more compact way.

\starttyping
(a,b) = z12 - z11 ; (c,d) = z22 - z21 ;
(e,f) = z32 - z31 ; (g,h) = z42 - z41 ;
\stoptyping

The centers of each square can also be calculated by \METAPOST. The next lines
define that those points are positioned halfway the extremes.

\starttyping
z1 = 0.5[z11,z13] ; z2 = 0.5[z21,z23] ;
z3 = 0.5[z31,z33] ; z4 = 0.5[z41,z43] ;
\stoptyping

Once we have defined the relations we can let \METAPOST\ solve the equations.
This is triggered when a variable is needed, for instance when we draw the
squares and their diagonals. We connect the centers of the squares using a dashed
line style.

Just to be complete, we add a symbol that marks the right angle. First we
determine the common point of the two lines, that lays at {\em whatever} point
\METAPOST\ finds suitable.

The definition of \type {mark_rt_angle} is copied from the \METAPOST\ manual and
shows how compact a definition can be (see \at {page} [zscaled] for an
introduction to \type {zscaled}).

\typebuffer[c]

So far, most equations are rather simple, and in order to solve them, \METAPOST\
did not have to work real hard. The only boundary condition is that in order to
find a solution, \METAPOST\ must be able to solve all dependencies.

The actual value of the \type {whatever} variable is that it saves us from
introducing a slew of variables that will never be used again. We could write:

\starttyping
z0 = A[z1,z3] = B[z2,z4] ;
\stoptyping

and get the same result, but the \type {whatever} variable saves us the trouble
of introducing intermediate variables for which we have no use once the
calculation is finished.

The macro \type{mark_rt_angle} draws the angle symbol and later we will see how
it is defined. First we draw the labels. Unfortunately we cannot package \typ
{btex ... etex} into a macro, because it is processed in a rather special way.
Each \typ {btex ... etex} occurance is filtered from the source and converted
into a snippet of \TEX\ code. When passed through \TEX, each snippet becomes a
page, and an auxiliary program converts each page into a \METAPOST\ picture
definition, which is loaded by \METAPOST. The limitation lays in the fact that
the filtering is done independent from the \METAPOST\ run, which means that loops
(and other code) are not seen at all. Later we will introduce the \METAFUN\ way
around this.

In order to get all the labels typeset, we have to put a lot of code here. The
macro \type {dotlabel} draws a dot and places the typeset label.

\typebuffer[d]

Watch out: as we are in \CONTEXT, we can pass regular \TEX\ code to the label
macro. In a standalone \METAPOST\ run you'd have to use the \type {btex} variant.

We are going to draw a lot of pictures, so we define an extra macro. This time we
hard||code some values. The fractions \type {i} and \type {j} are responsible for
the visual iteration process, while \type {s} determines the labels. We pass
these variables to the graphic using an extra argument. When you define the
(useable) graphic you need to tell what variables it can expect.

\typebuffer[e]

Of course we could have used a loop construct here, but defining auxiliary macros
probably takes more time than simply calling the drawing macro directly. The
results are shown on a separate page (\in{figure}[fig:solution]).

\startbuffer[x]
\def\MyTest#1#2%
  {\scale
     [width=.25\textwidth]
     {\useMPgraphic{solvers::one}{i=#1,j=#2,s=0}}}
\stopbuffer

\startbuffer[y]
  \startcombination[3*4]
    {\MyTest{1.0}{1.0}} {1.0 / 1.0} {\MyTest{0.8}{1.0}} {0.8 / 1.0}
    {\MyTest{0.6}{1.0}} {0.6 / 1.0} {\MyTest{0.4}{1.0}} {0.4 / 1.0}
    {\MyTest{0.2}{1.0}} {0.2 / 1.0} {\MyTest{0.0}{1.0}} {0.0 / 1.0}
    {\MyTest{0.0}{1.0}} {0.0 / 1.0} {\MyTest{0.0}{0.8}} {0.0 / 0.8}
    {\MyTest{0.0}{0.6}} {0.0 / 0.6} {\MyTest{0.0}{0.4}} {0.0 / 0.4}
    {\MyTest{0.0}{0.2}} {0.0 / 0.2} {\MyTest{0.0}{0.0}} {0.0 / 0.0}
  \stopcombination
\stopbuffer

We will use a helper macro (that saves us typing):

\typebuffer[x]

We now can say:

\typebuffer[y]

Watch how we pass the settings to the graphic definition using an extra argument.
We force using the \type {solvers} instance by prefixing the name.

\startpostponing

  \startnotmode[screen]
    \placefigure
      [here][fig:solution]
      {The solution.}
      {\getbuffer[x,y]}
  \stopnotmode

  \startmode[screen]
    \placefigure
      [here][fig:solution]
      {The solution.}
      {\getbuffer[x,y]}
  \stopmode

  \page

\stoppostponing

It does not need that much imagination to see the four sided problem converge to
a three sided one, which itself converges to a two sided one. In the two sided
alternative it's not that hard to prove that the angle is indeed 90 degrees.

As soon as you can see a clear pattern in some code, it's time to consider using
loops. In the previous code, we used semi indexes, like \type {12} in \type
{z12}. In this case \type{12} does reflect something related to square~1 and~2,
but in reality the 12 is just twelve. This does not harm our expressions.

A different approach is to use a two dimensional array. In doing so, we can
access the variables more easily using loops. If we omit the labels, and angle
macro, the previously defined macro can be reduced considerably.

\starttyping
def draw_problem (expr n, p, q, r, s) = % number and 4 positions
  begingroup ; save x, y ;

  z[1][1] = p ; z[2][1] = q ; z[3][1] = r ; z[4][1] = s ;

  for i=1 upto 4 :
    z[i][1] = (x[i][1],y[i][1]) = z[if i=1: 4 else: i-1 fi][2] ;
    z[i][2] = (x[i][2],y[i][2]) ;
    z[i][3] = (x[i][2]-y[i][2]+y[i][1], y[i][2]+x[i][2]-x[i][1]) ;
    z[i][4] = (x[i][1]-y[i][2]+y[i][1], y[i][1]+x[i][2]-x[i][1]) ;
    z[i] = 0.5[z[i][1],z[i][3]] ;
  endfor ;

  z[0] = whatever[z[1],z[3]] = whatever[z[2],z[4]] ;

  pickup pencircle scaled .5pt ;

  for i=1 upto 4 :
    draw z[i][1]--z[i][2]--z[i][3]--z[i][4]--cycle ;
    draw z[i][1]--z[i][3] ; draw z[i][2]--z[i][4] ;
    if i<3 : draw z[i]--z[i+2] dashed evenly fi ;
  endfor ;

  draw ((1,0)--(1,1)--(0,1))
    zscaled (unitvector(z[1]-z[0])*10pt)
    shifted z[0] ;

  endgroup ;
enddef ;
\stoptyping

I think that we could argue quite some time about the readability of this code.
If you start from a sketch, and the series of equations does a good job, there is
hardly any need for such improvements to the code. On the other hand, there are
situations where the simplified (reduced) case can be extended more easily, for
instance to handle 10 points instead of~4. It all depends on how you want to
spend your free hours.

\stopsection

\startsection[title={Clipping}]

\index{clipping}

For applications that do something with a drawing, for instance \TEX\ embedding a
graphic in a text flow, it is important to know the dimensions of the graphic.
The maximum dimensions of a graphic are specified by its bounding box.

\startlinecorrection[blank]
\startMPcode
path p ; p := fullcircle scaled 3cm ;
draw p withpen pencircle scaled 1mm withcolor .625red ;
draw boundingbox p withpen pencircle scaled .1mm ;
draw llcorner boundingbox p withpen pencircle scaled 2mm withcolor .625yellow  ;
draw urcorner boundingbox p withpen pencircle scaled 2mm withcolor .625yellow  ;
\stopMPcode
\stoplinecorrection

A bounding box is defined by its lower left and upper right corners. If you open
the \POSTSCRIPT\ file produced by \METAPOST, you may find lines like:

\starttyping
%%BoundingBox: -46 -46 46 46
\stoptyping

or, when supported,

\starttyping
%%HiResBoundingBox: -45.35432 -45.35432 45.35432 45.35432
\stoptyping

The first two numbers define the lower left corner and the last two numbers the
upper right corner. From these values, you can calculate the width and height of
the graphic.

A graphic may extend beyond its bounding box. It depends on the application that
uses the graphic whether that part of the graphic is shown.

In \METAPOST\ you can ask for all four points of the bounding box of a path or
picture as well as the center.

\starttabulate[|lT|l|]
\HL
\NC llcorner p \NC lower left corner  \NC \NR
\NC lrcorner p \NC lower right corner \NC \NR
\NC urcorner p \NC upper right corner \NC \NR
\NC ulcorner p \NC upper left corner  \NC \NR
\NC center   p \NC the center point   \NC \NR
\HL
\stoptabulate

You can construct the bounding box of path~\type {p} out of the four points
mentioned:

\starttyping
llcorner p -- lrcorner p -- urcorner p -- ulcorner p -- cycle
\stoptyping

You can set the bounding box of a picture, which can be handy if you want to
build a picture in steps and show the intermediate results using the same
dimensions as the final picture, or when you want to show only a small piece.

\startbuffer
fill fullcircle scaled 2cm withcolor .625yellow ;
setbounds currentpicture to unitsquare scaled 1cm ;
draw unitsquare scaled 1cm withcolor .625red ;
\stopbuffer

\typebuffer

Here, we set the bounding box with the command \type {setbounds}, which takes a
path.

\startlinecorrection[blank]
\processMPbuffer
\stoplinecorrection

The graphic extends beyond the bounding box, but the bounding box determines the
placement and therefore the spacing around the graphic. We can get rid of the
artwork outside the bounding box by clipping it.

\startbuffer
fill fullcircle scaled 2cm withcolor .625yellow ;
clip currentpicture to unitsquare scaled 1cm ;
\stopbuffer

\typebuffer

The resulting picture is just as large but shows less of the picture.

\startlinecorrection[blank]
\processMPbuffer
\stoplinecorrection

\stopsection

\startsection[title={Some extensions}]

We will now encounter a couple of transformations that can make your life easy
when you use \METAPOST\ for making graphics like the ones demonstrated in this
document. These transformations are not part of standard \METAPOST, but come with
\METAFUN.

A very handy extension is \type {enlarged}. Although you can feed it with any
path, it will return a rectangle larger or smaller than the boundingbox of that
path. You can specify a pair or a numeric.

\startbuffer
path p ; p := fullsquare scaled 2cm ;
drawpath p ; drawpoints p ;
p := (p shifted (3cm,0)) enlarged (.5cm,.25cm) ;
drawpath p ; drawpoints p ;
\stopbuffer

\typebuffer

\startlinecorrection[blank] \processMPbuffer \stoplinecorrection

There are a few more alternatives, like \type {bottomenlarged}, \type
{rightenlarged}, \type {topenlarged} and \type {leftenlarged}.

The \type {cornered} operator will replace sharp corners by rounded ones (we
could not use \type {rounded} because this is already in use).

\startbuffer
path p ; p := ((1,0)--(2,0)--(2,2)--(1,2)--(0,1)--cycle)
  xysized (4cm,2cm) ;
drawpath p ; drawpoints p ;
p := (p shifted (5cm,0)) cornered .5cm ;
drawpath p ; drawpoints p ;
\stopbuffer

\typebuffer

\startlinecorrection[blank] \processMPbuffer \stoplinecorrection

The \type {smoothed} operation is a less subtle one, since it operates on the
bounding box and thereby can result in a different shape.

\startbuffer
path p ; p := ((1,0)--(2,0)--(2,2)--cycle) xysized (4cm,2cm) ;
drawpath p ; drawpoints p ;
p := (p shifted (5cm,0)) smoothed .5cm ;
drawpath p ; drawpoints p ;
\stopbuffer

\typebuffer

\startlinecorrection[blank] \processMPbuffer \stoplinecorrection

The next one, \type {simplified}, can be applied to paths that are constructed
automatically. Instead of testing for duplicate points during construction, you
can clean up the path afterwards.

\startbuffer
path p ; p :=
  ((0,0)--(1,0)--(2,0)--(2,1)--(2,2)--(1,2)--(0,2)--(0,1)--cycle)
  xysized (4cm,2cm) ;
drawpath p ; drawpoints p ;
p := simplified (p shifted (5cm,0)) ;
drawpath p ; drawpoints p ;
\stopbuffer

\typebuffer

\startlinecorrection[blank] \processMPbuffer \stoplinecorrection

A cousin of the previous operation is \type {unspiked}. This one removes ugly
left|-|overs. It works well for the average case.

\startbuffer
path p ; p :=
  ((0,0)--(2,0)--(3,1)--(2,0)--(2,2)--(1,2)--(1,3)--(1,2)--(0,1)--cycle)
  xysized (4cm,2cm) ;
drawpath p ; drawpoints p ;
p := unspiked (p shifted (5cm,0)) ;
drawpath p ; drawpoints p ;
\stopbuffer

\typebuffer

\startlinecorrection[blank] \processMPbuffer \stoplinecorrection

There are a couple of operations that manipulate the path in more drastic ways.
Take \type {randomized}.

\startbuffer
path p ; p := fullsquare scaled 2cm ;
drawpath p ; drawpoints p ;
p := (p shifted (5cm,0)) randomized .5cm ;
drawpath p ; drawpoints p ;
\stopbuffer

\typebuffer

\startlinecorrection[blank] \processMPbuffer \stoplinecorrection

Or how about \type {squeezed}:

\startbuffer
path p ; p := fullsquare scaled 2cm randomized .5cm ;
drawpath p ; drawpoints p ;
p := (p shifted (5cm,0)) squeezed .5cm ;
drawpath p ; drawpoints p ;
\stopbuffer

\typebuffer

\startlinecorrection[blank] \processMPbuffer \stoplinecorrection

A \type {punked} path is, like a punked font, a font with less smooth curves (in
our case, only straight lines).

\startbuffer
path p ; p := fullcircle scaled 2cm randomized .5cm ;
drawpath p ; drawpoints p ;
p := punked (p shifted (5cm,0)) ;
drawpath p ; drawpoints p ;
\stopbuffer

\typebuffer

\startlinecorrection[blank] \processMPbuffer \stoplinecorrection

A \type {curved} path on the other hand has smooth connections. Where in many
cases a punked path becomes smaller, a curved path will be larger.

\startbuffer
path p ; p := fullsquare scaled 2cm randomized .5cm ;
drawpath p ; drawpoints p ;
p := curved (p shifted (5cm,0)) ;
drawpath p ; drawpoints p ;
\stopbuffer

\typebuffer

\startlinecorrection[blank] \processMPbuffer \stoplinecorrection

Probably less usefull (although we use it in one of the \OPENTYPE\ visualizers)
is \type {laddered}:

\startbuffer
path p ; p := fullcircle scaled 3cm ;
drawpath p ; drawpoints p ;
p := laddered (p shifted (5cm,0)) ;
drawpath p ; drawpoints p ;
\stopbuffer

\typebuffer

\startlinecorrection[blank] \processMPbuffer \stoplinecorrection

When writing \PPCHTEX\ (that can be used to draw chemical structure formulas) I
needed a parallelizing macro, so here it is:

\startbuffer
path p ; p := fullcircle scaled 3cm ;
drawpath p ; drawpoints p ;
p := p paralleled 1cm ;
drawpath p ; drawpoints p ;
\stopbuffer

\typebuffer

\startlinecorrection[blank] \processMPbuffer \stoplinecorrection

If you use a negative argument (like \type {-1cm}) the parallel line will be
drawn at the other side.

The \type {blownup} operation scales the path but keeps the center in the same
place.

\startbuffer
path p ; p := fullsquare xyscaled (4cm,1cm) randomized .5cm ;
drawpath p ; drawpoints p ;
p := p blownup .5cm ;
drawpath p ; drawpoints p ;
\stopbuffer

\typebuffer

\startlinecorrection[blank] \processMPbuffer \stoplinecorrection

The \type {shortened} operation also scales the path but only makes it longer or
shorter. This macro only works on straight paths.

\startbuffer
path p ; p := (0,0) -- (2cm,3cm) ;
drawpath p ; drawpoints p ;
p := p shortened 1cm ;
drawpath p ; drawpoints p ;
p := p shortened -1cm ;
drawpath p ; drawpoints p ;
\stopbuffer

\typebuffer

\startlinecorrection[blank] \processMPbuffer \stoplinecorrection

Here are a few more drawing helpers. Even if you don't need them you might at
some point take a look at their definitions to see what happens there. First we
give a square round corners with \type {roundedsquare}:

\startbuffer
path p ; p := roundedsquare(2cm,4cm,.25cm) ;
drawpath p ; drawpoints p ;
\stopbuffer

\typebuffer

\startlinecorrection[blank] \processMPbuffer \stoplinecorrection

Next we draw a square|-|like circle (or circle|-|like square) using \type
{tensecircle}:

\startbuffer
path p ; p := tensecircle(2cm,4cm,.25cm) ;
drawpath p ; drawpoints p ;
\stopbuffer

\typebuffer

\startlinecorrection[blank] \processMPbuffer \stoplinecorrection

Often I make such helpers in the process of writing larger drawing systems. Take
\type {crossed}:

\startbuffer
path p ; p := origin crossed 1cm ;
drawpath p ; drawpoints p ;
p := (origin crossed fullcircle scaled 2cm crossed .5cm) shifted (3cm,0) ;
drawpath p ; drawpoints p ;
\stopbuffer

\typebuffer

These examples demonstrate that a path is made up out of points (something that
you probably already knew by now). The \METAPOST\ operator \type {of} can be used
to \quote {access} a certain point at a curve.

\startbuffer
path p ; p := fullsquare xyscaled (3cm,2cm) randomized .5cm ;
drawpath p ; drawpoints p ; drawpointlabels p ;
draw point 2.25 of p withpen pencircle scaled 5mm withcolor .625red ;
\stopbuffer

\typebuffer

\startlinecorrection[blank] \processMPbuffer \stoplinecorrection

To this we add two more operators: \type {on} and \type {along}. With \type {on}
you get the point at the supplied distance from point~0; with \type {along} you
get the point at the fraction of the length of the path.

\startbuffer
path p, q, r ;
p := fullsquare xyscaled (2cm,2cm) randomized .5cm ;
q := p shifted (3cm,0) ; r := q shifted (3cm,0) ;
drawpath p ; drawpoints p ; drawpointlabels p ;
drawpath q ; drawpoints q ; drawpointlabels q ;
drawpath r ; drawpoints r ; drawpointlabels r ;
pickup pencircle scaled 5mm ;
draw point 2.25   of    p withcolor .625red ;
draw point 2.50cm on    q withcolor .625yellow ;
draw point  .45   along r withcolor .625white ;
\stopbuffer

\typebuffer

Beware: the \type {length} of a path is the number of points minus one. The
shapes below are constructed from 5~points and a length of~4. If you want the
length as dimension, you should use \type {arclength}.

\startlinecorrection[blank] \processMPbuffer \stoplinecorrection

We will now play a bit with simple lines. With \type {cutends}, you can (indeed)
cut off the ends of a curve. The specification is a dimension.

\startbuffer
path p ; p := (0cm,0cm)        -- (4cm,1cm) ;
path q ; q := (5cm,0cm){right} .. (9cm,1cm) ;
drawpath p ; drawpoints p ; drawpath q ; drawpoints q ;
p := p cutends .5cm ; q := q cutends .5cm ;
drawpathoptions (withpen pencircle scaled 5pt withcolor .625yellow) ;
drawpointoptions(withpen pencircle scaled 4pt withcolor .625red) ;
drawpath p ; drawpoints p ; drawpath q ; drawpoints q ;
resetdrawoptions ;
\stopbuffer

\typebuffer

\startlinecorrection[blank] \processMPbuffer \stoplinecorrection

As with more operators, \type {cutends} accepts a numeric or a pair. Watch the
subtle difference between the next and the previous use of \type {cutends}.

\startbuffer
path p ; p := (0cm,0) .. (4cm,0) .. (8cm,0) .. (4cm,0) .. cycle ;
drawpath p ; drawpoints p ; p := p cutends (2cm,1cm) ;
drawpathoptions (withpen pencircle scaled 5pt withcolor .625yellow) ;
drawpointoptions(withpen pencircle scaled 4pt withcolor .625red) ;
drawpath p ; drawpoints p ;
resetdrawoptions ;
\stopbuffer

\typebuffer

\startlinecorrection[blank] \processMPbuffer \stoplinecorrection

When \type {stretched} is applied to a path, it is scaled but the starting point
(point~0) keeps its location. The specification is a scale.

\startbuffer
path p ; p := (0cm,0) .. (3cm,1cm) .. (4cm,0) .. (5cm,1cm) ;
drawpath p ; drawpoints p ; p := p stretched 1.1 ;
drawpathoptions (withpen pencircle scaled 2.5pt withcolor .625yellow) ;
drawpointoptions(withpen pencircle scaled 4.0pt withcolor .625red) ;
drawpath p ; drawpoints p ; resetdrawoptions ;
\stopbuffer

\typebuffer

\startlinecorrection[blank] \processMPbuffer \stoplinecorrection

We can scale in two directions independently or even in one direction by
providing a zero value. In the next example we apply the stretch two times.

\startbuffer
path p ; p := (0cm,0) .. (3cm,1cm) .. (4cm,0) .. (5cm,1cm) ;
drawpath p ; drawpoints p ; p := p stretched (.75,1.25) ;
drawpathoptions (withpen pencircle scaled 2.5pt withcolor .625yellow) ;
drawpointoptions(withpen pencircle scaled 4.0pt withcolor .625red) ;
drawpath p ; drawpoints p ; p := p stretched (0,1.5) ;
drawpathoptions (withpen pencircle scaled 4.0pt withcolor .625red) ;
drawpointoptions(withpen pencircle scaled 2.5pt withcolor .625yellow) ;
drawpath p ; drawpoints p ; resetdrawoptions ;
\stopbuffer

\typebuffer

\startlinecorrection[blank] \processMPbuffer \stoplinecorrection

We already met the \type {randomize} operator. This one is the chameleon under
the operators.

\startbuffer
draw fullsquare xyscaled (4cm,2cm)
  randomized .25cm
  shifted origin randomized (1cm, 2cm)
  withcolor red randomized (.625, .850)
  withpen pencircle scaled (5pt randomized 1pt) ;
\stopbuffer

\typebuffer

So, \type {randomized} can handle a numeric, pair, path and color, and its
specification can be a numeric, pair or color, depending on what we're dealing
with.

\startlinecorrection[blank] \processMPbuffer \stoplinecorrection

In the previous example we also see \type {xyscaled} in action. Opposite to \type
{scaled}, \type {xscaled} and \type {yscaled}, this is not one of \METAPOST\
build in features. The same is true for the \type {.sized} operators.

\startbuffer[a]
picture p ; p := image
  ( draw fullsquare
      xyscaled (300,800)
      withpen pencircle scaled 50
      withcolor .625 yellow ; ) ;
draw p xysized (3cm,2cm) shifted (bbwidth(currentpicture)+.5cm,0) ;
draw p xysized  2cm      shifted (bbwidth(currentpicture)+.5cm,0) ;
draw p xsized   1cm      shifted (bbwidth(currentpicture)+.5cm,0) ;
draw p ysized   2cm      shifted (bbwidth(currentpicture)+.5cm,0) ;
\stopbuffer

\typebuffer[a]

\startlinecorrection[blank] \processMPbuffer[a] \stoplinecorrection

Here, the \type {image} macro creates an (actually rather large) picture. The
last four lines actually draw this picture, but at the given dimensions. Watch
how the line width scales accordingly. If you don't want this, you can add the
following line:

\startbuffer[b]
redraw currentpicture withpen pencircle scaled 2pt ;
draw boundingbox currentpicture withpen pencircle scaled .5mm ;
\stopbuffer

\typebuffer[b]

Watch how the boundingbox is not affected:

\startlinecorrection[blank] \processMPbuffer[a,b] \stoplinecorrection

In this example we also used \type {bbwidth} (which has a companion macro \type
{bbheight}). You can apply this macro to a path or a picture.

In fact you don't always need to follow this complex route if you want to simply
redraw a path with another pen or color.

\startbuffer
draw fullcircle scaled 1cm
  withcolor .625red    withpen pencircle scaled 1mm ;
draw currentpicture
  withcolor .625yellow withpen pencircle scaled 3mm ;
draw boundingbox currentpicture
  withpen pencircle scaled .5mm ;
\stopbuffer

\typebuffer

This is what you will get from this:

\startlinecorrection[blank] \processMPbuffer \stoplinecorrection

If you want to add a background color to a picture you can do that afterwards.
This can be handy when you don't know in advance what size the picture will have.

\startbuffer
fill fullcircle scaled 1cm withcolor .625red ;
addbackground withcolor .625 yellow ;
\stopbuffer

\typebuffer

The background is just a filled rectangle that gets the same size as the current
picture, that is put on top of it.

\startlinecorrection[blank] \processMPbuffer \stoplinecorrection

\stopsection

\startsection[title={Cutting and pasting}]

\index{paths+cutting}
\index{cutting}

When enhancing or building a graphic, often parts of already constructed paths
are needed. The \type {subpath}, \type {cutbefore} and \type {cutafter} operators
can be used to split paths in smaller pieces. In order to do so, we must know
where we are on the path that is involved. For this we use points on the path.
Unfortunately we can only use these points when we know where they are located.
In this section we will combine some techniques discussed in previous sections.
We will define a few macros, manipulate some paths and draw curves and points.

\startbuffer
path p ; p := fullcircle yscaled 3cm xscaled .9TextWidth ;
drawpath p ; drawpoints p withcolor .625red ; drawpointlabels p ;
\stopbuffer

\startlinecorrection[blank]
\processMPbuffer
\stoplinecorrection

This circle is drawn by scaling the predefined path \type {fullcircle}. This path
is constructed using 8~points. As you can see, these points are not distributed
equally along the path. In the following graphic, the second and third point of
the curve are colored red, and point 2.5 is colored yellow. Point~0 is marked in
black. This point is positioned halfway between point~2 and~3.

\startbuffer
path p ; p := fullcircle scaled 3cm xscaled 2 ;
pickup pencircle scaled 5mm ; autoarrows := true ;
drawarrow         p withcolor .625white ;
draw point 0.0 of p ;
draw point 2.0 of p withcolor .625red ;
draw point 2.5 of p withcolor .625yellow ;
draw point 3.0 of p withcolor .625red ;
\stopbuffer

\startlinecorrection[blank]
\processMPbuffer
\stoplinecorrection

It is clear that, unless you know exactly how the path is constructed, other
methods should be available. A specific point on a path is accessed by \typ
{point ... of}, but the next example demonstrates two more alternatives.

\startbuffer
path p ; p := fullcircle scaled 3cm xscaled 2 ;
pickup pencircle scaled 5mm ;
draw                 p withcolor .625white ;
draw point 3   of    p withcolor .625red ;
draw point .6  along p withcolor .625yellow ;
draw point 3cm on    p ;
\stopbuffer

\typebuffer

So, in addition to \type {on} to specify a point by number (in \METAPOST\
terminology called time), we have \type {along} to specify a point as fraction of
the path, and \type {on} to specify the position in a dimension.

\startlinecorrection[blank]
\processMPbuffer
\stoplinecorrection

The \type {on} and \type {along} operators are macros and can be defined as:

\starttyping
primarydef len on pat =
  (arctime len of pat) of pat
enddef ;

primarydef pct along pat =
  (arctime (pct * (arclength pat)) of pat) of pat
enddef ;
\stoptyping

These macros introduce two new primitives, \type {arctime} and \type {arclength}.
While \type {arctime} returns a number denoting the time of the point on the
path, \type {arclength} returns a dimension.

\quotation {When mathematicians draw parametric curves, they frequently need to
indicate the direction of motion. I often have need of a little macro that will
put an arrow of requested length, anchored at a point on the curve, and bending
with the curve in the direction of motion.}

When David Arnold asked me how this could be achieved, the fact that a length was
requested meant that the solution should be sought in using the primitives and
macros we introduced a few paragraphs before. Say that we want to call for such
an arrow as follows.

\startbuffer[a]
path p ; p := fullcircle scaled 3cm ;
pair q ; q := point .4 along p ;
pickup pencircle scaled 2mm ;
draw                p        withcolor .625white ;
drawarrow somearrow(p,q,2cm) withcolor .625red ;
draw                  q      withcolor .625yellow ;
\stopbuffer

\typebuffer[a]

Because we want to follow the path, we need to construct the arrow from this
path. Therefore, we first reduce the path by cutting off the part before the
given point. Next we cut off the end of the resulting path so that we keep a
slice that has the length that was asked for. Since we can only cut at points, we
determine this point using the \type {arctime} primitive.

\startbuffer[b]
vardef somearrow (expr pat, loc, len) =
  save p ; path p ; p := pat cutbefore loc ;
  (p cutafter point (arctime len of p) of p)
enddef ;
\stopbuffer

\typebuffer[b]

By using a \type {vardef} we hide the intermediate assignments. Such \type
{vardef} is automatically surrounded by \type {begingroup} and \type {endgroup},
so the \type {save} is local to this macro. When processed, this code produces
the following graphic:

\startbuffer[c]
autoarrows := true ;
\stopbuffer

\startlinecorrection[blank]
\processMPbuffer[c,b,a]
\stoplinecorrection

This graphic shows that we need a bit more control over the exact position of the
arrow. It would be nice if we could start the arrow at the point, or end there,
or center the arrow around the point. Therefore, the real implementation is a bit
more advanced.

\startbuffer
vardef pointarrow (expr pat, loc, len, off) =
  save l, r, s, t ; path l, r ; numeric s ; pair t ;
  t := if pair loc : loc else : point loc along pat fi ;
  s := len/2 - off ; if s<=0 : s := 0 elseif s>len : s := len fi ;
  r := pat cutbefore t ;
  r := (r cutafter point (arctime s of r) of r) ;
  s := len/2 + off ; if s<=0 : s := 0 elseif s>len : s := len fi ;
  l := reverse (pat cutafter t) ;
  l := (reverse (l cutafter point (arctime s of l) of l)) ;
  (l..r)
enddef ;
\stopbuffer

\typebuffer

This code fragment also demonstrates how we can treat the \type {loc} argument as
pair (coordinates) or fraction of the path. We calculate the piece of path before
and after the given point separately and paste them afterwards as \type {(l..r)}.
By adding braces we can manipulate the path in expressions without the danger of
handling \type {r} alone.

We can now implement left, center and right arrows by providing this macro the
right parameters. The offset (the fourth parameter), is responsible for a
backward displacement. This may seem strange, but negative values would be even
more confusing.

\startbuffer
def rightarrow (expr p,t,l) = pointarrow(p,t,l,-l) enddef ;
def leftarrow  (expr p,t,l) = pointarrow(p,t,l,+l) enddef ;
def centerarrow(expr p,t,l) = pointarrow(p,t,l, 0) enddef ;
\stopbuffer

\typebuffer

We can now apply this macro as follows:

\startbuffer[a]
path p ; p := fullcircle scaled 3cm ;
pickup pencircle scaled 2mm ;
draw p withcolor .625white ;
drawarrow leftarrow  (p,     .4     ,2cm) withcolor .625red ;
drawarrow centerarrow(p,point 5 of p,2cm) withcolor .625yellow ;
draw point .4 along p withcolor .625yellow ;
draw point  5 of    p withcolor .625red ;
\stopbuffer

\typebuffer[a]

\startlinecorrection[blank]
\processMPbuffer[a]
\stoplinecorrection

Watch how we can pass a point (\typ {point 5 of p}) as well as a fraction (\type
{.4}). The following graphic demonstrates a few more alternatives.

\startbuffer[a]
pickup pencircle scaled 2mm; autoarrows := true ;

path p ; p := fullcircle yscaled 3cm xscaled .9TextWidth ;

draw p withcolor .5white;

for i=1, 2, 3 :
  drawdot point i of p withpen pencircle scaled 5mm withcolor .625white ;
endfor ;
for i=.60, .75, .90 :
  drawdot point i along p withpen pencircle scaled 5mm withcolor .625white ;
endfor ;
\stopbuffer

\startbuffer[b]
drawarrow leftarrow   (p,point 1 of p,2cm) withcolor red     ;
drawarrow centerarrow (p,point 2 of p,2cm) withcolor blue    ;
drawarrow rightarrow  (p,point 3 of p,2cm) withcolor green   ;
drawarrow pointarrow  (p,.60,4cm,+.5cm)    withcolor yellow  ;
drawarrow pointarrow  (p,.75,3cm,-.5cm)    withcolor cyan    ;
drawarrow centerarrow (p,.90,3cm)          withcolor magenta ;
\stopbuffer

\startlinecorrection[blank]
\processMPbuffer[a,b]
\stoplinecorrection

The arrows are drawn using the previously defined macros. Watch the positive and
negative offsets in call to \type {pointarrow}.

\typebuffer[b]

\stopsection

\startsection[title={Current picture}]

\index {pictures}

When you draw paths, texts and|/|or pictures they are added to the so called
current picture. You can manipulate this current picture as is demonstrated in
this manual. Let's show a few current picture related tricks.

\startbuffer
  draw fullcircle scaled 1cm withpen pencircle scaled 1mm withcolor .625red ;
\stopbuffer

\typebuffer \startlinecorrection[blank] \processMPbuffer \stoplinecorrection

We can manipulate the picture as a whole:

\startbuffer
  draw fullcircle scaled 1cm withpen pencircle scaled 1mm withcolor .625red ;
  currentpicture := currentpicture slanted .5 ;
\stopbuffer

\typebuffer \startlinecorrection[blank] \processMPbuffer \stoplinecorrection

Sometimes it's handy to temporarily set aside the current picture.

\startbuffer
  draw fullcircle scaled 1cm withpen pencircle scaled 1mm withcolor .625red ;
  currentpicture := currentpicture slanted .5 ;
  pushcurrentpicture ;
  draw fullcircle scaled 1cm withpen pencircle scaled 1mm withcolor .625yellow ;
  currentpicture := currentpicture slanted -.5 ;
  popcurrentpicture ;
\stopbuffer

\typebuffer \startlinecorrection[blank] \processMPbuffer \stoplinecorrection

These are \METAFUN\ commands but \METAPOST\ itself comes with a variant, \type
{image}, and you explicitly have to draw this picture (or otherwise add it to the
currentpicture).

\startbuffer
  draw fullcircle scaled 1cm withpen pencircle scaled 1mm withcolor .625red ;
  currentpicture := currentpicture slanted .5 ;
  draw image (
    draw fullcircle scaled 1cm
        withpen pencircle scaled 1mm withcolor .625yellow ;
    currentpicture := currentpicture slanted -.5 ;
  ) ;
\stopbuffer

\typebuffer \startlinecorrection[blank] \processMPbuffer \stoplinecorrection

Each graphic starts fresh with an empty current picture. In \METAFUN\ we make
sure that we also reset some otherwise global variables, like color, pen and some
line properties.

\stopsection

\startsection[title={\UTF8}]

The \METAPOST\ library used in \LUATEX\ and \LUAMETATEX\ supports \UTF8\ input.
Actually there is not much magic needed to do this because all the engine in
interested in is bytes and some just have a special meaning (like parenthesis,
symbols that have a meaning in formulas etc).

\startbuffer
save p ; pen p ; p := currentpen ;
pickup pencircle scaled .05;

picture ○ ; ○ := image (draw fullcircle) ;
picture ◎ ; ◎ := image (draw fullcircle ; draw fullcircle scaled .5) ;

draw ◎ ysized  2cm                       withcolor darkblue ;
draw ○ xsized  2cm       shifted (3cm,0) withcolor darkgreen ;
draw ○ xysized (3cm,2cm) shifted (7cm,0) withcolor darkred ;
\stopbuffer

\typebuffer

Here we use a \UTF8\ encoded character as macro name and the next image
demonstrate that it does work indeed:

\startlinecorrection[blank] \processMPbuffer \stoplinecorrection

You can do crazy things like use emoji for special operators

\startbuffer
def ✏ = withpen pencircle enddef ;
def ✖️ = scaled enddef ;
fill fullsquare ✖️ 1cm ✏ ✖️ 1mm withcolor darkgray ;
draw fullsquare ✖️ 1cm ✏ ✖️ 1mm withcolor darkblue ;
\stopbuffer

\typebuffer

But do we really want to go there?

\startlinecorrection[blank] \processMPbuffer \stoplinecorrection

Normally using \UTF8\ makes more sense in text or regular macro names, so if you
want to use accented characters it is possible:

\startbuffer
def rændömîzèd = randomized 1/10 enddef ;

draw textext ("\strut rændömîzèd") ;
draw boundingbox currentpicture rændömîzèd
    enlarged 2mm
    withpen pencircle scaled 1mm
    withcolor darkgreen ;
\stopbuffer

\typebuffer

\page[preference]

it really does work:

\startlinecorrection[blank] \processMPbuffer \stoplinecorrection

\stopsection

\stopchapter

\stopcomponent