1. Introduction

1.1 PGPLOT

PGPLOT is a Fortran subroutine package for drawing simple scientific graphs on various graphics display devices. It was originally developed for use with astronomical data reduction programs in the Caltech Astronomy department.

This manual is intended for the Fortran programmer who wishes to write a program generating graphical output. For most applications, the program can be device-independent, and the output can be directed to the appropriate device at run time. The output device is described by a ``device specification,'' discussed below. The programmer can build a specific device specification into the program, but it is better to make this a parameter which the user of the program can supply.

All the examples in this manual use standard Fortran-77. PGPLOT itself is written mostly in standard Fortran-77, with a few non-standard, system-dependent subroutines.

1.2 This Manual

This manual is intended both as a tutorial introduction to PGPLOT and as a reference manual. The remainder of this chapter describes some fundamentals: how to include the PGPLOT library in your program, and the types of graphic devices that PGPLOT can use.

Chapter 2 is tutorial: it presents a Fortran program for drawing a graph using the minimum number of PGPLOT subroutines, and explains what each of these subroutines does. After reading this chapter, you should be able to write your own PGPLOT program, although it may be helpful to refer to the individual subroutine descriptions in Appendix A.

The basic features of PGPLOT are introduced in Chapters 3, 4, and 5. Chapter 3 explains the positioning and scaling of plots on the page, Chapter 4 describes the basic (``primitive'') routines for drawing lines, writing text, drawing graph markers, and shading areas, and Chapter 5 describes the routines for changing the ``attributes'' of these primitives: color, line-style, line-width, text font, etc.

Chapter 6 describes some ``high level'' routines that use the primitive routines to build up more complicated pictures: e.g., function plots, histograms, bar charts, and contour maps.

Chapter 7 describes PGPLOT's capabilities for ``interactive'' graphics, whereby the user of the PGPLOT program can control its action with a cursor, joystick, mouse, etc.

There are seven appendices. Appendix A is a list of all the PGPLOT routines, with detailed instructions for their use. Appendix B shows the complete set of PGPLOT characters and symbols that can be used for annotating graphs. Appendix C is intended for those who want to call PGPLOT subroutines from a program written in C. Appendix D gives details of the devices supported by PGPLOT. Appendix E provides instructions for programmers who want to extend PGPLOT to support other devices. Appendix F provides installation instructions, and Appendix G gives some hints for porting PGPLOT to a new operating system.

1.3 Using PGPLOT

In order to use PGPLOT subroutines, you will need to link your program with the graphics subroutine library.

1.3.1 UNIX

The following assumes that the PGPLOT library libpgplot.a has been installed in a standard location where the loader can find it. To compile, link, and run a graphics program example.f:

f77 -o example example.f -lpgplot
example

In some installations, it may be necessary to include other libraries, such as the Xwindow library, and specify a directory to search for the PGPLOT library; e.g.

f77 -o example example.f -L /usr/local/pgplot -lpgplot -lX11
example

1.3.2 VMS

On most VMS computers, the graphics subroutine library is scanned automatically by the LINK command, so the following sequence of instructions suffices to compile, link, and run a graphics program EXAMPLE.FOR:

$ FORTRAN EXAMPLE
$ LINK EXAMPLE
$ RUN EXAMPLE

On other VMS computers, the automatic search of the graphics library may not occur. You will then need to include the graphics library explicitly by using a LINK commands like the following:

$ LINK EXAMPLE,PGPLOT_DIR:GRPSHR/LIB

The PGPLOT subroutines are not included in your .EXE file, but are fetched from a shareable image when you execute the RUN command. This makes the .EXE file much smaller, and means that the program need not be relinked when changes are made to the graphics subroutines; but the .EXE file can only be run on a machine that has a copy of the shareable image and is running a compatible version of VMS. To make a transportable .EXE file, use the non-shared library as follows (the XLIB library is not required if your version of PGPLOT does not include an X-window driver):

$ LINK EXAMPLE,PGPLOT_DIR:GRPCKG/LIB,SYS$INPUT:/OPT
SYS$SHARE:DECW$XLIBSHR.EXE/SHARE
[ctrl-Z]
$

1.4 Graphics Devices

Graphics devices fall into two classes: devices which produce a hardcopy output, usually on paper; and interactive devices, which usually display the plot on a TV monitor. Some of the interactive devices allow modification to the displayed picture, and some have a movable cursor which can be used as a graphical input device. There is also a ``null device,'' to which unwanted graphical output can be directed. Hardcopy devices are not used interactively. One must first create a disk file and then send it to the appropriate device with a print or copy command. Consult Appendix D (or your System Manager) to determine the appropriate device-specific command.

A PGPLOT graphical output device is described by a ``device specification'' that consists of two parts, separated by a slash (/): the device name or file name, and the device type.

1.4.1 Device Name

