 News |
FAQ
|
| Search
|
Home
|
| Getting Started | Documentation | Glish | Learn More | Programming | Contact Us |
|
| Version 1.9 Build 1556 |
|
Much of this section is directly taken from the standard PGPLOT documentation. The documentation here is the summary documentation. Most of the PGPLOT User's Guide also applies to Glish/PGPLOT and is worthwhile reading for programmers who do not already know the PGPLOT subroutine library.
pg->arro (X1, Y1, X2, Y2)
Float 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 SCH. The default size is 1/40th smaller than the width or height of the view surface. The appearance of the arrowhead (shape and solid or open) is controlled by routine SAH.
Arguments: X1, Y1 : world coordinates of the tail of the arrow. X2, Y2 : world coordinates of the head of the arrow.
pg->ask (FLAG)
Boolean FLAG
Change the ``prompt state'' of PGPLOT. If the prompt state is ON, PAGE types ``Type RETURN for next page:'' and waits for you to type a carriage-return before starting a new page. The initial prompt state (after a call to BEG) is ON for interactive devices. Prompt state is always OFF for non-interactive devices.
Note: this command goes directly to the (pseudo) terminal, not through Glish.
Arguments:
FLAG : if T, and the device is an interactive device, the prompt
state is set to ON. If F, the prompt state is set
to OFF.
pg->bbuf ()
Begin saving graphical output commands in an internal buffer; the commands are held until a matching EBUF call (or until the buffer is emptied by UPDT). This can greatly improve the efficiency of PGPLOT. BBUF increments an internal counter, while EBUF decrements this counter and flushes the buffer to the output device when the counter drops to zero. BBUF and EBUF calls should always be paired.
Arguments: none.
Boolean OK := pg->beg (UNIT, FILE, NXSUB, NYSUB)
Integer UNIT, NXSUB, NYSUB
String FILE
Begin PGPLOT, open the plot file. A call to BEG 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:
OK : a status return value. A value of T indicates successful
completion, any other value indicates an error. In the event
of an error a message is written on the standard error unit.
Arguments:
UNIT : this argument is ignored by BEG (use zero).
FILE : the ``device specification'' for the plot device. Device
specifications are installation dependent, but usually have
the form ``device/type'' or ``file/type''. If this argument
is a question mark ('?'), BEG prompts you to supply
a string. If the argument is a blank string (' '), BEG
uses the value of environment variable PGPLOT_DEV.
NXSUB : the number of subdivisions of the view surface in X (>0 or
<0).
NYSUB : 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, PAGE 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.
pg->bin (X, DATA, CENTER)
Float X[], DATA[]
Boolean 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.
NOTE: bin has a hard limit of 200 bins built into the underlying PGPLOT library.
Arguments:
X : abscissae of bins.
DATA : data values of bins.
CENTER : if T, the X values denote the center of the bin; if F, the X
values denote the lower edge (in X) of the bin.
pg->box (XOPT, XTICK, NXSUB, YOPT, YTICK, NYSUB)
String XOPT, YOPT
Float XTICK, YTICK
Integer NXSUB, NYSUB
Annotate the viewport with frame, axes, numeric labels, etc. You call BOX using ENV, but also may be called explicitly.
Arguments:
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 BOX, so that there
are 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 BOX.
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; i.e. 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.
1 : force decimal labelling, instead of automatic choice (see NUMB).
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
upon which are requested. If none of ABC is specified, tick marks are not
drawn. When ENV calls BOX, 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, eight 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 TBOX.
pg->circ (XCENT, YCENT, RADIUS)
Float 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 : world x-coordinate of the center of the circle. YCENT : world y-coordinate of the center of the circle. RADIUS : radius of circle (world coordinates).
pg->clos ()
Close the currently selected graphics device. After the device is closed, either another open device must be selected with SLCT or another device must be opened with OPEN before any further plotting can be done. If the call to CLOS 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 END instead.]
Arguments: none.
pg->conb (A, C, TR, BLANK)
Float A[*,*], C[], TR[6], BLANK
Draw a contour map of an array. This routine is the same as CONS, except that array elements that have the ``magic value'' defined by 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 : data array.
C : array of contour levels (in the same units as the data in
array A).
TR : 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 : elements of array A that are exactly equal to this value are
ignored (blanked).
pg->conl (A, C, TR, LABEL, INTVAL, MININT)
Float A[*,*], C, TR[6]
String LABEL
Integer INTVAL, MININT
Label a contour map drawn with routine CONT. Routine CONT should be called first to draw the contour lines, then this routine 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 nine arguments are the same as those supplied to CONT, and normally should be identical to those used with CONT. Note that only one contour level can be specified; to label more contours, call CONL 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 is written in the MININT'th cell, and additional labels written every INTVAL cells thereafter. A contour that crosses less than MININT cells are not labelled. Some experimentation may be needed to get satisfactory results; a good place to start is INTVAL = 20, MININT = 10.
Arguments:
A : data array.
C : the level of the contour to be labelled (one of the values
given to CONT).
TR : 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 : character strings to be used to label the specified contour.
Leading and trailing blank spaces are ignored.
INTVAL : spacing along the contour between labels, in grid cells.
MININT : contours that cross less than MININT cells are not
labelled.
pg->cons (A, C, TR)
Float A[*,*], 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 CONT, 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 CONT, especially if several contour levels are drawn with one call of CONS.
Arguments:
A : data array.
C : array of contour levels (in the same units as the data in array
A).
TR : 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.
pg->cont (A, C, NC, TR)
Float A[*,*], C[], TR[6]
Boolean NC
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 T (see below), the line style is set by CONT to 1 (solid) for positive contours or 2 (dashed) for negative contours.
Arguments:
A : data array.
C : array of contour levels.
NC : line-style for contour lines. If NC is T, the line style is
chosen as described above. If NC is F, the current setting of
line-style is used for all of the contours.
TR : 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.
pg->ctab (L, R, G, B, CONTRA, BRIGHT)
Float L[], R[], G[], B[], CONTRA, BRIGHT
Use the given color table to change the color representations of all color indexes marked for use by IMAG. To change which color indexes are thus marked, call SCIR before calling CTAB or IMAG. On devices that can change the color representations of previously plotted graphics, CTAB also changes the colors of existing graphics that were plotted with the marked color indexes. This feature then can be combined with BAND to interactively manipulate the displayed colors of data previously plotted with IMAG.
Limitations:
Arguments:
L : an array of 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 are not visible if
CONTRA = 1.0 and BRIGHT = 0.5.
R : an array of normalized red intensities.
G : an array of normalized green intensities.
B : an array of normalized blue intensities.
CONTRA : the contrast of the color ramp (normally 1.0).
BRIGHT : brightness at the center colorindex (normally 0.5).
pg->draw (X, Y)
Float 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 : world x-coordinate of the end point of the line. Y : world y-coordinate of the end point of the line.
pg->ebuf ()
A call to EBUF marks the end of a batch of graphical output begun with the last call of BBUF. BBUF and EBUF calls should always be paired. Each call to BBUF increments a counter, while each call to EBUF decrements the counter. When the counter reaches 0, the batch of output is written on the output device.
Arguments: none.
pg->end ()
Terminate PGPLOT, close and release any open graphics devices. If the call to END is omitted, some or all of any open plots may be lost.
NOTE: At present, there is no way to reopen the PGPLOT widget once end is called. You can reopen PostScript devices.
Arguments: none.
pg->env (XMIN, XMAX, YMIN, YMAX, JUST, AXIS)
Float XMIN, XMAX, YMIN, YMAX
Integer JUST, AXIS
Set PGPLOT ``Plotter Environment.'' ENV establishes the scaling for subsequent calls to PT, LINE, etc. The plotter is advanced to a new page or panel, clearing the screen if necessary. If the ``prompt state'' is ON (see ASK), confirmation is requested from you before clearing the screen. If requested, a box, axes, labels, etc. are drawn according to the setting of argument AXIS.
A call to ENV can be replaced by successive calls to PAGE, SVP, SWIN and BOX.
Arguments:
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 BOX. ENV can be persuaded to call
BOX 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
pg->eras ()
Erase all graphics from the current page or panel.
Arguments: none.
pg->errb (DIR, X, Y, E, T)
Integer DIR
Float X[], Y[], E[], 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 PT is required.
Arguments:
DIR : 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).
X : world x-coordinates of the data.
Y : world y-coordinates of the data.
E : value of error bar distance to be added to the data position in
world coordinates.
T : 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
are drawn.
pg->errx (X1, X2, Y, T)
Float X1[], X2[], Y[], 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 PT or ERRY is required.
Arguments:
X1 : world x-coordinates of lower end of the error bars.
X2 : world x-coordinates of upper end of the error bars.
Y : world y-coordinates of the data.
T : 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 are drawn.
pg->erry (X, Y1, Y2, T)
Float X[], Y1[], Y2[], 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 PT or ERRX is required.
Arguments:
X : world x-coordinates of the data.
Y1 : world y-coordinates of top end of the error bars.
Y2 : world y-coordinates of bottom end of the error bars.
T : 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 are drawn.
pg->gray (A, FG, BG, TR)
Float A[*,*], FG, BG, TR[6]
Draw gray-scale map of an array in current window. The Array A 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.
GRAY uses two different algorithms, depending upon how many color indices are available in the color index range specified for images. (This range is set with routine SCIR, and the current or default range can be queried by calling routine QCIR.)
If sixteen or more color indices are available, GRAY 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 IMAG to draw the image using these color indices. In this mode, the shaded region is ``opaque'': every pixel is assigned a color.
If less than sixteen color indices are available, GRAY uses only color index 1, and uses a ``dithering'' algorithm to fill in pixels, with the shade (computed as above) determining the faction of pixels that are filled. In this mode the shaded region is ``transparent'' and allows previously-drawn graphics to show through.
The transformation matrix TR is used to calculate the world coordinates of the center of the ``cell'' that represents each 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 GRAY are given by applying this transformation to (I1 - 0.5, J1 - 0.5), (I2 + 0.5, J2 + 0.5).
Arguments:
A : the array to be plotted.
FG : the array value which is to appear with the foreground color
(corresponding to color index 1).
BG : the array value which is to appear with the background color
(corresponding to color index 0).
TR : transformation matrix between array grid and world coordinates.
pg->hi2d (DATA, X, IOFF, BIAS, CENTER, YLIMS)
Float DATA[*,*], X[], BIAS, YLIMS[]
Integer IOFF
Boolean 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 ENV may have to be changed to allow for the increased X range that is needed.
Arguments:
DATA : the data array to be plotted.
X : 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 : 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 : 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 : if T, the X values denote the center of the bins; if F, the X
values denote the lower edges (in X) of the bins.
YLIMS : workspace. Should be an array of at least (IX2 - IX1 + 1)
elements.
pg->hist (DATA, DATMIN, DATMAX, NBIN, PGFLAG)
Float DATA[], DATMIN, DATMAX
Integer NBIN, PGFLAG
Draw a histogram of the values in array DATA in the range DATMIN to DATMAX using NBIN bins. Note that array elements which fall exactly on the boundary between two bins are 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 are not counted at all.
Arguments:
DATA : the data values.
DATMIN : the minimum data value for the histogram.
DATMAX : the maximum data value for the histogram.
NBIN : 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 HIST. NBIN may not exceed
200.
PGFLAG : if PGFLAG = 1, the histogram is plotted in the current
window and viewport; if PGFLAG = 0, ENV is called
automatically by HIST to start a new plot (the x-limits of
the window are DATMIN and DATMAX; the y-limits are
chosen automatically. IF PGFLAG = 2,3 the histogram is
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 BIN.
pg->iden ()
Write username, date, and time at bottom of plot.
Arguments: none.
pg->imag (A, A1, A2, TR)
Float A[*,*], A1, A2, TR[6]
Draw a color image of an array in current window. The array A defined 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 SCIR before IMAG. The default values for C1 and C2 are device-dependent; these values can be determined by calling QCIR. Note that color representations should be assigned to color indices C1 to C2 by calling SCR before calling IMAG. On some devices (but not all), the color representation can be changed after the call to IMAG by calling SCR 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 SITF before IMAG; the default is linear.
On devices which have no available color indices (C1 > C2), IMAG 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 ``opaque,'' 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 ``cell'' that represents each 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 IMAG are given by applying this transformation to (-0.5, -0.5), (A::shape[1] + 0.5, A::shape[2] + 0.5).
Arguments: A : the array to be plotted. A1 : the array value which is to appear with shade C1. A2 : the array value which is to appear with shade C2. TR : transformation matrix between array grid and world coordinates.
pg->lab (XLBL, YLBL, TOPLBL)
String XLBL, YLBL, TOPLBL
Write labels outside the viewport. This routine is a simple interface to MTXT, which should be used if LAB is inadequate.
Arguments:
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).
pg->ldev ()
Writes a list to the terminal of all device types known to the current version of PGPLOT.
Arguments: none.
Float [XL, YL] := pg->len (UNITS, STRING)
Integer UNITS
String STRING
Work out length of a string in x and y directions
Returns:
XL : length of string in x direction.
YL : length of string in y direction.
Arguments:
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.
pg->line (XPTS, YPTS)
Float 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:
XPTS : world x-coordinates of the points.
YPTS : world y-coordinates of the points.
Inferred:
N : number of points defining the line; the line consists of (N -
1) straight-line segments.
The ``pen position'' is changed to (X(N), Y(N)) in world coordinates
(if N > 1).
pg->move (X, Y)
Float X, Y
Primitive routine to move the ``pen'' to the point with world coordinates (X, Y). No line is drawn.
Arguments: X : world x-coordinate of the new pen position. Y : world y-coordinate of the new pen position.
pg->mtxt (SIDE, DISP, COORD, FJUST, TEXT)
String SIDE, TEXT
Float 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 LAB. The text is written using the current values of attributes color-index, line-width, character-height, and character-font.
Arguments:
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 is placed at COORD; if JUST
= 0.5, the center of the string is placed at COORD; if
JUST = 1.0, the right-hand end of the string is placed
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.
String STRING := pg->numb (MM, PP, FORM)
Integer MM, PP, FORM
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 are 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 BOX to create numeric labels for a plot.
Formatting rules:
Returns:
STRING : the formatted character string, left justified. If an
internal error occurs, a single asterisk is returned.
Arguments:
MM
PP : the value to be formatted is MM * 10 ** PP.
FORM : controls how the number is formatted:
FORM = 0 -- use either decimal or exponential;
FORM = 1 -- use decimal notation;
FORM = 2 -- use exponential notation.
Integer ISTAT := pg->open (DEVICE)
String 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 SLCT or the device is closed with CLOS.
The value returned by OPEN should be tested to ensure that the device was opened successfully, e.g.:
istat := pg->open ('plot.ps/PS');
if (istat <= 0) fail;
The DEVICE argument is a character constant or variable; its value should be one of the following:
In cases (5) and (6), the device specification is read from the standard input. You should respond to the prompt with a device specification of the form (1), (2), or (3). If you type a question-mark in response to the prompt, a list of available device types is displayed and the prompt is re-issued. If you supply an invalid device specification, the prompt is re-issued. If you respond with an end-of-file character, e.g., ctrl-D in UNIX, program execution is aborted; this avoids the possibility of an infinite prompting loop. You should avoid use of PGPLOT-prompting if this behavior is not desirable.
The device type is case-insensitive (e.g., '/ps' and '/PS' are equivalent). The device or file name may be case-sensitive in some operating systems.
Examples of valid DEVICE arguments:
'plot.ps/ps', 'dir/plot.ps/ps', 'dir/plot.ps/ps'
'/ps' (PGPLOT interprets this as 'pgplot.ps/ps')
'plot.ps' (if PGPLOT_TYPE is defined as 'ps', PGPLOT interprets
this as 'plot.ps/ps')
' ' (if PGPLOT_DEV is defined)
'? '
'?Device specification for PGPLOT: '
NOTE: At present, there is no way to reopen the PGPLOT widget once end is called. You can reopen PostScript devices.
[This routine was added to PGPLOT in Version 5.1.0. Older programs use BEG instead.]
Returns:
ISTAT : returns either a positive value, the identifier of the
graphics device for use with SLCT, or a 0 or negative value
indicating an error. In the event of error a message is
written on the standard error unit.
Arguments:
DEVICE : the 'device specification' for the plot device (see above).
pg->page ()
Advance plotter to a new page or panel, clearing the screen if necessary. If the ``prompt state'' is ON (see ASK), confirmation is requested from you before clearing the screen. If the view surface has been subdivided into panels with BEG or SUBP, then PAGE advances to the next panel, and if the current panel is the last on the page, PAGE clears the screen or starts a new sheet of paper. PAGE does not change the PGPLOT window or the viewport (in normalized device coordinates); but note that if the size of the view-surface is changed externally (e.g., by a workstation window manager) the size of the viewport is chnaged in proportion.
Arguments: none.
pg->panl (IX, IY)
Integer IX, IY
Start plotting in a different panel. If the view surface has been divided into panels by BEG or SUBP, this routine can be used to move to a different panel. Note that PGPLOT does not remember what viewport and window were used in each panel; these should be reset if necessary after calling PANL. Nor does PGPLOT clear the panel: call ERAS after calling PANL to do this.
Arguments:
IX : the horizontal index of the panel (in the range 1 <= IX <=
number of panels in horizontal direction).
IY : the vertical index of the panel (in the range 1 <= IY <= number
of panels in horizontal direction).
pg->pap (WIDTH, ASPECT)
Float WIDTH, ASPECT
This routine changes the size of the view surface (``paper size'') 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.
This routine should be called either immediately after BEG or immediately before PAGE. The new size applies to all subsequent images until the next call to PAP.
Arguments:
WIDTH : the requested width of the view surface in inches; if WIDTH
= 0.0, PAP obtains the largest view surface available
consistent with argument ASPECT. (1 inch = 25.4 mm.)
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.
pg->pixl (IA, X1, X2, Y1, Y2)
Integer IA[*,*]
Float X1, X2, Y1, Y2
Draw lots of solid-filled (tiny) rectangles aligned with the coordinate axes. Best performance is achieved when output is directed to a pixel-oriented device and the rectangles coincide with the pixels on the device. In other cases, pixel output is emulated.
The array IA is mapped onto world-coordinate rectangle defined by X1, X2, Y1 and Y2. This rectangle is divided into NX * NY small rectangles. Each of these small rectangles is solid-filled with the color index specified by the corresponding element of IA.
On most devices, the output region is ``opaque,'' i.e., it obscures all graphical elements previously drawn in the region. But on devices that do not have erase capability, the background shade is ``transparent'' and allows previously-drawn graphics to show through.
Arguments:
IA : the array to be plotted.
X1, Y1 : world coordinates of one corner of the output region.
X2, Y2 : world coordinates of the opposite corner of the output
region.
Inferred:
NX, NY : the first and second dimensions of array IA, respectively.
pg->pnts (X, Y, SYMBOL)
Float X[], Y[]
Integer SYMBOL[]
Draw Graph Markers. Unlike PT, this routine can draw a different symbol at each point. 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).
Arguments:
X : world x-coordinate of the points.
Y : world y-coordinate of the points.
SYMBOL : code number of the symbol to be plotted at each point (see
PT).
Inferred:
N : number of points to mark.
pg->poly (XPTS, YPTS)
Float XPTS[], YPTS[]
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 (see SFS). 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.
Arguments:
XPTS : world x-coordinates of the vertices.
YPTS : world y-coordinates of the vertices.
Inferred:
N : number of points defining the polygon; the line consists of N
straight-line segments, joining points 1 to 2, 2 to 3, ... N-1
to N, N to 1.
pg->pt (XPTS, YPTS, SYMBOL)
Float XPTS[], YPTS[]
Integer SYMBOL
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).
Arguments:
XPTS : world x-coordinates of the points.
YPTS : world y-coordinates of the points.
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.
Inferred:
N : number of points to mark.
pg->ptxt (X, Y, ANGLE, FJUST, TEXT)
Float X, Y, ANGLE, FJUST
String TEXT
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 TEXT provides a simple interface to PTXT 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.
Arguments:
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 is left-justified at the point (X, Y);
if FJUST = 0.5, it is centered, and if FJUST = 1.0, it
is right justified. [Other values of FJUST give other
justifications.]
TEXT : the character string to be plotted.
Float [FS, ANGLE, VENT] := pg->qah ()
Integer FS (But returned in a float array.)
Float ANGLE, VENT
Query the style to be used for arrowheads drawn with routine ARRO.
Returns:
FS : FS = 1 => filled; FS = 2 => outline.
ANGLE : the acute angle of the arrow point, in degrees.
VENT : the fraction of the triangular arrow-head that is cut away
from the back.
Integer FONT := pg->qcf ()
Query the current Character Font (set by routine SCF).
Returns: FONT : the current font number (in range 1-4).
Float SIZE := pg->qch ()
Query the Character Size attribute (set by routine SCH).
Returns:
SIZE : current character size (dimensionless multiple of the default
size).
Integer CI := pg->qci ()
Query the Color Index attribute (set by routine SCI).
Returns:
CI : the current color index (in range 0-max). This is the color
index actually in use, and may differ from the color index last
requested by SCI if that index is not available on the output
device.
Integer [ICILO, ICIHI] := pg->qcir ()
Query the color index range to be used for producing images with GRAY or IMAG, as set by routine SCIR or by device default.
Returns: ICILO : the lowest color index to use for images. ICIHI : the highest color index to use for images.
Integer [CI1, CI2] := pg->qcol ()
Query the range of color indices available on the current device.
Returns:
CI1 : the minimum available color index. This is either 0 if
the device can write in the background color, or 1 if not.
CI2 : the maximum available color index. This is 1 if the
device has no color capability, or a larger number (e.g., 3, 7,
15, 255).
Float [CR, CG, CB] := pg->qcr (CI)
Integer CI
Query the RGB colors associated with a color index.
Returns: CR : red, green and blue intensities in the range 0.0 to 1.0. CG CB Arguments: CI : color index.
Float [XCH, YCH] := pg->qcs (UNITS)
Integer UNITS
Return the current PGPLOT character height in a variety of units. This routine provides facilities that are not available via QCH. Use QCS if the character height is required in units other than those used in SCH.
The PGPLOT ``character height'' is a dimension that scales with the size of the view surface and with the scale-factor specified with routine SCH. The default value is 1/40th of the height or width of the view surface (whichever is less); this value is then multiplied by the scale-factor supplied with SCH. Note that it is a nominal height only; the actual character size depends on the font and is usually somewhat smaller.
Returns:
XCH : the character height for text written with a vertical
baseline.
YCH : the character height for text written with a horizontal
baseline (the usual case).
Arguments:
UNITS : used to specify the units of the output value:
UNITS = 0 : normalized device coordinates;
UNITS = 1 : inches;
UNITS = 2 : millimeters;
UNITS = 3 : pixels;
UNITS = 4 : world coordinates;
Other values give an error message, and are treated as 0.
The character height is returned in both XCH and YCH.
If UNITS = 1 or UNITS = 2, XCH and YCH both receive the same value.
If UNITS = 3, XCH receives the height in horizontal pixel units, and YCH receives the height in vertical pixel units; on devices for which the pixels are not square, XCH and YCH will be different.
If UNITS = 4, XCH receives the height in horizontal world coordinates (as used for the x-axis), and YCH receives the height in vertical world coordinates (as used for the y-axis). Unless special care has been taken to achive equal world-coordinate scales on both axes, the values of XCH and YCH will be different.
If UNITS = 0, XCH receives the character height as a fraction of the horizontal dimension of the view surface, and YCH receives the character height as a fraction of the vertical dimension of the view surface.
Integer FS := pg->qfs ()
Query the current Fill-Area Style attribute (set by routine SFS).
Returns:
FS : the current fill-area style:
FS = 1 => solid (default);
FS = 2 => outline;
FS = 3 => hatched;
FS = 4 => cross-hatched.
Float [ANGLE, SEPN, PHASE] := pg->qhs ()
Query the style to be used hatching (fill area with fill-style 3).
Returns:
ANGLE : the angle the hatch lines make with the horizontal, in
degrees, increasing counterclockwise (this is an angle on the
view surface, not in world-coordinate space).
SEPN : the spacing of the hatch lines. The unit spacing is 1
percent of the smaller of the height or width of the view
surface.
PHASE : a float number between 0 and 1; the hatch lines are displaced
by this fraction of SEPN from a fixed reference. Adjacent
regions hatched with the same PHASE have contiguous hatch
lines.
Integer ID := pg->qid ()
This subroutine returns the identifier of the currently selected device, or 0 if no device is selected. The identifier is assigned when OPEN is called to open the device, and may be used as an argument to SLCT. Each open device has a different identifier.
[This routine was added to PGPLOT in Version 5.1.0.]
Returns:
ID : the identifier of the current device, or 0 if no device is
currently selected.
String VALUE := pg->qinf (ITEM)
String ITEM
This routine is used to obtain miscellaneous information about the PGPLOT environment. Input is a character string defining the information required, and output is a character string containing the requested information.
The following item codes are accepted (note that the strings must match exactly, except for case, but only the first eight characters are significant). For items marked *, PGPLOT must be in the OPEN state for the inquiry to succeed. If the inquiry is unsuccessful, either because the item code is not recognized or because the information is not available, a question mark ('?') is returned.
'VERSION' - version of PGPLOT software in use.
'STATE' - status of PGPLOT ('OPEN' if a graphics device is
open for output, 'CLOSED' otherwise).
'USER' - the username associated with the calling program.
'NOW' - current date and time (e.g., '17-FEB-1986 10:04').
'DEVICE' * - current PGPLOT device or file.
'FILE' * - current PGPLOT device or file.
'TYPE' * - device-type of the current PGPLOT device.
'DEV/TYPE' * - current PGPLOT device and type, in a form which is
acceptable as an argument for BEG.
'HARDCOPY' * - is the current device a hardcopy device? ('YES' or
'NO').
'TERMINAL' * - is the current device the user's interactive
terminal? ('YES' or 'NO').
'CURSOR' * - does the current device have a graphics cursor?
('YES' or 'NO').
Returns:
VALUE : returns a character-string containing the requested
information.
Arguments:
ITEM : character string defining the information to be returned; see
above for a list of possible values.
Integer ITF := pg->qitf ()
Return the Image Transfer Function as set by default or by a previous call to SITF. The Image Transfer Function is used by routines IMAG, GRAY, and WEDG.
Returns: ITF : type of transfer function (see SITF).
Integer LS := pg->qls ()
Query the current Line Style attribute (set by routine SLS).
Returns: LS : the current line-style attribute (in range 1-5).
Integer LW := pg->qlw ()
Query the current Line-Width attribute (set by routine SLW).
Returns: LW : the line-width (in range 1-201).
Float [X, Y] := pg->qpos ()
Query the current ``pen'' position in world C coordinates (X, Y).
Returns: X : world x-coordinate of the pen position. Y : world y-coordinate of the pen position.
Integer TBCI := pg->qtbg ()
Query the current Text Background Color Index (set by routine STBG).
Returns: TBCI : receives the current text background color index.
Float [XBOX, YBOX] := pg->qtxt (X, Y, ANGLE, FJUST, TEXT)
Float X, Y, ANGLE, FJUST
String TEXT
Float XBOX[4], YBOX[4]
This routine returns a bounding box for a text string. Instead of drawing the string as routine PTXT does, it returns in XBOX and YBOX the coordinates of the corners of a rectangle parallel to the string baseline that just encloses the string.
If the string is blank or contains no drwable characters, all four elements of XBOX and YBOX are assigned the starting point of the string, (X, Y).
Returns:
XBOX, YBOX : arrays of dimension 4; on output, they
contain the world coordinates of the
bounding box in (XBOX(1), YBOX(1)), ...,
(XBOX(4), YBOX(4)).
Arguments:
X, Y, ANGLE, FJUST, TEXT : these arguments are the same as the
corrresponding arguments in PTXT.
Float [X1, X2, Y1, Y2] := pg->qvp (UNITS)
Integer UNITS
Inquiry routine to determine the current viewport setting. The values returned may be normalized device coordinates, inches, mm, or pixels, depending on the value of the input parameter UNITS.
Returns:
X1 : the x-coordinate of the bottom left corner of the viewport.
X2 : the x-coordinate of the top right corner of the viewport.
Y1 : the y-coordinate of the bottom left corner of the viewport.
Y2 : the y-coordinate of the top right corner of the viewport.
Arguments:
UNITS : used to specify the units of the output parameters:
UNITS = 0 : normalized device coordinates;
UNITS = 1 : inches;
UNITS = 2 : millimeters;
UNITS = 3 : pixels;
Other values give an error message, and are treated as 0.
Float [X1, X2, Y1, Y2] := pg->qvsz (UNITS)
Integer UNITS
Return the window, in a variety of units, defined by the full device view surface (0 -> 1 in normalized device coordinates).
Returns:
X1, X2 : X window.
Y1, Y2 : Y window.
Arguments:
UNITS : 0, 1, 2, 3 for output in normalized device coords, inches,
mm, or absolute device units (dots).
Float [X1, X2, Y1, Y2] := pg->qwin ()
Inquiry routine to determine the current window setting. The values returned are world coordinates.
Returns: X1 : the x-coordinate of the bottom left corner of the window. X2 : the x-coordinate of the top right corner of the window. Y1 : the y-coordinate of the bottom left corner of the window. Y2 : the y-coordinate of the top right corner of the window.
pg->rect (X1, X2, Y1, Y2)
Float X1, X2, Y1, Y2
This routine can be used instead of POLY 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 RECT than POLY for drawing rectangles. The rectangle has vertices at (X1, Y1), (X1, Y2), (X2, Y2), and (X2, Y1).
Arguments: X1, X2 : the horizontal range of the rectangle. Y1, Y2 : the vertical range of the rectangle.
Float RND := pg->rnd (X, NSUB)
Float X
Integer NSUB
Routine to find the smallest ``round'' number larger than x, a ``round'' number being 1, 2 or 5 times a power of 10. If X is negative, RND(X) = -RND(ABS(X)), e.g. RND(8.7) = 10.0, RND(-0.4) = -0.5. If X is zero, the value returned is zero. This routine is used by BOX for choosing tick intervals.
Returns:
RND : the ``round'' number.
Arguments:
X : the number to be rounded.
NSUB : a suitable number of subdivisions for subdividing the ``nice''
number: 2 or 5.
Float [XLO, XHI] := pg->rnge (X1, X2)
Float X1, X2
Choose plotting limits XLO and XHI which encompass the data range X1 to X2.
Returns:
XLO, XHI : suitable values to use as the extremes of a graph axis
(XLO <= X1, XHI >= X2).
Arguments:
X1, X2 : the data range (X1 < X2), ie, the min and max values to be
plotted.
pg->sah (FS, ANGLE, VENT)
Integer FS
Float ANGLE, VENT
Set the style to be used for arrowheads drawn with routine ARRO.
Arguments:
FS : FS = 1 => filled; FS = 2 => outline. Other values are
treated as 2. Default 1.
ANGLE : the acute angle of the arrow point, in degrees; angles in the
range 20.0 to 90.0 give reasonable results. Default 45.0.
VENT : the fraction of the triangular arrow-head that is cut away
from the back. 0.0 gives a triangular wedge arrow-head; 1.0
gives an open >. Values 0.3 to 0.7 give reasonable results.
Default 0.3.
pg->save ()
This routine saves the current PGPLOT attributes in a private storage area. They can be restored by calling UNSA (unsave). Attributes saved are: character font, character height, color index, fill-area style, line style, line width, pen position, arrow-head style, hatching style. Color representation is not saved.
Calls to SAVE and UNSA should always be paired. Up to 20 copies of the attributes may be saved. UNSA always retrieves the last-saved values (last-in first-out stack).
Note that when multiple devices are in use, UNSA retrieves the values saved by the last SAVE call, even if they were for a different device.
Arguments: none.
pg->unsa ()
This routine restores the PGPLOT attributes saved in the last call to SAVE. Usage: CALL UNSA (no arguments). See SAVE.
Arguments: none.
pg->scf (FONT)
Integer FONT
Set the Character Font for subsequent text plotting. Four different fonts are available:
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.
Arguments:
FONT : the font number to be used for subsequent text plotting (in
range 1-4).
pg->sch (SIZE)
Float SIZE
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 BOX and terminals drawn by ERRX and ERRY.
Arguments:
SIZE : new character size (dimensionless multiple of the default
size).
pg->sci (CI)
Integer CI
Set 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 SCR (set color representation). Color indices 0-15 have predefined color representations (see the PGPLOT manual), but these may be changed with SCR. Color indices above 15 have no predefined representations: if these indices are used, SCR must be called to define the representation.
Arguments:
CI : 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.
pg->scir (ICILO, ICIHI)
Integer ICILO, ICIHI
Set the color index range to be used for producing images with GRAY or IMAG. If the range is not all within the range supported by the device, a smaller range is used. The number of different colors available for images is ICIHI-ICILO+1.
Arguments: ICILO : the lowest color index to use for images. ICIHI : the highest color index to use for images.
pg->scr (CI, CR, CG, CB)
Integer CI
Float CR, CG, CB
Set 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 SCR. Color indices 16-maximum have no predefined representations: if these indices are used, SCR 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.
Arguments:
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, in range 0.0 to 1.0.
CG
CB
Integer IER := pg->scrn (CI, NAME)
Integer CI
String NAME
Set 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. This is an alternative to routine SCR. The color representation is defined by name instead of (R, G, B) components.
Color names are defined in an external file which is read the first time that SCRN is called. The name of the external file is found as follows:
If all of these fail to find a file, an error is reported and the routine does nothing.
Each line of the file defines one color, with four blank- or tab-separated fields per line. The first three fields are the R, G, B components, which are integers in the range 0 (zero intensity) to 255 (maximum intensity). The fourth field is the color name. The color name may include embedded blanks. Example:
255 0 0 red 255 105 180 hot pink 255 255 255 white 0 0 0 black
Returns:
IER : returns 0 if the routine was successful, 1 if an error
occurred (either the external file could not be read, or the
requested color was not defined in the file).
Arguments:
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.
NAME : the name of the color to be associated with this color index.
This name must be in the external file. The names are not
case-sensitive. If the color is not listed in the file, the
color representation is not changed.
pg->sfs (FS)
Integer FS
Set the Fill-Area Style attribute for subsequent area-fill by POLY, RECT, or CIRC. Four different styles are available: solid (fill polygon with solid color of the current color-index), outline (draw outline of polygon only, using current line attributes), hatched (shade interior of polygon with parallel lines, using current line attributes), or cross-hatched. The orientation and spacing of hatch lines can be specified with routine SHS (set hatch style).
Arguments:
FS : the fill-area style to be used for subsequent plotting:
FS = 1 => solid (default);
FS = 2 => outline;
FS = 3 => hatched;
FS = 4 => cross-hatched;
Other values give an error message and are treated as 2.
pg->shls (CI, CH, CL, CS)
Integer CI
Float CH, CL, CS
Set color representation: i.e., define the color to be associated with a color index. This routine is equivalent to SCR, but the color is defined in the Hue-Lightness-Saturation model instead of the Red-Green-Blue model. Hue is represented by an angle in degrees, with red at 120, green at 240, and blue at 0 (or 360). Lightness ranges from 0.0 to 1.0, with black at lightness 0.0 and white at lightness 1.0. Saturation ranges from 0.0 (gray) to 1.0 (pure color). Hue is irrelevant when saturation is 0.0.
Examples: H L S R G B
black any 0.0 0.0 0.0 0.0 0.0
white any 1.0 0.0 1.0 1.0 1.0
medium gray any 0.5 0.0 0.5 0.5 0.5
red 120 0.5 1.0 1.0 0.0 0.0
yellow 180 0.5 1.0 1.0 1.0 0.0
pink 120 0.7 0.8 0.94 0.46 0.46
Reference: SIGGRAPH Status Report of the Graphic Standards Planning Committee, Computer Graphics, Vol. 13, No. 3, Association for Computing Machinery, New York, NY, 1979. See also: J. D. Foley et al, ``Computer Graphics: Principles and Practice,'' second edition, Addison-Wesley, 1990, section 13.3.5.
Arguments:
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.
pg->shs (ANGLE, SEPN, PHASE)
Float ANGLE, SEPN, PHASE
Set the style to be used for hatching (fill area with fill-style 3). The default style is ANGLE = 45.0, SEPN = 1.0, PHASE = 0.0.
Arguments:
ANGLE : the angle the hatch lines make with the horizontal, in
degrees, increasing counterclockwise (this is an angle on the
view surface, not in world-coordinate space).
SEPN : the spacing of the hatch lines. The unit spacing is 1
percent of the smaller of the height or width of the view
surface. This should not be zero.
PHASE : a float number between 0 and 1; the hatch lines are displaced
by this fraction of SEPN from a fixed reference. Adjacent
regions hatched with the same PHASE have contiguous hatch
lines. To hatch a region with alternating lines of two
colors, fill the area twice, with PHASE = 0.0 for one color
and PHASE = 0.5 for the other color.
pg->sitf (ITF)
Integer ITF
Set the Image Transfer Function for subsequent images drawn by IMAG, GRAY, or WEDG. The Image Transfer Function is used to map array values into the available range of color indices specified with routine SCIR or (for GRAY on some devices) into dot density.
Arguments:
ITF : type of transfer function:
ITF = 0 : linear;
ITF = 1 : logarithmic;
ITF = 2 : square-root.
pg->slct (ID)
Integer ID
Select one of the open graphics devices and direct subsequent plotting to it. The argument is the device identifier returned by OPEN when the device was opened. If the supplied argument is not a valid identifier of on open graphics device, a warning message is issued and the current selection is unchanged.
[This routine was added to PGPLOT in Version 5.1.0.]
Arguments: ID : identifier of the device to be selected.
pg->sls (LS)
Integer LS
Set 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).
Arguments: LS : the line-style code for subsequent plotting (in range 1-5).
pg->slw (LW)
Integer LW
Set the line-width attribute. This attribute affects lines, graph markers, and text. The line width is specified in units of 1/200 (0.005) inch (about 0.13 mm) and must be an integer in the range 1-201. On some devices, thick lines are generated by tracing each line with multiple strokes offset in the direction perpendicular to the line.
Arguments: LW : width of line, in units of 0.005 inch (0.13 mm) in range 1-201.
pg->stbg (TBCI)
Integer TBCI
Set the Text Background Color Index for subsequent text. By default text does not obscure underlying graphics. If the text background color index is positive, however, text is opaque: the bounding box of the text is filled with the color specified by STBG before drawing the text characters in the current color index set by SCI. Use color index 0 to erase underlying graphics before drawing text.
Arguments:
TBCI : the color index to be used for the background for subsequent
text plotting:
TBCI < 0 => transparent (default);
TBCI >= 0 => text will be drawn on an opaque background with
color index TBCI.
pg->subp (NXSUB, NYSUB)
Integer NXSUB, NYSUB
PGPLOT divides the physical surface of the plotting device (screen, window, or sheet of paper) into NXSUB x NYSUB `panels'. When the view surface is sub-divided in this way, PAGE moves to the next panel, not the next physical page. The initial subdivision of the view surface is set in the call to BEG. When SUBP is called, it forces the next call to PAGE to start a new physical page, subdivided in the manner indicated. No plotting should be done between a call of SUBP and a call of PAGE (or ENV, which calls PAGE).
If NXSUB > 0, PGPLOT uses the panels in row order; if < 0, PGPLOT uses them in column order, e.g.:
NXSUB=3, NYSUB=2 NXSUB=-3, NYSUB=2 +-----+-----+-----+ +-----+-----+-----+ | 1 | 2 | 3 | | 1 | 3 | 5 | +-----+-----+-----+ +-----+-----+-----+ | 4 | 5 | 6 | | 2 | 4 | 6 | +-----+-----+-----+ +-----+-----+-----+
PGPLOT advances from one panels to the next when PAGE is called, clearing the screen or starting a new page when the last panel has been used. It is also possible to jump from one panel to another in random order by calling PANL.
Arguments:
NXSUB : the number of subdivisions of the view surface in X (> 0 or
< 0).
NYSUB : the number of subdivisions of the view surface in Y (> 0).
pg->svp (XLEFT, XRIGHT, YBOT, YTOP)
Float XLEFT, XRIGHT, YBOT, YTOP
Change 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 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 BOX or LAB). The region of world space (the coordinate space of the graph) which is visible through the viewport is specified by a call to SWIN. It is legal to request a viewport larger than the view surface; only the part which appears on the view surface is plotted.
Arguments: 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.
pg->swin (X1, X2, Y1, Y2)
Float X1, X2, Y1, Y2
Change the window in world coordinate space that is to be mapped on to the viewport. Usually SWIN is called automatically by ENV, but it may be called directly by the user.
Arguments:
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).
pg->tbox (XOPT, XTICK, NXSUB, YOPT, YTICK, NYSUB)
String XOPT, YOPT
Float XTICK, YTICK
Integer NXSUB, NYSUB
Draw a box and optionally label one or both axes with (DD) HH MM SS style numeric labels (useful for time or RA - DEC plots). If this style of labelling is desired, then SWIN should have been called previously with the extrema in SECONDS of time.
In the seconds field, you can have at most 3 places after the decimal point, so that 1 ms is the smallest time interval you can time label.
Large numbers are coped with by fields of 6 characters long. Thus you could have times with days or hours as big as 999999. However, in practice, you might have trouble with labels overwriting themselves with such large numbers unless you a) use a small time INTERVAL, b) use a small character size or c) choose your own sparse ticks in the call to TBOX.
TBOX will attempt, when choosing its own ticks, not to overwrite the labels, but this algorithm is not very bright and may fail.
Note that small intervals but large absolute times such as TMIN = 200000.0s and TMAX = 200000.1s will cause the algorithm to fail. This is inherent in PGPLOT's use of single precision and cannot be avoided. In such cases, you should use relative times if possible.
TBOX's labelling philosophy is that the left-most or bottom tick of the axis contains a full label. Thereafter, only changing fields are labelled. Negative fields are given a '-' label, positive fields have none. Axes that have the DD (or HH if the day field is not used) field on each major tick carry the sign on each field. If the axis crosses zero, the zero tick will carry a full label and sign.
This labelling style can cause a little confusion with some special cases, but as long as you know its philosophy, the truth can be divined. Consider an axis with TMIN = 20s, TMAX = -20s. The labels will look like:
+----------+----------+----------+----------+
0h0m20s 10s -0h0m0s 10s 20s
Knowing that the left field always has a full label and that positive fields are unsigned, informs that time is decreasing from left to right, not vice versa. This can become very unclear if you have used the 'F' option, but that is your problem!
Exceptions to this labelling philosophy are when the finest time increment being displayed is hours (with option 'Y') or days. Then all fields carry a label. For example:
+----------+----------+----------+----------+
-10h -8h -6h -4h -2h
TBOX can be used in place of BOX; it calls BOX and only invokes time labelling if requested. Other options are passed intact to BOX.
Arguments:
XOPT : X-options for TBOX. Same as for BOX plus:
'Z' for (DD) HH MM SS.S time labelling.
'Y' means don't include the day field so that labels are
HH MM SS.S rather than DD HH MM SS.S The hours will
accumulate beyond 24 if necessary in this case.
'X' label the HH field as modulo 24. Thus, a label such as
25h 10m would come out as 1h 10m .
'H' means superscript numbers with d, h, m, & s symbols.
'D' means superscript numbers with o, ', & '' symbols.
'F' causes the first label (left- or bottom-most) to be
omitted. Useful for sub-panels that abut each other.
Care is needed because first label carries sign as
well.
'O' means omit leading zeros in numbers < 10, e.g. 3h 3m
1.2s rather than 03h 03m 01.2s. Useful to help save
space on X-axes. The day field does not use this
facility.
YOPT : Y-options for TBOX. See above.
XTICK : X-axis major tick increment. 0.0 for default.
YTICK : Y-axis major tick increment. 0.0 for default. If the 'Z'
option is used then XTICK and/or YTICK must be in seconds.
NXSUB : number of intervals for minor ticks on X-axis. 0 for
default.
NYSUB : number of intervals for minor ticks on Y-axis. 0 for
default.
The regular XOPT and YOPT axis options for BOX are:
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; i.e. 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.
1 : force decimal labelling, instead of automatic choice (see NUMB).
2 : force exponential labelling, instead of automatic.
The default is to write Y-labels parallel to the axis
****************** EXCEPTIONS *******************
Note that:
1) BOX option 'L' (log labels) is ignored with option 'Z'
2) The 'O' option is ignored for the 'V' option as it
makes it impossible to align the labels nicely
3) Option 'Y' is forced with option 'D'
***************************************************************
pg->text (X, Y, TEXT)
Float X, Y
String TEXT
Write 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 PTXT. For non-horizontal text, use PTXT.
Arguments: X : world x-coordinate of start of string. Y : world y-coordinate of start of string. TEXT : the character string to be plotted.
pg->updt ()
Update the graphics display: flush any pending commands to the output device. This routine empties the buffer created by BBUF, but it does not alter the BBUF/EBUF 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.
Arguments: none.
pg->vect (A, B, C, NC, TR, BLANK)
Float A[*,*], B[*,*], C, TR[6], BLANK
Integer NC
Draw a vector map of two arrays. This routine is similar to CONB in that array elements that have the ``magic value'' defined by the argument BLANK are ignored, making gaps in the vector map. The routine may be useful for data measured on most but not all of the points of a grid. Vectors are displayed as arrows; the style of the arrowhead can be set with routine SAH, and the the size of the arrowhead is determined by the current character size, set by SCH.
Arguments:
A : horizontal component data array.
B : vertical component data array.
C : scale factor for vector lengths, if 0.0, C will be set so
that the longest vector is equal to the smaller of TR(2) +
TR(3) and TR(5) + TR(6).
NC : vector positioning code:
< 0 vector head positioned on coordinates;
> 0 vector base positioned on coordinates;
= 0 vector centered on the coordinates.
TR : 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 : elements of arrays A or B that are exactly equal to this
value are ignored (blanked).
pg->vsiz (XLEFT, XRIGHT, YBOT, YTOP)
Float XLEFT, XRIGHT, YBOT, YTOP
Change 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 you view the graph. All the 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 BOX or LAB). The region of world space (the coordinate space of the graph) which is visible through the viewport is specified by a call to SWIN. It is legal to request a viewport larger than the view surface; only the part which appears on the view surface is plotted.
Arguments:
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.
pg->vstd ()
Define the viewport to be the standard viewport. The standard viewport is the full area of the view surface (or panel), less a margin of 4 character heights all round for labelling. It thus depends on the current character size, set by SCH.
Arguments: none.
pg->wedg (SIDE, DISP, WIDTH, FG, BG, LABEL)
String SIDE, LABEL
Float DISP, WIDTH, FG, BG
Plot an annotated grey-scale or color wedge parallel to a given axis of the the current viewport. This routine is designed to provide a brightness/color scale for an image drawn with IMAG or GRAY. The wedge is drawn with the transfer function set by SITF and using the color index range set by SCIR.
Arguments:
SIDE : the first character must be one of the characters 'B', 'L',
'T', or 'R' signifying the Bottom, Left, Top, or Right edge
of the viewport. The second character should be 'I' to use
IMAG to draw the wedge, or 'G' to use GRAY.
DISP : the displacement of the wedge 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.
WIDTH : the total width of the wedge including annotation, in units
of the character height.
FG : the value which appears with shade 1 (``foreground'').
Use the values of FG and BG that were supplied to GRAY or
IMAG.
BG : the value which appears with shade 0 (``background'').
LABEL : optional units label. If no label is required use ' '.
pg->wnad (X1, X2, Y1, Y2)
Float X1, X2, Y1, Y2
Change 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.
Arguments:
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).