\c -*-latexinfo-*-
\c advanced.tex
\c Maurice LeBrun
\c 19 May 1994

\node Advanced Use, Drivers, Simple Use, Top
\chapter{Advanced Use of PLplot}

In this chapter, we describe more precisely how to control the position
and scaling of a graph, how to alter the low-level line and character
attributes, and how to use the functions in PLplot for drawing
three-dimensional surface plots and contour plots.

Still updating this chapter.

\begin{menu}
* Concepts::		Basic PLplot Concepts
* Output Device::	Specifying the Output Device
* Arguments::		Command Line Arguments
* Viewports::		Defining the Viewport
* Windows::		Defining the Window
* Annotation::		Annotating the Viewport
* Standard Window::	Setting up a Standard Window
* Line Attributes::	Setting Line Attributes
* Fill Pattern::	Setting the Area Fill Pattern
* Characters::		Setting Character and Symbol Attributes
* Escape Sequences::	Escape Sequences in Text
* 3-d Plots::		Three Dimensional Surface Plots
* Contour Plots::	Contour and Shade Plots
\end{menu}

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node Concepts, Output Device, Advanced Use, Advanced Use
\message{Concepts}
\section{Basic PLplot Concepts}
\cindex{Basic Concepts}

When drawing a graph, the programmer usually wishes to specify the
coordinates of the points to be plotted in terms of the values of the
variables involved.  These coordinates are called \emph{world coordinates}, 
and may have any floating-point value representable by the computer. The
\emph{window} refers to the rectangular region of world-coordinate space
which is to be graphed.  This window is mapped onto a rectangular region
of the \emph{view surface}, which can be a terminal screen or a sheet of
paper in the output device (or a portion thereof, if subpages are being
used).  This physical region onto which the window is mapped is called
the \emph{viewport}.  Before a graph can be drawn, the program must
define both the window and the viewport by calling appropriate routines
in PLplot.\refill

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node Output Device, Arguments, Concepts, Advanced Use
\message{Output}
\section{Specifying the Output Device}
\cindex{Output device}

The main initialization routine for PLplot is \code{plinit}, which sets
up all internal data structures necessary for plotting and initializes
the output device driver.  The output device can be a terminal, disk
file, window system, pipe, or socket.  If the output device has not
already been specified when \code{plinit} is called, a list of valid
output devices is given and the user is prompted for a choice.  For
example:\refill

\begin{verbatim}
% x01c

Plotting Options:
 < 1> xwin       X-Window (Xlib)
 < 2> dp         Tcl-DP/TK Window
 < 3> tk         Tcl/TK Window
 < 4> xterm      Xterm Window
 < 5> tekt       Tektronix Terminal (4010)
 < 6> tek4107t   Tektronix Terminal (4105/4107)
 < 7> mskermit   MS-Kermit emulator
 < 8> versaterm  Versaterm vt100/tek emulator
 < 9> vlt        VLT vt100/tek emulator
 <10> plmeta     PLPLOT Native Meta-File
 <11> tekf       Tektronix File (4010)
 <12> tek4107f   Tektronix File (4105/4107)
 <13> ps         PostScript File (monochrome)
 <14> psc        PostScript File (color)
 <15> xfig       Xfig file
 <16> ljiip      LaserJet IIp/deskjet compressed graphics
 <17> ljii       LaserJet II Bitmap File (150 dpi)
 <18> null       Null device

Enter device number or keyword: 
\end{verbatim}

Either the device number or a device keyword is accepted.  Specifying
the device by keyword is preferable in aliases or scripts since the
device number is dependent on the install procedure (the installer can
choose which device drivers to include).  The device can be specified
prior to the call to \code{plinit} by:\refill

\begin{itemize}
\item
A call to \rou{plsdev}.

\item
The \code{-dev} \var{device} command line argument, if the program's
command line arguments are being passed to the PLplot function
\rou{plParseInternalOpts}.\refill
\end{itemize}

Additional startup routines \rou{plstar} and \rou{plstart} are available
but these are simply front-ends to \code{plinit}, and should be avoided.
It is preferable to call \code{plinit} directly, along with the
appropriate setup calls, for the greater amount of control this
provides (see the example programs for more info).

Before \code{plinit} is called, you may modify the number of subpages
the output device is divided into via a call to \rou{plssub}.  Subpages
are useful for placing several graphs on a page, but all subpages are
constrained to be of the same size.  For greater flexibility, viewports
can be used (\pxref{Viewports} for more info on viewports).  The routine
\code{pladv} is used to advance to a particular subpage or to the next
subpage.  The screen is cleared (or a new piece of paper loaded) if a
new subpage is requested when there are no subpages left on the current
page.  When a page is divided into subpages, the default character,
symbol and tick sizes are scaled inversely as the square root of the
number of subpages in the vertical direction.  This is designed to
improve readability of plot labels as the plot size shrinks.\refill

PLplot has the ability to write to multiple output streams.  An output
stream corresponds to a single logical device to which one plots
independent of all other streams.  The function \rou{plsstrm} is used to
switch between streams -- you may only write to one output stream at
a time.  At present, an output stream is not limited by the type of
device, however, it may not be wise to attempt opening two terminal
devices.  An example usage for the creation of multiple streams is as
follows:\refill

