PSPLOT Software

PostScript for Technical Drawings

Intended for users interested in generating technical drawings or graphics for technical journals in PostScript format. The manual describes PSPLOT, a library of Fortran-callable subroutines which can be combined in a calling program to produce PostScript plot files. The purpose, syntax, and calling convention of each subroutine is presented , along with plotting examples.

PostScript is a very robust graphics and typesetting language with wide-ranging capabilities. Since the focus of the subroutines in this library is to produce technical drawings, many of the "artistic" features of PostScript have not been addressed or included here.

The name PostScript is a registered trademark of Adobe Systems Incorporated. All instances of the name PostScript in this manual are references to the PostScript language as defined by Adobe Systems Incorporated.

PSPLOT is distributed free of charge for non-commercial use.

A Fortran 95 version of the software is available for download here with associated documentation. This version is not maintained, supported, or guaranteed by NSU OC and any technical inquiries should be directed to dregonjanos@gmail.com.

This section will present the conventions used by the plotting subroutines in the PSPLOT plotting library. This information can be used to create customized plotting subroutines.

A plotting session is a set of plotting instructions in a user's application program which produces hardcopy graphic display output. The output can be either a single plot or graph or a set of graphs. Every plotting session must begin with a call to subroutine PSINIT (with the exception of a call to NEWDEV) and end with a call to subroutine PLOTND.

Pen movement is occasionally mentioned throughout this manual. While PostScript does not use an actual pen for graphic production, it is useful to visualize the plot commands as directing the movements of a pen of variable thickness to a specified (x,y) coordinate, with the pen being either up or down. The plotting subroutines are simple, user-callable commands which direct the movements of an imagined pen upon a plotting sheet.

The initial coordinate origin is approximately .5 inches from the bottom and left paper edges. The orientation of the page must be specified to be either portrait (short side horizontal) or landscape (long side horizontal) and is set by the call to PSINIT (which see). The figure below shows the paper orientation and beginning plot origin for portrait and landscape modes. The current plot origin can be relocated to other positions during the plotting session to provide new reference points for subsequent plotting commands. When the next graph is started, the new origin should be placed far enough away to avoid overlapping the just-completed graph.

All plotting commands use an absolute plot coordinate system. This means that all coordinates passed to plotting subroutines are expected to be in terms of distance from the current plot origin. This is contrast to a relative plot coordinate system, in which coordinates are assumed to be in terms of distance from the current pen position.

In all plotting subroutines, plot coordinates, character heights, distances, etc. can be in arbitrary units. The default is inches. This can be changed by the variable conver in subroutine PSINIT.

Unless otherwise noted, any subroutine argument which specifies an angle is stated in degrees relative to the X axis, with positive angles measured counterclockwise from the X axis.

Most character variables are specified as Hollerith, rather than character strings. The reason for this is primarily historical, combined with the fact that the enormous amount of code already written and in use at my site precluded a comprehensive revision. This should not cause any problems, however.

The initial font of a plot session is Helvetica, with a size of 12 points. This can be changed permanently in subroutine PSINIT. Of course, the current font can always be changed with subroutine SETFNT. PSPLOT supports the standard 35 fonts found on most PostScript printers.

PSPLOT supports color, although all examples in this manual are shown in grayscale for the purposes of reproduction. Color is specified in the relevant subroutines as red, green, and blue (RGB) values.

Continuation allows you to append a character string or number to the end of a previously plotted string or number. The coordinates of the appended string are automatically calculated. Whether or not a subroutine supports continuation is stated in subroutine description in the next section.

Continuation is specified by setting the X and/or Y coordinate argument in calls to the subroutines listed above to 999, and may be applied to X and Y coordinates separately. A subroutine call with continuation must immediately follow the previous plotting call. Continuation is useful when plotting strings containing variable values, such that the resultant string length is not known beforehand.

