-
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,
-
-
-
-
-
-
-
-
-
上一篇:春节和圣诞节异同英文
下一篇:cad全命令注释