\begin{verbatim}
#include "plplot.h"

main()
{
    int nx = 2, ny = 2;

    plssub(nx, ny);
    plsdev("xwin");
    plinit();

    <plots for stream 0>

    plsstrm(1);
    plssub(nx, ny);
    plsdev("plmeta");
    plsfnam("tst.plm");
    plinit();

    <plots for stream 1>

    plsstrm(0);

    <plots for stream 0>
\end{verbatim}

and so on, for sending output simultaneously to an X-window and a metafile.
The default stream corresponds to stream number zero.  At present, the
majority of output drivers can only be used by a single stream
(exceptions include the metafile driver and X-window driver).  Also see
example program 14 (note: only the C version is available, although it
can be done equally well from Fortran).\refill

At the end of a plotting program, it is important to close the plotting
device by calling \rou{plend}.  This flushes any internal buffers and
frees any memory that may have been allocated, for all open output
streams.  You may call \rou{plend1} to close the plotting device for the
current output stream only.  Note that if PLplot is initialized more
than once during a program to change the output device, an automatic
call to \code{plend1} is made before the new device is opened for the
given stream.\refill

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node Arguments, Viewports, Output Device, Advanced Use    
\message{Arguments}
\section{Command line arguments}
\cindex{arguments}
\cindex{command line}

PLplot supports a large number of command line arguments, but it is up
to the user to pass these to PLplot for processing at the beginning
of execution.  The function \rou{plParseInternalOpts} is responsible
for parsing the argument list, removing all that are recognized by
PLplot, and taking the appropriate action before returning.  There are
an extensive number of options available to affect this process.  The
command line arguments recognized by PLplot are given by the -h 
option:\refill

\begin{verbatim}
% x01c -h

Usage:
        x01c [plplot options]

plplot options:
    -h                   Print out this message
    -v                   Print out the plplot library version number
    -dev name            Output device name
    -o name              Output filename
    -display name        X server to contact
    -px number           Plots per page in x
    -py number           Plots per page in y
    -geometry geom       Window size, in pixels (e.g. -geometry 400x300)
    -wplt xl,yl,xr,yr    Relative coordinates [0-1] of window into plot
    -mar margin          Margin space in relative coordinates (0 to 0.5, def 0)
    -a aspect            Page aspect ratio (def: same as output device)
    -jx justx            Page justification in x (-0.5 to 0.5, def 0)
    -jy justy            Page justification in y (-0.5 to 0.5, def 0)
    -ori orient          Plot orientation (0,2=landscape, 1,3=portrait)
    -width width         Sets pen width (1 <= width <= 10)
    -bg color            Background color (0=black, FFFFFF=white)
    -fam                 Create a family of output files
    -fsiz size           Output family file size in MB (e.g. -fsiz 1.0)
    -fbeg number         First family member number on output
    -finc number         Increment between family members
    -fflen length        Family member number minimum field width
    -nopixmap            Don't use pixmaps in X-based drivers
    -db                  Double buffer X window output
    -np                  No pause between pages
    -server_name name    Main window name of plplot server (tk driver)
    -server_host name    Host to run plplot server on (dp driver)
    -server_port name    Port to talk to plplot server on (dp driver)
    -user name           User name on remote node (dp driver)

All parameters must be white-space delimited.  Some options are driver
dependent.  Please see the plplot reference document for more detail.
\end{verbatim}

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node Viewports, Windows, Output Device, Advanced Use    
\message{Viewports}
\section{Defining the Viewport}
\cindex{viewports}

After defining the view surface, it is necessary to define the portion
of this surface which is to be used for plotting the graph (the
viewport).  All lines and symbols (except for labels drawn by
\code{plbox}, \code{plmtex} and \code{pllab}) are clipped at the
viewport boundaries.\refill

Viewports are created within the current subpage.  If the division of
the output device into equally sized subpages is inappropriate, it is
best to specify only a single subpage which occupies the entire output
device (by setting \code{nx = 1} and \code{ny = 1} in \code{plstart} or
\code{plstar}), and use one of the viewport specification subroutines
below to place the plot in the desired position on the page.\refill

There are four methods for specifying the viewport size, using the
subroutines \rou{plvpor}, \rou{plsvpa}, \rou{plvasp}, and \rou{plvpas}.
Each of these has the format:\refill

\begin{verbatim}
    plvpor(xmin, xmax, ymin, ymax);
    plsvpa(xmin, xmax, ymin, ymax);
    plvasp(aspect);
    plvpas(xmin, xmax, ymin, ymax, aspect);
\end{verbatim}

where in the case of \code{plvpor} and \code{plvpas}, the arguments are given
in \emph{normalized subpage coordinates} which are defined to run from 0.0
to 1.0 along each edge of the subpage.  Thus for example,\refill

\begin{verbatim}
    plvpor(0.0, 0.5, 0.5, 1.0);
\end{verbatim}

uses the top left quarter of the current subpage.

In order to get a graph of known physical size, the routine \code{plsvpa}
defines the viewport in terms of absolute coordinates (millimeters) measured
from the bottom left-hand corner of the current subpage.  This routine
should only be used when the size of the view surface is known, and a
definite scaling is required.\refill

The routine \code{plvasp} gives the largest viewport with the given aspect
ratio that fits in the current subpage (i.e. the ratio of the length of the
y axis to that of the x axis is equal to \code{aspect}).  It also allocates
space on the left and top of the viewport for labels.\refill

The routine \code{plvpas} gives the largest viewport with the given aspect
ratio that fits in the specified region (specified with normalized subpage
coordinates, as with \code{plvpor}).  This routine is functionally
equivalent to \code{plvpor} when a ``natural'' aspect ratio is chosen (done
by setting \code{aspect} to 0.0).  Unlike \code{plvasp}, this routine
reserves no extra space at the edges for labels.\refill

To help the user call \code{plsvpa} correctly, the routine \rou{plgspa}
is provided which returns the positions of the extremities of the
current subpage measured in millimeters from the bottom left-hand corner
of the device.  Thus, if to set up a viewport with a 10.0 mm margin
around it within the current subpage, the following sequence of calls
may be used:\refill

\begin{verbatim}
    plgspa(xmin, xmax, ymin, ymax);
    plsvpa(10.0, xmax-xmin-10.0, 10.0, ymax-ymin-10.0);
\end{verbatim}

A further routine \rou{plvsta} is available which sets up a standard
viewport within the current subpage with suitable margins on each side
of the viewport.  This may be used for simple graphs, as it leaves
enough room for axis labels and a title.  This standard viewport is that
used by \code{plenv} (\pxref{Standard Window}).\refill

Another way to get a specified aspect ratio is via the routine
\code{plsasp} [not!.. fix this], which sets the global aspect ratio and
must be called prior to \code{plstar}.  An aspect ratio of 0.0
corresponds to ``natural'' dimensions (i.e. fill the page); any positive
value will give the specified aspect ratio.  This scaling of plots is
actually done in the driver, and so may not work for all output devices
(note that
\code{plrender} is capable of scaled aspect ratio plots to any device
whether that device supports scaling or not).  In such scaled plots,
absolute plotting is done in the scaled coordinate system.\refill

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node Windows, Annotation, Viewports, Advanced Use
\message{Windows}
\section{Defining the Window}
\cindex{Windows}

The window must be defined after the viewport in order to map the world
coordinate rectangle into the viewport rectangle.  The routine
\rou{plwind} is used to specify the rectangle in world-coordinate space.
For example, if we wish to plot a graph showing the collector current
\begin{tex}
$I_C$ as a function of the collector to emitter voltage $V_{CE}$ for a
transistor where $0\le I_C\le 10.0\mbox{\, mA}$ and $0\le V_{CE}\le
12.0\mbox{\, V}$, 
\end{tex}
\begin{ifinfo}
\code{I_C} as a function of the collector to emitter voltage \code{V_CE}
for a transistor where \code{0 <= I_C <= 10.0 mA} and \code{0 <= V_CE <=
12.0 V},
\end{ifinfo}
we would call the function \code{plwind} as follows:\refill

\begin{verbatim}
    plwind(0.0, 12.0, 0.0, 10.0);
\end{verbatim}

Note that each of the arguments is a floating point number, and so the
decimal points are required.  If the order of either the X limits or
Y limits is reversed, the corresponding axis will point in the opposite
sense, (i.e., right to left for X and top to bottom for Y).  The window
must be defined before any calls to the routines which actually draw the
data points.  Note however that \code{plwind} may also be called to
change the window at any time.  This will affect the appearance of
objects drawn later in the program, and is useful for drawing two or
more graphs with different axes on the same piece of paper.\refill

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node Annotation, Standard Window, Windows, Advanced Use
\message{Annotation}
\section{Annotating the Viewport}
\cindex{Annotation}
\cindex{Writing Text}
\cindex{Labels}

The routine \rou{plbox} is used to specify whether a frame is drawn
around the viewport and to control the positions of the axis
subdivisions and numeric labels.  For our simple graph of the transistor
characteristics, we may wish to draw a frame consisting of lines on all
four sides of the viewport, and to place numeric labels along the bottom
and left hand side.  We can also tell PLplot to choose a suitable tick
interval and the number of subticks between the major divisions based
upon the data range specified to \code{plwind}.  This is done using the
following statement\refill

\begin{verbatim}
    plbox("bcnst", 0.0, 0, "bcnstv", 0.0, 0);
\end{verbatim}

Another routine \rou{pllab} provides for text labels for the bottom,
left hand side and top of the viewport.  These labels are not clipped,
even though they lie outside the viewport (but they are clipped at the
subpage boundaries).  \code{pllab} actually calls the more general
routine \code{plmtex} which can be used for plotting labels at any point
relative to the viewport.  For our example, we may use\refill

\begin{verbatim}
    pllab("V#dCE#u (Volts)", "I#dC#u (mA)", "TRANSISTOR CHARACTERISTICS");
\end{verbatim}

Note that \code{#d} and \code{#u} are escape sequences (\pxref{Escape
Sequences}) which allow subscripts and superscripts to be used in text.
They are described more fully later in this chapter.\refill

