PGRAF(3)

NAME
gopen, gclear, window, windowno, badset, axes, axesnox, axesnoy, axesnoxy, label, line, mark, fill, fill2, conto, conto2, vector, vector2, grid, grid2, pview, pline, plabel, paxes, pconto, psurface, gpause, gclose, scale, dcon, vscale: C routines to generate pgraf metacode.

SYNOPSIS
#include pgraf.h

file handling:

    gopen()
    This opens a file named pgraf3.out for writing. It must be the first routine called.

    gpause()
    This flushes output to pgraf3.out and creates a pause on graphics terminals so that a screenful of graphics may be examined before proceeding. This routine must also be called before gclose, or the terminal may be left in an odd state.

    gclose()
    This closes pgraf3.out, and must be the last statement called. Open and close pgraf3.out only once -- separate screenfuls by gpause.

screen handling:

    gclear()
    This clears the graphics screen and must be called after gopenandgpause.

    window(nw,xlow,xhigh,ylow,yhigh)
    windowno(nw,xlow,xhigh,ylow,yhigh)
    This defines a window in screen space and draws a box to indicate it. Ten windows may be in use at once -- the window number nw (integer) takes the range 1-10. Window numbers may be reused after everything within a window is plotted. Screen space ranges from 0 to 15 in x and 0 to 10 in y for all graphics devices. The lower and upper bounds, xlow, etc., are of type float. Window initially sets window space to range from 0 to 1 in both x and y. Window must be called after gopen and before any two or three-dimensional graphics. windowno produces a window but no lines are drawn to mark the edges.

two-dimensional plots:

    badset(badlim)
    This routine declares data values in excess of badlim in absolute magnitude to be bad or missing, and hence, not plotted. The default value is 1.e30.

    axes(nw,sxl,sxh,ntx,xlabel,syl,syh,nty,ylabel)
    This routine draws and labels axes in the window nw. Window space is redefined to lower and upper values in x and y by sxl, sxh, syl, and syh (float). The number of tic marks on each axis are given by ntx and nty (integer), and the axis labels are defined by the character strings xlabel and ylabel. If axes are desired in a particular window, this routine should be called before other two or three dimensional graphics routines, as the window space is redefined to make room for labels.

    axesnox(nw,sxl,sxh,ntx,syl,syh,nty,ylabel)
    axesnoy(nw,sxl,sxh,ntx,xlabel,syl,syh,nty)
    axesnoxy(nw,sxl,sxh,ntx,syl,syh,nty)
    These routines function like axes but the x, the y, and both axis labels respectively are omitted.

    label(nw,x,y,text)
    This routine writes a label in window nw starting at a location in window space defined by x and y. text is a character string containing the desired label. Newlines will be silently converted into spaces. The maximum length of text is 80 characters.

    line(nw,ltype,num,x,y)
    This routine draws num - 1 (integer) connected line segments in the window space of window nw. The line segment ends are defined by x[num] and y[num] (float). Different styles of lines may be specified by setting ltype (integer). The actual styles may differ from device to device, but for many, 1 = solid, 2 = dashed, 3 = dotted, and 4 = dot dashed. On color devices, adding 4 to the line type yields red lines of the equivalent type, adding 8 yields green lines, and adding 12 yields blue lines. If the absolute value of x or y for a particular point exceeds badlim, it is assumed to mean bad or missing data, and the line segments connected to this point are omitted. (This would be a problem if actual data exceeded this value. However, data this large has to be scaled down anyway, as axis labels cannot be this big.)

    mark(nw,mtype,x,y,size)
    This routine draws a symbol at the specified (x, y) point (float) in the window space of window nw. The various symbols are, mtype (integer) = 1: a plus sign; 2: a times sign; 3: a square; 4: a diamond. Adding 4, 8, or 12 to the mark type yields colors on color devices as for the line type above. If size = 1.0 (float), then each symbol is two character widths across. Varying size varies the symbol size in proportion. If the absolute value of x or y exceeds badlim, this is assumed to represent bad or missing data, and a symbol isn't plotted.

    conto(nw,nx,ny,dz,ltype,v)
    Conto draws a contour plot in the window nw. The line style is set by ltype, as in line. The data from which contours are drawn are given in the array v[nx][ny] (float). The contour interval is dz (float), starting from the zero contour. Regions in which the absolute value of v exceeds badlim are assumed to contain bad or missing data, and contours are not plotted.

    conto2(nw,nx,ny,dz,ltype,v,xloc,yloc)
    Conto2 functions like conto except that the values of v are plotted at the points specified by xloc[nx],yloc[ny] (float) instead of being evenly spaced.

    fill(nw,nx,ny,dvl,dvh,ltype,v)
    This routine draws contours at the values dvl and dvh (float) as defined by the array v[nx][ny] (float). Regions where v > dvh are filled with vertical lines, while horizontal lines fill regions with v < dvl. The line style defined by ltype is used. Regions in which the absolute value of v exceeds badlim are assumed to contain bad or missing data, and contours and fill lines are not plotted.

    fill2(nw,nx,ny,dvl,dvh,ltype,v,xloc,yloc)
    Fill2 is identical to fill with the exception that the values of v are plotted on the grid defined by xloc[nx],yloc[ny] (float).

    grid(nw,nx,ny,jx,jy,v)
    Grid prints the values of v[nx][ny] on an appropriate grid in the window nw. jx and jy determine how many grid points to skip in the printing in order to avoid overcrowding. For instance, jx = 3 causes the x values 2, 5, 8, etc. to be printed.

    grid2(nw,nx,ny,jx,jy,v,xloc,yloc)
    Grid2 plots the values of v on the grid defined by xloc[nx],yloc[ny] (float). As in grid jx and jy determine how many points to skip.

    vector(nw,nx,ny,sx,sy,vx,vy)
    This routine draws vectors whose x and y lengths are defined by vx[nx][ny] and vy[nx][ny] (float) in the window nw. The parameters sx and sy define the values of x and y components yielding vectors of size equal to an axis unit. Regions in which the absolute value of vx or vy exceeds badlim are assumed to contain bad or missing data and vectors are not plotted.

    vector2(nw,nx,ny,sx,sy,vx,vy,xloc,yloc)
    Vector2 is the same as vector with the exception that the vectors are plotted on the grid defined by xloc[nx],yloc[ny].

    Note: conto, fill, grid, and vector may be used together in any combination. Conto2, fill2, grid2, and vector2 may also be used together in any combination.

