There is a whole hierarchy of coordinate systems associated with
any PLplot graph. At the lowest level a device provides a view surface
(coordinates in mm's) which can be a terminal screen or a sheet of paper
in the output device. `plinit`

or `plstar`

(or `plstart`

) makes that
device view surface accessible as a page or divided up into sub-pages
(see `plssub`

) which are accessed with `pladv`

. Before a graph can be
drawn for a subpage, the program must call appropriate routines in
PLplot to define the viewport for the subpage and a window for the
viewport. A viewport is a rectangular region of the
*subpage* which is specified in normalized subpage
coordinates or millimetres. A window is a rectangular region of
world-coordinate space which is mapped directly to its viewport. (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 *world
coordinates*, and may have any floating-point value
representable by the computer.)

Although the usual choice is to have one viewport per subpage, and one window per viewport, each subpage can have more than one (possibly overlapping) viewport defined, and each viewport can have more than one window (more than one set of world coordinates) defined.

After defining the view surface and subpage with the appropriate
call to `plinit`

or `plstar`

(or `plstart`

) and a call to `pladv`

it
is necessary to define the portion of this subpage which is to be used
for plotting the graph (the viewport). All lines and symbols (except
for labels drawn by `plbox`

, `plmtex`

and `pllab`

) are clipped at the
viewport boundaries.

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 using `plinit`

or by setting
`nx = 1` and `ny = 1` in `plstar`

or `plstart`

), and use one of the viewport specification subroutines
below to place the plot in the desired position on the page.

There are four methods for specifying the viewport size, using the
subroutines `plvpor`

, `plsvpa`

, `plvasp`

, and `plvpas`

which are
called like this:

plvpor(xmin, xmax, ymin, ymax); plsvpa(xmin, xmax, ymin, ymax); plvasp(aspect); plvpas(xmin, xmax, ymin, ymax, aspect); |

where in the case of `plvpor`

and `plvpas`

, the arguments are given
in *normalized subpage coordinates* which are
defined to run from 0.0 to 1.0 along each edge of the subpage. Thus
for example,

plvpor(0.0, 0.5, 0.5, 1.0); |

uses the top left quarter of the current subpage.

In order to get a graph of known physical size, the routine `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.

The routine `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
`aspect`). It also allocates space on the left and
top of the viewport for labels.

The routine `plvpas`

gives the largest viewport with the given aspect
ratio that fits in the specified region (specified with normalized
subpage coordinates, as with `plvpor`

). This routine is functionally
equivalent to `plvpor`

when a "natural" aspect ratio is
chosen (done by setting `aspect` to 0.0). Unlike
`plvasp`

, this routine reserves no extra space at the edges for
labels.

To help the user call `plsvpa`

correctly, the routine `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:

plgspa(xmin, xmax, ymin, ymax); plsvpa(10.0, xmax-xmin-10.0, 10.0, ymax-ymin-10.0); |

A further routine `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 `plenv`

(See the Section called *Setting up a Standard Window*).

Another way to get a specified aspect ratio is via the routine
`plsasp`

[not!.. fix this], which sets the global
aspect ratio and must be called prior to `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 `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.

The window must be defined after the viewport in order to map the
world coordinate rectangle into the viewport rectangle. The routine
`plwind`

is used to specify the rectangle in world-coordinate space.
For example, if we wish to plot a graph showing the collector current
I_{C} as a function of the collector to emitter
voltage V_{CE} for a transistor where 0 ≤
I_{C} ≤ 10.0 mA and 0 ≤
V_{CE} ≤ 12.0 V, we would call the
function `plwind`

as follows:

plwind(0.0, 12.0, 0.0, 10.0); |

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

The routine `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 `plwind`

.
This is done using the following statement

plbox("bcnst", 0.0, 0, "bcnstv", 0.0, 0); |

The lengths of major and minor ticks on the axes are set up by the
routines `plsmaj`

and `plsmin`

.

Another routine `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). `pllab`

actually calls the more general
routine `plmtex`

which can be used for plotting labels at any point
relative to the viewport. For our example, we may use

pllab("V#dCE#u (Volts)", "I#dC#u (mA)", "TRANSISTOR CHARACTERISTICS"); |

Note that `#d` and `#u` are escape
sequences (see the Section called *Escape sequences in text*) which allow
subscripts and superscripts to be used in text. They are described
more fully later in this chapter.

The appearance of axis labels may be further altered by auxiliary
calls to `plprec`

, `plschr`

, `plsxax`

, `plsyax`

, and `plszax`

. The
routine `plprec`

is used to set the number of decimal places
precision for axis labels, while `plschr`

modifies the heights of
characters used for the axis and graph labels. Routines `plsxax`

,
`plsyax`

, and `plszax`

are used to modify the
`digmax` setting for each axis, which affects how
floating point labels are formatted.

The `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.

For example, let's suppose that we have set `digmax =
5` via `plsyax`

, and for our plot a label is generated at
`y = 0.0000478`. In this case the actual field
width is longer than `digmax`, so PLplot switches to
floating point. In this representation, the label is printed as
simply 4.78 with the 10^{-5} exponent placed
separately.

The determination of maximum length (i.e. `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 (`digfix`) may not always match the user's
specification (via `digmax`). However, it will
always be true that `digfix ≤ digmax`. The
PLplot defaults are set up such that good results are usually
obtained without user intervention.

Finally, after the call to `plbox`

, the user may call routines
`plgxax`

, `plgyax`

, or `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 `plgyax`

to
get the value of `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 `digits` value for each axis for the
current plot is not correct until *after* the call
to `plbox`

is complete.

Having to call `pladv`

, `plvpor`

, `plwind`

and `plbox`

is excessively
cumbersome for drawing simple graphs. Subroutine `plenv`

combines
all four of these in one subroutine, using the standard viewport, and
a limited subset of the capabilities of `plbox`

. For example, the
graph described above could be initiated by the call:

plenv(0.0, 12.0, 0.0, 10.0, 0, 0); |

which is equivalent to the following series of calls:

pladv(0); plvsta(); plwind(0.0, 12.0, 0.0, 10.0); plbox("bcnst", 0.0, 0, "bcnstv", 0.0, 0); |