This section describes the user-level subroutines in the PSPLOT plotting library. These routines are Fortran-callable from an application program. Below is a brief summary of the subroutines, followed by an alphabetical listing of each subroutine containing a more detailed description of its function, syntax, and calling arguments.

Note that the code examples here are shown in black and white and grayscale, as that is how they are produced in the hardcopy User's Manual. PSPLOT fully supports color graphics.

Purpose:AXIS draws an axis of a graph, with user-specified axis titles. Tick marks are drawn with a spacing of one inch. Code Example

Syntax: CALL AXIS (XPP, YPP, IBCD, NC, AXLEN, THETA, RMIN, DEL)

Arguments:

XPP, YPP X, Y coordinates of axis origin.

IBCD Axis title (Hollerith).

NC Number of characters in title. Its sign is used to specify on which side of the axis the title is to appear: positive for the counterclockwise side of the axis, negative for the clockwise side. Positive labeling is generally used for Y axes, negative for X axes.

Purpose:BORDER draws a rectangular border with tick marks. The lower left corner of the border is located at the current plot origin. Code Example

Syntax: CALL BORDER (XLEN, YLEN, ITIC, IBRD, MAJX, MINX, MAJY, MINY)

Arguments:

XLEN Length of x-direction side of border.

YLEN Length of y-direction side of border.

ITIC Four digit number which determines which of the border sides will contain tick marks. Each of the digits is either 0 or 1, and if set to 1, that side will contain tick marks. The border sides are ordered as follows:

Left-vertical Bottom Right-vertical Top

For example, if ITIC = 1011, all sides except the bottom would contain tick marks. Additionally, if ITIC < 0, the tick marks will be drawn on the outside of the border than on the inside (default).

IBRD IBRD is similar to ITIC except that it determines which sides of the border will be drawn. Hence, you can have tick marks with no border, and vice versa.

MAJX Number of major divisions in the x-direction. A longer tick mark is drawn for these divisions.

MINX Number of minor divisions in the x-direction, i.e. the number of divisions per major division. A shorter tick mark is drawn for these divisions.

Purpose:CHOPIT logically closes the current graphics page and begins a new one.

Syntax: CALL CHOPIT (XPP, YPP)

Arguments:

XPP, YPP, X, Y coordinates of the initial plot origin of the next plot. This allows you to begin all plots at the same origin on each page.

Note: XPP and YPP are coordinates independent of the current scaling factor. That is, XPP and YPP represent actual inches, not scaled coordinates. The current scaling factor is reinstated after the new coordinate origin is set.

Subroutine CHOPIT should not be confused with subroutine PLOTND, which is called once at the end of each plotting session and which closes the entire output PostScript file.

ARR Two-dimensional array containing regularly spaced data to be contoured. CONCOLR assumes ARR(1,1) is located at the lower left corner of the plot. Data points ARR(1,1) through ARR(IEXT,JEXT) are contoured in an area XLEN x YLEN.

IMAX The first dimension of ARR in the calling program.

IEXT Number of points in x-direction of ARR to be contoured.

JEXT Number of points in y-direction of ARR to be contoured.

XLEN X-direction length of plotting area.

YLEN Y-direction length of plotting area.

CVAL Array containing the values to be used for contour intervals (1 to NVAL). CVAL must be dimensioned with a dimension of at least 1. Unlike in subroutine CONREC, NVAL cannot equal 0.

COLOR Array dimensioned (3,NVAL) containing the red, green, and blue values for each of the contour levels. The red value is stored in (1,n), the green value in (2,n) and the blue value in (3,n), where n specifies the contour index corresponding to CVAL. Regions less than or equal to the corresponding contour value CVAL are filled with the corresponding RBG values.

NVAL Number of contour intervals. NVAL must be less than or equal to 100, and unlike in CONREC, NVAL cannot equal 0.

IOFFP Flag indicating that grid boxes whose vertices have the value SPVAL are to be ignored during contouring.

SPVAL Special value denoting which grid boxes are to be ignored during contouring.