three-dimensional plots:

    pview(nw,xp,yp,zp,xf,yf,zf,zoom)
    This routine defines a perspective point (xp, yp, zp) (float) and a focal point (xf, yf, zf) (float) in 3-D space for window nw. Subsequent routines convert 3-D structures into 2-D perspective views. The focal point is in the middle of the window, and zoom (float) defines the field of view. Roughly speaking, zoom = 2.0 is equivalent to about what an ordinary camera would see. Larger values simulate a telephoto lens. Pview must be called before any other 3-D routines, and after window.

    pline(nw,ltype,num,x,y,z)
    Pline draws the perspective view of a 3-D set of connected line segments defined by x[num], y[num], and z[num] (float). Line style ltype is used as in line.

    plabel(nw,x,y,z,text)
    Plabel places the character string text at the perspective viewpoint defined by (x, y, z) (float) in window nw.

    paxes(nw,sxl,sxh,xst,xlabel,syl,syh,yst,ylabel,szl,szh,zst,zlabel)
    Paxes draws and labels coordinate axes for a 3-D perspective view in window nw. The min and max locations on the x axis are sxl and sxh (float). The y and z axes are treated similarly. The x, y, and z axes are stretched by the factors xst, yst, and zst (float). The labels (strings) are printed at the ends of the axes.

    psurface(nw,nx,ny,ltype,v,xvals,yvals)
    This routine makes a perspective view plot of a function of two variables in window nw. The line type ltype (int) is used to make the plot. The data from which the plot is drawn are given in the array v[nx][ny] (float) and the x and y values over which v is defined are given by the arrays xvals[nx] and yvals[nx] (float).

    pconto(nw,ltype,nx,ny,cval,v,orig,xa,ya)
    This routine defines a contour in a rectangle from the data v[nx][ny] (float) at the value cval (float). The contour is then drawn in perspective view. The location and orientation of the rectangle containing the contour is defined by orig[3], xa[3], and ya[3] (float). The vector orig defines the corner of the rectangle that we denote the origin. The vectors xa and ya then respectively define the x and y edges of the rectangle. Any orientation and location in space for the contour is therefore possible. Note that xa and ya must be normal to each other. Obscure results follow otherwise. Line style ltype is used as in line.

    Note: pline, plabel, paxes, psurface, and pconto may be used in any combination.

information routines:

    scale(n,coarse,array,&max,&min)
    This routine computes max (float) and min (float) values of array[n] (float) and then adjusts these values up and down respectively to integer multiples of coarse (float). It is useful for determining sensible bounds on window space in axes.

    float dcon(nx,ny,nz,v)
    This function returns a value that equals the difference between the maximum and minimum values in the array v[nx][ny] (float) divided by nz (integer). It is useful for determining a sensible contour interval for conto.

    vscale(nx,ny,x,y,&sx,&sy)
    This function determines a reasonable value for the vector scaling factors sx and sy. Nx and ny are the numbers of points (integer) while x and y are the arrays that hold the values at those points.

DESCRIPTION

These routines are a part of the pgraf system for generating device-independent graphics. When linked to a user program, they create a file called pgraf3.out (in the current directory) that contains a metacode data stream. Interpretation by pg(1) yields graphics images on various devices. C versions of the routines are available. To link with a C program, compile with the -lpgc and -lm flags and include <pgraf.h> in the program.

SEE ALSO

pgraf(1) - the metacode interpreter programs

pgraf(5) - the metacode format

BUGS

Pview can't look straight up or down( i.e., in the plus or minus z direction). Label and plabel begin text at the specified point and write the the right. Centered placement might be better, but this is difficult on some graphics devices. Generation of a new pgraf3.out file overwrites any pre-existing file of that name. This means that only one metacode file can exist at a time in any directory unless renaming is done.