% vector_graphics.tex
%
% The documentation in this file is part of Pyxplot
% <http://www.pyxplot.org.uk>
%
% Copyright (C) 2006-2012 Dominic Ford <coders@pyxplot.org.uk>
%               2008-2012 Ross Church
%
% $Id: vector_graphics.tex 1302 2012-09-05 17:30:27Z dcf21 $
%
% Pyxplot is free software; you can redistribute it and/or modify it under the
% terms of the GNU General Public License as published by the Free Software
% Foundation; either version 2 of the License, or (at your option) any later
% version.
%
% You should have received a copy of the GNU General Public License along with
% Pyxplot; if not, write to the Free Software Foundation, Inc., 51 Franklin
% Street, Fifth Floor, Boston, MA  02110-1301, USA

% ----------------------------------------------------------------------------

% LaTeX source for the Pyxplot Users' Guide

\chapter{Producing vector graphics}
\label{ch:vector_graphics}

This chapter provides a systematic description of how Pyxplot can be used to
produce general-purpose vector graphics.  It also describes how to produce
galleries of multiple graphs side-by-side, together with how graphs may be
annotated with text or arrows. For more information about how to produce
graphical output in various image formats, see Section~\ref{sec:set_terminal}.
For more information about graph plotting, see Chapter~\ref{ch:plotting}.

\section{Adding other vector graphics objects}

In addition to graphs, a range of other objects can be placed on graphics
canvas:

\begin{itemize}
\item Rectangular boxes (the \indcmdt{box}).
\item Circles and arcs (the {\tt arc} and \indcmdt{circle}s).
\item Ellipses and elliptical arcs (the \indcmdt{ellipse}).
\item Graphical images in {\tt bmp}, {\tt eps}, {\tt gif}, {\tt jpeg} or {\tt png} formats (the {\tt eps} and \indcmdt{image}s).
\item Lines and arrows (the {\tt arrow} and \indcmdt{line}s).
\item Piecharts (the \indcmdt{piechart}).
\item Points labelled by crosses and other symbols (the \indcmdt{point}).
\item Polygons (the \indcmdt{polygon}).
\item Text labels (the \indcmdt{text}).
\end{itemize}
Put together, these commands can be used to produce a wide range of vector
graphics. The remainder of this chapter describes each of these commands in
turn, providing a variety of examples of their use.

These commands all interface with Pyxplot's maths environment in common ways.
For example, vector positions on the graphics canvas may be specified in three
ways:

\begin{itemize}
\item Two comma-separated dimensionless numbers, taken to be in centimetres, e.g.\ {\tt 4,5}.
\item Two comma-separated numbers with dimensions of length, e.g.\ {\tt 45*unit(mm), 13*unit(cm)}.
\item As a vector, either dimensionless, or with units of length, e.g.\ {\tt vector(4,5)} or {\tt vector(13,25)*unit(mm)}.
\end{itemize}

Many of these commands take rotation angles as inputs: these may be specified either as dimensionless numbers, taken to be in degrees,
or as values with physical units of angle, e.g.\ {\tt 0.25*unit(rev)}.

Where these commands take colors as inputs, as elsewhere in Pyxplot, the color may be specified in one of three ways:

\begin{itemize}
\item As a number, referred to a color from a present palette; see Section~\ref{sec:palette}.
\item As a recognised named color, e.g.\ {\tt red}; see Section~\ref{sec:color_names} for a list of these.
\item As an object of type color, for example, {\tt rgb(0,1,0)}, {\tt hsb(0.5,0.5,0.5)}, {\tt gray(0.2)}, {\tt colors.green + colors.red}, {\tt colors.yellow - colors.green}.
\end{itemize}

\section{Multiplot mode}
\label{sec:multiplot}
\index{multiplot}

