pgplot命令大全

PGPLOT Subroutine Descriptions

Introduction

This

appendix

includes

a

list

of

all

the

PGPLOT

subroutines,

and

then

gives

detailed instructions for the use of each routine in Fortran programs.

The subroutine descriptions are in alphabetical order.

Arguments

The

subroutine

descriptions

indicate

the

data

type

of

each

argument.

When

arguments

are

described

as

``input'',

they

may

be

replaced

with

constants

or

expressions

in

the

CALL

statement,

but

make

sure

that

the

constant

or

expression has the correct data type.

INTEGER arguments:

these

should

be

declared

INTEGER

or

INTEGER*4

in

the

calling

program,

not INTEGER*2.

REAL arguments:

these

should

be

declared

REAL

or

REAL*4

in

the

calling

program,

not

REAL*8 or DOUBLE PRECISION.

LOGICAL arguments:

these should be declared LOGICAL or LOGICAL*4 in the calling

program.

CHARACTER arguments:

any valid Fortran CHARACTER variable may be used (declared

CHARACTER*n for some integer n).

Index of Routines

Version 5.1

?

?

?

?

?

?

?

?

?

?

PGARRO

-- draw an arrow

PGASK

-- control new page prompting

PGBAND

-- read cursor position, with anchor

PGBBUF

-- begin batch of output (buffer)

PGBEG

-- begin PGPLOT, open output device

PGBIN

-- histogram of binned data

PGBOX

-- draw labeled frame around viewport

PGCIRC

-- draw a filled or outline circle

PGCLOS

-- close the selected graphics device

PGCONB

-- contour map of a 2D data array, with blanking

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

PGCONL

-- label contour map of a 2D data array

PGCONS

-- contour map of a 2D data array (fast algorithm)

PGCONT

-- contour map of a 2D data array (contour-following)

PGCONX

-- contour map of a 2D data array (non rectangular)

PGCTAB

-- install the color table to be used by PGIMAG

PGCURS

-- read cursor position

PGDRAW

-- draw a line from the current pen position to a point

PGEBUF

-- end batch of output (buffer)

PGEND

-- terminate PGPLOT

PGENV

-- set window and viewport and draw labeled frame

PGERAS

-- erase all graphics from current page

PGERRB

-- horizontal or vertical error bar

PGERRX

-- horizontal error bar

PGERRY

-- vertical error bar

PGETXT

-- erase text from graphics display

PGFUNT

-- function defined by X = F(T), Y = G(T)

PGFUNX

-- function defined by Y = F(X)

PGFUNY

-- function defined by X = F(Y)

PGGRAY

-- gray-scale map of a 2D data array

PGHI2D

-- cross-sections through a 2D data array

PGHIST

-- histogram of unbinned data

PGIDEN

-- write username, date, and time at bottom of plot

PGIMAG

-- color image from a 2D data array

PGLAB

-- write labels for x-axis, y-axis, and top of plot

PGLCUR

-- draw a line using the cursor

PGLDEV

-- list available device types

PGLEN

-- find length of a string in a variety of units

PGLINE

-- draw a polyline (curve defined by line-segments)

PGMOVE

-- move pen (change current pen position)

PGMTXT

-- write text at position relative to viewport

PGNCUR

-- mark a set of points using the cursor

PGNUMB

-- convert a number into a plottable character string

PGOLIN

-- mark a set of points using the cursor

PGOPEN

-- open a graphics device

PGPAGE

-- advance to new page

PGPANL

-- switch to a different panel on the view surface

PGPAP

-- change the size of the view surface

PGPIXL

-- draw pixels

PGPNTS

-- draw one or more graph markers, not all the same

PGPOLY

-- fill a polygonal area with shading

PGPT

-- draw one or more graph markers

PGPTXT

-- write text at arbitrary position and angle

PGQAH

-- inquire arrow-head style

PGQCF

-- inquire character font

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

PGQCH

-- inquire character height

PGQCI

-- inquire color index

PGQCIR

-- inquire color index range

PGQCOL

-- inquire color capability

PGQCR

-- inquire color representation

PGQCS

-- inquire character height in a variety of units

PGQFS

-- inquire fill-area style

PGQHS

-- inquire hatching style

PGQID

-- inquire current device identifier

PGQINF

-- inquire PGPLOT general information

PGQITF

-- inquire image transfer function

PGQLS

-- inquire line style

PGQLW

-- inquire line width

PGQPOS

-- inquire current pen position

PGQTBG

-- inquire text background color index

PGQTXT

-- find bounding box of text string

PGQVP

-- inquire viewport size and position

PGQVSZ

-- find the window defined by the full view surface

PGQWIN

-- inquire window boundary coordinates

PGRECT

-- draw a rectangle, using fill-area attributes

PGRND