ARR Two-dimensional array containing regularly spaced data to be contoured. CONFILL assumes ARR(1,1) is located at the lower left corner of the plot. Data points ARR(1,1) through ARR(IEXT, JEXT) are contoured in an area XLEN x YLEN.

IMAX The first dimension of ARR in the calling program.

IEXT Number of points in x-direction of ARR to be contoured.

JEXT Number of points in y-direction of ARR to be contoured.

XLEN X-direction length of plotting area.

YLEN Y-direction length of plotting area.

CVAL Array containing the values to be used for contour intervals (1 to NVAL). CVAL must be dimensioned with a dimension of at least 1. Unlike subroutine CONREC, NVAL cannot equal 0.

GRYLEV Array dimensioned (NVAL) containing the grayscale values for each of the contour levels. Regions less than or equal to the corresponding contour value CVAL are filled with the corresponding grayscale values. Grayscale values range from 0. (black) to 1.0 (white).

NVAL Number of contour intervals. NVAL must be less than or equal to 100, and unlike in CONREC, NVAL cannot equal 0.

IOFFP Flag indicating that grid boxes whose vertices have the value SPVAL are to be ignored during contouring.

SPVAL Special value denoting which grid boxes are to be ignored during contouring.

ARR Two-dimensional array containing regularly spaced data to be contoured. CONREC assumes ARR(1,1) is located at the lower left corner of the plot. Data points ARR(1,1) through ARR(IEXT,JEXT) are contoured in an area XLEN x YLEN.

IMAX The first dimension of ARR in the calling program.

IEXT Number of points in x-direction of ARR to be contoured.

JEXT Number of points in y-direction of ARR to be contoured.

XLEN X-direction length of plotting area.

YLEN Y-direction length of plotting area.

CVAL Array containing the values to be used for contour intervals (1 to NVAL). CVAL must be dimensioned with a dimension of at least 1. If NVAL = 0, the individual contour values are automatically computed.

NVAL Number of contour intervals. If NVAL = 0, the number of contour intervals and the contour interval values are automatically calculated. This is helpful if the range of data values is not known beforehand. NVAL must be less than or equal to 100.

Special features of CONREC:

If NVAL < 0, only high and lows are plotted instead of contours.

Common block CONPAR is used to control various characteristics of the contour plot from the calling program. The variables in CONPAR are shown below, along with their default values:

LSCAL If LSCAL = 0, the contours are scaled such that 0 < labeled values < 100. If LSCAL = 1, the contours are not scaled, i.e. the contour values are the actual data values. Default = 0.

LDASH Specifies whether contours are solid (LDASH = 0) or dashed (LDASH NE 0). If LDASH is not equal to 0, then LDASH specifies the type of dash line to use to draw the contours. The numeric value of LDASH is the number of times the dashed pattern (solid line/blank space) is repeated per inch. Default= 0.

HGTLAB Specifies the height of contour labels. If HGTLAB=0, the height of the contours is .11 inches.

XPP, YPP, X, Y coordinates of the Greek symbol to be plotted. Plotting may be continued from the end of a previously plotted character when used in conjunction with any of the subroutines which support continuation.

Purpose:KEKEXP plots a floating point number in exponential format. Code Example

Syntax: CALL KEKEXP (XPP, YPP, HEIGHT, FNUM, ANG, NDEC, MJUS)

Arguments:

XPP, YPP, X, Y coordinates of the number to be plotted. Plotting may be continued from the end of a previously plotted character when used in conjunction with any of the subroutines which support continuation

HEIGHT Height of number to be plotted.

FNUM Floating point number to be plotted.

ANG Angle, measured counterclockwise from the X-axis, at which the number is to be plotted.

NDEC Controls the plotted precision of FNUM.

If NDEC > 0, it specifies the number of digits to the right of the decimal point, after rounding.

If NDEC = 0, only the number's integer portion and a decimal point are plotted, after rounding.

If NDEC = -1, only the number's integer portion is plotted, after rounding.