Pyxplot has two modes in which it can produce graphical output. In {\it
singleplot} mode, the default, each time the {\tt plot} command is issued, the
canvas is wiped clean and the new plot is placed alone on a blank page. In {\it
multiplot} mode, vector graphics objects accumulate on the canvas. Each time
the {\tt plot} command is issued, the new graph is placed on top of any other
objects which were already on the canvas, and many plots can be placed
side-by-side.

The user can switch between these two modes of operation by issuing the
commands \indcmdts{set multiplot} and \indcmdts{set nomultiplot}. The
\indcmdt{set origin} is required for multiplot mode to be useful when placing
plots side-by-side: it sets the position on the page of the lower-left corner
of the next plot. It takes a comma-separated $(x,y)$ coordinate pair, which may
have units of length, or, if dimensionless, are assumed to be measured in
centimetres. The following example plots a graph of $\sin(x)$ to the left of a
plot of $\cos(x)$:
\begin{verbatim}
set multiplot
set width 8
plot sin(x)
set origin 10,0
plot cos(x)
\end{verbatim}

\section{The {\tt text} command}

Text labels may be added to multiplot canvases using the \indcmdt{text}. This
has the following syntax:

\begin{verbatim}
text 'This is some text' at x,y
\end{verbatim}

In this case, the string `This is some text' would be rendered at position
$(x,y)$ on the multiplot. As with the \indcmdt{set label}, a color may
optionally be specified with the {\tt with color} modifier, as well as a
rotation angle to rotate text labels through any given angle, measured in
degrees counter-clockwise. For example:\indkey{rotate}

\begin{verbatim}
text 'This is some text' at x,y rotate r with color red
\end{verbatim}

The commands \indcmdts{set textcolor}, \indcmdts{set texthalign} and
\indcmdts{set textvalign} can be used to set the color and alignment of the
text produced with the \indcmdt{text}. Alternatively, the \indcmdt{text} takes
three modifiers to control the alignment of the text which override these {\tt
set} commands. The {\tt halign} and {\tt valign} modifiers may be followed by
any of the settings which may follow the {\tt set texthalign} and {\tt set
textvalign} commands respectively, as in the following examples:

\begin{verbatim}
text 'This is some text' at 0,0 halign left valign top
text 'This is some text' at 0,0 halign right valign centre
\end{verbatim}

\noindent The {\tt gap} modifier allows a gap to be inserted in the alignment
of the text. For example, the string {\tt halign left gap 3*unit(mm)} would
cause text to be rendered with its left side $3\,\mathrm{mm}$ to the right of
the position specified for the text. This is useful for labelling points on
diagrams, where the labels should be slightly offset from the points that they
are associated with. If the {\tt gap} modifier is followed by a dimensionless
number, rather than one with dimensions of lengths, then it is assumed to be
measured in centimetres.

It should be noted that the \indcmdt{text} can also be used outside of the
multiplot environment, to render a single piece of short text instead of a
graph. One obvious application is to produce equations rendered as graphical
files which can subsequently be imported into documents, slideshows or
webpages.\index{presentations}

\section{The {\tt arrow} and {\tt line} commands}

Arrows may also be added to multiplot canvases using the \indcmdt{arrow}, which
has syntax:

\begin{verbatim}
arrow from x,y to x,y
\end{verbatim}

The \indcmdt{arrow} may be followed by the \indmodt{with} keyword to specify to
style of the arrow. The line type, line width and color of the arrow, may be
specified using the same syntax as used in the plot command, using the {\tt
linetype}, {\tt linewidth} and {\tt color} modifiers after the word {\tt
with}, as in the example:

\begin{verbatim}
arrow from 0,0 to 10,10 \
with linetype 2 linewidth 5 color red
\end{verbatim}

\noindent The style of the arrow may also be specified after the word {\tt
with}, and three options are available: {\tt head} (the default), {\tt nohead},
which produces line segments with no arrowheads on them, and {\tt twoway},
which produces bidirectional  arrows with heads on both ends.

The \indcmdt{arrow} has a twin, the \indcmdt{line}, which has the same syntax
but with a different style setting of {\tt nohead}.

\example{ex:notice}{A simple notice generated with the {\tt text} and {\tt arrow} commands}{
In this example script, we use Pyxplot's {\tt arrow} and {\tt text} commands to
produce a simple notice advertising that a lecture has moved to a different
seminar room:
\nlscf
\input{examples/tex/ex_notice_1.tex}
\nlscf
\centerline{\includegraphics[width=\textwidth]{examples/eps/ex_notice}}
}

\section{Editing items on the canvas}

All objects on a multiplot canvas have a unique identification number.  By
default, these count up from one, such that the first item placed on the canvas
is number one, the next is number two, and so forth. Alternatively, the user
may specify a particular number for a particular object by supplying the
modifier {\tt item} to the {\tt plot} command, followed by an integer
identification number, as in the following example:
\begin{verbatim}
plot item 6 'data.dat'
\end{verbatim}
If there were already an object on the canvas with identification number~6,
this object would be deleted and replaced with the new object.

A list of all of the objects on the current multiplot canvas can be obtained
using the \indcmdt{list}, which produces output in the following format:
\begin{verbatim}
# ID   Command
    1  plot item 1 'data1.dat'
    2  plot item 2 'data2.dat'
    3  [deleted] plot item 3 'data3.dat'
\end{verbatim}

A multiplot canvas can be wiped clean by issuing the \indcmdt{clear}, which
removes all items currently on the canvas. Alternatively, individual items may
be removed using the \indcmdt{delete}, which should be followed by a
comma-separated list of the identification numbers of the objects to be
deleted.  Deleted items may be restored using the \indcmdt{undelete}, which
likewise takes a comma-separated list of the identification numbers of the
objects to be restored, e.g.:
\begin{verbatim}
delete 1,2
undelete 2
\end{verbatim}
Once a canvas has been cleared using the \indcmdt{clear}, however, there is no
way to restore it.  Objects may be moved around on the canvas using the
\indcmdt{move}. For example, the following would move item 23 to position
$(8,8)$ measured in inches:
\begin{verbatim}
move 23 to 8*unit(in), 8*unit(in)
\end{verbatim}

\subsection{Settings associated with multiplot items}

Of the settings which can be set with the \indcmdt{set}, some refer to
Pyxplot's global environment and whole multiplot canvases. Others, such as {\tt
set width} and {\tt set origin} refer specifically to individual graphs and
vector graphics items. For this reason, whenever a new multiplot graphics item
is produced, it takes a copy of the settings which are specific to it, allowing
these settings to be changed by the user before producing other multiplot
items, without affecting previous items. The settings associated with a
particular multiplot item can be queried by passing the modifier {\tt item} to
the \indcmdt{show}, followed by the integer identification number of the item,
as in the examples:
\begin{verbatim}
show item 3 width    # Shows the width of item 3
show item 3 settings # Shows all settings associated with item 3
\end{verbatim}

The settings associated with a particular multiplot item can be changed by
passing the same {\tt item} modifier to the \indcmdt{set}, as in the example,
which sets the width of item~3 to be $10\,\mathrm{cm}$:
\begin{verbatim}
set item 3 width 10*unit(cm)
\end{verbatim}
After making such changes, the \indcmdt{refresh} is useful: it produces a new
graphical image of the current multiplot to reflect any settings which have
been changed. The following example would produce a pair of plots, and then
change the color of the text on the first plot:
\begin{verbatim}
set multiplot
plot f(x)
set origin 10,0
plot g(x)
set item 1 textcolor red
refresh
\end{verbatim}

Another common use of the \indcmdt{refresh} is to produce multiple
copies of an image in different graphical formats. For example, having just
developed a multiplot canvas interactively in the {\tt X11\_singlewindow},
copies can be produced as {\tt eps} and {\tt jpeg} images using the following
commands:
\begin{verbatim}
set terminal eps
set output 'figure.eps'
refresh
set terminal jpeg
set output 'figure.jpg'
refresh
\end{verbatim}

\subsection{Reordering multiplot items}

Items on multiplot canvases are drawn in order of increasing identification
number, and thus items with low identification numbers are drawn first, at the
back of the multiplot, and items with higher identification numbers are later,
towards the front of the multiplot. When new items are added, they are given
higher identification numbers than previous items and appear at the front of
the multiplot.

If this is not the desired ordering, then the \indcmdt{swap} may be used to
rearrange items. It takes the identification numbers of two multiplot items and
swaps their identification numbers and hence their positions in the ordered
sequence.  Thus, if, for example, the corner of item~3 disappears behind the
corner of item~5, when the converse effect is actually desired, the following
command should be issued:
\begin{verbatim}
swap 3 5
\end{verbatim}

\subsection{The construction of large multiplots}
\label{sec:set_display}

By default, whenever an item is added to a multiplot, or an existing item moved
or replotted, the whole multiplot is replotted to show the change. This can be
a time consuming process on large and complex multiplots. For this reason, the
\indcmdt{set nodisplay} is provided, which stops Pyxplot from producing any
output. The \indcmdt{set display} can subsequently be issued to return to
normal behaviour.

This can be especially useful in scripts which produce large multiplots. There
is no point in producing output at each step in the construction of a large
multiplot, and a great speed increase can be achieved by wrapping the script
with:

\begin{verbatim}
set nodisplay
[...prepare large multiplot...]
set display
refresh
\end{verbatim}

\example{ex:euclid}{A diagram from Euclid's {\it Elements}}{
In this more extended example script, we use Pyxplot's {\tt arrow} and {\tt
text} commands to reproduce a diagram illustrating the 47th Proposition from
Euclid's First Book of {\it Elements}, better known as Pythagoras' Theorem. A
full text of the proof which accompanies this diagram can be found at
\url{http://www.gutenberg.org/etext/21076}.
\nlscf
\input{examples/tex/ex_euclid_I_47_1.tex}
\nlscf
\centerline{\includegraphics[width=8cm]{examples/eps/ex_euclid_I_47}}
}

\example{ex:nanotubes}{A diagram of the conductivity of nanotubes}{
In this example we produce a diagram of the {\it irreducible wedge} of possible
carbon nanotube configurations, highlighting those configurations which are
electrically conductive. We use Pyxplot's loop constructs to automate the
production of the hexagonal grid which forms the basis of the diagram.
\nlscf
\input{examples/tex/ex_nanotubes_1.tex}
\nlscf
\centerline{\includegraphics[width=9cm]{examples/eps/ex_nanotubes}}
}

\section{Linked axes and galleries of plots}

In the previous chapter (Section~\ref{sec:linked_axes}), linked axes were
introduced as a mechanism by which several axes on a single plot could be set
to have the same range, or to be algebraically related to one another. Another
common use for them is to make several plots on a multiplot canvas share common
axes. Just as the following statement links two axes on a single plot to one
another
\begin{verbatim}
set axis x2 linked x
\end{verbatim}
axes on the current plot can be linked to those of previous plots which are
already on the multiplot canvas using syntax of the form:
\begin{verbatim}
set axis x2 linked item 2 x
\end{verbatim}

A common reason for doing this is to produce galleries of side-by-side plots.
The following series of commands would produce a $2\times2$ grid of plots, with
axes only labelled along the bottom and left sides of the grid:

\vspace{3mm}
\input{examples/tex/ex_gallery_1.tex}
\vspace{3mm}

\centerline{\includegraphics[width=\textwidth]{examples/eps/ex_gallery}}

\subsection{The {\tt replot} command revisited}

In multiplot mode, the \indcmdt{replot} can be used to modify the last plot
added to the page. For example, the following would change the title of the
latest plot to `foo', and add a plot of the function $g(x)$ to it:

\begin{verbatim}
set title 'foo'
replot cos(x)
\end{verbatim}

Additionally, it is possible to modify any plot on the page by adding an {\tt
item} modifier to the {\tt replot} statement to specify which plot should be
replotted.  The following example would produce two plots, and then add an
additional function to the first plot:

\begin{verbatim}
set multiplot
plot f(x)
set origin 10,0
plot g(x)
replot item 1 h(x)
\end{verbatim}

If no {\tt item} number is specified, then the \indcmdt{replot} acts by default
upon the most recent plot to have been added to the multiplot canvas.

\section{The {\tt polygon} command}

\example{ex:polygon1}{A simple polygon}{
In this simple example, we use Pyxplot's {\tt polygon} command to generate a
geometric shape from a list of points.
\nlscf
\input{examples/tex/ex_polygon1_1.tex}
\nlscf
\centerline{\includegraphics[width=8cm]{examples/eps/ex_polygon1}}
}

\example{ex:polygon2}{The first eight regular polygons}{
This example uses Pyxplot's flow control commands, together with its list
methods and the {\tt polygon} command, to generate a diagram of the first eight
regular polygons.
\nlscf
\input{examples/tex/ex_polygon2_1.tex}
\nlscf
\centerline{\includegraphics[width=8cm]{examples/eps/ex_polygon2}}
}