-- find the smallest `round' number greater than x

PGRNGE

-- choose axis limits

PGSAH

-- set arrow-head style

PGSAVE

-- save PGPLOT attributes

PGUNSA

-- restore PGPLOT attributes

PGSCF

-- set character font

PGSCH

-- set character height

PGSCI

-- set color index

PGSCIR

-- set color index range

PGSCR

-- set color representation

PGSCRN

-- set color representation by name

PGSFS

-- set fill-area style

PGSHLS

-- set color representation using HLS system

PGSHS

-- set hatching style

PGSITF

-- set image transfer function

PGSLCT

-- select an open graphics device

PGSLS

-- set line style

PGSLW

-- set line width

PGSTBG

-- set text background color index

PGSUBP

-- subdivide view surface into panels

PGSVP

-- set viewport (normalized device coordinates)

PGSWIN

-- set window

PGTBOX

-- draw frame and write (DD) HH MM SS.S labelling

PGTEXT

-- write text (horizontal, left-justified)

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

?

PGUPDT

-- update display

PGVECT

-- vector map of a 2D data array, with blanking

PGVSIZ

-- set viewport (inches)

PGVSTD

-- set standard (default) viewport

PGWEDG

-- annotate an image plot with a wedge

PGWNAD

-- set window and adjust viewport to same aspect ratio

PGADVANCE

-- non- standard alias for PGPAGE

PGBEGIN

-- non-standard alias for PGBEG

PGCURSE

-- non-standard alias for PGCURS

PGLABEL

-- non-standard alias for PGLAB

PGMTEXT

-- non-standard alias for PGMTXT

PGNCURSE

-- non-standard alias for PGNCUR

PGPAPER

-- non-standard alias for PGPAP

PGPOINT

-- non-standard alias for PGPT

PGPTEXT

-- non-standard alias for PGPTXT

PGVPORT

-- non-standard alias for PGSVP

PGVSIZE

-- non-standard alias for PGVSIZ

PGVSTAND

-- non-standard alias for PGVSTD

PGWINDOW

-- non-standard alias for PGSWIN

PGARRO -- draw an arrow

SUBROUTINE PGARRO (X1, Y1, X2, Y2)

REAL X1, Y1, X2, Y2

Draw an arrow from the point with world-coordinates (X1,Y1) to

(X2,Y2). The size of the arrowhead at (X2,Y2) is determined by

the current character size set by routine

PGSCH

. The default size

is 1/40th of the smaller of the width or height of the view surface.

The appearance of the arrowhead (shape and solid or open) is

controlled by routine

PGSAH

.

Arguments:

X1, Y1 (input) : world coordinates of the tail of the arrow.

X2, Y2 (input) : world coordinates of the head of the arrow.

PGASK -- control new page prompting

SUBROUTINE PGASK (FLAG)

LOGICAL FLAG

Change the ``prompt state'' of PGPLOT. If the prompt state is

ON,

PGPAGE

will type ``Type RETURN for next page:'' and will wait

for the user to type a carriage-return before starting a new page.

The initial prompt state (after a call to

PGBEG

) is ON for

interactive devices. Prompt state is always OFF for non-interactive

devices.

Arguments:

FLAG (input) : if .TRUE., and if the device is an interactive

device, the prompt state will be set to ON. If

.FALSE., the prompt state will be set to OFF.

PGBAND -- read cursor position, with anchor

INTEGER FUNCTION PGBAND (MODE, POSN, XREF, YREF, X, Y, CH)

INTEGER MODE, POSN

REAL XREF, YREF, X, Y

CHARACTER*(*) CH

Read the cursor position and a character typed by the user.

The position is returned in world coordinates.

PGBAND

positions

the cursor at the position specified (if POSN=1), allows the user to

move the cursor using the mouse or arrow keys or whatever is available

on the device. When he has positioned the cursor, the user types a

single character on the keyboard;

PGBAND

then returns this

character and the new cursor position (in world coordinates).

Some interactive devices offer a selection of cursor types,

implemented as thin lines that move with the cursor, but without

erasing underlying graphics. Of these types, some extend between

a stationary anchor-point at XREF,YREF, and the position of the

cursor, while others simply follow the cursor without changing shape

or size. The cursor type is specified with one of the following MODE

values. Cursor types that are not supported by a given device, are

treated as MODE=0.

-- If MODE=0, the anchor point is ignored and the routine behaves

like

PGCURS

.

-- If MODE=1, a straight line is drawn joining the anchor point

and the cursor position.

-- If MODE=2, a hollow rectangle is extended as the cursor is moved,

with one vertex at the anchor point and the opposite vertex at the

current cursor position; the edges of the rectangle are horizontal

and vertical.

-- If MODE=3, two horizontal lines are extended across the width of

the display, one drawn through the anchor point and the other

through the moving cursor position. This could be used to select

a Y-axis range when one end of the range is known.

-- If MODE=4, two vertical lines are extended over the height of

the display, one drawn through the anchor point and the other

through the moving cursor position. This could be used to select an

X-axis range when one end of the range is known.

-- If MODE=5, a horizontal line is extended through the cursor

position over the width of the display. This could be used to select

an X-axis value such as the start of an X-axis range. The anchor point

is ignored.

-- If MODE=6, a vertical line is extended through the cursor

position over the height of the display. This could be used to select

a Y-axis value such as the start of a Y-axis range. The anchor point

is ignored.

-- If MODE=7, a cross-hair, centered on the cursor, is extended over

the width and height of the display. The anchor point is ignored.

Returns:

PGBAND

: 1 if the call was successful; 0 if the device

has no cursor or some other error occurs.

Arguments:

MODE (input) : display mode (0, 1, ..7: see above).

POSN (input) : if POSN=1,

PGBAND

attempts to place the cursor

at point (X,Y); if POSN=0, it leaves the cursor

at its current position. (On some devices this

request may be ignored.)

XREF (input) : the world x-coordinate of the anchor point.

YREF (input) : the world y-coordinate of the anchor point.

X (in/out) : the world x-coordinate of the cursor.

Y (in/out) : the world y-coordinate of the cursor.

CH (output) : the character typed by the user; if the device has

no cursor or if some other error occurs, the value

CHAR(0) [ASCII NUL character] is returned.

Note: The cursor coordinates (X,Y) may be changed by

PGBAND

even if

the device has no cursor or if the user does not move the cursor.

Under these circumstances, the position returned in (X,Y) is that of

the pixel nearest to the requested position.

PGBBUF -- begin batch of output (buffer)

SUBROUTINE PGBBUF

Begin saving graphical output commands in an internal buffer; the

commands are held until a matching

PGEBUF

call (or until the buffer

is emptied by

PGUPDT

). This can greatly improve the efficiency of

PGPLOT.

PGBBUF

increments an internal counter, while

PGEBUF

decrements this counter and flushes the buffer to the output

device when the counter drops to zero.

PGBBUF

and

PGEBUF

calls

should always be paired.

Arguments: none

PGBEG -- begin PGPLOT, open output device

INTEGER FUNCTION PGBEG (UNIT, FILE, NXSUB, NYSUB)

INTEGER UNIT

CHARACTER*(*) FILE

INTEGER NXSUB, NYSUB

Begin PGPLOT, open the plot file. A call to

PGBEG

is

required before any other calls to PGPLOT subroutines. If a plot

file is already open for PGPLOT output, it is closed before the new

file is opened.

Returns:

PGBEG

: a status return value. A value of 1 indicates

successful completion, any other value indicates

an error. In the event of error a message is

written on the standard error unit.

To test the return value, call

PGBEG

as a function, eg IER=PGBEG(...); note

that

PGBEG

must be declared INTEGER in the

calling program.

Arguments:

UNIT (input) : this argument is ignored by

PGBEG

(use zero).

FILE (input) : the

Device specifications are installation dependent,

but usually have the form

question mark ('?'),

PGBEG

will prompt the user

to supply a string. If the argument is a blank

string (' '),

PGBEG

will use the value of

environment variable PGPLOT_DEV.

NXSUB (input) : the number of subdivisions of the view surface in

X (>0 or <0).

NYSUB (input) : the number of subdivisions of the view surface in

Y (>0).

PGPLOT puts NXSUB x NYSUB graphs on each plot

page or screen; when the view surface is sub-

divided in this way,

PGPAGE

moves to the next

panel, not the next physical page. If

NXSUB > 0, PGPLOT uses the panels in row

order; if <0, PGPLOT uses them in column order.

PGBIN -- histogram of binned data

SUBROUTINE PGBIN (NBIN, X, DATA, CENTER)

INTEGER NBIN

REAL X(*), DATA(*)

LOGICAL CENTER

Plot a histogram of NBIN values with X(1..NBIN) values along

the ordinate, and DATA(1...NBIN) along the abscissa. Bin width is

spacing between X values.

Arguments:

NBIN (input) : number of values.

X (input) : abscissae of bins.

DATA (input) : data values of bins.

CENTER (input) : if .TRUE., the X values denote the center of the

bin; if .FALSE., the X values denote the lower

edge (in X) of the bin.

PGBOX -- draw labeled frame around viewport

SUBROUTINE PGBOX (XOPT, XTICK, NXSUB, YOPT, YTICK, NYSUB)

CHARACTER*(*) XOPT, YOPT

REAL XTICK, YTICK

INTEGER NXSUB, NYSUB

Annotate the viewport with frame, axes, numeric labels, etc.

PGBOX

is called by on the user's behalf by

PGENV

, but may also be

called explicitly.

Arguments:

XOPT (input) : string of options for X (horizontal) axis of

plot. Options are single letters, and may be in

any order (see below).

XTICK (input) : world coordinate interval between major tick marks

on X axis. If XTICK=0.0, the interval is chosen by

PGBOX

, so that there will be at least 3 major tick

marks along the axis.

NXSUB (input) : the number of subintervals to divide the major

coordinate interval into. If XTICK=0.0 or NXSUB=0,

the number is chosen by

PGBOX

.

YOPT (input) : string of options for Y (vertical) axis of plot.

Coding is the same as for XOPT.

YTICK (input) : like XTICK for the Y axis.

NYSUB (input) : like NXSUB for the Y axis.

Options (for parameters XOPT and YOPT):

A : draw Axis (X axis is horizontal line Y=0, Y axis is vertical

line X=0).

B : draw bottom (X) or left (Y) edge of frame.

C : draw top (X) or right (Y) edge of frame.

G : draw Grid of vertical (X) or horizontal (Y) lines.

I : Invert the tick marks; ie draw them outside the viewport

instead of inside.

L : label axis Logarithmically (see below).

N : write Numeric labels in the conventional location below the

viewport (X) or to the left of the viewport (Y).

P : extend (

option I is specified).

M : write numeric labels in the unconventional location above the

viewport (X) or to the right of the viewport (Y).

T : draw major Tick marks at the major coordinate interval.

S : draw minor tick marks (Subticks).

V : orient numeric labels Vertically. This is only applicable to Y.

The default is to write Y-labels parallel to the axis.

1 : force decimal labelling, instead of automatic choice (see

PGNUMB

).

2 : force exponential labelling, instead of automatic.

To get a complete frame, specify BC in both XOPT and YOPT.

Tick marks, if requested, are drawn on the axes or frame

or both, depending which are requested. If none of ABC is specified,

tick marks will not be drawn. When

PGENV

calls

PGBOX

, it sets both

XOPT and YOPT according to the value of its parameter AXIS:

-1: 'BC', 0: 'BCNST', 1: 'ABCNST', 2: 'ABCGNST'.

For a logarithmic axis, the major tick interval is always 1.0. The

numeric label is 10**(x) where x is the world coordinate at the

tick mark. If subticks are requested, 8 subticks are drawn between

each major tick at equal logarithmic intervals.

To label an axis with time (days, hours, minutes, seconds) or

angle (degrees, arcmin, arcsec), use routine

PGTBOX

.

PGCIRC -- draw a filled or outline circle

SUBROUTINE PGCIRC (XCENT, YCENT, RADIUS)

REAL XCENT, YCENT, RADIUS

Draw a circle. The action of this routine depends

on the setting of the Fill-Area Style attribute. If Fill- Area Style

is SOLID (the default), the interior of the circle is solid-filled

using the current Color Index. If Fill- Area Style is HOLLOW, the

outline of the circle is drawn using the current line attributes

(color index, line-style, and line-width).

Arguments:

XCENT (input) : world x-coordinate of the center of the circle.

YCENT (input) : world y-coordinate of the center of the circle.

RADIUS (input) : radius of circle (world coordinates).

PGCLOS -- close the selected graphics device

SUBROUTINE PGCLOS

Close the currently selected graphics device. After the device has

been closed, either another open device must be selected with

PGSLCT

or another device must be opened with

PGOPEN

before any further

plotting can be done. If the call to

PGCLOS

is omitted, some or all

of the plot may be lost.

[This routine was added to PGPLOT in Version 5.1.0. Older programs

use

PGEND

instead.]

Arguments: none

PGCONB -- contour map of a 2D data array, with

blanking

SUBROUTINE PGCONB (A, IDIM, JDIM, I1, I2, J1, J2, C, NC, TR,

1 BLANK)

INTEGER IDIM, JDIM, I1, I2, J1, J2, NC

REAL A(IDIM,JDIM), C(*), TR(6), BLANK

Draw a contour map of an array. This routine is the same as

PGCONS

,

except that array elements that have the

argument BLANK are ignored, making gaps in the contour map. The

routine may be useful for data measured on most but not all of the

points of a grid.

Arguments:

A (input) : data array.

IDIM (input) : first dimension of A.

JDIM (input) : second dimension of A.

I1,I2 (input) : range of first index to be contoured (inclusive).

J1,J2 (input) : range of second index to be contoured (inclusive).

C (input) : array of contour levels (in the same units as the

data in array A); dimension at least NC.

NC (input) : number of contour levels (less than or equal to

dimension of C). The absolute value of this

argument is used (for compatibility with

PGCONT

,

where the sign of NC is significant).

TR (input) : array defining a transformation between the I,J

grid of the array and the world coordinates. The

world coordinates of the array point A(I,J) are

given by:

X = TR(1) + TR(2)*I + TR(3)*J

Y = TR(4) + TR(5)*I + TR(6)*J

Usually TR(3) and TR(5) are zero - unless the

coordinate transformation involves a rotation

or shear.

BLANK (input) : elements of array A that are exactly equal to

this value are ignored (blanked).

PGCONL -- label contour map of a 2D data array

SUBROUTINE PGCONL (A, IDIM, JDIM, I1, I2, J1, J2, C, TR,

1 LABEL, INTVAL, MININT)

INTEGER IDIM, JDIM, I1, J1, I2, J2, INTVAL, MININT

REAL A(IDIM,JDIM), C, TR(6)

CHARACTER*(*) LABEL

Label a contour map drawn with routine

PGCONT

. Routine PGCONT should

be called first to draw the contour lines, then this routine should be

called to add the labels. Labels are written at intervals along the

contour lines, centered on the contour lines with lettering aligned

in the up-hill direction. Labels are opaque, so a part of the under-

lying contour line is obscured by the label. Labels use the current

attributes (character height, line width, color index, character

font).

The first 9 arguments are the same as those supplied to

PGCONT

, and

should normally be identical to those used with

PGCONT

. Note that

only one contour level can be specified; tolabel more contours, call

PGCONL

for each level.

The Label is supplied as a character string in argument LABEL.

The spacing of labels along the contour is specified by parameters

INTVAL and MININT. The routine follows the contour through the

array, counting the number of cells that the contour crosses. The

first label will be written in the MININT'th cell, and additional

labels will be written every INTVAL cells thereafter. A contour

that crosses less than MININT cells will not be labelled. Some

experimentation may be needed to get satisfactory results; a good

place to start is INTVAL=20, MININT=10.

Arguments:

A (input) : data array.

IDIM (input) : first dimension of A.

JDIM (input) : second dimension of A.

I1, I2 (input) : range of first index to be contoured (inclusive).

J1, J2 (input) : range of second index to be contoured (inclusive).

C (input) : the level of the contour to be labelled (one of the

values given to

PGCONT

).

TR (input) : array defining a transformation between the I,J

grid of the array and the world coordinates.

The world coordinates of the array point A(I,J)

are given by:

X = TR(1) + TR(2)*I + TR(3)*J

Y = TR(4) + TR(5)*I + TR(6)*J

Usually TR(3) and TR(5) are zero - unless the

coordinate transformation involves a rotation or

shear.

LABEL (input) : character strings to be used to label the specified

contour. Leading and trailing blank spaces are

ignored.

INTVAL (input) : spacing along the contour between labels, in

grid cells.

MININT (input) : contours that cross less than MININT cells

will not be labelled.

PGCONS -- contour map of a 2D data array (fast

algorithm)

SUBROUTINE PGCONS (A, IDIM, JDIM, I1, I2, J1, J2, C, NC, TR)

INTEGER IDIM, JDIM, I1, I2, J1, J2, NC

REAL A(IDIM,JDIM), C(*), TR(6)

Draw a contour map of an array. The map is truncated if

necessary at the boundaries of the viewport. Each contour line is

drawn with the current line attributes (color index, style, and

width). This routine, unlike

PGCONT

, does not draw each contour as a

continuous line, but draws the straight line segments composing each

contour in a random order. It is thus not suitable for use on pen

plotters, and it usually gives unsatisfactory results with dashed or

dotted lines. It is, however, faster than

PGCONT

, especially if

several contour levels are drawn with one call of

PGCONS

.

Arguments:

A (input) : data array.

IDIM (input) : first dimension of A.

JDIM (input) : second dimension of A.

I1,I2 (input) : range of first index to be contoured (inclusive).

J1,J2 (input) : range of second index to be contoured (inclusive).

C (input) : array of contour levels (in the same units as the

data in array A); dimension at least NC.

NC (input) : number of contour levels (less than or equal to

dimension of C). The absolute value of this

argument is used (for compatibility with

PGCONT

,

where the sign of NC is significant).

TR (input) : array defining a transformation between the I,J

grid of the array and the world coordinates. The

world coordinates of the array point A(I,J) are

given by:

X = TR(1) + TR(2)*I + TR(3)*J

Y = TR(4) + TR(5)*I + TR(6)*J

Usually TR(3) and TR(5) are zero - unless the

coordinate transformation involves a rotation

or shear.

PGCONT -- contour map of a 2D data array

(contour- following)

SUBROUTINE PGCONT (A, IDIM, JDIM, I1, I2, J1, J2, C, NC, TR)

INTEGER IDIM, JDIM, I1, J1, I2, J2, NC

REAL A(IDIM,JDIM), C(*), TR(6)

Draw a contour map of an array. The map is truncated if

necessary at the boundaries of the viewport. Each contour line

is drawn with the current line attributes (color index, style, and

width); except that if argument NC is positive (see below), the line

style is set by

PGCONT

to 1 (solid) for positive contours or 2

(dashed) for negative contours.

Arguments:

A (input) : data array.

IDIM (input) : first dimension of A.

JDIM (input) : second dimension of A.

I1, I2 (input) : range of first index to be contoured (inclusive).

J1, J2 (input) : range of second index to be contoured (inclusive).

C (input) : array of NC contour levels; dimension at least NC.

NC (input) : +/- number of contour levels (less than or equal

to dimension of C). If NC is positive, it is the

number of contour levels, and the line-style is

chosen automatically as described above. If NC is

negative, it is minus the number of contour

levels, and the current setting of line-style is

used for all the contours.

TR (input) : array defining a transformation between the I,J

grid of the array and the world coordinates.

The world coordinates of the array point A(I,J)

are given by:

X = TR(1) + TR(2)*I + TR(3)*J

Y = TR(4) + TR(5)*I + TR(6)*J

Usually TR(3) and TR(5) are zero - unless the

coordinate transformation involves a rotation or

shear.

PGCONX -- contour map of a 2D data array (non

rectangular)

SUBROUTINE PGCONX (A, IDIM, JDIM, I1, I2, J1, J2, C, NC, PLOT)

INTEGER IDIM, JDIM, I1, J1, I2, J2, NC

REAL A(IDIM,JDIM), C(*)

EXTERNAL PLOT

Draw a contour map of an array using a user-supplied plotting

routine. This routine should be used instead of

PGCONT

when the

data are defined on a non-rectangular grid.

PGCONT

permits only

a linear transformation between the (I,J) grid of the array

and the world coordinate system (x,y), but

PGCONX

permits any

transformation to be used, the transformation being defined by a

user- supplied subroutine. The nature of the contouring algorithm,

however, dictates that the transformation should maintain the

rectangular topology of the grid, although grid-points may be

allowed to coalesce. As an example of a deformed rectangular

grid, consider data given on the polar grid theta=0.1n(pi/2),

for n=0,1,...,10, and r=0.25m, for m=0,1,..,4. This grid

contains 55 points, of which 11 are coincident at the origin.

The input array for

PGCONX

should be dimensioned (11,5), and

data values should be provided for all 55 elements.

PGCONX

can

also be used for special applications in which the height of the

contour affects its appearance, e.g., stereoscopic views.

The map is truncated if necessary at the boundaries of the viewport.

Each contour line is drawn with the current line attributes (color

index, style, and width); except that if argument NC is positive

(see below), the line style is set by

PGCONX

to 1 (solid) for

positive contours or 2 (dashed) for negative contours. Attributes

for the contour lines can also be set in the user-supplied

subroutine, if desired.

Arguments:

A (input) : data array.

IDIM (input) : first dimension of A.

JDIM (input) : second dimension of A.

I1, I2 (input) : range of first index to be contoured (inclusive).

J1, J2 (input) : range of second index to be contoured (inclusive).

C (input) : array of NC contour levels; dimension at least NC.

NC (input) : +/- number of contour levels (less than or equal

to dimension of C). If NC is positive, it is the

number of contour levels, and the line-style is

chosen automatically as described above. If NC is

negative, it is minus the number of contour

levels, and the current setting of line-style is

used for all the contours.

PLOT (input) : the address (name) of a subroutine supplied by

the user, which will be called by

PGCONX

to do

the actual plotting. This must be declared

EXTERNAL in the program unit calling

PGCONX

.

The subroutine PLOT will be called with four arguments:

CALL PLOT(VISBLE,X,Y,Z)

where X,Y (input) are real variables corresponding to

I,J indices of the array A. If VISBLE (input, integer) is 1,

PLOT should draw a visible line from the current pen

position to the world coordinate point corresponding to (X,Y);

if it is 0, it should move the pen to (X,Y). Z is the value

of the current contour level, and may be used by PLOT if desired.

Example:

SUBROUTINE PLOT (VISBLE,X,Y,Z)

REAL X, Y, Z, XWORLD, YWORLD

INTEGER VISBLE

XWORLD = X*COS(Y) ! this is the user-defined

YWORLD = X*SIN(Y) ! transformation

IF (.0) THEN

CALL

PGMOVE

(XWORLD, YWORLD)

ELSE

CALL

PGDRAW

(XWORLD, YWORLD)

END IF

END

PGCTAB -- install the color table to be used by

PGIMAG

SUBROUTINE PGCTAB(L, R, G, B, NC, CONTRA, BRIGHT)

INTEGER NC

REAL L(NC), R(NC), G(NC), B(NC), CONTRA, BRIGHT

Use the given color table to change the color representations of

all color indexes marked for use by

PGIMAG

. To change which

color indexes are thus marked, call

PGSCIR

before calling

PGCTAB

or

PGIMAG

. On devices that can change the color representations

of previously plotted graphics,

PGCTAB

will also change the colors

of existing graphics that were plotted with the marked color

indexes. This feature can then be combined with

PGBAND

to

interactively manipulate the displayed colors of data previously

plotted with

PGIMAG

.

Limitations:

1. Some devices do not propagate color representation changes

to previously drawn graphics.

2. Some devices ignore requests to change color representations.

3. The appearance of specific color representations on grey-scale

devices is device-dependent.

Arguments:

L (input) : An array of NC normalized ramp-intensity levels

corresponding to the RGB primary color intensities

in R(),G(),B(). Colors on the ramp are linearly

interpolated from neighbouring levels.

Levels must be sorted in increasing order.

0.0 places a color at the beginning of the ramp.

1.0 places a color at the end of the ramp.

Colors outside these limits are legal, but will

not be visible if CONTRA=1.0 and BRIGHT=0.5.

R (input) : An array of NC normalized red intensities.

G (input) : An array of NC normalized green intensities.

B (input) : An array of NC normalized blue intensities.

NC (input) : The number of color table entries.

CONTRA (input) : The contrast of the color ramp (normally 1.0).

BRIGHT (input) : Brightness at the center colorindex (normally 0.5).

PGCURS -- read cursor position

INTEGER FUNCTION PGCURS (X, Y, CH)

REAL X, Y

CHARACTER*(*) CH

Read the cursor position and a character typed by the user.

The position is returned in world coordinates.

PGCURS

positions

the cursor at the position specified, allows the user to move the

cursor using the joystick or arrow keys or whatever is available on

the device. When he has positioned the cursor, the user types a

single character on the keyboard;

PGCURS

then returns this

character and the new cursor position (in world coordinates).

Returns:

PGCURS

: 1 if the call was successful; 0 if the device

has no cursor or some other error occurs.

Arguments:

X (in/out) : the world x-coordinate of the cursor.

Y (in/out) : the world y-coordinate of the cursor.

CH (output) : the character typed by the user; if the device has

no cursor or if some other error occurs, the value

CHAR(0) [ASCII NUL character] is returned.

Note: The cursor coordinates (X,Y) may be changed by

PGCURS

even if

the device has no cursor or if the user does not move the cursor.

Under these circumstances, the position returned in (X,Y) is that of

the pixel nearest to the requested position.

PGDRAW -- draw a line from the current pen

position to a point

SUBROUTINE PGDRAW (X, Y)

REAL X, Y

Draw a line from the current pen position to the point

with world-coordinates (X,Y). The line is clipped at the edge of the

current window. The new pen position is (X,Y) in world coordinates.

Arguments:

X (input) : world x-coordinate of the end point of the line.

Y (input) : world y-coordinate of the end point of the line.

PGEBUF -- end batch of output (buffer)

SUBROUTINE PGEBUF

A call to

PGEBUF

marks the end of a batch of graphical output begun

with the last call of

PGBBUF

. PGBBUF and

PGEBUF

calls should always

be paired. Each call to

PGBBUF

increments a counter, while each call

to

PGEBUF

decrements the counter. When the counter reaches 0, the

batch of output is written on the output device.

Arguments: none

PGEND -- terminate PGPLOT

SUBROUTINE PGEND

Terminate PGPLOT, close and release any open graphics devices.

If the call to

PGEND

is omitted, some or all of any open plots

may be lost.

Arguments: none

PGENV

--

set

window

and

viewport

and

draw

labeled

frame

SUBROUTINE PGENV (XMIN, XMAX, YMIN, YMAX, JUST, AXIS)

REAL XMIN, XMAX, YMIN, YMAX

INTEGER JUST, AXIS

Set PGPLOT

PGENV

establishes the scaling

for subsequent calls to

PGPT

,

PGLINE

, etc. The plotter is

advanced to a new page or panel, clearing the screen if necessary.

If the

PGASK

), confirmation

is requested from the user before clearing the screen.

If requested, a box, axes, labels, etc. are drawn according to

the setting of argument AXIS.

Arguments:

XMIN (input) : the world x-coordinate at the bottom left corner

of the viewport.

XMAX (input) : the world x-coordinate at the top right corner

of the viewport (note XMAX may be less than XMIN).

YMIN (input) : the world y-coordinate at the bottom left corner

of the viewport.

YMAX (input) : the world y-coordinate at the top right corner

of the viewport (note YMAX may be less than YMIN).

JUST (input) : if JUST=1, the scales of the x and y axes (in

world coordinates per inch) will be equal,

otherwise they will be scaled independently.

AXIS (input) : controls the plotting of axes, tick marks, etc:

AXIS = -2 : draw no box, axes or labels;

AXIS = -1 : draw box only;

AXIS = 0 : draw box and label it with coordinates;

AXIS = 1 : same as AXIS=0, but also draw the

coordinate axes (X=0, Y=0);

AXIS = 2 : same as AXIS=1, but also draw grid lines

at major increments of the coordinates;

AXIS = 10 : draw box and label X-axis logarithmically;

AXIS = 20 : draw box and label Y-axis logarithmically;

AXIS = 30 : draw box and label both axes logarithmically.

For other axis options, use routine

PGBOX

.

PGENV

can be persuaded to

call

PGBOX

with additional axis options by defining an environment

parameter PGPLOT_ENVOPT containing the required option codes.

Examples:

PGPLOT_ENVOPT=P ! draw Projecting tick marks

PGPLOT_ENVOPT=I ! Invert the tick marks

PGPLOT_ENVOPT=IV ! Invert tick marks and label y Vertically

PGERAS -- erase all graphics from current page

SUBROUTINE PGERAS

Erase all graphics from the current page or panel.

Arguments: none

PGERRB -- horizontal or vertical error bar

SUBROUTINE PGERRB (DIR, N, X, Y, E, T)

INTEGER DIR, N

REAL X(*), Y(*), E(*)

REAL T

Plot error bars in the direction specified by DIR.

This routine draws an error bar only; to mark the data point at

the start of the error bar, an additional call to

PGPT

is required.

Arguments:

DIR (input) : direction to plot the error bar relative to

the data point.

One-sided error bar:

DIR is 1 for +X (X to X+E);

2 for +Y (Y to Y+E);

3 for -X (X to X-E);

4 for -Y (Y to Y-E).

Two-sided error bar:

DIR is 5 for +/-X (X-E to X+E);

6 for +/-Y (Y-E to Y+E).

N (input) : number of error bars to plot.

X (input) : world x-coordinates of the data.

Y (input) : world y-coordinates of the data.

E (input) : value of error bar distance to be added to the

data position in world coordinates.

T (input) : length of terminals to be drawn at the ends

of the error bar, as a multiple of the default

length; if T = 0.0, no terminals will be drawn.

Note: the dimension of arrays X, Y, and E must be greater

than or equal to N. If N is 1, X, Y, and E may be scalar

variables, or expressions.

PGERRX -- horizontal error bar

SUBROUTINE PGERRX (N, X1, X2, Y, T)

INTEGER N

REAL X1(*), X2(*), Y(*)

REAL T

Plot horizontal error bars.

This routine draws an error bar only; to mark the data point in

the middle of the error bar, an additional call to

PGPT

or

PGERRY

is required.

Arguments:

N (input) : number of error bars to plot.

X1 (input) : world x-coordinates of lower end of the

error bars.

X2 (input) : world x-coordinates of upper end of the

error bars.

Y (input) : world y-coordinates of the data.

T (input) : length of terminals to be drawn at the ends

of the error bar, as a multiple of the default

length; if T = 0.0, no terminals will be drawn.

Note: the dimension of arrays X1, X2, and Y must be greater

than or equal to N. If N is 1, X1, X2, and Y may be scalar

variables, or expressions, eg:

CALL

PGERRX

(1,X-SIGMA,X+SIGMA,Y)

PGERRY -- vertical error bar

SUBROUTINE PGERRY (N, X, Y1, Y2, T)

INTEGER N

REAL X(*), Y1(*), Y2(*)

REAL T

Plot vertical error bars.

This routine draws an error bar only; to mark the data point in

the middle of the error bar, an additional call to

PGPT

or

PGERRX

is required.

Arguments:

N (input) : number of error bars to plot.

X (input) : world x-coordinates of the data.

Y1 (input) : world y-coordinates of top end of the

error bars.

Y2 (input) : world y-coordinates of bottom end of the

error bars.

T (input) : length of terminals to be drawn at the ends

of the error bar, as a multiple of the default

length; if T = 0.0, no terminals will be drawn.

Note: the dimension of arrays X, Y1, and Y2 must be greater

than or equal to N. If N is 1, X, Y1, and Y2 may be scalar

variables or expressions, eg:

CALL

PGERRY

(1,X,Y+SIGMA,Y-SIGMA)

PGETXT -- erase text from graphics display

SUBROUTINE PGETXT

Some graphics terminals display text (the normal interactive dialog)

on the same screen as graphics. This routine erases the text from the

view surface without affecting the graphics. It does nothing on

devices which do not display text on the graphics screen, and on

devices which do not have this capability.

Arguments:

None

PGFUNT

--

function

defined

by

X

=

F(T),

Y

=

G(T)

SUBROUTINE PGFUNT (FX, FY, N, TMIN, TMAX, PGFLAG)

REAL FX, FY

EXTERNAL FX, FY

INTEGER N

REAL TMIN, TMAX

INTEGER PGFLAG

Draw a curve defined by parametric equations X = FX(T), Y = FY(T).

Arguments:

FX (external real function): supplied by the user, evaluates

X-coordinate.

FY (external real function): supplied by the user, evaluates

Y-coordinate.

N (input) : the number of points required to define the

curve. The functions FX and FY will each be

called N+1 times.

TMIN (input) : the minimum value for the parameter T.

TMAX (input) : the maximum value for the parameter T.

PGFLAG (input) : if PGFLAG = 1, the curve is plotted in the

current window and viewport; if PGFLAG = 0,

PGENV

is called automatically by

PGFUNT

to

start a new plot with automatic scaling.

Note: The functions FX and FY must be declared EXTERNAL in the

Fortran program unit that calls

PGFUNT

.

PGFUNX -- function defined by Y = F(X)

SUBROUTINE PGFUNX (FY, N, XMIN, XMAX, PGFLAG)

REAL FY

EXTERNAL FY

INTEGER N

REAL XMIN, XMAX

INTEGER PGFLAG

Draw a curve defined by the equation Y = FY(X), where FY is a

user- supplied subroutine.

Arguments:

FY (external real function): supplied by the user, evaluates

Y value at a given X-coordinate.

N (input) : the number of points required to define the

curve. The function FY will be called N+1 times.

If PGFLAG=0 and N is greater than 1000, 1000

will be used instead. If N is less than 1,

nothing will be drawn.

XMIN (input) : the minimum value of X.

XMAX (input) : the maximum value of X.

PGFLAG (input) : if PGFLAG = 1, the curve is plotted in the

current window and viewport; if PGFLAG = 0,

PGENV

is called automatically by

PGFUNX

to

start a new plot with X limits (XMIN, XMAX)

and automatic scaling in Y.

Note: The function FY must be declared EXTERNAL in the Fortran

program unit that calls

PGFUNX

. It has one argument, the

x-coordinate at which the y value is required, e.g.

REAL FUNCTION FY(X)

REAL X

FY = .....

END

PGFUNY -- function defined by X = F(Y)

SUBROUTINE PGFUNY (FX, N, YMIN, YMAX, PGFLAG)

REAL FX

EXTERNAL FX

INTEGER N

REAL YMIN, YMAX

INTEGER PGFLAG

Draw a curve defined by the equation X = FX(Y), where FY is a

user-supplied subroutine.

Arguments:

FX (external real function): supplied by the user, evaluates

X value at a given Y-coordinate.

N (input) : the number of points required to define the

curve. The function FX will be called N+1 times.

If PGFLAG=0 and N is greater than 1000, 1000

will be used instead. If N is less than 1,

nothing will be drawn.

YMIN (input) : the minimum value of Y.

YMAX (input) : the maximum value of Y.

PGFLAG (input) : if PGFLAG = 1, the curve is plotted in the

current window and viewport; if PGFLAG = 0,

PGENV

is called automatically by

PGFUNY

to

start a new plot with Y limits (YMIN, YMAX)

and automatic scaling in X.

Note: The function FX must be declared EXTERNAL in the Fortran

program unit that calls

PGFUNY

. It has one argument, the

y-coordinate at which the x value is required, e.g.

REAL FUNCTION FX(Y)

REAL Y

FX = .....

END

PGGRAY -- gray-scale map of a 2D data array

SUBROUTINE PGGRAY (A, IDIM, JDIM, I1, I2, J1, J2,

1 FG, BG, TR)

INTEGER IDIM, JDIM, I1, I2, J1, J2

REAL A(IDIM,JDIM), FG, BG, TR(6)

Draw gray-scale map of an array in current window. The subsection

of the array A defined by indices (I1:I2, J1:J2) is mapped onto

the view surface world- coordinate system by the transformation

matrix TR. The resulting quadrilateral region is clipped at the edge

of the window and shaded with the shade at each point determined

by the corresponding array value. The shade is a number in the

range 0 to 1 obtained by linear interpolation between the background

level (BG) and the foreground level (FG), i.e.,

shade = [A(i,j) - BG] / [FG - BG]

The background level BG can be either less than or greater than the

foreground level FG. Points in the array that are outside the range

BG to FG are assigned shade 0 or 1 as appropriate.

PGGRAY

uses two different algorithms, depending how many color

indices are available in the color index range specified for images.

(This range is set with routine

PGSCIR

, and the current or default

range can be queried by calling routine

PGQCIR

).

If 16 or more color indices are available,

PGGRAY

first assigns

color representations to these color indices to give a linear ramp

between the background color (color index 0) and the foreground color

(color index 1), and then calls

PGIMAG

to draw the image using these

color indices. In this mode, the shaded region is

pixel is assigned a color.

If less than 16 color indices are available,

PGGRAY

uses only

color index 1, and uses a

with the shade (computed as above) determining the faction of pixels

that are filled. In this mode the shaded region is

allows previously-drawn graphics to show through.

The transformation matrix TR is used to calculate the world

coordinates of the center of the

array element. The world coordinates of the center of the cell

corresponding to array element A(I,J) are given by:

X = TR(1) + TR(2)*I + TR(3)*J

Y = TR(4) + TR(5)*I + TR(6)*J

Usually TR(3) and TR(5) are zero -- unless the coordinate

transformation involves a rotation or shear. The corners of the

quadrilateral region that is shaded by

PGGRAY

are given by

applying this transformation to (I1-0.5,J1-0.5), (I2+0.5, J2+0.5).

Arguments:

A (input) : the array to be plotted.

IDIM (input) : the first dimension of array A.

JDIM (input) : the second dimension of array A.

I1, I2 (input) : the inclusive range of the first index

(I) to be plotted.

J1, J2 (input) : the inclusive range of the second

index (J) to be plotted.

FG (input) : the array value which is to appear with the

foreground color (corresponding to color index 1).

BG (input) : the array value which is to appear with the

background color (corresponding to color index 0).

TR (input) : transformation matrix between array grid and

world coordinates.

PGHI2D

--

cross-sections

through

a

2D

data

array

SUBROUTINE PGHI2D (DATA, NXV, NYV, IX1, IX2, IY1, IY2, X, IOFF,

1 BIAS, CENTER, YLIMS)

INTEGER NXV, NYV, IX1, IX2, IY1, IY2

REAL DATA(NXV,NYV)

REAL X(IX2-IX1+1), YLIMS(IX2-IX1+1)

INTEGER IOFF

REAL BIAS

LOGICAL CENTER

Plot a series of cross-sections through a 2D data array.

Each cross-section is plotted as a hidden line histogram. The plot

can be slanted to give a pseudo-3D effect - if this is done, the

call to

PGENV

may have to be changed to allow for the increased X

range that will be needed.

Arguments:

DATA (input) : the data array to be plotted.

NXV (input) : the first dimension of DATA.

NYV (input) : the second dimension of DATA.

IX1 (input)

IX2 (input)

IY1 (input)

IY2 (input) :

PGHI2D

plots a subset of the input array DATA.

This subset is delimited in the first (x)

dimension by IX1 and IX2 and the 2nd (y) by IY1

and IY2, inclusively. Note: IY2 < IY1 is

permitted, resulting in a plot with the

cross-sections plotted in reverse Y order.

However, IX2 must be => IX1.

X (input) : the abscissae of the bins to be plotted. That is,

X(1) should be the X value for DATA(IX1,IY1), and

X should have (IX2-IX1+1) elements. The program

has to assume that the X value for DATA(x,y) is

the same for all y.

IOFF (input) : an offset in array elements applied to successive

cross-sections to produce a slanted effect. A

plot with IOFF > 0 slants to the right, one with

IOFF < 0 slants left.

BIAS (input) : a bias value applied to each successive cross-

section in order to raise it above the previous

cross-section. This is in the same units as the

data.

CENTER (input) : if .true., the X values denote the center of the

bins; if .false. the X values denote the lower

edges (in X) of the bins.

YLIMS (input) : workspace. Should be an array of at least

(IX2-IX1+1) elements.

PGHIST -- histogram of unbinned data

SUBROUTINE PGHIST(N, DATA, DATMIN, DATMAX, NBIN, PGFLAG)

INTEGER N

REAL DATA(*)

REAL DATMIN, DATMAX

INTEGER NBIN, PGFLAG

Draw a histogram of N values of a variable in array

DATA(1...N) in the range DATMIN to DATMAX using NBIN bins. Note

that array elements which fall exactly on the boundary between

two bins will be counted in the higher bin rather than the

lower one; and array elements whose value is less than DATMIN or

greater than or equal to DATMAX will not be counted at all.

Arguments:

N (input) : the number of data values.

DATA (input) : the data values. Note: the dimension of array

DATA must be greater than or equal to N. The

first N elements of the array are used.

DATMIN (input) : the minimum data value for the histogram.

DATMAX (input) : the maximum data value for the histogram.

NBIN (input) : the number of bins to use: the range DATMIN to

DATMAX is divided into NBIN equal bins and

the number of DATA values in each bin is

determined by

PGHIST

. NBIN may not exceed 200.

PGFLAG (input) : if PGFLAG = 1, the histogram is plotted in the

current window and viewport; if PGFLAG = 0,

PGENV

is called automatically by

PGHIST

to start

a new plot (the x-limits of the window will be

DATMIN and DATMAX; the y-limits will be chosen

automatically.

IF PGFLAG = 2,3 the histogram will be in the same

window and viewport but with a filled area style.

If pgflag=4,5 as for pgflag = 0,1, but simple

line drawn as for

PGBIN

PGIDEN -- write username, date, and time at

bottom of plot

SUBROUTINE PGIDEN

Write username, date, and time at bottom of plot.

Arguments: none.

PGIMAG -- color image from a 2D data array

SUBROUTINE PGIMAG (A, IDIM, JDIM, I1, I2, J1, J2,

1 A1, A2, TR)

INTEGER IDIM, JDIM, I1, I2, J1, J2

REAL A(IDIM,JDIM), A1, A2, TR(6)

Draw a color image of an array in current window. The subsection

of the array A defined by indices (I1:I2, J1:J2) is mapped onto

the view surface world- coordinate system by the transformation

matrix TR. The resulting quadrilateral region is clipped at the edge

of the window. Each element of the array is represented in the image

by a small quadrilateral, which is filled with a color specified by

the corresponding array value.

The subroutine uses color indices in the range C1 to C2, which can

be specified by calling

PGSCIR

before

PGIMAG

. The default values

for C1 and C2 are device-dependent; these values can be determined by

calling

PGQCIR

. Note that color representations should be assigned to

color indices C1 to C2 by calling

PGSCR

before calling

PGIMAG

. On some

devices (but not all), the color representation can be changed after

the call to

PGIMAG

by calling

PGSCR

again.

Array values in the range A1 to A2 are mapped on to the range of

color indices C1 to C2, with array values <= A1 being given color

index C1 and values >= A2 being given color index C2. The mapping

function for intermediate array values can be specified by

calling routine

PGSITF

before

PGIMAG

; the default is linear.

On devices which have no available color indices (C1 > C2),

PGIMAG

will return without doing anything. On devices with only

one color index (C1=C2), all array values map to the same color

which is rather uninteresting. An image is always

i.e., it obscures all graphical elements previously drawn in

the region.

The transformation matrix TR is used to calculate the world

coordinates of the center of the

array element. The world coordinates of the center of the cell

corresponding to array element A(I,J) are given by:

X = TR(1) + TR(2)*I + TR(3)*J

Y = TR(4) + TR(5)*I + TR(6)*J

Usually TR(3) and TR(5) are zero -- unless the coordinate

transformation involves a rotation or shear. The corners of the

quadrilateral region that is shaded by

PGIMAG

are given by

applying this transformation to (I1-0.5,J1-0.5), (I2+0.5, J2+0.5).

Arguments:

A (input) : the array to be plotted.

IDIM (input) : the first dimension of array A.

JDIM (input) : the second dimension of array A.

I1, I2 (input) : the inclusive range of the first index

(I) to be plotted.

J1, J2 (input) : the inclusive range of the second

index (J) to be plotted.

A1 (input) : the array value which is to appear with shade C1.

A2 (input) : the array value which is to appear with shade C2.

TR (input) : transformation matrix between array grid and

world coordinates.

PGLAB

--

write

labels

for

x-axis,

y-axis,

and

top

of plot

SUBROUTINE PGLAB (XLBL, YLBL, TOPLBL)

CHARACTER*(*) XLBL, YLBL, TOPLBL

Write labels outside the viewport. This routine is a simple

interface to

PGMTXT

, which should be used if

PGLAB

is inadequate.

Arguments:

XLBL (input) : a label for the x-axis (centered below the

viewport).

YLBL (input) : a label for the y-axis (centered to the left

of the viewport, drawn vertically).

TOPLBL (input) : a label for the entire plot (centered above the

viewport).

PGLCUR -- draw a line using the cursor

SUBROUTINE PGLCUR (MAXPT, NPT, X, Y)

INTEGER MAXPT, NPT

REAL X(*), Y(*)

Interactive routine for user to enter a polyline by use of

the cursor. Routine allows user to Add and Delete vertices;

vertices are joined by straight-line segments.

Arguments:

MAXPT (input) : maximum number of points that may be accepted.

NPT (in/out) : number of points entered; should be zero on

first call.

X (in/out) : array of x-coordinates (dimension at least MAXPT).

Y (in/out) : array of y-coordinates (dimension at least MAXPT).

Notes:

(1) On return from the program, cursor points are returned in

the order they were entered. Routine may be (re-)called with points

already defined in X,Y (# in NPT), and they will be plotted

first, before editing.

(2) User commands: the user types single-character commands

after positioning the cursor: the following are accepted:

A (Add) - add point at current cursor location.

D (Delete) - delete last-entered point.

X (eXit) - leave subroutine.

PGLDEV -- list available device types

SUBROUTINE PGLDEV

Writes a list to the terminal of all device types known to the

current version of PGPLOT.

Arguments: none.

PGLEN

--

find

length

of

a string

in

a

variety

of

units

SUBROUTINE PGLEN (UNITS, STRING, XL, YL)

REAL XL, YL

INTEGER UNITS

CHARACTER*(*) STRING

Work out length of a string in x and y directions

Input

UNITS : 0 => answer in normalized device coordinates

1 => answer in inches

2 => answer in mm

3 => answer in absolute device coordinates (dots)

4 => answer in world coordinates

5 => answer as a fraction of the current viewport size

STRING : String of interest

Output

XL : Length of string in x direction

YL : Length of string in y direction

PGLINE -- draw a polyline (curve defined by

line-segments)

SUBROUTINE PGLINE (N, XPTS, YPTS)

INTEGER N

REAL XPTS(*), YPTS(*)

Primitive routine to draw a Polyline. A polyline is one or more

connected straight-line segments. The polyline is drawn using

the current setting of attributes color-index, line-style, and

line-width. The polyline is clipped at the edge of the window.

Arguments:

N (input) : number of points defining the line; the line

consists of (N-1) straight-line segments.

N should be greater than 1 (if it is 1 or less,

nothing will be drawn).

XPTS (input) : world x-coordinates of the points.

YPTS (input) : world y-coordinates of the points.

The dimension of arrays X and Y must be greater than or equal to N.

The

(if N > 1).

PGMOVE

--

move

pen

(change

current

pen

position)

SUBROUTINE PGMOVE (X, Y)

REAL X, Y

Primitive routine to move the

coordinates (X,Y). No line is drawn.

Arguments:

X (input) : world x-coordinate of the new pen position.

Y (input) : world y-coordinate of the new pen position.

PGMTXT -- write text at position relative to

viewport

SUBROUTINE PGMTXT (SIDE, DISP, COORD, FJUST, TEXT)

CHARACTER*(*) SIDE, TEXT

REAL DISP, COORD, FJUST

Write text at a position specified relative to the viewport (outside

or inside). This routine is useful for annotating graphs. It is used

by routine

PGLAB

. The text is written using the current values of

attributes color-index, line-width, character-height, and

character-font.

Arguments:

SIDE (input) : must include one of the characters 'B', 'L', 'T',

or 'R' signifying the Bottom, Left, Top, or Right

margin of the viewport. If it includes 'LV' or

'RV', the string is written perpendicular to the

frame rather than parallel to it.

DISP (input) : the displacement of the character string from the

specified edge of the viewport, measured outwards

from the viewport in units of the character

height. Use a negative value to write inside the

viewport, a positive value to write outside.

COORD (input) : the location of the character string along the

specified edge of the viewport, as a fraction of

the length of the edge.

FJUST (input) : controls justification of the string parallel to

the specified edge of the viewport. If

FJUST = 0.0, the left-hand end of the string will

be placed at COORD; if JUST = 0.5, the center of

the string will be placed at COORD; if JUST = 1.0,

the right-hand end of the string will be placed at

at COORD. Other values between 0 and 1 give inter-

mediate placing, but they are not very useful.

TEXT (input) : the text string to be plotted. Trailing spaces are

ignored when justifying the string, but leading

spaces are significant.

PGNCUR -- mark a set of points using the cursor

SUBROUTINE PGNCUR (MAXPT, NPT, X, Y, SYMBOL)

INTEGER MAXPT, NPT

REAL X(*), Y(*)

INTEGER SYMBOL

Interactive routine for user to enter data points by use of

the cursor. Routine allows user to Add and Delete points. The

points are returned in order of increasing x-coordinate, not in the

order they were entered.

Arguments:

MAXPT (input) : maximum number of points that may be accepted.

NPT (in/out) : number of points entered; should be zero on

first call.

X (in/out) : array of x-coordinates.

Y (in/out) : array of y-coordinates.

SYMBOL (input) : code number of symbol to use for marking

entered points (see

PGPT

).

Note (1): The dimension of arrays X and Y must be greater than or

equal to MAXPT.

Note (2): On return from the program, cursor points are returned in

increasing order of X. Routine may be (re-)called with points

already defined in X,Y (number in NPT), and they will be plotted

first, before editing.

Note (3): User commands: the user types single-character commands

after positioning the cursor: the following are accepted:

A (Add) - add point at current cursor location.

D (Delete) - delete nearest point to cursor.

X (eXit) - leave subroutine.

PGNUMB -- convert a number into a plottable

character string

SUBROUTINE PGNUMB (MM, PP, FORM, STRING, NC)

INTEGER MM, PP, FORM

CHARACTER*(*) STRING

INTEGER NC

This routine converts a number into a decimal character

representation. To avoid problems of floating-point roundoff, the

number must be provided as an integer (MM) multiplied by a power of 10

(10**PP). The output string retains only significant digits of MM,

and will be in either integer format (123), decimal format (0.0123),

or exponential format (1.23x10**5). Standard escape sequences u, d

raise the exponent and x is used for the multiplication sign.

This routine is used by

PGBOX

to create numeric labels for a plot.

Formatting rules:

(a) Decimal notation (FORM=1):

- Trailing zeros to the right of the decimal sign are

omitted

- The decimal sign is omitted if there are no digits

to the right of it

- When the decimal sign is placed before the first digit

of the number, a zero is placed before the decimal sign

- The decimal sign is a period (.)

- No spaces are placed between digits (ie digits are not

grouped in threes as they should be)

- A leading minus (-) is added if the number is negative

(b) Exponential notation (FORM=2):

- The exponent is adjusted to put just one (non- zero)

digit before the decimal sign

- The mantissa is formatted as in (a), unless its value is

1 in which case it and the multiplication sign are omitted

- If the power of 10 is not zero and the mantissa is not

zero, an exponent of the form x10u[-]nnn is appended,

where x is a multiplication sign (cross), u is an escape

sequence to raise the exponent, and as many digits nnn

are used as needed

(c) Automatic choice (FORM=0):

Decimal notation is used if the absolute value of the

number is less than 10000 or greater than or equal to

0.01. Otherwise exponential notation is used.

Arguments:

MM (input)

PP (input) : the value to be formatted is MM*10**PP.

FORM (input) : controls how the number is formatted:

FORM = 0 -- use either decimal or exponential

FORM = 1 -- use decimal notation

FORM = 2 -- use exponential notation

STRING (output) : the formatted character string, left justified.

If the length of STRING is insufficient, a single

asterisk is returned, and NC=1.

NC (output) : the number of characters used in STRING:

the string to be printed is STRING(1:NC).

PGOLIN -- mark a set of points using the cursor

SUBROUTINE PGOLIN (MAXPT, NPT, X, Y, SYMBOL)

INTEGER MAXPT, NPT

REAL X(*), Y(*)

INTEGER SYMBOL

Interactive routine for user to enter data points by use of

the cursor. Routine allows user to Add and Delete points. The

points are returned in the order that they were entered (unlike

PGNCUR

).

Arguments:

MAXPT (input) : maximum number of points that may be accepted.

NPT (in/out) : number of points entered; should be zero on

first call.

X (in/out) : array of x-coordinates.

Y (in/out) : array of y-coordinates.

SYMBOL (input) : code number of symbol to use for marking

entered points (see

PGPT

).

Note (1): The dimension of arrays X and Y must be greater than or

equal to MAXPT.

Note (2): On return from the program, cursor points are returned in

the order they were entered. Routine may be (re-)called with points

already defined in X,Y (number in NPT), and they will be plotted

first, before editing.

Note (3): User commands: the user types single-character commands

after positioning the cursor: the following are accepted:

A (Add) - add point at current cursor location.

D (Delete) - delete the last point entered.

X (eXit) - leave subroutine.

PGOPEN -- open a graphics device

INTEGER FUNCTION PGOPEN (DEVICE)

CHARACTER*(*) DEVICE

Open a graphics device for PGPLOT output. If the device is

opened successfully, it becomes the selected device to which

graphics output is directed until another device is selected

with

PGSLCT

or the device is closed with

PGCLOS

.

The value returned by

PGOPEN

should be tested to ensure that

the device was opened successfully, e.g.,

ISTAT =

PGOPEN

('/PS')

IF (ISTAT .LE. 0 ) STOP

Note that

PGOPEN

must be declared INTEGER in the calling program.

The DEVICE argument is a character constant or variable; its value

should be one of the following:

(1) A complete device specification of the form 'device/type' or

'file/type', where 'type' is one of the allowed PGPLOT device

types (installation- dependent) and 'device' or 'file' is the

name of a graphics device or disk file appropriate for this type.

The 'device' or 'file' may contain '/' characters; the final

'/' delimits the 'type'. If necessary to avoid ambiguity,

the 'device' part of the string may be enclosed in double

quotation marks.

(2) A device specification of the form '/type', where 'type' is one

of the allowed PGPLOT device types. PGPLOT supplies a default

file or device name appropriate for this device type.

(3) A device specification with '/type' omitted; in this case

the type is taken from the environment variable PGPLOT_TYPE,