PGPLOT

Annotated List of Routines

Version 5.2

Many of the routines that set the values of parameters used by PGPLOT have corresponding inquiry routines that can be used to determine the current parameter values. Most of these routines have names starting PGQ... and are indicated in italics.

Opening, Closing, and Selecting Devices

Use PGOPEN to open a graphical device or file and select it for PGPLOT output, PGCLOS to close the device when graphical output is completed, and PGSLCT to switch subsequent output to a different open device. PGBEG is an alternative to PGOPEN, retained for compatibility with existing programs. PGEND can be used to close all open devices.

PGOPEN : open a graphics device
PGBEG : open a graphics device
PGSLCT : select an open graphics device
PGCLOS : close the selected graphics device
PGEND : close all open graphics devices
PGQID : inquire current device identifier

The following routines can be used to determine what types of graphics device are available - the list of types is installation-dependent.

PGLDEV : list available device types on standard output
PGQNDT : inquire number of available device types (New in version 5.2)
PGQDT : inquire name of n^th available device type (New in version 5.2)

After a graphics device has been opened, the following routines may be used to determine some of its device-dependent characteristics.

PGQINF : inquire PGPLOT general information
PGQCOL : inquire color capability

Controlling the View Surface

Use PGPAGE to start a new page, or PGERAS to clear the screen without starting a new page. On interactive devices, PGPLOT prompts the user before starting a new page unless told not to via PGASK.

PGPAGE : advance to new page
PGERAS : erase all graphics from current page
PGASK : control new page prompting

The size of the view surface is device-dependent and is established when the graphics device is opened. Use PGQVSZ if you need to know the absolute size of the view surface. On some devices, it can be changed by calling PGPAP before starting a new page with PGPAGE. On some devices, the size can be changed (e.g., by a workstation window manager) outside PGPLOT, and PGPLOT detects the change when PGPAGE is used.

PGPAP : change the size of the view surface
PGQVSZ : inquire size of view surface

PGPLOT can divide the view surface into two or more panels; to request this, call PGSUBP after opening the device or before starting a new page. When the view surface is divided into panels, PGPAGE advances to the next panel, only clearing the screen or starting a new page after all the panels have been filled. It is also possible to move to a specific panel by calling PGPANL.

PGSUBP : subdivide view surface into panels
PGPANL : switch to a different panel on the view surface

To improve efficiency by buffering graphical output, group a sequence of PGPLOT routines between PGBBUF and PGEBUF calls. To force a screen update, call PGUPDT.

PGBBUF : begin batch of output (buffer)
PGEBUF : end batch of output (buffer)
PGUPDT : update display

Windows and Viewports

Specify the viewport to indicate where on the device's view surface you want the graph to appear.

PGSVP : set viewport (normalized device coordinates)
PGVSIZ : set viewport (inches)
PGVSTD : set standard (default) viewport
PGQVP : inquire viewport size and position

Specify the window to define the range of your world-coordinate space that will be visible in the viewport.

PGSWIN : set window
PGWNAD : set window and adjust viewport to same aspect ratio
PGQWIN : inquire window boundary coordinates

Normally all PGPLOT primitives except text are ``clipped'' at the edge of the viewport; use PGSCLP to disable or re-enable clipping.

PGSCLP : enable or disable clipping at edge of viewport (New in version 5.2)
PGQCLP : inquire clipping status (New in version 5.2)

Primitives

Lines

Straight lines and curves made up of straight-line segments can be specified either segment by segment (PGMOVE, PGDRAW) or by a list of points to be joined together (PGLINE).

PGMOVE : move pen (change current pen position)
PGDRAW : draw a line from the current pen position to a point
PGQPOS : inquire current pen position
PGLINE : draw a polyline (curve defined by line-segments)

Polygons and Filled Areas

Closed polygons, circles, and rectangles canbe outlined, filled with solid color, or shaded using hatching, depending on the current fill-area attributes.

PGPOLY : draw a polygon, using fill-area attrutes
PGCIRC : draw a circle, using fill-area attributes
PGRECT : draw a rectangle, using fill-area attributes

Graph Markers

Use PGPT1 to mark a single point, PGPT to mark several points with the same symbol, or PGPNTS to mark several points with different symbols.

PGPT1 : draw one graph marker (New in version 5.2)
PGPT : draw several graph markers
PGPNTS : draw several graph markers, not all the same