device name or file name is the name by which the output device is known to the operating system. For most hardcopy devices, this should be the name of a disk file, while for interactive devices, it should be the name of a device of the appropriate type; in both cases, the name should be specified according to the syntax of the operating system in use. If the device or file name includes a slash (/), enclose the name in double quotation marks ("). If the device name is omitted from the device specification, a default device is used, the default depending on the device type (see Appendix D). In Unix, device and file names are case-sensitive.

1.4.2 Device Type

device type tells PGPLOT what sort of graphical device it is. Appendix D lists the device types available at the time of writing, together with the names by which they are known to PGPLOT. If the device type is omitted, a system-dependent default type is assumed (this is the value of the ``environment variable'' PGPLOT_TYPE). The device type is not case-sensitive: you can use uppercase or lowercase letters, or a mixture of the two.

1.4.3 Examples

A window on the default Xwindow display screen:

/XWINDOW

Tektronix 4006/4010 terminal:

/TEK (the logged-in terminal)
tta4/TEK (VMS device _TTA4:)
"/dev/tty6"/TEK (Unix device tty6)

Disk file, PostScript format:

plot.ps/PS (in the current default directory)
plot.ps/VPS (the same, but in portrait orientation)
"/scr/tjp/plot.ps"/PS (in a specified directory)

1.5 Environment Variables

Some aspects of the behavior of PGPLOT can be modified at run time by specifying environment variables. The variables have names which begin with PGPLOT_.

In UNIX systems, environment variables can be defined using the shell. For the bash, bourne (sh), or korn (ksh) shell, use commands like the following:

PGPLOT_DIR="/usr/local/pgplot"; export PGPLOT_DIR

For the c-shell and tcsh, use

setenv PGPLOT_DIR "/usr/local/pgplot/"

Note that the names of PGPLOT environment variables are specified using upper case characters, e.g. PGPLOT_DIR, not pgplot_dir.

In VMS systems, environment variables are ``logical names'' and can be defined with the DEFINE or ASSIGN command, e.g.

$ DEFINE PGPLOT_DIR user_disk:[local.pgplot]
$ DEASSIGN PGPLOT_DIR

The following environment variables affect all PGPLOT programs:

PGPLOT_DIR

Directory name. Unless told otherwise by environment variables PGPLOT_FONT and PGPLOT_RGB, PGPLOT looks for the files it needs at run-time in this directory. The binary font file is grfont.dat and the color-name database is rgb.txt. If this variable is undefined, or if the specified file does not exist in this directory, PGPLOT looks in the current default directory. e.g.

setenv PGPLOT_DIR /usr/local/lib/pgplot/

PGPLOT_FONT

File name for the binary font file. If this variable is defined, PGPLOT will interpret the value as a file name for the binary font file. If it is not defined, PGPLOT will look for the binary font file under name grfont.dat in the directory specified by PGPLOT_DIR. e.g.

setenv PGPLOT_FONT /usr/local/pgplot/grfont.dat

PGPLOT_RGB

File name for the color-name database. If this variable is defined, PGPLOT will interpret the value as a file name for the color-name database. If it is not defined, PGPLOT will look for the binary font file under name rgb.txt in the directory specified by PGPLOT_DIR. The color-name database is only used by programs that call PGSCRN, or when environment variable PGPLOT_BACKGROUND or PGPLOT_FOREGROUND is defined. e.g.

setenv PGPLOT_RGB /usr/local/pgplot/rgb.txt

PGPLOT_DEV

Device specification. If this variable is defined, it is used as the default device specification: if the device specification given to PGBEG (or supplied by the user in response to the PGPLOT prompt) is a blank string, this device specification is used, e.g.

setenv PGPLOT_DEV /xwin

PGPLOT_TYPE

Device type. If this variable is defined, it is used as the default device type: if the device specification supplied to PGBEG consists of a file name without a trailing slash (/) and device type, this device type is assumed. e.g.

setenv PGPLOT_TYPE ps

PGPLOT_ENVOPT

Character string. This affects programs that call routine PGENV. The characters supplied are options for PGBOX (in addition to those assumed by default by PGENV, i.e., `BCNST'. Useful options include `G' to draw a grid, `V' to draw y-axis labels upright, `I' to draw axis tick marks outside the box instead of inside, `1' or `2' to change the numeric label style. e.g.

setenv PGPLOT_ENVOPT IVG

PGPLOT_FOREGROUND

Color name. This variable can be used to change the color representation of color index 1 (the ``foreground'' color) from its device-dependent default (usually white or black). The value of the variable should be a color name defined in the color-name database. If the variable is defined, the effect is the same as a call to PGSCRN with this name as argument immediately after the graphics device is opened. Color names are case-insensitive and embedded spaces are ignored. e.g.

setenv PGPLOT_FOREGROUND springgreen

PGPLOT_BACKGROUND

Color name. This variable can be used to change the color representation of color index 0 (the ``background'' color) from its device-dependent default (usually black or white). The value of the variable should be a color name defined in the color-name database. If the variable is defined, the effect is the same as a call to PGSCRN with this name as argument immediately after the graphics device is opened. On devices without a color lookup table, changing the background color only affects the color of elements explicitly drawn in color index 0. To ensure that the background of the entire view surface changes to the new color, it is also necessary to call PGERAS at the start of each page. e.g.

setenv PGPLOT_BACKGROUND slateblue

PGPLOT_BUFFER

Switch. If this variable is defined, with any non-null value, PGPLOT buffers output. The effect is the same as if PGBBUF is called immediately after opening the graphics device, and PGEBUF immediately before closing it. It will have no effect on programs that already include these calls. On some devices, buffering output can lead to large improvements in speed, but enabling buffering may upset synchronization between graphical output and other program activity. e.g.

setenv PGPLOT_BUFFER yes

PGPLOT_DEBUG

Switch. If this variable is defined, with any non-null value, PGPLOT will print some debugging information on the standard output. Currently this includes attempts to open input files (binary font file and color-name database), and, when the null device is selected for output, statistics of device-driver calls. e.g.

setenv PGPLOT_DEBUG yes

In addition to these environment variables, several device drivers use device-specific environment variables. See the device descriptions for details.

Next: Chapter 2