\section{The {\tt image} command}

Graphical images in {\tt bmp}, {\tt gif}, {\tt jpeg} or {\tt png} format may be
placed on multiplot canvases using the \indcmdt{image}\footnote{To maintain
compatibility with historic versions of Pyxplot, the {\tt image} command may
also be spelt {\tt jpeg}, with the identical syntax thereafter.}. In its
simplest form, this has the syntax:
\begin{verbatim}
image 'filename' at x,y width w
\end{verbatim}

As an alternative to the \indkeyt{width} keyword the height of the image can be
specified, using the analogous \indkeyt{height} keyword.  An optional angle can
also be specified using the \indkeyt{rotate} keyword; this causes the included
image to be rotated counter-clockwise by a specified angle, measured in
degrees.  The keyword {\tt smooth} may optionally be supplied to cause the
pixels of the image to be interpolated\footnote{Many commonly-used PostScript
display engines, including Ghostscript, do not support this functionality.}.

Images which include transparency are supported. The optional keyword {\tt
notransparent} may be supplied to the \indcmdt{image} to cause transparent
regions to be filled with the image's default background color. Alternatively,
an RGB color may be specified in the form {\tt rgb<r>:<g>:<b>} after the
keyword {\tt transparent} to cause that particular color to become
transparent; the three components of the RGB color should be in the range~0
to~255.