MJUS Controls the justification of the number to be plotted.

If MJUS = 0, (XPP, YPP) denotes the position of the lower left corner of the plotted number.

If MJUS = 1, (XPP, YPP) denotes the position of the center of the plotted number.

If MJUS = 2, (XPP, YPP) denotes the position of the lower right corner of the plotted number.

Purpose:KEKNUM plots a floating point number in floating point format. Code Example

Syntax: CALL KEKNUM (XPP, YPP, HEIGHT, FNUM, ANG, NDEC, MJUS)

Arguments:

XPP, YPP X, Y coordinates of the number to be plotted. Plotting may be continued from the end of a previously plotted character when used in conjunction with any of the subroutines which support continuation.

HEIGHT Height of number to be plotted.

FNUM Floating point number to be plotted.

ANG Angle, measured counterclockwise from the X-axis, at which the number is to be plotted.

NDEC Controls the plotted precision of FNUM.

If NDEC > 0, it specifies the number of digits to the right of the decimal point, after rounding.

If NDEC = 0, only the number's integer portion and a decimal point are plotted, after rounding.

If NDEC = -1, only the number's integer portion is plotted, after rounding.

MJUS Controls the justification of the number to be plotted.

If MJUS = 0, (XPP, YPP) denotes the position of the lower left corner of the plotted number.

If MJUS = 1, (XPP, YPP) denotes the position of the center of the plotted number.

If MJUS = 2, (XPP, YPP) denotes the position of the lower right corner of the plotted number.

XPP, YPP, X, Y coordinates of the character string to be plotted. Plotting may be continued from the end of a previously plotted character when used in conjunction with any of the subroutines which support continuation.

HEIGHT Height of character string to be plotted.

IBCD Character string to be plotted (Hollerith).

ANG Angle, measured counterclockwise from the X-axis, at which the character string is to be plotted.

NCHAR Number of characters in the string to plot.

MJUS Controls the justification of the character string to be plotted.

If MJUS = 0, (XPP, YPP) denotes the position of the lower left corner of the character string.

If MJUS = 1, (XPP, YPP) denotes the position of the center of the character string.

If MJUS = 2, (XPP, YPP) denotes the position of the lower right corner of the character string.

Special feature of KEKSYM:

You can plot special characters, for example the characters in fonts Symbol and Zapf Dingbats, by setting NCHAR=-999 and IBCD equal to the octal code of the character you want to plot.

Purpose:KEKSYMC plots a character string. Same as KEKSYM, but text is input as a character string rather than Hollerith.

Syntax: CALL KEKSYMC (XPP, YPP, HEIGHT, CSTR, ANG, NCHAR, MJUS)

Arguments:

XPP, YPP, X, Y coordinates of the character string to be plotted. Plotting may be continued from the end of a previously plotted character when used in conjunction with any of the subroutines which support continuation.

HEIGHT Height of character string to be plotted.

CSTR Character string to be plotted (Hollerith).

ANG Angle, measured counterclockwise from the X-axis, at which the character string is to be plotted.

NCHAR Number of characters in the string to plot.

MJUS Controls the justification of the character string to be plotted.

If MJUS = 0, (XPP, YPP) denotes the position of the lower left corner of the character string.

If MJUS = 1, (XPP, YPP) denotes the position of the center of the character string.

If MJUS = 2, (XPP, YPP) denotes the position of the lower right corner of the character string.

Special feature of KEKSYMC:

You can plot special characters, for example the characters in fonts Symbol and Zapf Dingbats, by setting NCHAR=-999 and CSTR equal to the octal code of the character you want to plot. CSTR must be in single quotes.

Purpose:KEKSYMO plots a character string; however, the characters are outlined rather than filled (solid). Code Example

Syntax: CALL KEKSYMO (XPP, YPP, HEIGHT, IBCD, ANG, NCHAR, MJUS)

Arguments:

XPP, YPP, X, Y coordinates of the character string to be plotted. Plotting may be continued from the end of a previously plotted character when used in conjunction with any of the subroutines which support continuation.

