PGPLOT Extensions Part I

pgAsk

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.

pgBbuf

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

pgBegin

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

pgEbuf

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

pgEnd

Terminates PGPLOT, closes the plot file and releases the graphics device.

Calling sequence:

pgEnd

pgPage

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

pgPaper

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.

pgUpdt

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

pgBox

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.

pgEnv

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.

pgVport

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.

pgVsize

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.

pgVstand

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

pgWindow

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).

pgWnad

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).

pgDraw

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.

pgLine

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).

pgMove

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.

pgPoint

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.

pgPoly

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).

pgRect

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.

pgLabel

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).

pgMtext

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.

pgPtext

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.

pgText

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.

pgScf

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).

pgSch

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).

pgSci

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.

pgScr

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 :

pgSfs

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.

pgShls

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.

pgSls

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).

pgSlw

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).

pgBin

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.