\section{The {\tt eps} command}

Vector graphic images in eps format may be placed on multiplot canvases
using the \indcmdt{eps}, which has a syntax analogous to the {\tt image}
command.  However neither height nor width need be specified; in this case the
image will be included at its native size.  For example:

\begin{verbatim}
eps 'filename' at 3,2 rotate 5
\end{verbatim}

\noindent will place the eps file with its bottom-left corner at position
$(3,2)$\,cm from the origin, rotated counter-clockwise through 5 degrees.

\section{The {\tt box} and {\tt circle} commands}
\label{sec:rectangle}

Rectangular boxes and circles may be placed on multiplot canvases
using the {\tt box} and {\tt circle} commands\indcmd{box}\indcmd{circle}, as
in:

\begin{verbatim}
box from 0*unit(mm),0*unit(mm) to 25*unit(mm),70*unit(mm)
circle at 0*unit(mm),0*unit(mm) radius 70*unit(mm)
\end{verbatim}

\noindent In the former case, two corners of the rectangle are specified,
meanwhile in the latter case the centre of the circle and its radius are
specified. The \indcmdt{box} may also be invoked by the synonym {\tt
rectangle}\indcmd{rectangle}. Boxes may be rotated using an optional {\tt
rotate} modifier, which may be followed by a counter-clockwise rotational angle
which may either have dimensions of angle, or is assumed to be in degrees if
dimensionless. The rotation is performed about the centre of the rectangle:

\begin{verbatim}
box from 0,0 to 10,3 rotate 45
\end{verbatim}

The positions and dimensions of boxes may also be specified by giving the
position of one of the corners of the box, together with its width and height.
The specified corner is assumed to be the bottom-left corner if both the
specified width and height are positive; other corners may be specified if the
supplied width and/or height are negative. If such boxes are rotated, the
rotation is about the specified corner:

\begin{verbatim}
box at 0,0 width 10 height 3 rotate 45
\end{verbatim}

The line type, line width, and color of line with which the outlines of boxes
and circles are drawn may be specified as in the {\tt arrow} command, for
example:

\begin{verbatim}
circle at 0,0 radius 5 with linetype 1 linewidth 2 color red
\end{verbatim}

\noindent The shapes may be filled by specifying a {\tt fillcolor}:

\begin{verbatim}
circle at 0,0 radius 5 with lw 10 color red fillcolor yellow
\end{verbatim}

\example{ex:noentry}{A simple no-entry sign}{
In this example script, we use Pyxplot's {\tt box} and {\tt circle} commands to
produce a no-entry sign warning passers by that code monkeys can turn nasty
when interrupted from their work.
\nlscf
\input{examples/tex/ex_noentry_1.tex}
\nlscf
\centerline{\includegraphics[width=5cm]{examples/eps/ex_noentry}}
}

\section{The {\tt arc} command}
\label{sec:arc}

Partial arcs of circles may be drawn using the \indcmdt{arc}. This has similar
syntax to the \indcmdt{circle}, but takes two additional angles, measured
clockwise from the upward vertical direction, which specify the extent of the
arc to be drawn. The arc is drawn clockwise from start to end, and hence the
following two instructions draw two complementary arcs which together form a
complete circle:

\begin{verbatim}
set multiplot
arc at 0,0 radius 5 from -90 to   0 with lw 3 col red
arc at 0,0 radius 5 from   0 to -90 with lw 3 col green
\end{verbatim}

\noindent If a {\tt fillcolor} is specified, then a pie-wedge is drawn:

\begin{verbatim}
arc at 0,0 radius 5 from 0 to 30 with lw 3 fillcolor red
\end{verbatim}

\example{ex:triangle}{Labelled diagrams of triangles}{
In this example, we make a subroutine to draw labelled diagrams of the interior
angles of triangles, taking as its inputs the lengths of the three sides of the
triangle to be drawn and the position of its lower-left corner. The subroutine
calculates the positions of the three vertices of the triangle and then labels
them. We use Pyxplot's automatic handling of physical units to generate the
\latexdcf\ strings required to label the side lengths in centimetres and the
angles in degrees. We use Pyxplot's {\tt arc} command to draw angle symbols in
the three corners of a triangle.
\nlscf
\input{examples/tex/ex_triangle_1.tex}
\nlscf
\centerline{\includegraphics{examples/eps/ex_triangle}}
}

\example{ex:lens}{A labelled diagram of a converging lens forming a real image}{
In this example, we make a subroutine to draw labelled diagrams of converging
lenses forming real images.
\nlscf
\input{examples/tex/ex_lenses_1.tex}
\nlscf
\centerline{\includegraphics{examples/eps/ex_lenses}}
}

\section{The {\tt point} command}
\label{sec:point}

The \indcmdt{point} places a single point on a multiplot canvases, in the same
style which would be used when plotting a dataset on a graph with the {\tt
points} plotting style. It is useful for marking significant points on
technical diagrams with crosses or other motifs.

The \indcmdt{point} that the position of the point to be marked be specified
after the {\tt at} modifier. A text label to be attached next to the point may
optionally be specified using the same {\tt label} modifier as taken by the
{\tt plot} command. A {\tt with} modifier may then be supplied, followed by any
of the style modifiers: {\tt color}, {\tt pointlinewidth}, {\tt pointsize},
{\tt pointtype}, {\tt style}.