The appearance of axis labels may be further altered by auxiliary calls
to \rou{plprec}, \rou{plschr}, \rou{plsxax}, \rou{plsyax}, and
\rou{plszax}.  The routine \code{plprec} is used to set the number of
decimal places precision for axis labels, while \code{plschr} modifies
the heights of characters used for the axis and graph labels.  Routines
\code{plsxax}, \code{plsyax}, and \code{plszax} are used to modify the
\code{digmax} setting for each axis, which affects how floating point
labels are formatted.\refill

The \code{digmax} variable represents the maximum field width for the
numeric labels on an axis (ignored if less than one).  If the numeric
labels as generated by PLplot exceed this width, then PLplot automatically
switches to floating point representation.  In this case the exponent will
be placed at the top left for a vertical axis on the left, top right for
a vertical axis on the right, and bottom right for a horizontal axis.\refill

\c For example, let's suppose that we have set \code{digmax} $ = 5$ via
\c \code{plsyax}, and for our plot a label is generated at \code{y} $ =
\c 0.0000478$.  In this case the actual field width is longer than
\c \code{digmax}, so PLplot switches to floating point.  In this
\c representation, the label is printed as simply $4.78$ with the $10^{-5}$
\c exponent placed separately.\refill

The determination of maximum length (i.e. \code{digmax}) for fixed point
quantities is complicated by the fact that long fixed point
representations look much worse than the same sized floating point
representation.  Further, a fixed point number with magnitude much less
than one will actually gain in precision when written as floating point.
There is some compensation for this effect built into PLplot, thus the
internal representation for number of digits kept (\code{digfix}) may
not always match the user's specfication (via \code{digmax}).  However,
\c it will always be true that \code{digfix} $\le$ \code{digmax}.  The
\c PLplot defaults are set up such that good results are usually obtained
\c without user intervention.\refill

