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.
The routines plvpor
, plsvpa
, plvasp
, plvpas
, and
plvsta
may be used to specify the limits of the viewport within the
current subpage. The plvpor
routine specifies the viewport limits
in normalized subpage coordinates. The plsvpa
routine (often used in
conjunction with the plgspa
routine which returns the physical
limits of the current subpage) specifies the viewport limits in
physical coordinates. The routine plvasp
specifies the largest
viewport with the given aspect ratio that fits in the current subpage
while allowing for a standard margins on each side of the viewport.
The routine plvpas
specifies the largest viewport with the given
aspect ratio that fits in a region that is specified by normalized
subpage coordinates as with plvpor
. (The routine plvpas
is functionally equivalent to plvpor
when the specified aspect ratio
is set to zero.) The plvsta
routine specifies the largest viewport
that fits in the current subpage while allowing for a standard margins
on each side of the viewport. This standard viewport is that used by
plenv
(See the section called “Setting up a Standard Window”).
The routine plwind
is used to map the world coordinate
rectangle into the viewport rectangle. 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 viewport.
The routine plbox
is used to specify how much (if any) of
the frame is drawn around the viewport and to control the positions of
the axis subdivisions and numeric labels. In addition, non-default
lengths of major and minor ticks on the axes may be set up by calls to
the routines plsmaj
and plsmin
.
The routine pllab
is used to specify 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.
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.