The following example labels the origin as such:
\begin{verbatim}
set texthalign left
set textvalign centre
point at 0,0 label "The Origin" with ps 2
\end{verbatim}

\section{The {\tt ellipse} command}
\label{sec:ellipse}

Ellipses may be placed on multiplot canvases using the \indcmdt{ellipse}. The
shape of the ellipse may be specified in many different ways, by specifying

\begin{enumerate}[(i)]
\item the position of two corners of the smallest rectangle which can enclose
the ellipse when its major axis is horizontal, together with an optional
counter-clockwise rotation angle, applied about the centre of the ellipse.
For example:

\begin{verbatim}
ellipse from 0,0 to 4,1 rot 70
\end{verbatim}

\item the position of both the centre and one of the foci of the ellipse,
together with any one of the following additional pieces of information: the
ellipse's major axis length, its semi-major axis length, its minor axis length,
its semi-minor axis length, its eccentricity, its latus rectum, or its
semi-latus rectum.  For example:

\begin{verbatim}
ellipse focus 0,0 centre 2,2 majoraxis 4
ellipse focus 0,0 centre 2,2 minoraxis 4
ellipse focus 0,0 centre 2,2 ecc 0.5
ellipse focus 0,0 centre 2,2 LatusRectum 6
ellipse focus 0,0 centre 2,2 slr 3
\end{verbatim}

\item the position of either the centre or one of the foci of the ellipse,
together with any two of the following additional pieces of information: the
ellipse's major axis length, its semi-major axis length, its minor axis length,
its semi-minor axis length, its eccentricity, its latus rectum, or its
semi-latus rectum. An optional counter-clockwise rotation angle may also be
specified, applied about either the centre or one of the foci of the ellipse,
whichever is specified. If no rotation angle is given, then the major axis of
the ellipse is horizontal.  For example:

\begin{verbatim}
ellipse centre 0,0 majoraxis 4 minoraxis 4
\end{verbatim}
\end{enumerate}

The line type, line width, and color of line with which the outlines of
ellipses are drawn may be specified after the keyword {\tt with}, as in the
{\tt box} and {\tt circle} commands above. Likewise, ellipses may be filled in
the same manner.

\example{ex:ellipse}{A labelled diagram of an ellipse}{
In this example script, we illustrate the text of Section~\ref{sec:ellipse} by
using Pyxplot's {\tt ellipse} command, together with arrows and text labels, to
produce a labelled diagram of an ellipse. We label the semi-major axis $a$, the
semi-minor axis $b$, the semi-latus rectum $L$, and the distance between the
centre of the ellipse and one of its foci with the length $ae$, where $e$ is
the eccentricity of the ellipse.
\nlscf
\input{examples/tex/ex_ellipse_1.tex}
\nlscf
\centerline{\includegraphics[width=8cm]{examples/eps/ex_ellipse}}
}

\section{The {\tt piechart} command}
\label{sec:piechart}

The \indcmdt{piechart} produces piecharts based upon single columns of data
read from \datafile s, which are taken to indicate the sizes of the pie wedges.
The \indcmdt{piechart} has the following syntax:
\begin{verbatim}
piechart ('<filename>'|<function>)
     [using <using specifier>]
     [select <select specifier>]
     [index <index specifier>]
     [every <every specifier>]
     [label <auto|key|inside|outside> <label>]
     [format <format string>]
     [with <style> [<style modifier> ... ] ]
\end{verbatim}

Immediately after the {\tt piechart} keyword, the file (or indeed, function)
from which the data is to be taken should be specified; any of the modifiers
taken by the {\tt plot} command -- i.e.\ {\tt using}, {\tt index}, etc.\ -- may
be used to specify which data from this \datafile\ should be used. The {\tt
label} modifier should be used to specify how a name for each pie wedge should
be drawn from the \datafile, and has a similar syntax to the equivalent
modifier in the {\tt plot} command, except that the name string may be
prefixed by a keyword to specify how the pie wedge names should be positioned.
Four options are available:

