PGENV, but in order to obtain complete control of positioning and scaling, it is necessary to understand the concepts of the View Surface, the Window, and the Viewport, and two coordinate systems: World Coordinates and Device Coordinates.
A simple PGPLOT picture might be a two-dimensional graph showing the dependence of one variable on another. A typical graph has data points, represented by error bars or special markers such as dots or diamonds, possibly connected by lines, or perhaps plotted on the same scale as a theoretical model drawn as a smooth curve. The graph must be labeled with two axes to indicate the coordinate scales.
The programmer must describe to PGPLOT the various elements of the
graph in terms of rectangular Cartesian coordinates. The only
limitation on the coordinates is that they be represented as
otherwise we are totally free to choose the meaning of the
coordinates. For example, in a graph showing the temporal variation of
a radio source, the abscissa (x-coordinate) might be Epoch (in
years) and the ordinate (y-coordinate) Flux Density (in Jy).
In accordance with common practice in graphics programming, these coordinates, chosen by the programmer, are termed world coordinates. PGPLOT maps a selected rectangular region of the world-coordinate space (termed the window) onto a specified rectangle (termed the viewport) on the view surface (the screen of an interactive display or a sheet of paper on a hardcopy plotter). The program must make calls to PGPLOT routines to define both the window and the viewport. For complete descriptions of the routines and their arguments, refer to Appendix A.
PGBEG. For example, to create a plot file for a PostScript printer:
INTEGER PGBEG IER = PGBEG (0, 'plotfile.ps/PS', 1, 1)Equally important, when all plotting has been completed, it is necessary to call
PGENDto flush any pending plot requests:
CALL PGENDNote that only one device can be used at a time. If
PGBEGis called while a plot is in progress, the old plot is closed and a new one is begun.
PGBEG the program has access to a view
surface. For workstations, it is a window on the workstation
screen. For interactive devices, this is the full screen of the
device. For hardcopy devices, it is a standard page, usually about 10
inches (width) by 8 inches (height) on a device used in ``landscape''
mode (e.g, device type
/QMS), or 8
inches by 10 inches on a device used in ``portrait'' mode (e.g.,
On some devices, it is possible to plot on a larger or smaller piece
of paper than the standard page; see the description of routine
PGPAP, which must be called immediately after
PGBEG to change the size of the view surface. The
different devices differ not only in the size of the view surface, but
also in its aspect ratio (height/width).
can be called to ensure that a plot has the same aspect ratio no
matter what device it is plotted on.
After completing a graph, it is possible to advance to a new page to
start a new graph (without closing the plot file) by calling
CALL PGPAGEThis clears the screen on interactive devices, or gives a new piece of paper on hardcopy devices. It does not change the viewport or window.
The last two arguments of
NY) can be used to subdivide the view surface into
smaller pieces called panels, each of which can then be used
separately. The view-surface is divided into
NY (vertically) panels. When the view
surface has been subdivided in this way,
PGPAGE moves the
plotter to the next panel, and only clears the screen or loads a new
piece of paper if there are no panels left on the current page.
In addition to selecting the view surface,
defines a default viewport and window. It is good practice, however,
to define the viewport and window explicitly as described below.
PGSVP defines the viewport in a device-independent
manner, using a coordinate system whose coordinates run from 0 to 1 in
both x and y. This coordinate system is called
normalized device coordinate space. For example, if we wish to
divide the view surface into four quadrants and map a different plot
onto each quadrant, we can define a new viewport before starting each
PGSVP has the format:
CALL PGSVP (XMIN, XMAX, YMIN, YMAX)For example, to map the viewport onto the upper left quadrant of the view surface:
CALL PGSVP (0.0, 0.5, 0.5, 1.0)(Note that this does not leave room around the edge of the viewport for annotation.)
PGVSIZ defines the viewport in absolute coordinates (inches); it
should only be used when it is known how big the view surface is and a
definite plot scale is required. The arguments are the same as for
PGSVP, but measured in inches from the bottom left corner of the
view surface. For example:
CALL PGVSIZ (1.5, 9.5, 1.5, 6.5)defines a rectangular viewport 8 by 5 inches, offset 1.5 inches from the bottom and left edges of the view surface.
PGVSTD defines a standard viewport, the size of which
depends on the particular device being used, and on the current
character size (it uses the whole view surface excluding a margin of
four character heights all around):
CALL PGVSTDThis is the default viewport set up by
Note that the viewport must be defined before calling any routines that would actually generate a display. The viewport may, however, be changed at any time: this will affect the appearance of objects drawn later in the program.
PGSWIN, whose arguments specify the world-coordinate limits of the window along each coordinate axis, e.g.
CALL PGSWIN (1975.0, 1984.0, 5.0, 20.0)specifies that the x-axis (epoch) is going to run (left to right) from 1975 to 1984, and the y-axis (flux density) is going to run (bottom to top) from 5 to 20~Jy. Note that the arguments are floating-point numbers (Fortran
REALvariables or constants), and require decimal points. If the order of either the x pair or the y pair is reversed, the corresponding axis will point in the opposite sense, \ie, right to left for x or top to bottom for y. PGPLOT uses the window specification to construct a mapping that causes the image of the window to coincide with the viewport on the view surface. Furthermore, PGPLOT ``clips'' lines so that only those portions of objects that lie within the window are displayed on the view surface.
Like the viewport, the window must be defined before drawing any
objects. The window can be defined either before or after the
viewport: the effect will be the same. The default window, set up by
PGBEG, has x limits 0.0--1.0 and y limits
If the ratio of the sides of the window does not equal the ratio of
the sides of the viewport, the mapping of the world coordinates onto
the view surface results in an image whose shape is compressed in
either x or y. One way to avoid this compression is to
carefully choose the viewport to have the same aspect ratio as the
PGWNAD can do this: it defines the
window and simultaneously adjusts the viewport to have the same aspect
ratio as the window. The new viewport is the largest that can fit
inside the old one, and is centered in the old one.
PGBOX. For our sample graph, the call might be:
CALL PGBOX ('BCTN', 0.0, 0, 'BCNST', 0.0, 0)Another routine,
PGLAB, provides text labels for the bottom, left hand side, and top of the viewport:
CALL PGLAB ('Epoch', 'Flux Density (Jy)', 'Variation of 3C345 at 10.7 GHz')The first two arguments provide explanations for the two axes; the third provides a title for the whole plot. Note that unlike all the other plotting routines, the lines and characters drawn by
PGLABare not clipped at the boundaries of the window.
PGLABactually calls a more general routine,
PGMTXT, which can be used for plotting labels at any point relative to the viewport.
The amount of space needed outside the viewport for annotation depends
on the exact options specified in
PGBOX; usually four
character heights will be sufficient, and this is the amount allowed
when the standard viewport (created by
used. The character height can be changed by using routine
PGBOXis excessively cumbersome for drawing simple graphs. Routine
PGENV(for PGplot ENVironment) combines all four of these in one subroutine, using the standard viewport, and a limited set of the capabilities of
PGBOX. For example, the graph described above could be initiated by the following call:
CALL PGENV (1975.0, 1984.0, 5.0, 20.0, 0, 0)which is equivalent to the following series of calls:
CALL PGPAGE CALL PGVSTD CALL PGSWIN (1975.0, 1984.0, 5.0, 20.0) CALL PGBOX ('BCNST', 0.0, 0, 'BCNST', 0.0, 0)
PGENVuses the standard viewport. The first four arguments define the world-coordinate limits of the window. The fifth argument can be 0 or 1; if it is 1,
PGSWINso that the plot has equal scales in x and y. The sixth argument controls the amount of annotation.