NAME
----
The CALCOMP Graphics Library User Guide
Last Revised 07/01/91
This is documentation for the CALCOMP graphics library. It is
complete except for graphics figures and the documentation of a few
local enhancements to the library that will not affect general users.
Copies of the figures are available as GIF images.
The CALCOMP library is a simple set of FORTRAN callable graphic
routines that allows users to construct plots. It is principally
available for use by purchased software from outside vendors and to
ease the conversion process for users migrating CALCOMP code. It is
not usually recommended for use in new code. Consult the supplement
at the end of this guide for specific guidelines on how to convert
existing user and vendor CALCOMP code.
1 TABLE OF CONTENTS
Section Title
------- -----
1.0 INTRODUCTION
2.0 CALCOMP BASIC SOFTWARE
2.1 C_PLOT - Move or Draw to specified point,
establish plot origin, update pen position
and terminate plotting
2.2 C_PLOTS - Initialization, specify output file unit number
2.3 C_FACTOR - Adjusts the overall size of the plot
2.4 C_WHERE - Returns current pen location
2.5 C_NFRAME - Ends current frame and re-origins pen position
2.6 C_SYMBOL - Plots annotation (text) and special symbols
2.7 C_NUMBER - Plot decimal equivalent of a floating point number
2.8 C_SCALE - Determine starting value and scale for an array
to be plotted on a graph
2.9 C_AXIS - Draws an annotated linear graph axis
2.10 C_LINE - Scale and plot a set of X,Y values
2.11 C_NEWPEN - Select new pen color
2.12 Sample Plotting Program
3.0 CALCOMP GENERAL FUNCTIONAL SOFTWARE
3.1 C_CIRCL - Draws a circle, arc, or spiral
3.2 C_ELIPS - Draws an ellipse or elliptical (or circular) arc
3.3 C_DASHL - Draws dashed line connecting a series of data points
3.4 C_DASHP - Draws a dashed line to a specified point
3.5 C_FIT - Draws a curve through three points
3.6 C_GRID - Draws a linear grid
3.7 C_POLY - Draws an equilateral polygon
3.8 C_RECT - Draws a rectangle
4.0 CALCOMP SCIENTIFIC FUNCTIONAL SOFTWARE
4.1 C_CURVX - Draws a function of X over a given range
4.2 C_CURVY - Draws a function of Y over a given range
4.3 C_FLINE - Draws a smooth curve through a set of data points
4.4 C_SMOOT - Draws a smooth curve through sequential data points
4.5 C_SCALG - Performs scaling for logarithmic plotting
4.6 C_LGAXS - Plots an annotated logarithmic axis
4.7 C_LGLIN - Draws data in either log-log or semi-log mode
4.8 C_POLAR - Draws data points using polar coordinates
5.0 APPLICATIONS ROUTINES
5.1 C_CNTOUR - Makes a contour plot
6.0 ACCESSING THE CALCOMP ROUTINES
7.0 CALCOMP CODE MIGRATION SUPPLEMENT
1
RECORD OF REVISIONS
(Preliminary release was made 06/24/85 for COS)
07/11/89 Third parameter of C_PLOTS is no longer ignored, but
may be used to set the FORTRAN unit number used for
output metafile 'pdf'.
The routine C_NEWPEN may be used to select color.
07/01/91
The first release of the documentation on UNICOS.
Output file goes to default filename "pdf". User
may specify the output filename with the environmental
variable CALCOMP_PDF.
1
1.0 INTRODUCTION
This user's guide describes the calling sequences and arguments
for the FORTRAN-callable CALCOMP software subroutines which was
leased from CALCOMP and interfaced to TEMPLATE. The routines do not
produce a device dependent CALCOMP file but rather produce an
intermediate, device independent metalanguage file that must
be post-processed to a selected graphics device. This metalanguage
file is written in the format of a TEMPLATE Pseudo Device File
(PDF).
CALCOMP divides their routines into three categories:
Basic, General Function, and Scientific Function.
They are all placed in a single library called libcalcomp.a
Differences between the implemented routines and the standard CALCOMP
routines are:
A. All coordinate values should be greater than or equal to zero, and
less than 100 inches. Values outside this range may result in
unpredictable results (Negative values are possible if the
frame coordinate origin is set first using the C_PLOT call).
B. The metalanguage output filename is "pdf", and uses FORTRAN
unit 50 unless an appropriate alternate value is specified
in the C_PLOTS routine call. The output filename may be specified
using the environmental variable CALCOMP_PDF.
C. A routine C_NFRAME is available for creating multiple frames for
graphic devices other than pen plotters.
D. Color is supported via the C_NEWPEN routine
E. Frames will not plot to true inches unless specific steps are
taken in the generation and post-processing of the plot file.
Other changes may be needed in existing CALCOMP code from vendors as CALCOMP
has produced several versions of CALCOMP routines that vary in such ways as
use of CHARACTER variables versus Hollerith, the number of parameters on
C_SYMBOL calls, and the current pen position after a call to C_SYMBOL.
The CALCOMP subroutines were written for use with CALCOMP pen plotters and
originally worked in units of inches for the mapping of the plot directly to
the output device. There are two classes of CALCOMP subroutines--those that
accept user units and scale them to inches and those that require data to be
directly in units of inches.
Table 1 lists the CALCOMP subroutines that fall into each class.
The main difference CALCOMP users will notice when using this CALCOMP library
is that when the CALCOMP subroutines were incorporated into TEMPLATE,
the meaning of CALCOMP inches was altered to no longer mean a physical inch
but just a unit-less measure (since TEMPLATE uses device-independent space and
the graphics post processing procedures produce output for a number of
graphics devices, some of which have a limited device space unlike pen
plotters). THIS DIFFERENCE IS USUALLY ONLY OF SIGNIFICANCE TO USERS TRYING
TO PRODUCE PLOTS USING TRUE INCHES.
The graphics post processing procedures use the CALCOMP inches to determine
the aspect ratio of the plot, and the plot is made as large as possible for a
given device while maintaining the aspect ratio specified by the user CALCOMP
calls. A parameter called SIZE is included with most graphics post-processor
procedures which facilitates the scaling of plots to a specific size in
inches. An example program shows how to use these parameters to get
consistent frames in as close as possible to true inches.
1
TABLE 1
Routines Which Routines Which Require
Perform Scaling Inches
of User Data to Inches (Data Must be Scaled to Inches)
______________________ _______________________________
C_SCALE C_PLOT
C_AXIS C_WHERE
C_LINE C_SYMBOL
C_DASHL C_NUMBER
C_FLINE C_CIRCL
C_SCALG C_ELIPS
C_LGAXS C_DASHP
C_LGLIN C_FIT
C_POLAR C_GRID
C_POLY
C_RECT
C_CURVX
C_CURVY
C_SMOOT
1
2.0 CALCOMP BASIC SOFTWARE
The routines included in the CALCOMP Basic Software category are C_PLOT,
C_PLOTS, C_FACTOR, C_WHERE, C_SYMBOL, C_NUMBER, C_SCALE, C_AXIS,
C_LINE and C_NEWPEN . C_NFRAME, an enhancement, is included here
because it performs a basic function.
1
Usually when examining existing CALCOMP code you will find it
breaks down into two categories - that which produces XY plots and
that which does almost everything in its own high-level routines and
uses CALCOMP mostly just to draw lines with the C_PLOT command.
Therefore you are likely not to need to be familiar with many of the
CALCOMP routines described here.
The majority of graphic applications are intended to produce
an XY-plot. Usually the production of these graphs requires only a
combination of the routines C_PLOTS (initialize), C_SCALE, C_AXIS,
C_LINE, C_NFRAME and C_PLOT (terminate). Additional text can be added
with C_SYMBOL, and options such as frame borders and general line
drawing might be added with C_PLOT calls.
When plotting requirements cannot be satisfied by using these
subroutines, the code often calls the C_PLOT routine almost exclusively
( which basically draws a line or moves the pen directly in units
of inches). This is often done by vendors so that it is very easy for
them to interface to virtually any graphics library.
Two other routines are often found in programs that do not call the
higher level routines (such as the axis and contour plot routines):
follows:
C_FACTOR Adjusts the overall size of a plot.
C_WHERE Returns the current pen location.
1
2.1 Subroutine C_PLOT
---------------
FUNCTION
The C_PLOT subroutine is used to move the pen in a straight line
to a new position, with the pen either up or down during the movement.
Another function of C_PLOT is to establish a new reference point
(origin) for the current plot frame. This must be done if any draws
or moves use values which are negative relative to the ORIGINAL
frame origin.
C_PLOT also is used to terminate CALCOMP plotting, and must be
called once and only once at the end of plotting calls in each CALCOMP
application.
CALLING SEQUENCE:
CALL C_PLOT (XPAGE,YPAGE,+-IPEN)
where:
XPAGE, YPAGE are the X, Y coordinates in CALCOMP inches. The values
are measured relative to the current frame reference
(origin).
An origin (where both X, Y equal zero) may be
established anywhere on the plotting surface by using
negative IPEN values, as explained below.
Because CALCOMP routines are interfaced to write a TEMPLATE
PDF, some limits on X and Y coordinates were required.
All coordinate values (XPAGE, YPAGE) should be
greater than or equal to zero and less than 100 inches.
If negative values are necessary a new frame origin must
be set so the negative values are positive relative to
the ORIGINAL frame origin.
0 < XPAGE+origin x-offset < 100
0 < YPAGE+origin y-offset < 100
The values of XPAGE and YPAGE which are used to establish
a new origin must also be considered. See the discussion
under subroutine C_NFRAME for details.
+-IPEN is a signed integer which controls pen status (up or
down), and the 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.
If IPEN= -2, or -3, a new origin is defined at
(XPAGE,YPAGE)
after the movement is completed as if IPEN were positive.
That is, the X,Y coordinates of the new pen position are
set equal to zero. This position is the reference point
for succeeding pen movements.
If IPEN=999 the metalanguage file is closed. (Note this
must be the last call made by the plotting application).
1
2.2 Subroutine C_PLOTS
----------------
FUNCTION:
Subroutine C_PLOTS is used to initialize the CALCOMP package. It must be
called once and only once before any other CALCOMP calls are used in the
application program.
C_PLOTS also is used to specify which FORTRAN unit number will be used by the
output metalanguage file.
Note that calling C_PLOTS produces a logfile message indicating the CALCOMP
source code version number and the CFT level used when building the library.
CALLING SEQUENCE:
CALL C_PLOTS (O,O,LDEV)
where:
LDEV is the FORTRAN unit number for the metalanguage file.
If LDEV is not in the range of 1 to 99 inclusive, then
FORTRAN unit 50 is used. The FORTRAN unit used for
the output file cannot be used for any other purposes
within the application program (Avoid units 1,2,5 and
6 which are often associated with standard input and
output).
The output metafile default name is 'pdf'.
It may be specified through the environmental variable
CALCOMP_PDF.
The first two arguments of C_PLOTS are no longer used,
but are maintained for compatibility with previous
versions of the CALCOMP software package.
** NOTE : In versions before the library for CFT11531, LDEV
was ignored and unit 50 was always used; and no logfile
message was produced.
1
2.3 Subroutine C_FACTOR
-----------------
FUNCTION:
Subroutine C_FACTOR enables the user to enlarge or reduce the
size of the entire plot by changing the ratio of the desired plot
size to the normal plot size. C_FACTOR is often called only once in
a program, immediately after the initialization call to C_PLOTS,
to rescale all plotting to a single specific scale.
Because CALCOMP inches are unit-less units in PDF files, this routine
is not necessary unless inch units greater than 100 are needed (100 is
maximum PDF frame size) or if the program needs to remain portable to
standard true-inch CALCOMP libraries and using the actual values used
in the C_PLOT calls would produce a very small or very large plot.
USERS TRYING TO PRODUCE TRUE INCHES PLEASE NOTE:
In this CALCOMP, all frames are scaled individually to the maximum
size obtainable on the output device they are produced on. This means
to keep frames scaled relative to each other, you must move to the
same maximum XY value IN EACH FRAME (see routine C_NFRAME description)
with a call to C_PLOTS so that each frame is the same number of
unit-less units in size. An example program at the end of this manual
illustrates keeping frames scaled relative to each other.
CALLING SEQUENCE:
CALL C_FACTOR (FACT)
where:
FACT is the ratio of the desired plot size to the normal plot
size. For example, if FACT=2.0, all subsequent pen
movements will be twice their normal size. When FACT is
reset to 1.0, all plotting returns to normal size.
During the debugging of a plotting application program,
plotting time can be saved by reducing the size of the
entire plot output on certain devices such as pen
plotters. This is done by calling C_FACTOR with a value
less than 1.0 after calling C_PLOTS. When debugging is
completed, this call statement can be removed.
1
2.4 Subroutine C_WHERE
----------------
FUNCTION:
Subroutine C_WHERE returns the current position coordinates (that are in use by
the C_PLOT subroutine) and the plot-scaling factor. This permits user-written
subroutines to know the current location for optimizing pen movement or for
determining coordinates for future calls.
CALLING SEQUENCE:
CALL C_WHERE (RXPAGE,RYPAGE,RFACT)
where:
RXPAGE, RYPAGE are variables that will be set to the current position
coordinates resulting from the previous call to C_PLOT
(which may have been called internally by C_SYMBOL, C_NUMBER,
C_AXIS, C_LINE or most other CALCOMP routines).
RFACT is set to the current plot-sizing factor, i.e., the value
last supplied by a call to C_FACTOR or 1.0 if C_FACTOR has
not been called.
A call to C_WHERE made after a call to C_SYMBOL returns the coordinates of the
location of the last point actually plotted.
Please note that different versions of CALCOMP may return different values to
this routine. For example, CALCOMP has produced CALCOMP libraries that will
return the following to C_WHERE after a call to C_SYMBOL has been made:
a) The beginning coordinate of the string produced by C_SYMBOL
b) The end point of the string produced
c) The position where the next character will be drawn if C_SYMBOL
is called with the 999 value flags (as described in the C_SYMBOL
routine description).
1
2.5 Subroutine C_NFRAME
-----------------
FUNCTION:
Terminates the current frame and resets the current pen position and
origin to zero (The lower left-hand corner of the new frame).
C_NFRAME is a locally-developed routine.
Subroutine C_NFRAME allows users to define the logical beginning
and ending of a plot. This capability is necessary if plots are to
be drawn on a graphics device with a limited display area (e.g.,
a graphics terminal or microfiche/ film). A call to C_NFRAME enters
a plot terminator in the user's metalanguage file. All plotting
data generated between calls to C_NFRAME is treated as a single plot
by the graphics post processing procedures. The absence of calls to
C_NFRAME results in all plotting data being processed as a single
plot by the post processor (e.g., all plotting data will be drawn
in a single frame on microfiche).
The call to C_NFRAME should be placed before the call to subroutine
C_PLOT that is used to move the pen to the origin of the next plot.
Be aware that the area encompassed by moving the pen to
establish the origin of a plot is considered part of the plot and will
produce a visible bottom and left margin on plot frames if no negative
values are subsequently used.
As mentioned previously, a plot frame is limited to a maximum size in
either the X or Y direction of 100 "CALCOMP inches." Each plot frame is
initialized by a call to subroutine C_PLOT with the third argument
(IPEN) equal to -2 or -3. For example:
CALL C_PLOT (0.5,1.0,-3)
says to move 0.5 inches in the X-direction and 1.0 inch in the
Y-direction before establishing a new origin. When establishing a
new origin, all offsets are included inside the frame boundary and
are therefore part of the plot frame size. If any X or Y coordinate
value (plus the appropriate offset) exceeds the 100 inch limit,
results are unpredictable. In programs where X and Y coordinate values
exceed the scaling limit, a call to the CALCOMP routine C_FACTOR
may be used to scale down the plot size appropriately. No additional
offset is added by the call to C_NFRAME. Knowledge of the plot frame
size in the X and Y directions will be needed to scale pen plots to
actual inches with the device dependent post processing procedures.
The following example is provided to assist in understanding how the
frame size is determined.
PROGRAM CALTEST
C Perform initialization
CALL C_PLOTS(0,0,0)
C Establish origin for first plot (Negative Y values up to -0.5 are
C now permitted also)
CALL C_PLOT (0.0,0.5,-3)
C Draw a box inside of which all lines will appear
C but notice plot frame size now includes the offset plus this box size
C Plot frame size = maximum coordinate value used + offset
C Plot frame size in the X-direction is 8 inches
C Plot frame size in the Y-direction is 9.5 inches (0.5 offset in C_PLOT
C call above!
CALL C_PLOT (8.,0.,2)
CALL C_PLOT (8.,9.,2)
CALL C_PLOT (0.,9.,2)
CALL C_PLOT (0.,0.,2)
C Calls to generate first plot go here
C .
C .
C .
C Terminate first plot
CALL C_NFRAME
C Establish origin for second plot
CALL C_PLOT (1.0,2.0,-3)
C Plot frame size in the X-direction is 6 inches
C Plot frame size in the Y-direction is 6 inches
CALL C_PLOT (5.0,0.0,2)
CALL C_PLOT (5.0,4.0,2)
CALL C_PLOT (0.0,4.0,2)
CALL C_PLOT (0.0,0.0,2)
C Calls to generate second plot go here
C .
C .
C .
C Close the plot file
CALL C_PLOT (0.0,0.0,999)
END
An inch drawn in frame 1 will not appear equal in length to an inch
drawn in frame 2 because their unit-less frame sizes are not equal (
8.5 x 9 versus 6 x 6 ) !
The size of each frame is determined by the maximum value reached
in each frame relative to the ORIGINAL frame origin. Each frame, when
plotted, is stretched without distortion to the maximum size
it can obtain in the plotting area specified on post-processor calls
(Usually the SIZE, and XI and YI parameters as described in the DOCLIB
document GRPHDOC).
CALLING SEQUENCE:
CALL C_NFRAME
1
2.6 Subroutine C_SYMBOL
-----------------
FUNCTION:
The C_SYMBOL subroutine produces plot annotation at any angle
and in practically any size. There are two C_SYMBOL call formats:
1) the "standard" call, which can be used to draw text such
as titles, captions, and legends.
2) the "special" call, which is used to draw special
centered symbols such as a box, octagon, triangle, etc., for
denoting data points.
Both forms of the C_SYMBOL calling sequence have seven arguments.
Which form is being used is determined by the value of the NCHAR
parameter.
The standard characters that are drawn by C_SYMBOL include the
letters A-Z, digits 0-9, and certain special characters. See Table 2
for a description of CALCOMP's symbol table.
The parameter NCHAR is used to specify whether a text string
or a single symbol is being plotted. If NCHAR is >= 0, the text
string in IBCD is used. If NCHAR= -1 or -2, a single symbol is
produced using the value of INTEQ (Which MUST then be between 0 and
90, inclusive).
It is recommended that 999 be used for INTEQ when NCHAR is greater
than or equal to zero, and either a dummy character variable (e.g.
CHARACTER*1 DUMMY) or a literal character string (e.g. ' ') be used
for IBCD when NCHAR is less than zero (not just a plain word as a
dummy variable)!
CALLING SEQUENCE:
The "standard" call which produces a line of text is:
CALL C_SYMBOL (XPAGE,YPAGE,HEIGHT,IBCD,INTEQ,ANGLE,+NCHAR)
where:
XPAGE, YPAGE are the coordinates, in inches, of the lower left-hand
corner (before character rotation) of the first character
to be produced. The pen is up while moving to this point.
Annotation may be continued from the position following
that at which the last annotation ended. Continuation
occurs when XPAGE and/or YPAGE equals 999.0, and may be
applied to X or Y independently. (Calling C_WHERE to
obtain the current pen position and using RXPAGE, RYPAGE
in another call to C_SYMBOL would not give the same results
as using 999.)
HEIGHT is the height, in inches, of the character(s) to be
plotted. For best results, it should be a multiple of
seven times the standard CALCOMP increment size of 0.01
(e.g., 0.07, 0.14, 0.21), but other values are
acceptable. The width of a character, including spacing,
is normally the same as the height (e.g., a string of 10
characters 0.14 inch high is 1.4 inches wide).
IBCD is the text to be used as annotation. The character(s)
must be in a character array or single variable. (The
data should be stored as TYPE CHARACTER.)
INTEQ Ignored (Assuming NCHAR is positive!)
ANGLE is the angle, in degrees from the X axis, at which the
annotation is to be plotted. If ANGLE=0.0, the
character(s) will be plotted right side up and parallel
to the X axis. The absolute magnitude of ANGLE can not
exceed 1800 degrees.
+NCHAR is the number of characters to be plotted from IBCD.
If NCHAR=0, one alphanumeric character is produced, using
a single character which is the first element of IBCD.
For example, the following call to C_SYMBOL will result in the characters TITLE
10 being output beginning at the X and Y coordinates of 1.0.
CHARACTER GRLBL*8
GRLBL='TITLE 10'
CALL C_SYMBOL (1.0,1.0,0.14,GRLBL,999,0.0,8)
A second form is the "special" call, which produces only a single symbol
based on the value of INTEQ - not on the ASCII representation of a character.
The "special" call is:
CALL C_SYMBOL (XPAGE,YPAGE,HEIGHT,IBCD,INTEQ,ANGLE,-NCHAR)
where:
XPAGE, YPAGE, are the same as described for the "standard" call. If
and ANGLE the symbol to be produced is one of the centered symbols
(e.g., if INTEQ is less than 14), XPAGE, YPAGE represent
the geometric center of the character produced.
HEIGHT is the height (and width), in inches, of the centered
symbol to be drawn. Preferably, it should be a multiple
of four times the CALCOMP 0.01 increment size.
IBCD Ignored (assuming NCHAR is negative!)
INTEQ is the integer equivalent of the desired symbol. Valid
integers and their symbols are listed in the Symbol Table
(Table 2). If INTEQ is 0 through 14, a centered symbol
is produced. INTEQ -MUST- be greater than or equal to zero
and less than or equal to 90.
NCHAR is negative and determines whether the pen is up or down
during the move to XPAGE, YPAGE.
When NCHAR is:
-1, the pen is up during the move, after which a single
symbol is produced.
-2, or less, the pen is down during the move, after which
a single symbol is produced.
For example, the following call to C_SYMBOL will result in special symbol
number 5 being output with its center at X and Y coordinates of 1.0.
CALL C_SYMBOL (1.0,1.0,0.16,' ',5,0.0,-1)
Table 2 shows the current symbols available and the integer equivalents for
each symbol which are used in the "special" call. When a "standard" call to
C_SYMBOL is made, the host computer's internal characters are translated to the
appropriate characters from this table.
1
2.7 Subroutine C_NUMBER
-----------------
FUNCTION:
Subroutine C_NUMBER plots a floating-point number; using the specified number
of decimals in the mantissa (Using FORTRAN F-type format).
The routine is very similar to C_SYMBOL, with the exception that a numeric
value, not a string, is to be plotted.
CALLING SEQUENCE:
CALL C_NUMBER (XPAGE,YPAGE,HEIGHT,FPN,ANGLE,+-NDEC)
where:
XPAGE,YPAGE, are the same as those arguments described for subroutine
HEIGHT,ANGLE C_SYMBOL. The continuation feature, where XPAGE or YPAGE
equals 999.0, may be used.
FPN is the floating-point number that is to be converted and
plotted.
+-NDEC controls the precision of the conversion of the number
FPN. If the value of NDEC>0, it specifies the number of
digits to the right of the decimal point that are to be
converted and plotted, after proper rounding. For
example, assume an internal value of - 0.12345678 x
10**3. If NDEC were 2, the plotted number would be
-123.46.
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. (The above example would be plotted as
-123 with no decimal point).
If NDEC < -1, ABS (NDEC) -1 digits are truncated from the
integer portion, after rounding.
The magnitude of NDEC should not exceed 9.
1
2.8 Subroutine C_SCALE
----------------
FUNCTION:
Calculate scaling factors and a starting value for an array of X or Y values
for use in producing XY plots with the C_LINE and C_AXIS routines, for example.
Typically, the user's program will accumulate plotting data in two arrays:
o An array of independent variables, X(i)
o An array of dependent variables, Y(i)=f(X(i))
Typically these values should not be drawn directly in units of inches, but
should be rescaled (A temperature of 3000 should not require the generation
of a 3000 inch plot!).
For some problems the range of data is predictable. The programmer can
predetermine suitable conversion factors for use in drawing the axis scale
values and plot the data points on the graph directly in units of inches
using the C_PLOT routine. Usually, however, these factors are not known in
advance.
Therefore, the C_SCALE subroutine can examine the data values in an array and
determine a starting value (minimum or maximum) and a scaling factor
(positive or negative) such that:
1) The scale numbers drawn by the C_AXIS subroutine at each
division will properly represent the range of real data
values in the array.
2) The data points, when plotted by the C_LINE subroutine,
will fit in a given plotting area (Generally the bounds of the
plot axis drawn with C_AXIS).
These values are computed and stored by C_SCALE at the END OF THE INPUT VALUE
ARRAY.
The computed scaling factor (DELTAV) represents the number of data units per
inch of axis, adjusting DELTAV so that it is always an interval of 1, 2, 4,
5, or 8 x 10**n (where n is an exponent consistent with the original
unadjusted scaling factor). Thus, an array may have a range of values from
301 to 912, to be plotted over an axis of 10 inches. The unadjusted scaling
factor is (912-301)/10=61.1 units/inch. The adjusted DELTAV would be 8 x
10**1 = 80. This will allow the production of 'nice' axes, that start and
end on rounded units and are divided into increments people can easily
interpolate between.
The starting value (FIRSTV) is intended to be used as the first numeric label
on the axis, is computed as a multiple of DELTAV that is equal to or outside
the limits of the data in the array. For the example given above, if a
minimum is wanted for FIRSTV, 240 would be chosen as the best value. If a
maximum is desired instead, 960 would be selected (The nearest multiple of
80=DELTAV that is below or above the minimum and maximum data values 301 and
912).
CALLING SEQUENCE:
CALL C_SCALE (ARRAY,AXLEN,NPTS,+-INC)
where:
ARRAY is the first element of the array of data points to be
examined.
AXLEN is the length of the axis, in inches, to which the data
is to be scaled. Its value must be greater than 1.0 inch,
and less than 100 inches.
NPTS is the number of data values to be scanned in the array.
The FORTRAN DIMENSION statement must specify at least two
elements more than the number of values being scaled, to
allow room for C_SCALE to store the computed starting value
and scaling factor at the end of the array.
+-INC is an integer whose magnitude is used by C_SCALE as the
increment with which to select the data values to be
scaled in the array. Normally INC=1; if it is 2, every
other value is examined.
If INC is positive, the selected starting value (FIRSTV)
approximates a minimum, and the scale factor (DELTAV) is
positive.
If INC is negative, the selected starting value (FIRSTV)
approximates a maximum, and the scaling factor (DELTAV)
is negative.
WARNING:
If INC= +-1, the array must be dimensioned at least two
elements larger than the actual number of data values it
contains. If the magnitude of INC > 1, the computed
values are stored at (INC) elements and (2*INC) elements
beyond the last data point. The subscripted element for
FIRSTV is ARRAY(NPTS*INC+1); for DELTAV it is ARRAY
(NPTS*INC+INC+1). Therefore, ARRAY must always be
dimensioned at least NPTS*INC+INC+1.
Generally, C_SCALE is called to examine each array to be
plotted. If the user knows the range of his data values,
he does not have to call C_SCALE for that array so long as
he supplies an appropriate FIRSTV and DELTAV when C_AXIS
and C_LINE are called.
1
2.9 Subroutine C_AXIS
---------------
FUNCTION:
Draws a linear axis with numeric scale and axis label.
Important: Axis labels can be 0.4 inches lower than or to the left of the
axis origin (XPAGE,YPAGE). Since lines drawn whose value is negative
relative to the frame's ORIGINAL origin will be clipped, XPAGE and YPAGE must
be greater than 0.4 or a new origin must be specified at least 0.4 units up
and to the right from the original using C_PLOT(0.4,.4,-3) when (XPAGE,YPAGE)
is (0.,0.).
Most graphs require axis lines and scales to indicate the orientation and
values of the plotted data points. The most common type of scaled axis is
produced by the C_AXIS subroutine which draws any length line at any angle,
divides the line into one-inch segments, annotates the divisions with
appropriate scale values and labels the axis with a centered title. When
both the X and Y axes are needed, C_AXIS is called separately for each one.
CALLING SEQUENCE:
CALL C_AXIS(XPAGE,YPAGE,IBCD,+-NCHAR,AXLEN,ANGLE,FIRSTV,DELTAV)
where:
XPAGE,YPAGE are the coordinates, in inches, of the axis line's
starting point. The entire line should be at least
one-half inch from any side to allow space for the scale
annotation and axis title. Usually, both the X and Y
axes are joined at the origin of the graph, where XPAGE
and YPAGE equal zero, but other starting points can be
used. When using the C_LINE subroutine to plot data on an
axis, at least one of the coordinates must be 0, i.e.,
for an X axis, XPAGE=0, and for a Y axis, YPAGE=0.
IBCD is the title, which is centered and placed parallel to
the axis line. This parameter may be a character array
or single variable. (The data should be stored as TYPE
CHARACTER.) The characters have a fixed height of 0.14
inch (about seven characters per inch).
+-NCHAR The magnitude specifies the number of characters in the
axis title, and the sign determines on which side of the
line the scale (tick) marks and labeling information
shall be placed. Since the axis line may be drawn at any
angle, the line itself is used as a reference.
If the sign is positive, all annotation appears on the
positive (counterclockwise) side of the axis. This
condition is normally desired for the Y axis.
If the sign is negative, all annotation appears on the
negative (clockwise) side of the axis. This condition is
normally desired for the X axis.
AXLEN is the length of the axis line, in inches.
ANGLE is the angle in degrees (positive or negative), at which
the axis is drawn. The value is 0 degrees for the X-axis
and 90 degrees for the Y-axis.
FIRSTV is the starting value (either minimum or maximum) which
will appear at the first tick mark on the axis. This
value may either be computed by the C_SCALE subroutine and
stored at subscripted location ARRAY(NPTS*INC+1), or the
value may be determined by the user and stored at any
location.
This number and scale value along the axis is drawn with
two decimal places. Since the digit size is 0.105 inch
(about 10 characters per inch), and since a scale value
appears every inch, no more than six digits and a sign
should appear to the left of the decimal point.
DELTAV represents the number of data units per inch of axis.
This value (increment or decrement), which is added to
FIRSTV for each succeeding one-inch division along the
axis, may either be computed by C_SCALE and stored beyond
FIRSTV at ARRAY(NPTS*INC+INC+1), or the value may be
determined by the user and stored at any location.
In order to use a standard format of two decimal places,
the size of DELTAV is adjusted to less than 100, but not
less than 0.01. As a result, the decimal point may be
shifted left or right in the scale values as drawn, and
the axis title is then followed by "*10**n", where n is
the power-of-ten adjustment factor. (See X-axis example
in Figure _____.)
1
2.10 Subroutine C_LINE
---------------
FUNCTION:
Plots a series of XY points with optional rescaling.
The C_LINE subroutine produces a line plot of the pairs of data values in two
arrays (XARRAY and YARRAY). C_LINE computes the page coordinates of each
plotted point according to the data values in each array and the respective
scaling parameters. The data points may be represented by centered symbols
and/or connecting lines between points.
The scaling parameters corresponding to FIRSTV and DELTAV (see C_SCALE) must
immediately follow each array. If these parameters have not been computed by
the C_SCALE subroutine they must be supplied by the user. If scaling is not
required, the user must place the appropriate minimum and delta values in the
specified elements of the arrays. For a one-to-one correspondence between
array data and plotted data, these values should be 0.0 (minimum) and 1.0
(delta).
CALLING SEQUENCE:
CALL C_LINE (XARRAY,YARRAY,NPTS,INC,+-LINTYP,INTEQ)
where:
XARRAY is the name of the array containing the abscissa (X)
values and the scaling parameters for the X array.
YARRAY is the name of the array containing the ordinate (Y)
values and the scaling parameters for the Y array.
NPTS is the number of data points to be plotted in each of the
two arrays just mentioned. The number does not include
the extra two locations for the scaling parameters. The
number of points in each array must be the same.
INC is the increment that the C_LINE subroutine is to use in
gathering data from the two arrays, as described
previously for the C_SCALE subroutine. XARRAY and YARRAY
must be dimensioned NPTS*INC+INC+1.
+-LINTYP is a control parameter which describes the type of line
to be drawn through the data points. The magnitude of
LINTYP determines the frequency of plotted symbols.
If LINTYP is zero, the points are connected by straight
lines but no symbols are plotted.
If LINTYP=1, a line plot with a symbol at each data point
is produced.
If LINTYP=n, a line plot connects every data point
defined in the array; a symbol is drawn at every nth data
point. (The pen is up when moving from its current
position to the first point.) For example, if LINTYP=4,
a special symbol (denoted by INTEQ) is plotted at every
fourth data point.
If LINTYP=-n, no connecting lines are drawn; only the
symbols are plotted, at every nth data point.
INTEQ is the integer equivalent of the special plotting symbol
centered at each data point. This value normally can be
0 through 14 (see Table 2), and has meaning only when
LINTYP is not zero. Some of these symbols are as
follows: box, octagon, triangle, plus, X, diamond, and
asterisk.
1
2.10 Subroutine C_NEWPEN
-----------------
FUNCTION
Select a new pen color. The number of colors available depends on the output
device used, but on almost all color devices the following values will
produce the associated colors:
0 -black
1 -red
2 -green
3 -yellow
4 -purple
5 -magenta
6 -cyan
7 -white (the default)
CALLING SEQUENCE
**
CALL C_NEWPEN(ICOLOR)
** This routine only produces color when CFT levels of 11531 or above
are used. Before this, this routine forced the pen back to the frame
origin and had no other affect.
1
2.12 A Sample Plotting Program
-------------------------
To illustrate the use of the CALCOMP routines, a sample program is provided
which will produce the graph shown in Figure ____. The only assumption made
is that the 24 pairs of TIME and VOLTAGE data values are contained in a file
of 24 records.
PROGRAM SAMPLE
Metalanguage output file is "pdf".
DIMENSION XARRAY(26),YARRAY(26)
Reserve space for 24 data values plus two additional locations
required by the C_SCALE, C_AXIS, and C_LINE subroutines.
10 CALL C_PLOTS (0,0,0)
Perform initialization.
20 READ (5,25)(XARRAY(I),YARRAY(I),I=1,24)
25 FORMAT(2F6.2)
Read 24 pairs of TIME and VOLTAGE from an input file into two arrays
with names XARRAY and YARRAY.
30 CALL C_PLOT(0.0,0.5,-3)
Establish a new origin one-half inch higher than the point where the
pen was initially placed so that the annotation of the TIME axis will
fit between the axis and the edge of the plotting surface.
40 CALL C_SCALE (XARRAY,5.0,24,1)
Compute scale factors for use in plotting the TIME values within a
five-inch plotting area.
50 CALL C_SCALE(YARRAY,6.0,24,1)
Compute scale factors for use in plotting the VOLTAGE data values
within a six-inch plotting area (i.e., the data pairs of TIME,
VOLTAGE will plot within a five-by-six inch area).
60 CALL C_AXIS(0.0,0.0,'TIME IN MILLISECONDS',-20,5.0,0.0,XARRAY(25),
XARRAY(26))
Draw the TIME axis (5 inches long), using the scale factors computed
in statement 40 to determine the milliseconds at each inch along the
TIME axis.
70 CALL C_AXIS(0.0,0.0,'VOLTAGE',7,6.0,90.0,YARRAY(25),YARRAY(26))
Draw the VOLTAGE axis (6 inches long) using the scale factors
computed in statement 50 to determine the voltage at each inch along
the VOLTAGE axis.
80 CALL C_LINE(XARRAY,YARRAY,24,1,2,4)
Plot VOLTAGE vs TIME, drawing a line between each of the 24 scaled
points and a symbol X at every other point.
90 CALL C_SYMBOL(0.5,5.6,0.21,'PERFORMANCE TEST',INTEQ,0.0,16)
Plot the first line of the graph title.
100 CALL C_SYMBOL(0.5,5.2,0.14,'REF. NO. 1623-46',INTEQ,0.0,16)
Plot the second line of the graph title.
110 CALL C_NFRAME
Terminate the plot.
120 CALL C_PLOT(0.0,00.0,999)
Close the plot file.
130 CALL EXIT
Terminate Program execution.
1
3.0 CALCOMP GENERAL FUNCTIONAL SOFTWARE
The routines included in the CALCOMP General Functional software category
are C_CIRCL, C_DASHL, C_DASHP, C_ELIPS, C_FIT, C_GRID, C_POLY and
C_RECT. These routines call the Basic routines and should be viewed
as an extension of the Basic library rather than as a separate entity.
1
3.1 Subroutine C_CIRCL
----------------
GENERAL DESCRIPTION:
C_CIRCL is a FORTRAN subroutine that draws, starting at a given point, an arc
which may be extended to form a circle or spiral.
CALLING SEQUENCE:
CALL CIRCLE (XPAGE,YPAGE,THO,THF,RO,RF,DI)
where:
XPAGE,YPAGE are the coordinates in inches, of the arc's starting
point.
THO is the radius angle, in degrees from the X-axis, for the
start of the arc.
THF is the radius angle, in degrees from the X-axis, for the
end of the arc.
RO is the arc's starting radius, in inches.
RF is the arc's ending radius, in inches.
DI is a code used to specify the type of line desired.
If DI = 0.0, a solid arc is drawn;
0.5, a dashed arc is drawn.
COMMENTS:
THO and THF may be positive or negative. If THO is less than THF, the arc is
drawn in a counterclockwise direction; and if THO is greater than THF, the
arc is drawn in a clockwise direction.
1
3.2 Subroutine C_ELIPS
----------------
GENERAL DESCRIPTION:
C_ELIPS is a FORTRAN subroutine which draws an ellipse or elliptical arc.
CALLING SEQUENCE:
CALL C_ELIPS (XPAGE,YPAGE,RMAJ,RMIN,ANGLE,THO,THF,IPEN)
where:
XPAGE,YPAGE are the coordinates, in inches, of the starting point of
the ellipse or arc.
RMAJ,RMIN are the lengths, in inches, of the semi-major and
semi-minor axes, respectively.
ANGLE is the angle of the major axis, in degrees.
THO,THF are the angles, in degrees with respect to ANGLE, of the
arc's starting and ending points.
IPEN is the code that moves the pen to the arc's starting
point. If the value of IPEN is:
3, the pen is up for the move;
2, the pen is down for the move.
COMMENTS:
THO and THF may be positive or negative. If THO is less than THF, the arc is
drawn in a counterclockwise direction; if THO is greater than THF, the arc is
drawn in a clockwise direction.
1
3.3 Subroutine C_DASHL
----------------
GENERAL DESCRIPTION:
C_DASHL is a FORTRAN subroutine which draws dashed lines connecting a series of
data points. Its operation is similar to that of the C_LINE subroutine.
CALLING SEQUENCE:
CALL C_DASHL (XARRAY,YARRAY,NPTS,INC)
where:
XARRAY is the name of the array containing the X values of the
data points to be plotted and the scaling parameters for
the X array.
YARRAY is the name of the array containing the Y values of the
data points to be plotted and the scaling parameters for
the Y array.
NPTS is the quantity of data points to be plotted.
INC is the increment between array elements to be plotted.
INC is greater than 1 if the values to be plotted are in
a mixed or multi-dimensioned array. (Normally INC = 1).
COMMENTS:
The arrays must be dimensioned with at least NPTS + 2 elements. The adjusted
minimum value (FIRSTV) and the adjusted delta value (DELTAV), normally
provided by the C_SCALE subroutine, must be stored following the data array.
For the X array, the adjusted minimum is stored in XARRAY (NPTS*INC + 1), and
the adjusted delta is in XARRAY (NPTS*INC + INC + 1). Similarly, for the Y
array, the minimum is in YARRAY (NPTS*INC + 1), and the delta is in YARRAY
(NPTS*INC + INC + 1). Therefore, XARRAY and YARRAY must be dimensioned to be
at least NPTS*INC+INC+1.
If scaling is not required, the user must place the appropriate minimum and
delta values in the specified elements of the arrays. For a one-to-one
correspondence between array data and plotted data, these values should be
0.0 (minimum) and 1.0 (delta).
A dashed line, with dashes approximately 0.1 inch long, is drawn connecting
sequential points. Coding is optimized so that plotting may either begin at
the first point and progress forward or begin at the last point and progress
backward.
1
3.4 Subroutine C_DASHP
----------------
GENERAL DESCRIPTION:
C_DASHP is a FORTRAN subroutine which draws a dashed line from the pen's
present position to a specified point.
CALLING SEQUENCE:
CALL C_DASHP (XPAGE,YPAGE,DASH)
where:
XPAGE,YPAGE are the coordinates, in inches, of the point to which the
dashed line is to be drawn.
DASH is the length, in inches, of each dash and of the space
between dashes.
COMMENTS:
If the line length is less than double the dash length, the dash length is
adjusted to half the line length.
1
3.5 Subroutine C_FIT
--------------
GENERAL DESCRIPTION:
C_FIT is a FORTRAN subroutine which draws a semi-hyperbolic curve through three
points.
CALLING SEQUENCE:
CALL C_FIT (XPAGE1,YPAGE1,XPAGE2,YPAGE2,XPAGE3,YPAGE3)
where:
XPAGE1,YPAGE1 are the X and Y coordinates, in inches, of the three
XPAGE2,YPAGE2 points through which the curve passes.
XPAGE3,YPAGE3
COMMENTS:
This subroutine generates a semi-hyperbolic fit using the three given points.
A set of points for which a fit is not possible is drawn with straight-line
segments.
RESTRICTIONS:
The curve through the three points must be multi-valued in both X and Y.
That is, the middle point (XPAGE2,YPAGE2) must be between the endpoints along
the X-axis or the Y-axis.
XPAGE1XPAGE2>XPAGE3 or
YPAGE1YPAGE2>YPAGE3
1
3.6 Subroutine C_GRID
---------------
GENERAL DESCRIPTION:
C_GRID is a FORTRAN subroutine which draws a linear grid.
CALLING SEQUENCE:
CALL C_GRID (XPAGE,YPAGE,DELTAX,DELTAY,NXSP,NYSP)
where:
XPAGE,YPAGE are the coordinates, in inches, of the grid's lower left
corner.
DELTAX is the number of inches between grid lines in the X
direction.
DELTAY is the number of inches between grid lines in the Y
direction.
NXSP,NYSP are the number of grid intervals in the X and Y
directions, respectively. The number of grid lines is
one more than the number of grid intervals.
COMMENTS:
C_GRID generates a linear grid of any size. The number of lines drawn is
NXSP\+\1 in the X direction and NYSP + 1 in the Y direction.
1
3.7 Subroutine C_POLY
---------------
GENERAL DESCRIPTION:
C_POLY is a FORTRAN subroutine used to draw equilateral polygons.
CALLING SEQUENCE:
CALL C_POLY (XPAGE,YPAGE,SLEN,SN,ANGLE)
where:
XPAGE,YPAGE are the coordinates, in inches, of the polygon's starting
point.
SLEN is the length, in inches, of a side of the polygon.
SN is the number of sides of the polygon.
ANGLE is the angle, in degrees, of the first side of the
polygon.
COMMENTS:
If SN is negative, a star is drawn with SN points.
1
3.8 Subroutine C_RECT
---------------
GENERAL DESCRIPTION:
C_RECT is a FORTRAN subroutine used to draw rectangles.
CALLING SEQUENCE:
CALL C_RECT (XPAGE,YPAGE,HEIGHT,WIDTH,ANGLE,IPEN)
where:
XPAGE,YPAGE are the coordinates, in inches, of the rectangle's lower
left corner, before rotation.
HEIGHT is the rectangle's height, in inches.
WIDTH is the rectangle's width, in inches. (This parameter
defines the base of the rectangle.)
ANGLE is the angle, in degrees, at which the rectangle's base
is to be drawn. (Rectangle is rotated about XPAGE,YPAGE.)
IPEN is the code that moves the pen to the rectangle's
starting point.
If the value of IPEN is:
3, the pen is up for the move;
2, the pen is down for the move.
1
4.0 CALCOMP SCIENTIFIC FUNCTIONAL SOFTWARE
The routines included in the CALCOMP Scientific Functional software
category are C_CURVX, C_CURVY, C_FLINE, C_LGAXS, C_LGLIN, C_POLAR,
C_SCALG, and C_SMOOT. These routines call the Basic routines and
should be viewed as an extension of the Basic library.
1
4.1 Subroutine C_CURVX
----------------
GENERAL DESCRIPTION:
C_CURVX is a FORTRAN subroutine which plots a function of X over a given range.
CALLING SEQUENCE:
CALL C_CURVX (XO,XF,COEFF1,EXP1,COEFF2,EXP2,COEFF3,EXP3,COEFF4,EXP4)
where:
XO,XF are the starting and ending values of X. (These are
assumed to be inches.)
COEFF1,COEFF2, are the coefficients of the polynomial that defines
COEFF3,COEFF4 the function to be plotted.
EXP1,EXP2, are the exponents of the polynomial that defines
EXP3,EXP4 the function to be plotted.
COMMENTS:
The polynomial that defines the function to be plotted is:
Y=COEFF1*X**EXP1+COEFF2*X**EXP2+COEFF3*X**EXP3+COEFF4*X**EXP4
for values of X from XO to XF, where deltaX=0.01. Since values of X are
assumed to be inches, any scaling required must be performed before calling
this subroutine. Errors may be generated if X is zero or negative.
1
4.2 Subroutine C_CURVY
----------------
GENERAL DESCRIPTION:
C_CURVY is a FORTRAN subroutine which plots a function of Y over a given range.
CALLING SEQUENCE:
Call C_CURVY(YO,YF,COEFF1,EXP1,COEFF2,EXP2,COEFF3,EXP3,COEFF4,EXP4)
where:
YO,YF are the starting and ending values of Y. (These are
assumed to be inches.)
COEFF1,COEFF2, are the coefficients of the polynomial that
COEFF3,COEFF4 defines the function to be plotted.
EXP1,EXP2 are the exponents of the polynomial that defines
EXP3,EXP4 the function to be plotted.
COMMENTS:
The polynomial that defines the function to be plotted is:
X=COEFF1*Y**EXP1+COEFF2*Y**EXP2+COEFF3*Y**EXP3+COEFF4*Y**EXP4
for values of Y from YO to YF, where deltaY=0.01. Since values of Y are
assumed to be inches, any scaling required must be performed before calling
this subroutine.
If Y is zero or negative, errors may be generated.
1
4.3 Subroutine C_FLINE
----------------
GENERAL DESCRIPTION:
CALLING SEQUENCE:
Call C_FLINE (XARRAY,YARRAY,NPTS,INC,+-LINTYP,INTEQ)
where:
XARRAY is the name of the array containing the values to be
plotted as the abscissa and the appropriate scaling
parameters.
YARRAY is the name of the array containing the values to be
plotted as the ordinates and the appropriate scaling
parameters.
NPTS is the number of data points to be plotted:
if NPTS >0 a straight line is drawn between the points.
if NPTS <0 a smooth curve, drawn using a modified
spline-fitting technique, is drawn between the points.
INC is the increment between elements in the array to be
plotted. INC >1 if the values to be plotted are in a
mixed array. (Usually INC = 1.)
+-LINTYP is used to control the type of graph produced:
if LINTYP = 0 a line is plotted between successive data
points. (No symbols are plotted.)
if LINTYP = 1 a line plot is produced, with a symbol at
each data point.
if LINTYP = n a line plot is produced, with a symbol at
every nth data point.
if LINTYP = -n, connecting lines are not plotted between
data points; a symbol appears at every nth data point.
INTEQ is the integer equivalent used to specify the symbol to
be plotted at a data point. (Refer to the description of
C_SYMBOL for possible values of INTEQ.)
COMMENTS:
The arrays must be dimensioned with at least NPTS + 2 elements. The adjusted
minimum value (FIRSTV) and the adjusted delta value (DELTAV), normally
provided by the C_SCALE subroutine, must be stored following the data array.
For the X array, the adjusted minimum is stored in XARRAY (NPTS*INC + 1), and
the adjusted delta is in XARRAY (NPTS*INC + INC + 1). Similarly, for the Y
array, the minimum is in YARRAY (NPTS*INC + 1), and the delta is in YARRAY
(NPTS*INC + INC + 1). Therefore, XARRAY and YARRAY must be dimensioned to be
at least NPTS*INC+INC+1.
If scaling is not required, the user must place the appropriate minimum and
delta values in the specified elements in the arrays. For a one-to-one
correspondence between array data and plotted data, these values should be
0.0 (minimum) and 1.0 (delta).
1
4.4 Subroutine C_SMOOT
----------------
GENERAL DESCRIPTION:
C_SMOOT is a FORTRAN subroutine which draws a smooth curve through
a set of data points. It accomplishes this by using a modified
spline-fitting technique. The subroutine receives a single coordinate
pair on each call and accumulates the points until it has received a
sufficient number to compute a pair of cubic parametric equations
for a smooth curve. This accumulation method requires the user to
specify an initial and a terminal call to the subroutine.
The C_SMOOT subroutine operates in either of two modes: Smooth Mode
and Plot Mode.
CALLING SEQUENCE:
Call C_SMOOT (XPAGE,YPAGE,IPEN)
XPAGE,YPAGE are the coordinates, in inches, of a single point through
which the pen moves.
IPEN determines the mode and action of the C_SMOOT subroutine.
DETAILED DESCRIPTION:
The first call to C_SMOOT must use an IPEN value of 0 or -1 to put C_SMOOT in the
Smooth Mode.
if IPEN = 0, XPAGE,YPAGE define the initial point (P(1))
on the curve. The smoothing function ends at the last
point (P(n)). An open curve is produced.
if IPEN = -1, XPAGE,YPAGE are used to define the initial
point (P(1)) on the curve. The smoothing function
continues from the last point (P(n)) back to the initial
point (P(1)). A closed curve is produced.
SMOOTH MODE:
When C_SMOOT is in the Smooth Mode, IPEN performs the following functions:
IPEN = -2 XPAGE,YPAGE are used to define points P(2), P(3),...,
P(N-1), and a smoothed curve is drawn through the points
on the curve.
IPEN = -3 XPAGE,YPAGE are used to define points P(2), P(3),
...,P(N-1), and the pen, in the up position, is moved
through these points. The smoothing function is
maintained.
IPEN = 2 or 3 The call is treated as a normal CALL C_PLOT
(XPAGE,YPAGE,IPEN), and the point is not considered a
point on the curve. The point of departure from the
curve is the next-to-last point received by C_SMOOT, not
the last point.
When the next call to C_SMOOT with IPEN = -2 or -3 is received,
the pen is repositioned to the point where it left the smooth curve.
The smooth curve is then continued as though the calls with IPEN =
2 or 3 had not occurred.
IPEN <=(-24) is used for the terminal call while C_SMOOT is in the
Smooth Mode. XPAGE,YPAGE represent P(N). The curve is finished,
and the subroutine returns to the Plot Mode.
C_PLOT MODE:
C_SMOOT is in the Plot Mode after receiving a terminal call.
IF IPEN = +-2 or +-3, the call is treated as a normal CALL
C_PLOT (XPAGE,YPAGE,IPEN).
COMMENTS:
When C_SMOOT is called while it is in the Smooth Mode, the pen
is not moved until three points on an open curve or four points on a
closed curve have been received. For subsequent calls to C_SMOOT,
the actual pen position is the next-to-last point received.
Calls to other plotting subroutines may be intermixed with calls
to C_SMOOT. Point-of-departure restrictions are the same as noted
in the Smooth Mode description above.
The first call to C_SMOOT must be with IPEN = 0 or -1.
1
4.5 Subroutine C_SCALG
----------------
GENERAL DESCRIPTION:
C_SCALG is a FORTRAN subroutine used to determine scale factors of a
data array to be plotted on a logarithmic scale. The scale factors
are those used by subroutines C_LGLIN and C_LGAXS. C_SCALG is similar
in operation to C_SCALE.
CALLING SEQUENCE:
CALL C_SCALG(ARRAY,AXLEN,NPTS,INC)
where:
ARRAY is the array containing the data to be scaled. The
FORTRAN DIMENSION statement must specify at least two
elements more than the number of values being scaled, to
allow room for C_SCALG to store the computed starting value
and scaling factor at the end of the array.
AXLEN is the maximum length, in inches, over which the data is
to be plotted.
NPTS is the number of values in ARRAY to be scaled.
INC is the increment between elements of the array to be
plotted. INC is greater than 1 if the values to be
plotted are in a mixed or multi-dimensioned array.
(Normally INC = 1).
COMMENTS:
The array must be dimensioned with at least NPTS + 2 elements.
The adjusted minimum value (FIRSTV) and the delta value (DELTAV) are
stored by C_SCALG in the data array.
The adjusted minimum is stored in ARRAY (NPTS*INC + 1), and the
adjusted delta (log cycles per inch) is in ARRAY (NPTS*INC + INC + 1).
Therefore, ARRAY must be dimensioned to be at least NPTS*INC+INC+1.
Every INCth element of the array ARRAY, beginning with the first,
is scanned to find the minimum and maximum values of the array.
Next, the greatest value of 10**n (integer n) less than or equal
to the minimum value is found and then stored in ARRAY (NPTS*INC + 1).
Finally, the smallest value of 10**m (integer m) greater than or
equal to the maximum value is established.
The delta value is the difference between the minimum and maximum
powers of ten, divided by AXLEN, yielding log cycles per inch.
The delta value is stored in ARRAY (NPTS*INC + INC + 1).
Examples:
A. For the following array of values
ARRAY(1) = 1500.0
ARRAY(2) = 3000.0
ARRAY(3) = 2500.0
ARRAY(4) = 300.0
and the following argument values
AXLEN = 1.0
NPTS = 4
INC = 1
the adjusted minimum (FIRSTV) and delta value (DELTAV) stored by
C_SCALG are:
FIRSTV: ARRAY(5) = 100.0
DELTAV: ARRAY(6) = 2.0
B. If the value of AXLEN in Example A were changed to 4.0, the resultant
values stored would be:
FIRSTV: ARRAY(5) = 100.0
DELTAV: ARRAY(6) = 0.5
C. For the following array of values
ARRAY(1) = 1.2*
ARRAY(2) = 100.0
ARRAY(3) = 2.3*
ARRAY(4) = 88.0
ARRAY(5) = 1.8*
ARRAY(6) = 0.0
ARRAY(7) = 0.8*
ARRAY(8) = 10.0
ARRAY(9) = 0.7*
ARRAY(10) = 10.0
and the following argument values:
AXLEN = 10.0
NPTS = 5
INC = 2.
the adjusted minimum (FIRSTV) and delta value (DELTAV) are determined
from the value of the asterisked items (1, 3, 5, 7, and 9) in the
above array. The computed values are also stored two subscript
elements apart.
FIRSTV: ARRAY(11) = 0.1
DELTAV: ARRAY(13) = 0.2
1
4.6 Subroutine C_LGAXS
----------------
GENERAL DESCRIPTION:
C_LGAXS is a FORTRAN subroutine which draws a logarithmic axis with annotation
in powers of ten. C_LGAXS is similar in operation to C_AXIS.
CALLING SEQUENCE:
CALL C_LGAXS(XPAGE,YPAGE,IBCD,+-NCHAR,AXLEN,ANGLE,FIRSTV,DELTAV)
where:
XPAGE,YPAGE are the coordinates, in inches, of the axis starting
point.
IBCD is the character data to be used as the axis title (may
be one or more characters). It is centered and
positioned parallel to the axis.
+-NCHAR is the number of characters in the axis title.
if NCHAR is:
negative, annotation is placed on the clockwise side of
the axis (normally used for the X axis);
positive, annotation is placed on the counterclockwise
side of the axis (normally used for the Y axis).
AXLEN is the length of the axis, in inches.
ANGLE is the angle, in degrees, at which the axis is to be
drawn. (The axis is rotated about XPAGE,YPAGE). The X
axis is at 0 degrees; the Y axis is at 90 degrees.
FIRSTV is the value of annotation at the beginning of the axis.
DELTAV is the number of log cycles per inch (the reciprocal of
the length of one cycle, in inches).
COMMENTS:
A tick mark is placed on the axis for each power of ten and for each of the
nine integer values between.
Annotation is placed at the tick marks as follows:
If a cycle is not less than two inches long, the integer tick marks are
annotated.
The power-of-ten tick marks are annotated in the form 10**N.
1
4.7 Subroutine C_LGLIN
----------------
GENERAL DESCRIPTION:
C_LGLIN is a FORTRAN subroutine used to plot data either in log-log or semi-log
mode. C_LGLIN is similar in operation to C_LINE.
CALLING SEQUENCE:
CALL C_LGLIN (XARRAY,YARRAY,NPTS,INC,+-LINTYP,INTEQ,LOGTYP)
where:
XARRAY,YARRAY are the arrays containing the variables to be plotted as
abscissa and ordinate, respectively; either logarithmic
or linear, depending on the value of LOGTYP. They also
contain the scaling parameters.
NPTS is the number of points to be plotted.
INC is the increment between elements in the array to be
plotted. INC>1 if the values to be plotted are in a
mixed array. (Usually INC = 1).
+-LINTYP is used to control the type of graph produced:
If LINTYP = 0 a line is plotted between successive data
points. No symbols are plotted.
If LINTYP = 1 a line plot is produced, with a symbol at
each data point.
If LINTYP = n a line plot is produced, with a symbol at
every nth data point.
If LINTYP = -n, connecting lines are not plotted between
data points; a symbol appears at every nth data point.
INTEQ is the integer equivalent used to specify the symbol to
be plotted at a data point. (Refer to the description of
C_SYMBOL for possible values of INTEQ.)
LOGTYP is a code specifying the type of plot.
If LOGTYP is:
-1, a semi-log plot, logarithmic in X and linear in Y is
produced;
0, a log-log plot is produced;
+1, a semi-log plot, linear in X and logarithmic in Y is
produced.
COMMENTS:
The arrays XARRAY and YARRAY must be dimensioned with at least NPTS + 2
elements. The adjusted minimum values and the delta values (normally
provided by the C_SCALG subroutine for logarithmic data and by the C_SCALE
subroutine for linear data) must be stored in the data arrays.
For the X array, the adjusted minimum is stored in XARRAY (NPTS*INC + 1), and
the adjusted delta is in XARRAY (NPTS*INC + INC + 1). Similarly, for the Y
array, the minimum is in YARRAY (NPTS*INC + 1), and the delta is in YARRAY
(NPTS*INC + INC + 1). Therefore, XARRAY and YARRAY must be dimensioned to be
at least NPTS*INC+INC+1 words long.
If scaling is not required, the user must place the appropriate minimum and
delta values in the specified locations in the arrays. For linear arrays,
these values should be 0.0 (minimum) and 1.0 (delta), to ensure a one-to-one
correspondence between array data and plotted data.
1
4.8 Subroutine C_POLAR
----------------
GENERAL DESCRIPTION:
C_POLAR is a FORTRAN subroutine which scales and plots a radial variable of any
magnitude against an angular variable (angle in radians) as polar
coordinates. C_POLAR produces either a line plot (with lines connecting data
points) or a point plot, centered at (0.0).
CALLING SEQUENCE:
CALL C_POLAR (RADAR,ANGAR,NPTS,INC,+-LINTYP,INTEQ,RMAX,DR)
where:
RADAR is the name of the array containing the radial values.
ANGAR is the name of the array containing the angular values
(radians).
NPTS is the number of data points to be plotted.
INC is the increment between elements in the array. INC is
greater than 1 if the values to be plotted are in a mixed
array. Every INCth point in the array is plotted.
(Normally INC = 1). RADAR and ANGAR must be dimensioned
to be INC*NPTS words long.
+-LINTYP is used to control the type of graph produced:
If LINTYP = 0 a line is plotted between successive data
points. No symbols are plotted.
If LINTYP = 1 a line plot is produced, with a symbol at
each data point.
If LINTYP = n a line plot is produced, with symbol at
every nth data point.
If LINTYP = -n, connecting lines are not plotted between
data points; a symbol appears at every nth data point.
INTEQ is the integer equivalent used to specify the symbol to
be plotted at the data point. (Refer to the description
of C_SYMBOL for possible values of INTEQ).
RMAX is the maximum radius for the plotting area, in page
inches. If RMAX<=(0), DR is used as scale factor.
DR is the scale factor. If RMAX>0, DR is computed by the
C_POLAR subroutine; if RMAX<=(0), DR must contain the scale
factor. DR is expressed in units of data per page inch.
COMMENTS:
Angles are measured in radians counterclockwise around (0.,0.), with zero
being in the +X direction.
Radial values are measured from (0.,0.), with negative values being plotted
radially opposite from positive values.
1
5.0 APPLICATION ROUTINES
The routines included in this category draw, on a single call, complete plots
of types useful to engineers. They are not part of the software leased from
CALCOMP, but they do use the Basic CALCOMP subroutines.
1
5.1 Subroutine C_CNTOUR
-----------------
GENERAL DESCRIPTION:
A contour map is a graphical representation of a three-dimensional surface or
a function of two variables. A contour is defined as the intersection of the
surface or function with a specified plane parallel to the reference plane.
If the surface is denoted by z = f(x,y) where x and y are the coordinate
values in the (x,y)-plane (reference plane), then z equals a constant defines
the plane of intersection.
A contour map consists of a set of contours, usually generated for equally
spaced values of z. In a region where the surface changes rapidly, the
individual contours are close together, and where the surface changes
gradually, they are far apart. Thus, a contour map provides a means of
observing topological behavior of a surface as well as locating regions where
the function z has specific values.
The C_CNTOUR subroutine and its supporting routines provide the
user with a general-purpose package for preparing contour maps.
The package was developed at the Westinghouse Research Laboratories
and released at the Westinghouse Symposium for general use.
CALLING SEQUENCE:
CALL C_CNTOUR (A, NX, NY, X, Y, HGT, CV, NCV, LEGEND, NDIMA)
where:
A input double-subscripted array containing the discrete
values of the function.
NX index of the last row of data in A (INTEGER).
NY index of the last column of data in A (INTEGER).
X single-scripted array containing values of x
corresponding to row positions of A.
Y single-subscripted array containing values of y
corresponding to column positions of A.
HGT height of plot restricted to less than or equal to 6.5
inches (REAL). The width is established accordingly.
CV single-scripted array of contour values to be plotted.
NCV number of contour values (INTEGER).
LEGEND Logical option. If .TRUE., the legend relating contour
values and their identification numbers is printed. If
.FALSE., this legend will not be printed.
NDIMA the dimensional number of rows for A.
COMMENTS:
The CALCOMP initialization (C_PLOTS(0,0,0)) and termination (C_PLOT(X,Y,999))
calls must be supplied by the user, external to C_CNTOUR. These calls were
left out of C_CNTOUR to allow the user to create multiple plots in a single
program.
1
6.0 ACCESSING THE CALCOMP ROUTINES
Program execution creates a metalanguage file with the default name "pdf".
This file may be cataloged for future use or post processed immediately. The
name of the output metalanguage file can be specified through the environmental
variable "CALCOMP_PDF".
Post processing is done using the device dependent graphics post
processing procedures which are described in detail in the DOCLIB file called
GRPHDOC.
SAMPLE JOB USING THE CALCOMP LIBRARY
------------------------------------
# assign a user specified name to output PDF
export CALCOMP_PDF
CALCOMP_PDF=pdf.$$
# compile and load user program "mycode.f" with calcomp library routines
cf77 my_code.f -L/usr/local/lib -lcalcomp -o my_code.exe
# execute user absolute my_code.e
my_code.e < my_code.data
gview -f pdf.$$ -t x11 -p 1
1
7.0
CALCOMP SUPPLEMENT - MOVING EXISTING CALCOMP CODE
I. INTRODUCTION -------------
The CALCOMP plot library is based on materials leased from California
Computer Products, Inc; and had been available in a very similar
form on the old CDC 7600 Super Computers. Of course, this similarity
is intentional. This library is trying to provide a consistent
programming environment wherever possible. Therefore, users will
notice that this guide is based heavily on it's 7600 predecessor.
All of the subroutines from the 7600 version of the CALCOMP library
have been included in this version; although plots generated will
not always look exactly the same as those produced on the 7600s.
The CALCOMP library is interfaced to locally developed routines (called
primitives) which produce a file compatible with TEMPLATE PDF files. This
allows CALCOMP-based code to generate output which can be sent to any
supported TEMPLATE output device.
Although TEMPLATE IS THE RECOMMENDED GRAPHICS PACKAGE,
CALCOMP is being provided to meet certain special requirements:
1) To facilitate the migration of user code that already uses a
CALCOMP-like package to new machines.
2) To support interfaces to non-inhouse code. Such code may
often already support a set of CALCOMP-like calls.
3) Applications where resource utilization is more important that
powerful graphics capabilities.
There are no plans to provide local enhancements to CALCOMP, and
TEMPLATE capabilities (such as high-level charting routines) will
not be made available with CALCOMP. Those involved in program
conversions and development are urged to consider long-term graphics
requirements in deciding which package to use (CALCOMP or TEMPLATE).
The CALCOMP software was initially developed to drive only CALCOMP
plotters. In general, the calls produced plots directly in inches
(A call to draw a line one unit long produced a one-inch line on
the plotter).
With the interfacing of CALCOMP to the TEMPLATE graphics system (which
provides the ability to obtain output on a wide range of devices),
the meaning of units in the CALCOMP library has undergone
a change. CALCOMP Inches, therefore, may not translate directly
into physical inches on a pen plotter SECTION II is written for the
special audiences that most often will be using CALCOMP.
It details the differences between this CALCOMP and 7600 CALCOMP and
talks about how to get true inches when using PDF files. Also,
important differences exist between this CALCOMP and standard CALCOMPs
third-party software often provides interfaces to. The format
of the following primary example program can be used as a guide as to
how to nullify the affects of these differences.
1
II. DIFFERENCES FROM 7600 CALCOMP LIBRARIES
--------------------------------------------
1. For subroutines C_SYMBOL, C_AXIS, and C_LGAXS, the parameter used to
specify text or title information (IBCD) has been changed to be
type CHARACTER to be consistent with ANSI 77 FORTRAN. Data for these
arguments should be changed to be type CHARACTER (although use of
a Hollerith string or INTEGER array may currently work, their use is
not recommended, and there are no plans to support this usage).
2. For subroutine C_SYMBOL on the 7600s, there is a "STANDARD" call
(used to plot a text string) and a "SPECIAL" call (used to plot a
single symbol). To Accommodate CHARACTER data and both versions of
the call to C_SYMBOL, the calling sequence was modified to have 7
arguments. All programs being converted from the 7600
-MUST- make this change to the call to C_SYMBOL.
The new calling sequence is
CALL C_SYMBOL (XPAGE,YPAGE,HEIGHT,IBCD,INTEQ,ANGLE,NCHAR)
Where XPAGE, YPAGE, HEIGHT, and ANGLE are defined as on the 7600s, and the
user guide can be consulted for details of their use.
The last parameter NCHAR is used as a flag to specify whether a text string
or a single symbol is being plotted. If NCHAR is less that zero, a single
symbol is plotted regardless of the contents of IBCD. If NCHAR is equal to
or greater than zero the string is IBCD is used (FAILURE TO SPECIFY THE
PROPER VALUE FOR NCHAR, INTEQ OR IBCD WILL CAUSE ERRONEOUS RESULTS).
To use C_SYMBOL to plot text for titles, captions, or legends--
IBCD--Contains the text string as CHARACTER data.
INTEQ--Should be set to 999.
(THE ACTUAL VALUE IS NOT USED FOR ANYTHING.)
NCHAR--Is the number of characters in IBCD.
For example, the following call to C_SYMBOL will result in the characters
'TITLE 10' being output beginning at X and Y coordinates of 1.0.
CHARACTER GRLBL*8
GRLBL = 'TITLE 10'
CALL C_SYMBOL (1.0,1.0,0.14,GRLBL,999,0.0,8)
To use C_SYMBOL to plot a single symbol or character--
IBCD--A dummy CHARACTER variable or string should be used
THE ACTUAL VALUE IS NOT USED FOR ANYTHING.)
INTEQ--Contains the INTEGER EQUIVALENT of the desired symbol.
If INTEQ has a value of 0 (zero) through 14, a centered
symbol (where XPAGE and YPAGE specify the center of
the symbol) is produced. The symbol table is unchanged
from that on the 7600s, so the table on page 2-10 of the
7600 CALCOMP guide is still applicable.
NCHAR--Determines whether the pen is up or down during the move
to XPAGE and YPAGE. (IT MUST BE NEGATIVE.)
When NCHAR is--
-1, the pen is UP during the move.
-2 or less, the pen is DOWN during the move.
For example, the following call to C_SYMBOL will result in special symbol
number 5 being output with its center at XY coordinates of (1.0,1.0).
CALL C_SYMBOL (1.0,1.0,0.14,DUMMY,5,0.0,-1)
3. Because of interfacing the CALCOMP routines to the device
dependent TEMPLATE-based post-processing procedures , some limit for
the maximum plot size had to be established. For the CALCOMP
library, a plot frame is limited to a maximum size in either the
X or Y direction of 100 "CALCOMP inches". (The actual frame size
on a particular output medium is dependent on the method of post-
processing and the device selected.)
Each plot frame is initialized by a call to subroutine C_PLOT with the third
argument (IPEN) equal to -2 or -3. For example,
CALL C_PLOT (0.5,1.0,-3)
Says to move 0.5 inches in the X-direction and 1.0 inch in the Y-direction
before establishing a new origin. When establishing a new origin, all
offsets are included inside the frame boundary, and therefore, they are part
of the plot frame size. If any X or Y coordinate value (Plus the appropriate
offset) exceeds the 100 inch limit, results are unpredictable. In programs
where X and Y coordinate values exceed the scaling limit, a call to the
CALCOMP routine C_FACTOR may be used to scale down the plot size appropriately.
Each plot frame is terminated by a call to subroutine C_NFRAME; no additional
offset is added here.
KNOWLEDGE OF THE PLOT FRAME SIZE IN THE X AND Y DIRECTIONS WILL BE NEEDED TO
SCALE PEN PLOTS TO ACTUAL INCHES WHEN THE DEVICE DEPENDENT POST PROCESSING
PROCEDURES ARE AVAILABLE. THE FOLLOWING EXAMPLE IS PROVIDED TO ASSIST IN
UNDERSTANDING HOW THE FRAME SIZE IS DETERMINED.
PROGRAM CALTEST
CALL C_PLOTS (0,0,0) ! perform initialization
CALL BORDER(8.5,11.0) ! establish a consistent frame size
C Calls to generate first plot go here
C where all calls stay inside area established by border
C .
C .
CALL C_NFRAME ! terminate first plot
CALL BORDER(8.5,11.0) ! establish a consistent frame size
C In next plot negative values up to (-1,-2) are needed
CALL C_PLOT (1.0,2.0,-3) ! establish origin for second plot
C To stay in the border no numbers greater than XBORDER-1 in X
C or YBORDER-2 can be used
C Calls to generate second plot go here
C .
C .
CALL C_NFRAME ! terminate second plot
CALL C_PLOT (0.0,0.0,999)! close the plot file
END
SUBROUTINE BORDER(XBORDER,YBORDER)
C Must be called with same values throughout entire program
C or not all frames will plot to same scale.
C Draw a box inside of which all frames can appear
CALL C_PLOT (XBORDER,0.0, 2)
CALL C_PLOT (XBORDER,YBORDER,2)
CALL C_PLOT (0.0, YBORDER,2)
CALL C_PLOT (0.0, 0.0, 2)
RETURN
END
4. All coordinate values (XPAGE, YPAGE for example) should be greater than
or equal to zero relative to the original frame origin. Negative
values will be clipped or might cause post-processor errors.
(Although this was not a requirement on the 7600s, it is necessary
because metafiles must contain only positive values and it
would be very inefficient to store each frame's data and then translate
all the values to positive numbers once the frame was finished and the
largest negative numbers in the frame could be identified.
5. Use of the CALCOMP library results in a segmented -PDF- being created
on a dataset called "pdf". Subroutine C_PLOTS can not be used to alter
this name, only the FORTRAN unit number used when referencing it.
6. Subroutine C_PLOTS must still be the first CALCOMP subroutine called.
It performs various initialization functions and should be called
only one time per program execution. Although some of the values
are not used, they are maintained for compatibility purposes.
7. Subroutine C_CNTOUR (Which was developed at the Westinghouse Research
Laboratories) is available in the CALCOMP library. The plot
produced by C_CNTOUR will look different from that produced
on the 7600s since the legend is placed at the top of the plot. If more
that 20 contours are used, the legend could overwrite the plot. A limit
of 6.5 inches must be observed for the height parameter (HGT).