Finally, after the call to \code{plbox}, the user may call routines
\rou{plgxax}, \rou{plgyax}, or \rou{plgzax} to obtain information about the
window just drawn.  This can be helpful when deciding where to put
captions.  For example, a typical usage would be to call \code{plgyax} to
get the value of \code{digits}, then offset the y axis caption by that amount
(plus a bit more) so that the caption ``floats'' just to the outside of the
numeric labels.  Note that the \code{digits} value for each axis for the
current plot is not correct until \emph{after} the call to \code{plbox} is
complete.\refill

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node Standard Window, Line Attributes, Annotation, Advanced Use
\message{Standard}
\section{Setting up a Standard Window}
\cindex{Standard window}
\cindex{plenv}

Having to call \code{pladv}, \code{plvpor}, \code{plwind} and
\code{plbox} is excessively cumbersome for drawing simple graphs.
Subroutine \code{plenv} combines all four of these in one subroutine,
using the standard viewport, and a limited subset of the capabilities of
\code{plbox}.  For example, the graph described above could be initiated
by the call:\refill

\begin{verbatim}
    plenv(0.0, 12.0, 0.0, 10.0, 0, 0);
\end{verbatim}

which is equivalent to the following series of calls:

\begin{verbatim}
    pladv(0);
    plvsta();
    plwind(0.0, 12.0, 0.0, 10.0);
    plbox("bcnst", 0.0, 0, "bcnstv", 0.0, 0);
\end{verbatim}

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node Line Attributes, Fill Pattern, Standard Window, Advanced Use
\message{Line}
\section{Setting Line Attributes}
\cindex{Line attributes}

The graph drawing routines may be freely mixed with those described in
this section, allowing the user to control line color, width and styles.
The attributes set up by these routines apply modally, i.e, all
subsequent objects (lines, characters and symbols) plotted until the
next change in attributes are affected in the same way.  The only
exception to this rule is that characters and symbols are not affected
by a change in the line style, but are always drawn using a continuous
line.\refill

Line color is set using the routine \rou{plcol}.  The argument
is ignored for devices which can only plot in one color, although some
terminals support line erasure by plotting in color zero.\refill

Line width is set using \rou{plwid}.  This option is not supported by
all devices.\refill

Line style is set using the routine \rou{plstyl} or \rou{pllsty}.  A
broken line is specified in terms of a repeated pattern consisting of
marks (pen down) and spaces (pen up).  The arguments to this routine are
the number of elements in the line, followed by two pointers to integer
arrays specifying the mark and space lengths in micrometers.  Thus a
line consisting of long and short dashes of lengths 4\, mm and 2\, mm,
separated by spaces of length 1.5\, mm is specified by:\refill

\begin{verbatim}
    mark[0] = 4000;
    mark[1] = 2000;
    space[0] = 1500;
    space[1] = 1500;
    plstyl(2, mark, space);
\end{verbatim}

To return to a continuous line, just call \code{plstyl} with first
argument set to zero.  You can use \code{pllsty} to choose between 8
different predefined styles.\refill

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node Fill Pattern, Characters, Line Attributes, Advanced Use
\message{Fill}
\section{Setting the Area Fill Pattern}
\cindex{Fill pattern}

The routine \rou{plpat} can be used to set the area fill pattern.  The
pattern consists of 1 or 2 sets of parallel lines with specified
inclinations and spacings.  The arguments to this routine are the number
of sets to use (1 or 2) followed by two pointers to integer arrays (of 1
or 2 elements) specifying the inclinations in tenths of a degree and the
spacing in micrometers (the inclination should be between -900 and 900).
Thus to specify an area fill pattern consisting of horizontal lines
spaced 2\, mm apart use:\refill