HEIGHT Height of character string to be plotted.

IBCD Character string to be plotted (Hollerith).

ANG Angle, measured counterclockwise from the X-axis, at which the character string is to be plotted.

NCHAR Number of characters in the string to plot.

MJUS Controls the justification of the character string to be plotted.

If MJUS = 0, (XPP, YPP) denotes the position of the lower left corner of the character string.

If MJUS = 1, (XPP, YPP) denotes the position of the center of the character string.

If MJUS = 2, (XPP, YPP) denotes the position of the lower right corner of the character string.

Special feature of KEKSYMO:

You can plot special characters, for example the characters in fonts Symbol and Zapf Dingbats, by setting NCHAR=-999 and IBCD equal to the octal code of the character you want to plot.

Purpose:OVERBAR plots a character string with an overbar. Code Example

Syntax: CALL OVERBAR (XPP, YPP, HEIGHT, IBCD, ANG, NCHAR, MJUS)

Arguments:

XPP, YPP, X, Y coordinates of the character string to be plotted. Plotting may be continued from the end of a previously plotted character when used in conjunction with any of the subroutines which support continuation.

HEIGHT Height of number to be plotted.

IBCD Character string to be plotted (Hollerith).

ANG Angle, measured counterclockwise from the X-axis, at which the character string is to be plotted.

NCHAR Number of characters in the string to plot.

MJUS Controls the justification of the character string to be plotted.

If MJUS = 0, (XPP, YPP) denotes the position of the lower left corner of the character string.

If MJUS = 1, (XPP, YPP) denotes the position of the center of the character string.

If MJUS = 2, (XPP, YPP) denotes the position of the lower right corner of the character string.

XPP, YPP, X, Y coordinates of the character string to be plotted. Plotting may be continued from the end of a previously plotted character when used in conjunction with any of the subroutines which support continuation.

HEIGHT Height of character string to be plotted.

IBCD Character string to be plotted (Hollerith).

ANG Angle, measured counterclockwise from the X-axis, at which the character string is to be plotted.

NCHAR Number of characters in the string to plot.

MJUS Controls the justification of the character string to be plotted.

If MJUS = 0, (XPP, YPP) denotes the position of the lower left corner of the character string.

If MJUS = 1, (XPP, YPP) denotes the position of the center of the character string.

If MJUS = 2, (XPP, YPP) denotes the position of the lower right corner of the character string.

XPP, YPP X, Y coordinates of the character string to be plotted. Plotting may be continued from the end of a previously plotted character when used in conjunction with any of the subroutines which support continuation.

XPP, YPP, X, Y coordinates of the character string to be plotted. Plotting may be continued from the end of a previously plotted character when used in conjunction with any of the subroutines which support continuation.

HEIGHT Height of character string to be plotted.

IBCD Character string to be plotted (Hollerith).

ANG Angle, measured counterclockwise from the X-axis, at which the character string is to be plotted.

NCHAR Number of characters in the string to plot.

MJUS Controls the justification of the character string to be plotted.

If MJUS = 0, (XPP, YPP) denotes the position of the lower left corner of the character string.

If MJUS = 1, (XPP, YPP) denotes the position of the center of the character string.

If MJUS = 2, (XPP, YPP) denotes the position of the lower right corner of the character string.

XPP, YPP, X, Y coordinates of the character string to be plotted. Plotting may be continued from the end of a previously plotted character when used in conjunction with any of the subroutines which support continuation.

XPP, YPP X, Y coordinates of the character string to be plotted. Plotting may be continued from the end of a previously plotted character when used in conjunction with any of the subroutines which support continuation.

HEIGHT Height of character string to be plotted.

IBCD Character string to be plotted (Hollerith).

ANG Angle, measured counterclockwise from the X-axis, at which the character string is to be plotted.

NCHAR Number of characters in the string to plot.

MJUS Controls the justification of the character string to be plotted.