\noindent
\begin{itemize}
\item {\tt auto} -- specifies that the {\tt inside} positioning mode should be used on wide pie wedges, and the {\tt outside} positioning mode should be used on narrow pie wedges. {\bf [default]}
\item {\tt key} -- specifies that all of the labels should be arranged in a vertical list to the right-hand side of the piechart.
\item {\tt inside} -- specifies that the labels should be placed within the pie wedges themselves.
\item {\tt outside} -- specifies that the labels should be arranged around the circumference of the pie chart.
\end{itemize}

Having specified a name for each wedge using the {\tt label} modifier, the {\tt
format} modifier determines the final text which is printed along side each
wedge.  For example, a wedge with name `Europe' might be labelled as `27\%
Europe', applying the default format string:
\begin{verbatim}
"%.1d\%% %s"%(percentage,label)
\end{verbatim}
Three variables may be used in format strings: {\tt label} contains the name of
the wedge as specified by the {\tt label} modifier, {\tt percentage} contains
the numerical percentage size of the wedge, and {\tt wedgesize} contains the
absolute unnormalised size of the wedge, as read from the input \datafile,
before the sizes were renormalised to sum to 100\%.

The {\tt with} modifier may be followed by the keywords {\tt color}, {\tt
linewidth}, {\tt style}, which all apply to the lines drawn around the
circumference of the piechart and between its wedges. The fill color of the
wedges themselves are taken sequentially from the current palette, as set by
the {\tt set palette} command. Note that Pyxplot's default palette is optimised
more for producing plots with datasets in different and distinct colors than
for producing piecharts in aesthetically pleasing shades, where a little more
subtly may be desirable. A suitable call to the {\tt set palette} command is
highly recommended before the \indcmdt{piechart} is used.

As with the {\tt plot} command, the position and size of the piechart are
governed by the {\tt set origin} and {\tt set size} commands. The former
determines where the centre of the piechart is positioned; the latter
determines its diameter.

\example{ex:piechart}{A piechart of the composition of the Universe}{
In this example, we use Pyxplot's {\tt piechart} command to produce a diagram
of the composition of the Universe, showing that of the mass in the Universe,
only 4\% is in the form of the baryonic matter; of the rest, 22\% is in the
form of dark matter and 74\% in the form of dark energy:
\nlscf
\input{examples/tex/ex_piechart_1.tex}
\nlscf
\centerline{\includegraphics{examples/eps/ex_piechart}}
\nlfcf
Below, we show the change produced by replacing the line\vspace{2mm}\newline
\noindent{\tt piechart '--' using \$1 label key "\%s"\%(\$2)}\vspace{2mm}\newline
with\vspace{2mm}\newline
\noindent{\tt piechart '--' using \$1 label auto "\%s"\%(\$2)}\vspace{2mm}\newline
Note that the labels on the piechart are placed either within the pie, in the
cases of large wedges, and around the edge of the pie for those wedges which
are too narrow for this.
\nlscf
\centerline{\includegraphics{examples/eps/ex_piechart2}}
}

\section{LaTeX and Pyxplot}

The \indcmdt{text} can straightforwardly be used to render simple one-line
\latexdcf\index{latex} strings, but sometimes the need arises to place more
substantial blocks of text onto a plot. For this purpose, it can be useful to
use the \latexdcf\ {\tt parbox} or {\tt minipage} environments\footnote{Remember,
any valid \latexdcf\ string can be passed to the \indcmdt{text} and \indcmdt{set
label}.}. For example:

\input{examples/tex/ex_text1_1.tex}

\begin{center}
\fbox{\includegraphics{examples/eps/ex_text1}}
\end{center}

If unusual mathematical symbols are required, for example those in the {\tt
amsmath} package\index{amsmath package@{\tt amsmath} package}, such a package
can be loaded using the \indcmdt{set preamble}. For example:

\input{examples/tex/ex_text2_1.tex}

\begin{center}
\fbox{\includegraphics{examples/eps/ex_text2}}
\end{center}