\begin{verbatim}
    *inc = 0;
    *del = 2000;
    plpat(1, inc, del);
\end{verbatim}

To set up a symmetrical crosshatch pattern with lines directed 30 degrees
above and below the horizontal and spaced 1.5\, mm apart use:\refill

\begin{verbatim}
    *inc = 300;
    *(inc+1) = -300;
    *del = 1500;
    *(del+1) = 1500;
    plpat(2, inc, del);
\end{verbatim}

The routine \rou{plpsty} can be used to select from 1 of 8 predefined
patterns.\refill

The area fill routines also use the current line style, width and
colors to give a virtually infinite number of different patterns.

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node Characters, Escape Sequences, Characters, Advanced Use
\message{Characters}
\section{Setting Character and Symbol Attributes}
\cindex{Character attributes}
\cindex{Symbol attributes}

There are two character sets included with PLplot.  These are known as
the standard and extended character sets respectively.  The standard
character set is a subset of the extended set.  It contains 177
characters including the ascii characters in a normal style font, the
greek alphabet and several plotter symbols.  The extended character set
contains almost 1000 characters, including four font styles, and several
math, musical and plotter symbols.

The standard character set is loaded into memory automatically when
\code{plstar} or \code{plstart} is called.  The extended character set
is loaded by calling \rou{plfontld}.  The extended character set
requires about 50 kbytes of memory, versus about 5 kbytes for the
standard set.  \code{plfontld} can be used to switch between the
extended and standard sets (one set is unloaded before the next is
loaded).  \code{plfontld} can be called before \code{plstar}.\refill

When the extended character set is loaded there are four different font
styles to choose from.  In this case, the routine \rou{plfont} sets up the
default font for all character strings.  It may be overridden for any
portion of a string by using an escape sequence within the text, as
described below.  This routine has no effect when the standard font set is
loaded.  The default font (1) is simple and fastest to draw; the others are
useful for presentation plots on a high-resolution device.

The font codes are interpreted as follows:
\begin{itemize}
   \item\code{font = 1}: normal simple font
   \item\code{font = 2}: roman font
   \item\code{font = 3}: italic font
   \item\code{font = 4}: script font
\end{itemize}

The routine \rou{plschr} is used to set up the size of subsequent
characters drawn.  The actual height of a character is the product of
the default character size and a scaling factor.  If no call is made to
\code{plschr}, the default character size is set up depending on the
number of subpages defined in the call to \code{plstar} or
\code{plstart}, and the scale is set to 1.0.  Under normal
circumstances, it is recommended that the user does not alter the
default height, but simply use the scale parameter.  This can be done by
calling \code{plschr} with \code{def = 0.0} and \code{scale} set to the
desired multiple of the default height.  If the default height is to be
changed, \code{def} is set to the new default height in millimeters, and
the new character height is again set to \code{def} multiplied by
\code{scale}.\refill

The routine \rou{plssym} sets up the size of all subsequent symbols
drawn by calls to \code{plpoin} and \code{plsym}.  It operates
analogously to \code{plschr} as described above.\refill

The lengths of major and minor ticks on the axes are set up by the
routines \rou{plsmaj} and \rou{plsmin}.

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node Escape Sequences, 3-d Plots, Characters, Advanced Use
\message{Escape}
\section{Escape Sequences in Text}
\cindex{Escape sequences}