If MJUS = 0, (XPP, YPP) denotes the position of the lower left corner of the character string.

If MJUS = 1, (XPP, YPP) denotes the position of the center of the character string.

If MJUS = 2, (XPP, YPP) denotes the position of the lower right corner of the character string.

XPP, YPP, X, Y coordinates of the Greek symbol to be plotted. Plotting may be continued from the end of a previously plotted character when used in conjunction with any of the subroutines which support continuation.

XPP, YPP, X, Y coordinates of the Greek symbol to be plotted. Plotting may be continued from the end of a previously plotted character when used in conjunction with any of the subroutines which support continuation.

Purpose:PLOT is the most fundamental user-level plotting command. It gives you direct control of pen movement (to any X, Y coordinate position) and pen status (up or down). Additionally, it allows you to re-define the current plotting origin. Code Example

Syntax: CALL PLOT (XPP, YPP, IPEN)

Arguments:

XPP, YPP, X, Y coordinates of the position to which the pen is to be moved. An origin may be established anywhere on or off the plotting surface, as explained below for negative IPEN values.

IPEN A signed integer which controls pen status (up/down) and origin definition.

If IPEN = 2, the pen is down during movement, thus drawing a visible line.

If IPEN = 3, the pen is up during movement, thus changing the pen's current position only.

If IPEN = -2 or -3, a new origin is defined at the position (XPP, YPP) after the movement is completed as if IPEN were positive. The logical X,Y coordinates of the new pen position are set to (0,0), so that all subsequent pen movements use this position as a reference point.

If IPEN = 999, the call to PLOT closes the output file. Thus, a call to PLOT with IPEN = 999 may be used only once in a given plotting session, and if used, must be the last plotting command in the plotting session. Calling PLOT with IPEN = 999 is identical to calling PLOTND (which see).

XPP, YPP, X, Y coordinates of the symbol to be plotted. Plotting may be continued from the end of a previously plotted character when used in conjunction with any of the subroutines which support continuation.

HEIGHT Height of symbol to be plotted.

ANG Angle, measured counterclockwise from the X-axis, at which the symbol is to be plotted.

MJUS Controls the justification of the character string to be plotted.

If MJUS = 0, (XPP, YPP) denotes the position of the lower left corner of the character.

If MJUS = 1, (XPP, YPP) denotes the position of the center of the character.

If MJUS = 2, (XPP, YPP) denotes the position of the lower right corner of the character.

XPP, YPP, X, Y coordinates of the symbol to be plotted. Plotting may be continued from the end of a previously plotted character when used in conjunction with any of the subroutines which support continuation.

HEIGHT Height of symbol to be plotted.

ANG Angle, measured counterclockwise from the X-axis, at which the symbol is to be plotted.

MJUS Controls the justification of the symbol to be plotted.

If MJUS = 0, (XPP, YPP) denotes the position of the lower left corner of the character.

If MJUS = 1, (XPP, YPP) denotes the position of the center of the character.

If MJUS = 2, (XPP, YPP) denotes the position of the lower right corner of the character.

Purpose:PSINIT is called to begin a plotting session. It must be called before any other plotting command, with the exception of NEWDEV.

Syntax: CALL PSINIT (PRTRT)

Arguments:

PRTRT Logical variable indicating the paper orientation. If PRTRT=.TRUE., the paper is oriented in portrait mode, i.e. long side of page is vertical. If PRTRT=.false., the paper is oriented in landscape mode, i.e. long side of page is horizontal.

The fonts sets 29 (Symbol) and 35 (ZapfDingbats) require the octal code of the character to be plotted. Click the appropriate table to see the character sets and corresponding octal code values for these two fonts. SymbolZapfDingbats

Helpful Resources

NSU Oceanographic Center Supporting Institutes:

The Mission of the Oceanographic Center is to carry out innovative, basic and applied research and to provide high-quality graduate and undergraduate education in a broad range of marine science and related disciplines.