PGPLOT Extensions Part I
Changes 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 <CR> before starting a new page. The initial
prompt state (after a call to pgBegin) is ON for interactive devices.
Prompt state is always OFF for non-interactive devices.
Calling sequence:
pgAsk <flag>
flag = 1 : prompt user for response before displaying next page
flag = 0 : do not prompt user.
Begin saving graphical output commands in an internal buffer; the
commands are held until a matching pgEbuf call is given (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 drop to zero. pgBbuf and pgEbuf calls
should always be paired.
Calling sequence:
pgBbuf
Begin PGPLOT, open the plot file. A call to pgBegin 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.
Calling sequence:
pgBegin [device [xsub ysub]]
Optional arguments:
device = plot device specification. If argument is '?', pgBegin will
prompt the user to supply string.
Default: /XWINDOW
xsub = number of subdivisions in X
Default: 1
ysub = number of subdivisions in Y
Default: 1
A call to this routine marks the end of saving graphics commands.
pgBbuf and pgEbuf calls must always be paired. Upon last pairing,
the batch of output is written to the output device.
Calling sequence:
pgEbuf
Terminates PGPLOT, closes the plot file and releases the graphics device.
Calling sequence:
pgEnd
Advance plotter to a new (sub-)page, clearing the screen if necessary.
If the "prompt state" is ON (see pgAsk), confirmation is
requested from the user before clearing the screen. For an
explanation of sub-pages, see pgBegin. pgPage does not change the
window or the position of the viewport relative to the (sub-)page.
Calling sequence:
pgPage
Changes the size of the view surface to a specified
width and aspect ratio (height/width), in so far as this is possible
on the specific device. It is always possible to obtain a view
surface smaller than the default size; on some devices (e.g.,
printers that print on roll or fan-feed paper) it is possible
to obtain a view surface larger than the default.
If this routine is used, it must be called immediately after pgBegin.
Calling sequence:
pgPaper <width> <aspect>
where:
width : the requested width of the view surface in inches;
if width=0.0, pgPaper will obtain the largest view
surface available consistent with argument aspect.
aspect : the aspect ratio (height/width) of the view
surface; e.g., aspect=1.0 gives a square view
surface, aspect=0.618 gives a horizontal
rectangle, aspect=1.618 gives a vertical rectangle.
Updates the graphics display: flush any pending commands to the
output device. This routine empties the buffer created by pgBbuf,
but it does not alter the pgBbuf/pgEbuf counter. The routine should
be called when it is essential that the display be completely up to
date (before interaction with the user, for example) but it is not
known if output is being buffered.
Calling sequence:
pgUpdt
Annotates 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.
Calling sequence:
pgBox [xopt xtick nxsub yopt ytick nysub]
if no arguments are passed the following values are used:
xopt = BCNT
xtick = 0.0
nxsub = 0
yopt = BCNST
ytick = 0.0
nysub = 0
where:
xopt : string of options for X (horizontal) axis of
plot. Options are single letters, and may be in
any order (see below).
xtick : 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 : 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 : string of options for Y (vertical) axis of plot.
Coding is the same as for xopt.
ytick : like xtick for the Y axis.
nysub : 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 ("Project") major tick marks outside the box (ignored if
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
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.
Sets PGPLOT "Plotter Environment". pgEnv establishes the scaling
for subsequent calls to pgPtext, pgLine, etc. The plotter is
advanced to a new (sub-)page, clearing the screen if necessary.
If the "prompt state" is ON (see 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.
Calling sequence:
pgEnv <xmin> <xmax> <ymin> <ymax> <just> <axis>
where:
xmin : the world x-coordinate at the bottom left corner
of the viewport.
xmax : the world x-coordinate at the top right corner
of the viewport (note xmax may be less than xmin).
ymin : the world y-coordinate at the bottom left corner
of the viewport.
ymax : the world y-coordinate at the top right corner
of the viewport (note ymax may be less than ymin).
just : 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 : 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.
Changes the size and position of the viewport, specifying
the viewport in normalized device coordinates. Normalized
device coordinates run from 0 to 1 in each dimension. The
viewport is the rectangle on the view surface "through"
which one views the graph. All the PG routines which plot lines
etc. plot them within the viewport, and lines are truncated at
the edge of the viewport (except for axes, labels etc drawn with
pgBox or pgLabel). The region of world space (the coordinate
space of the graph) which is visible through the viewport is
specified by a call to pgWindow. It is legal to request a
viewport larger than the view surface; only the part which
appears on the view surface will be plotted.
Calling sequence:
pgVport <xleft> <xright> <ybot> <ytop>
where:
xleft : x-coordinate of left hand edge of viewport, in NDC.
xright : x-coordinate of right hand edge of viewport,
in NDC.
ybot : y-coordinate of bottom edge of viewport, in NDC.
ytop : y-coordinate of top edge of viewport, in NDC.
Changes the size and position of the viewport, specifying
the viewport in physical device coordinates (inches). The
viewport is the rectangle on the view surface "through"
which one views the graph. All the PG routines which plot lines
etc. plot them within the viewport, and lines are truncated at
the edge of the viewport (except for axes, labels etc drawn with
pgBox or pgLabel). The region of world space (the coordinate
space of the graph) which is visible through the viewport is
specified by a call to pgWindow. It is legal to request a
viewport larger than the view surface; only the part which
appears on the view surface will be plotted.
Calling sequence:
pgVsize <xleft> <xright> <ybot> <ytop>
where:
xleft : x-coordinate of left hand edge of viewport, in
inches from left edge of view surface.
xright : x-coordinate of right hand edge of viewport, in
inches from left edge of view surface.
ybot : y-coordinate of bottom edge of viewport, in
inches from bottom of view surface.
ytop : y-coordinate of top edge of viewport, in inches
from bottom of view surface.
Defines the viewport to be the standard viewport. The standard
viewport is the full area of the view surface (or subpage),
less a margin of 4 character heights all round for labeling.
It thus depends on the current character size, set by pgSch.
Calling sequence:
pgVstand
Changes the window in world coordinate space that is to be mapped on
to the viewport. Usually pgWindow is called automatically by pgEnv,
but it may be called directly by the user.
Calling sequence:
pgWindow <x1> <x2> <y1> <y2>
where:
x1 : the x-coordinate of the bottom left corner of the viewport.
x2 : the x-coordinate of the top right corner of the viewport
(note x2 may be less than x1).
y1 : the y-coordinate of the bottom left corner of the viewport.
y2 : the y-coordinate of the top right corner of the viewport
(note y2 may be less than y1).
Changes the window in world coordinate space that is to be mapped on
to the viewport, and simultaneously adjust the viewport so that the
world-coordinate scales are equal in x and y. The new viewport is
the largest one that can fit within the previously set viewport
while retaining the required aspect ratio.
Calling sequence:
pgWnad <x1> <x2> <y1> <y2>
where:
x1 : the x-coordinate of the bottom left corner of the viewport.
x2 : the x-coordinate of the top right corner of the viewport
(note x2 may be less than x1).
y1 : the y-coordinate of the bottom left corner of the viewport.
y2 : the y-coordinate of the top right corner of the viewport
(note y2 may be less than y1).
Draws 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.
Calling sequence:
pgDraw <x> <y>
where:
x : world x-coordinate of the end point of the line.
y : world y-coordinate of the end point of the line.
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.
Calling sequence:
pgLine <xpts> <ypts>
where:
xpts : world x-coordinates of the points (1-dimensional array).
ypts : world y-coordinates of the points (1-dimensional array).
For example: pgLine {0.0 0.1 0.2 0.5} {0.0 0.2 0.5 0.9}
The dimension of arrays for X and Y must be equal.
The "pen position" is changed to (X(N),Y(N)) in world coordinates
(if the number of points > 1, if <= 1 nothing is drawn).
Primitive routine to move the "pen" to the point with world
coordinates (X,Y). No line is drawn.
Calling sequence:
pgMove <x> <y>
where:
x : world x-coordinate of the new pen position.
y : world y-coordinate of the new pen position.
Primitive routine to draw Graph Markers (polymarker). The markers
are drawn using the current values of attributes color-index,
line-width, and character-height (character-font applies if the symbol
number is >31). If the point to be marked lies outside the window,
no marker is drawn. The "pen position" is changed to
(xpts(n),ypts(n)) in world coordinates (if n > 0).
Calling sequence:
pgPoint <xpts> <ypts> <symbol>
where:
xpts : world x-coordinates of the points (1-dimensional array).
ypts : world y-coordinates of the points (1-dimensional array).
symbol : code number of the symbol to be drawn at each point:
-1, -2 : a single dot (diameter = current
line width).
-3..-31 : a regular polygon with ABS(symbol)
edges (style set by current fill style).
0..31 : standard marker symbols.
32..127 : ASCII characters (in current font).
e.g. to use letter F as a marker, let
SYMBOL = ICHAR('F').
> 127 : a Hershey symbol number.
For example: pgPoint {0 0.2 0.5} {0.3 0.4 0.5} 12
Note: the dimension of arrays for X and Y must be equal.
If number of elements is 1, X and Y may be scalars (constants or variables).
If number of elements is less than 1, nothing is drawn.
Fill-area primitive routine: shade the interior of a closed
polygon in the current window. 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 polygon is solid-filled
using the current Color Index. If Fill-Area Style is HOLLOW, the
outline of the polygon is drawn using the current line attributes
(color index, line-style, and line-width). Other values of the Fill-
Area attribute may be allowed in future, e.g., for shading with
patterns or hatching. The polygon is clipped at the edge of the
window. The pen position is changed to (xpts(1),ypts(1)) in world
coordinates (if n > 1). If the polygon is not convex, a point is
assumed to lie inside the polygon if a straight line drawn to
infinity intersects and odd number of the polygon's edges.
Calling sequence:
pgPoly <xpts> <ypts>
where:
xpts : world x-coordinates of the vertices (1-dimensional array).
ypts : world y-coordinates of the vertices (1-dimensional array).
For example pgPoly {0.1 0.1 0.5} {0.1 0.5 0.5}
Note: The dimension of arrays xpts and ypts must be equal.
The line will consist of N straight-line segments,
joining points 1 to 2, 2 to 3,... N-1 to N, N to 1.
The number of points should be greater than 2
(if it is 2 or less, nothing will be drawn).
This routine can be used instead of pgPoly for the special case of
drawing a rectangle aligned with the coordinate axes; only two
vertices need be specified instead of four. On most devices, it is
faster to use pgRect than pgPoly for drawing rectangles. The
rectangle has vertices at (x1,y1), (x1,y2), (x2,y2), and (x1,y2).
Calling sequence:
pgRect <x1> <x2> <y1> <y2>
where:
x1, x2 : the horizontal range of the rectangle.
y1, y2 : the vertical range of the rectangle.
Writes labels outside the viewport. This routine is a simple
interface to pgMtext, which should be used if pgLabel is inadequate.
Calling sequence:
pgLabel <xlbl> <ylbl> [toplbl]
where:
xlbl : a label for the x-axis (centered below the viewport).
ylbl : a label for the y-axis (centered to the left of the viewport,
drawn vertically).
toplbl : a label for the entire plot (centered above the viewport).
Writes text at a position specified relative to the viewport (outside
or inside). This routine is useful for annotating graphs. It is used
by routine pgLabel. The text is written using the current values of
attributes color-index, line-width, character-height, and
character-font.
Calling sequence:
pgMtext <side> <disp> <coord> <fjust> <text>
where:
side : 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 : 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 : the location of the character string along the
specified edge of the viewport, as a fraction of
the length of the edge.
fjust : 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 intermediate
placing, but they are not very useful.
text : the text string to be plotted. Trailing spaces are
ignored when justifying the string, but leading
spaces are significant.
Primitive routine for drawing text. The text may be drawn at any
angle with the horizontal, and may be centered or left- or right-
justified at a specified position. Routine pgText provides a
simple interface to pgPtext for horizontal strings. Text is drawn
using the current values of attributes color-index, line-width,
character-height, and character-font. Text is NOT subject to
clipping at the edge of the window.
Calling sequence:
pgPtext <x> <y> <angle> <fjust> <text>
where:
x : world x-coordinate.
y : world y-coordinate. The string is drawn with the
baseline of all the characters passing through
point (x,y); the positioning of the string along
this line is controlled by argument fjust.
angle : angle, in degrees, that the baseline is to make
with the horizontal, increasing counter-clockwise
(0.0 is horizontal).
fjust : controls horizontal justification of the string.
If fjust = 0.0, the string will be left-justified
at the point (x,y); if fjust = 0.5, it will be
centered, and if fjust = 1.0, it will be right
justified. [Other values of fjust give other justifications.]
text : the character string to be plotted.
Writes text. The bottom left corner of the first character is placed
at the specified position, and the text is written horizontally.
This is a simplified interface to the primitive routine pgPtext.
For non-horizontal text, use pgPtext.
Calling sequence:
pgText <x> <y> <text>
where:
x : world x-coordinate of start of string.
y : world y-coordinate of start of string.
text : the character string to be plotted.
Set the Character Font for subsequent text plotting. Four different
fonts are available:
1: (default) a simple single-stroke font ("normal" font)
2: roman font
3: italic font
4: script font
This call determines which font is in effect at the beginning of
each text string. The font can be changed (temporarily) within a text
string by using the escape sequences \fn, \fr, \fi, and \fs for fonts
1, 2, 3, and 4, respectively.
Calling sequence:
pgScf if
where:
if : the font number to be used for subsequent text
plotting (in range 1-4).
Set the character size attribute. The size affects all text and graph
markers drawn later in the program. The default character size is
1.0, corresponding to a character height about 1/40 the height of
the view surface. Changing the character size also scales the length
of tick marks drawn by pgBox and terminals drawn by pgErrx and pgErry.
Calling sequence:
pgSch <size>
where:
size : new character size (dimensionless multiple of the default size).
Sets the Color Index for subsequent plotting, if the output device
permits this. The default color index is 1, usually white on a black
background for video displays or black on a white background for
printer plots. The color index is an integer in the range 0 to a
device-dependent maximum. Color index 0 corresponds to the background
color; lines may be "erased" by overwriting them with color index 0
(if the device permits this).
If the requested color index is not available on the selected device,
color index 1 will be substituted.
The assignment of colors to color indices can be changed with
subroutine pgScr (set color representation). Color indices 0-15
have predefined color representations (see the PGPLOT manual), but
these may be changed with pgScr. Color indices above 15 have no
predefined representations: if these indices are used, pgScr must
be called to define the representation.
Calling sequence:
pgSci <color>
where:
color : the color index to be used for subsequent plotting
on the current device (in range 0-max). If the
index exceeds the device-dependent maximum, the
default color index (1) is used.
Sets color representation: i.e., define the color to be
associated with a color index. Ignored for devices which do not
support variable color or intensity. Color indices 0-15
have predefined color representations (see the PGPLOT manual), but
these may be changed with pgScr. Color indices 16-maximum have no
predefined representations: if these indices are used, pgScr must
be called to define the representation. On monochrome output
devices (e.g. VT125 terminals with monochrome monitors), the
monochrome intensity is computed from the specified Red, Green, Blue
intensities as 0.30*R + 0.59*G + 0.11*B, as in US color television
systems, NTSC encoding. Note that most devices do not have an
infinite range of colors or monochrome intensities available;
the nearest available color is used. Examples: for black,
set CR=CG=CB=0.0; for white, set CR=CG=CB=1.0; for medium gray,
set CR=CG=CB=0.5; for medium yellow, set CR=CG=0.5, CB=0.0.
Calling sequence:
pgScr <ci> <cr> <cg> <cb>
where:
ci : the color index to be defined, in the range 0-max.
If the color index greater than the device
maximum is specified, the call is ignored. Color
index 0 applies to the background color.
cr : red, green, and blue intensities,
cg : in range 0.0 to 1.0.
cb :
Sets the Fill-Area Style attribute for subsequent area-fill by
pgPoly. At present only two styles are available: solid (fill
polygon with solid color of the current color-index), and hollow
(draw outline of polygon only, using current line attributes).
Calling sequence:
pgSfs <fill_style>
where:
fill_style : the fill-area style to be used for subsequent plotting:
fill_style = 1 => solid (default)
fill_style = 2 => hollow
Other values give an error message and are treated as 2.
Sets color representation: i.e., define the color to be
associated with a color index. This routine is equivalent to
pgScr, but the color is defined in the Hue-Lightness-Saturation
model instead of the Red-Green-Blue model.
Calling sequence:
pgShls <ci> <ch> <cl> <cs>
where:
ci : the color index to be defined, in the range 0-max.
If the color index greater than the device
maximum is specified, the call is ignored. Color
index 0 applies to the background color.
ch : hue, in range 0.0 to 360.0.
cl : lightness, in range 0.0 to 1.0.
cs : saturation, in range 0.0 to 1.0.
Sets the line style attribute for subsequent plotting. This
attribute affects line primitives only; it does not affect graph
markers, text, or area fill.
Five different line styles are available, with the following codes:
1 (full line), 2 (dashed), 3 (dot-dash-dot-dash), 4 (dotted),
5 (dash-dot-dot-dot). The default is 1 (normal full line).
Calling sequence:
pgSls <line_style>
where:
line_style : the line-style code for subsequent plotting (in range 1-5).
Sets the line-width attribute. This attribute affects lines, graph
markers, and text. Thick lines are generated by tracing each line
with multiple strokes offset in the direction perpendicular to the
line. The line width is specified by the number of strokes to be
used, which must be in the range 1-201. The actual line width
obtained depends on the device resolution.
Calling sequence:
pgSlw <line_width>
where:
line_width : the number of strokes to be used (in range 1-201).
Plots 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
Calling sequence:
pgBin <x> <data> [D:center | lowedge]
where:
x : abscissa of bins (1-dimensional array).
data : data values of bins (1-dimensional array).
center : if "center", the x values denote the center of the
bin; if "lowedge", the x values denote the lower
edge (in x) of the bin.