The routines which draw text all allow you to include escape sequences
in the text to be plotted.  These are character sequences that are
interpreted as instructions to change fonts, draw superscripts and
subscripts, draw non-ASCII (e.g. Greek), and so on.  All escape
sequences start with a number symbol (\code{#}).\refill

The following escape sequences are defined:
\begin{itemize}
   \item \code{#u}: move up to the superscript position
    (ended with \code{#d})
   \item \code{#d}: move down to subscript position
    (ended with \code{#u})
   \item \code{#b}: backspace (to allow overprinting)
   \item \code{##}: number symbol
   \item \code{#+}: toggle overline mode
   \item \code{#-}: toggle underline mode
   \item \code{#gx}: Greek letter corresponding to Roman letter \code{x}
                     (see below)
   \item \code{#fn}: switch to normal font
   \item \code{#fr}: switch to Roman font
   \item \code{#fi}: switch to italic font
   \item \code{#fs}: switch to script font
   \item \code{#(nnn)}: Hershey character nnn (1 to 4 decimal digits)
\end{itemize}

Sections of text can have an underline or overline appended.  For
example, the string
\begin{tex}
\[
{\rm\overline{S}(\underline{freq})}
\]
\end{tex}
\begin{ifinfo}
	_
	S(freq)
	  ----
\end{ifinfo}
is obtained by specifying \code{"#+S#+(#-freq#-)"}.

Greek letters are obtained by \code{#g} followed by a Roman letter.
Table \ref{greek} shows how these letters map into Greek
characters.\refill
\noinput{table}

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node 3-d Plots, Contour Plots, Escape Sequences, Advanced Use
\message{3}
\section{Three Dimensional Surface Plots}
\cindex{3-d plots}
\cindex{Surface plots}

PLplot includes routines that will represent a single-valued function of
two variables as a surface.  In this section, we shall assume that the
function to be plotted is \code{Z[X][Y]}, where \code{Z} represents the
dependent variable and \code{X} and \code{Y} represent the independent
variables.\refill

As usual, we would like to refer to a three dimensional point \code{(X,
Y, Z)} in terms of some meaningful user-specified coordinate system.
These are called \emph{three-dimensional world coordinates}.  We need to
specify the ranges of these coordinates, so that the entire surface is
contained within the cuboid defined by
\code{xmin}<\code{x}<\code{xmax}, \code{ymin}<\code{y}<\code{ymax}
and \code{zmin}<\code{z}<\code{zmax}.  Typically, we shall want to
view the surface from a variety of angles, and to facilitate this, a
two-stage mapping of the enclosing cuboid is performed.  Firstly, it is
mapped into another cuboid called the \emph{normalized box} whose size
must also be specified by the user, and secondly this normalized box is
viewed from a particular azimuth and elevation so that it can be
projected onto the two-dimensional window.\refill

This two-stage transformation process allows considerable flexibility in
specifying how the surface is depicted.  The lengths of the sides of the
normalized box are independent of the world coordinate ranges of each of
the variables, making it possible to use ``reasonable'' viewing angles
even if the ranges of the world coordinates on the axes are very
different.  The size of the normalized box is determined essentially by
the size of the two-dimensional window into which it is to be mapped.
The normalized box is centered about the origin in the \code{x} and \code{y}
directions, but rests on the plane \code{z = 0}.  It is viewed by an
observer located at altitude \code{alt} and azimuth \code{az}, where
both angles are measured in degrees.  The altitude should be restricted
to the range zero to ninety degrees for proper operation, and represents
the viewing angle above the xy plane.  The azimuth is defined so that
when \code{az = 0}, the observer sees the xz plane face on, and as the
angle is increased, the observer moves clockwise around the box as
viewed from above the xy plane.  The azimuth can take on any
value.\refill 

The first step in drawing a surface plot is to decide on the size of the
two-dimensional window and the normalized box.  For example, we could
choose the normalized box to have sides of length

\begin{verbatim}
    basex = 2.0;
    basey = 4.0;
    height = 3.0;
\end{verbatim}

\begin{tex} 
A reasonable range for the x coordinate of the two-dimensional window
is -2.5 to +2.5, since the length of the diagonal across the base of the
normalized box is $\sqrt{2^2+4^2} = 2\sqrt{5}$,\end{tex}
\begin{ifinfo}
A reasonable range for the x coordinate of the two-dimensional window
is -2.5 to +2.5, since the length of the diagonal across the base of the
normalized box is sqrt(2^2+4^2) = 2 sqrt(5),\end{ifinfo}
which fits into this coordinate range.  A reasonable range for the y
coordinate of the two dimensional window in this case is -2.5 to +4, as
the the projection of the normalized box lies in this range for the
allowed range of viewing angles.\refill

The routine \rou{plwind} or \rou{plenv} is used in the usual way to
establish the size of the two-dimensional window.  The routine
\rou{plw3d} must then be called to establish the range of the three
dimensional world coordinates, the size of the normalized box and the
viewing angles.  After calling \code{plw3d}, the actual surface is drawn
by a call to \rou{plot3d}.\refill

\message{foo}
For example, if the three-dimensional world-coordinate ranges are
\begin{tex}
$-10.0\le\code{x}\le 10.0$, $-3.0\le\code{y}\le +7.0$ and 
$0.0\le\code{z}\le 8.0$, 
\end{tex}
\begin{ifinfo}
-10.0 <= \code{x} <=  10.0, -3.0 <= \code{y} <=  +7.0 and
0.0 <= \code{z} <=  8.0, 
\end{ifinfo}
we could use the following statements:\refill

\begin{verbatim}
    xmin2d = -2.5;
    xmax2d =  2.5;
    ymin2d = -2.5;
    ymax2d =  4.0;
    plenv(xmin2d, xmax2d, ymin2d, ymax2d, 0, -2);
    basex = 2.0;
    basey = 4.0;
    height = 3.0;
    xmin = -10.0;
    xmax = 10.0;
    ymin = -3.0;
    ymax = 7.0;
    zmin = 0.0;
    zmax = 8.0;
    alt = 45.0;
    az = 30.0;
    side = 1;
    plw3d(basex, basey, height, xmin, xmax, ymin, ymax, zmin, zmax, alt, az);
    plot3d(x, y, z, nx, ny, opt, side);
\end{verbatim}

The values of the function are stored in a two-dimensional array
\code{z[][]} where the array element \code{z[i][j]} contains the value
of the function at the point x_i, y_j.  (The two-dimensional array
\code{z} is a vectored array instead of a fixed size array.  \code{z}
points to an array of pointers which each point to a rwo of the matrix.)
Note that the values of the independent variables x_i and y_j do not
need to be equally spaced, but they must lie on a rectangular grid.
Thus two further arrays \code{x[nx]} and \code{y[ny]} are required as
arguments to \code{plot3d} to specify the values of the independent
variables.  The values in the arrays x and y must be strictly increasing
with the index.  The argument \code{opt} specifies how the surface is
outlined.  If \code{opt = 1}, a line is drawn representing z as a
function of x for each value of y, if \code{opt = 2}, a line is drawn
representing z as a function of y for each value of x, and if \code{opt
= 3}, a net of lines is drawn.  The first two options may be preferable
if one of the independent variables is to be regarded as a parameter,
whilst the third is better for getting an overall picture of the
surface.  If side is equal to one then sides are drawn on the figure so
that the graph doesn't appear to float.\refill

The routine \rou{plmesh} is similar to \code{plot3d}, except that it is
used for drawing mesh plots.  Mesh plots allow you to see both the top
and bottom sides of a surface mesh, while 3D plots allow you to see the
top side only (like looking at a solid object).  The side option is not
available with \code{plmesh.}\refill

Labelling a three-dimensional or mesh plot is somewhat more complicated
than a two dimensional plot due to the need for skewing the characters
in the label so that they are parallel to the coordinate axes.  The
routine \rou{plbox3} thus combines the functions of box drawing and
labelling.

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node Contour plots, , 3-d Plots, Advanced Use
\message{Contour}
\section{Contour and Shade Plots}
\cindex{Contour plots}
\cindex{Shade plots}

Several routines are available in PLplot which perform a contour or
shade plot of data stored in a two-dimensional array.  The contourer
uses a contour following algorithm is used, so that it is possible to
use non-continuous line styles.  Further, one may specify arbitrary
coordinate mappings from array indices to world coordinates, such as for
contours in a polar coordinate system.  In this case it is best to draw
the distinction between a C and Fortran language caller, so these are
handled in turn.

\begin{menu}
* Contour Plots - C::		Contour plot C language bindings
* Contour Plots - Fortran::	Contour plot Fortran language bindings
\end{menu}

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node Contour Plots - C, Contour Plots - Fortran, Contour Plots, Advanced Use
\message{Contour}
\subsection{Contour Plots from C}
\cindex{Contour Plots -- C}

There are two routines callable from C for plotting contours,
\rou{plcont} and \rou{plconf}.  Routine \code{plcont} has the
form:\refill

\name{plcont(z, nx, ny, kx, lx, ky, ly, clevel, nlevel, pltr)}

where \code{z} is the two-dimensional array of size
\code{nx} by \code{ny} containing samples of the function to be
contoured.  (\code{z} is a vectored two-dimensional array as described
in the previous section.  It is \emph{not} a fixed-size two-dimensional
array.) The parameters \code{kx}, \code{lx}, \code{ky} and \code{ly}
specify the portion of \code{z} that is to be considered.  The array
\code{clevel} of length \code{nlevel} is a list of the desired contour
levels.  Routine \code{plconf} has the form:\refill

\name{plconf(z, nx, ny, kx, lx, ky, ly, clevel, nlevel, pltr, xg, yg)}

with all arguments identical to those in \code{plcont} except for the
pointers to transformation arrays \code{xg} and \code{yg}.  These are
used as input to the transformation function \code{pltr}.\refill

The path of each contour is initially computed in terms of the values of
the array indicies which range from \code{0} to \code{nx-1} in the first
index and from \code{0} to \code{ny-1} in the second index.  Before
these can be drawn in the current window (\pxref{Windows}), it is
necessary to convert from these array indicies into world coordinates.
This is done by passing a pointer to a user-defined function to
\code{plcont} (the case for \code{plconf} is slightly different and
discussed below).  This function pointer is the last argument
\code{pltr}.  This function must be declared as type \code{void} in the
module which calls \code{plcont}.  This transformation function must
have the parameter list:\refill

\name{void pltr(x, y, tx, ty);}

where \code{(x, y)} is the point through which the contour runs
expressed in terms of array indicies, and \code{(tx, ty)} are pointers
to float variables which are the world coordinates of the point which
corresponds to these indicies.\refill

Often, the transformation between array indices and world coordinates can be
expressed as a linear transformation.  A routine is provided within the
library which can be passed to \code{plcont} as \code{pltr}.  This
transformation routine is:\refill

\begin{verbatim}
#include "plplot.h"

#ifdef PLSTDC
void 
xform(PLFLT x, PLFLT y, PLFLT * tx, PLFLT * ty)
#else
void 
xform(x, y, tx, ty)
PLFLT x, y, *tx, *ty;
#endif
{
    *tx = tr[0] * x + tr[1] * y + tr[2];
    *ty = tr[3] * x + tr[4] * y + tr[5];
}
\end{verbatim}

and should be compiled as part of the user's code (it is \emph{not}
normally linked in with the PLplot library since the \code{tr} data
array is unspecified).\refill

Thus by setting up the values in the array \code{tr[]}, we can apply an
arbitrary translation, rotation and/or shear to the array before drawing
out the contours.  By defining other transformation subroutines, it is
possible to draw contours wrapped around polar grids etc.  If no
transformation is required, you can simply set \code{tr[0] = tr[4] =
1.}, with other entries set to 0..  Alternately you can pass the
built-in function \code{pltr0} to \code{plcont}; this function merely
sets \code{*tx} to \code{x} and \code{*ty} to {y}, resulting in no net
transformation.\refill

As an example in setting up \code{tr[]}, suppose that the array \code{z}
is of size 21 by 41 and contains the values of the function
\code{z[x][y]}, where \code{x} ranges from 0.0 to 4.0 and \code{y}
ranges from -8.0 to 8.0.  Furthermore, let us also suppose that the
window (as defined using
\code{plenv} or \code{plwind}) covers this range of world coordinates.
Since we wish the index (0, 0) in array \code{z} to map to (0.0, -8.0)
and the index (20, 40) to map to (4.0, 8.0), and for there to be no skew
in the axes, we should choose elements of \code{tr[]} so that\refill
\begin{tex}
\[
   \begin{array}{l@{\; = \;}l}
   tx & 0.2x \\
   ty & 0.4y - 8.
   \end{array}
\]
\end{tex}
\begin{ifinfo}

	(omitted in info version)

\end{ifinfo}
and so \code{tr[0] = 0.2}, \code{tr[1] = 0.0}, \code{tr[2] = 0.0}, 
\code{tr[3] = 0.0}, \code{tr[4] = 0.4}, \code{tr[5] = -8.}.\refill

For routine \code{plconf}, the user must pass pointers to transformation
arrays as well as the function pointer.  The use of transformation
arrays is generally the most convenient and flexible way to map
coordinates, since the mapping function (which only handles
interpolation) need not change from one problem to the next.  In this
case there are two built-in transformation functions to assist the user;
these are:\refill

\name{void pltr1(x, y, tx, ty, xg, yg, nx, ny);}
\name{void pltr2(x, y, tx, ty, xg, yg, nx, ny);}

where \code{(xg, yg)} are pointers to the transformation arrays and
\code{(nx, ny)} are the number of gridpoints in each dimension.  These
functions handle all necessary interpolations to calculate coordinate
values between grid points.  The transformation arrays passed to
\code{pltr1} must be functions of a single variable only (\code{xg[i],
yg[i]}), while those passed to \code{pltr2} must be functions of two
variables (\code{xg[i, j], yg[i, j]}).  This is further discussed in the
following section.\refill

\c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\node Contour Plots - Fortran, , Contour Plots - C, Advanced Use
\message{Contour}
\subsection{Contour Plots from Fortran}
\cindex{Contour Plots -- Fortran}

The routines mentioned above are not recommended for use directly from
Fortran due to the need to pass a function pointer.  That is, the
transformation function is written in C and can not generally be changed
by the user.  The call for routine \code{plcont} from Fortran is
then:\refill

\name{call plcont(z, nx, ny, kx, lx, ky, ly, clevel, nlevel, tr)} 

where \code{tr} is a 6 element array with the coefficients for the
transformation function \code{xform} given above and all other arguments
are the same as in the call from C (see above discussion of
\code{plcont}).\refill

The three routines recommended for use from Fortran are \rou{plcon0},
\rou{plcon1}, and \rou{plcon2}.  These routines are similar to existing
commercial plot package contour plotters in that they offer successively
higher complexity, with \code{plcon0} utilizing no transformation
arrays, while those used by \code{plcon1} and \code{plcon2} are one and
two dimensional, respectively.  The call syntax for each is\refill

\name{call plcon0(z, nx, ny, kx, lx, ky, ly, clevel, nlevel)} 
\name{call plcon1(z, nx, ny, kx, lx, ky, ly, clevel, nlevel, xg1, yg1)} 
\name{call plcon2(z, nx, ny, kx, lx, ky, ly, clevel, nlevel, xg2, yg2)} 

The \code{plcon0} routine is implemented via a call to \code{plcont}
with a very simple (identity) transformation function, while
\code{plcon1} and \code{plcon2} use interpolating transformation
functions in a call to \code{plconf}.\refill

The transformation arrays are used by these routines to specify a
mapping between the computational coordinate system and the physical
one.  For example, the transformation to polar coordinates might look
like:\refill

\begin{verbatim}
    do i = 1, NX
        do j = 1, NY
            xg(i, j) = r(i) * cos( theta(j) )
            yg(i, j) = r(i) * sin( theta(j) )
        enddo
    enddo
\end{verbatim}

\c assuming the user had already set up arrays \code{r} and \code{theta} to
\c specify the $(r, \theta)$ values at the gridpoints in his system.  For this
\c example, it is recommended that the user add an additional cell in theta
\c such that \code{xg(i, NY+1) = xg(i, 1)} and \code{yg(i, NY+1) = yg(i, 1)} so
\c that the contours show the proper periodic behavior in $\theta$ (see also
example program 9).\refill

The transformation function not only specifies the transformation at grid
points, but also at intermediate locations, via linear interpolation.  For
example, in the \code{pltr1} transformation function used by \code{plcon1}, 
the 1-d interpolation to get \code{tx} as a function of \code{x} 
looks like (in C):\refill

\begin{verbatim}
    ul = (PLINT)x;
    ur = ul + 1;
    du = x - ul;

    xl = *(xg+ul);
    xr = *(xg+ur);

    *tx = xl * (1-du)  +  xr * du;
\end{verbatim}

while in Fortran this might look like:

\begin{verbatim}
    lxl = x
    lxr = lxl + 1
    dx = x - lxl

    xl = xg(lxl)
    xr = xg(lxr)

    tx = xl * (1-dx)  +  xr * dx
\end{verbatim}