Text

The basic routine for drawing text is PGPTXT. PGTEXT provides a simplified interface for the commonest case.

PGTEXT : write text (horizontal, left-justified)
PGPTXT : write text at arbitrary position and angle

In order to correctly position text on a graph, it may be necessary to determine the space occupied by a text string without actually drawing it.

PGLEN : find length of a string in a variety of units
PGQTXT : find bounding box of text string

Arrows

An arrow is made up of a line (for the shaft) and a polygon (for the head), but can be regarded as a separate primitive.

PGARRO : draw an arrow

Attributes

Color

PGSCI : set color index
PGQCI : inquire color index
PGSCR : set color representation
PGQCR : inquire color representation
PGSCRN : set color representation by name
PGSHLS : set color representation using HLS system

Line Attributes

PGSLS : set line style
PGQLS : inquire line style
PGSLW : set line width
PGQLW : inquire line width

Text and Marker Attributes

PGSCF : set character font
PGQCF : inquire character font
PGSCH : set character height
PGQCH : inquire character height
PGQCS : inquire character height in a variety of units
PGSTBG : set text background color index
PGQTBG : inquire text background color index

Fill-Area Attributes

PGSFS : set fill-area style
PGQFS : inquire fill-area style
PGSHS : set hatching style
PGQHS : inquire hatching style

Arrow Attributes

PGSAH : set arrow-head style
PGQAH : inquire arrow-head style

Saving and Restoring Attributes

PGSAVE : save PGPLOT attributes
PGUNSA : restore PGPLOT attributes

Axes, Boxes, and Labels

To label a graph with axes or a box around the viewport, use PGBOX (or PGTBOX if one or both coordinates are to be treated as a time or angle). More complete control over axes is possible with PGAXIS, including drawing axes that are not parallel to the edges of the viewport. If you need complete control over how an axis is labeled, e.g., for non-linear or curved axes, draw the axis with line-drawing routines and then label it with PGTICK.

PGBOX : draw labeled frame around viewport
PGTBOX : draw frame and write (DD) HH MM SS.S labelling
PGAXIS : draw an axis (New in version 5.2)
PGTICK : draw a single tick mark on an axis (New in version 5.2)

To place labels around the edges of the viewport, use PGLAB or PGMTXT.

PGLAB : write labels for x-axis, y-axis, and top of plot
PGMTXT : write text at position relative to viewport

XY Plots

Error Bars

PGERRB : horizontal or vertical error bars
PGERR1 : single horizontal or vertical error bar (New in version 5.2)
PGERRX : horizontal error bars
PGERRY : vertical error bars

Curves Defined by Functions

PGFUNT : function defined by X = F(T), Y = G(T)
PGFUNX : function defined by Y = F(X)
PGFUNY : function defined by X = F(Y)

Histograms

PGBIN : histogram of binned data
PGHI2D : cross-sections through a 2D data array
PGHIST : histogram of unbinned data

Contour Maps

PGCONB : contour map of a 2D data array, with blanking
PGCONF : fill between two contours (New in version 5.2)
PGCONL : label contour map of a 2D data array
PGCONS : contour map of a 2D data array (fast algorithm)
PGCONT : contour map of a 2D data array (contour-following)
PGCONX : contour map of a 2D data array (non rectangular)

Images

PGIMAG : color image from a 2D data array
PGSCIR : set color index range
PGQCIR : inquire color index range
PGCTAB : install the color table to be used by PGIMAG
PGGRAY : gray-scale map of a 2D data array
PGPIXL : draw pixels
PGSITF : set image transfer function
PGQITF : inquire image transfer function
PGWEDG : annotate an image plot with a wedge

Vector Plots

PGVECT : vector map of a 2D data array, with blanking

Interactive Graphics

PGCURS : read cursor position
PGBAND : read cursor position, with anchor
PGLCUR : draw a line using the cursor
PGNCUR : mark a set of points using the cursor
PGOLIN : mark a set of points using the cursor
PGSCRL : scroll window (New in version 5.2)

Miscellaneous Routines

PGNUMB : convert a number into a plottable character string
PGRND : find the smallest `round' number greater than x
PGRNGE : choose axis limits
PGETXT : erase text from graphics display
PGIDEN : write username, date, and time at bottom of plot