rs@uunet.UUCP (07/09/87)
Submitted-by: "Wombat" <rsk@j.cc.purdue.edu>
Posting-Number: Volume 10, Issue 48
Archive-name: crc_plot/Part04
# This is a shell archive.
# Remove everything above and including the cut line.
# Then run the rest of the file through sh.
#----cut here-----cut here-----cut here-----cut here----#
#!/bin/sh
# shar: Shell Archiver
# Run the following text with /bin/sh to create:
# doc [other files... don't panic --r$]
mkdir doc
chdir doc
cat << \SHAR_EOF > HowtoInstall
.NP
.EQ
delim $$
.EN
.ce
Notes on how to install
.br
.sp
.ce
"The CRC Graphics Package"
.br
.sp
.ce 4
Carl Crawford
School of Electrical Engineering
Purdue University
West Lafayette, IN 47901
.sp
.ce
Tel:~~317-494-3456
.sp
.ce 3
UUCP Address:~~VCBVAX!PUR-EE!CRC
~~~~~~~~~~~~~~~IHNP4!PUR-EE!CRC
~~~~~~~~~~~~~~~DECVAX!PUR-EE!CRC
.sp 2
.br
.ul
Introduction
.PP
This set of notes is to help new sites install
"the CRC graphics package"
on their systems.
The document first presents descriptions of the sources that are needed
to build the package.
Then how to compile and build the
package.
Finally,
how to configure the defaults to fit the system.
.sp
.ul
.ne 6
Sources
.PP
Create a source directory for the
graphics.
Currently the distribution tape
assumes that
.sp
.ce
/u/crc/graphics
.sp
is the root of the graphics system.
For the purpose of this paper,
.sp
.ce
$"~"~crc$
.sp
will indicate the root of the graphics source.
.PP
Within this directory,
these are the following sub-directories:
.sp
$"~"$crc/lib~~~~~~~~~~library subroutines
.br
$"~"$crc/src~~~~~~~~~~runtime programs
.br
$"~"$crc/charfont~~~~~character' font information
.br
$"~"$crc/doc~~~~~~~~~~nroff sources for documentation
.br
$"~"$crc/tmp~~~~~~~~~~junk directory. (Ignore if present).
.sp
.PP
The library routines are subroutines
callable from either F77 or C.
Actual device control is done through pipes to programs in
$"~"$crc/src.
The current drivers are:
.sp
$"~"$crc/src/gp.c~~~~~~Versatec electrostatic printer
.br
$"~"$crc/src/gp/p.c~~~~Printronix lineprinter
.br
$"~"$crc/src/hpd.c~~~~~HP Flatbed plotter
.br
$"~"$crc/src/gd.c~~~~~~Control/Grinnel image displays
.sp
The path names to the respective drivers are within
the code.
Change them to reflect the configuration of your system.
'GPLP' pipes its output to 'OPR'.
If you don't have 'OPR',
just write directly to the printronix.
.sp 2
.ul
.ne 8
Installation First Time
.sp
.ul
.ti +5
Library Subroutines
.in +10
CD $"~"$crc/lib
.br
CC -c *.c
.br
AR CA /usr/lib/libG.a 'lorder*.c ltsort' (used to set up proper order
for a one-pass load.)
.sp
.in -10
.ne 8
Runtime
.br
.in +5
.br
CD~~$"~"$crc/src
.br
CC~~gplot.c~-i~-1G~-1m~-0\
.br
.ti +8
/u/bin/gplot
.br
.ti +12
*(note /u is the same as /usr)
.br
CC~~gp.c -0 /u/bin/gp
.br
CC~~gp/p.c -0 /u/bin/gp/p
.br
CC~~strip7.c -0 /u/bin/strip7
.br
mkdir~~/u/lib/graphics
.br
CC~~hpd.c -0 /u/lib/graphics/hpd
.br
CC~~gd.c -0 /u/lib(graphics)gd
.sp
.in -5
.ne 8
Charfont
.in +5
CD~~$"~"$crc/charfont
.br
CC~~genfont.c -0 genfont
.br
genfont /u/lib/graphics/font.5x7 \ < ifont.5x7
.br
(I just noticed that genfont.c is not up to date.
Just copy font.5x7 from the distribution tape).
.in -5
.sp
.PP
I realize that this is all very terse.
But if you look at the distribution tape,
and then at the 'makefiles',
it will be easy to figure out what I mean.
A note on the 'makefiles'.
At Purdue,
we run a network of machines.
The source for the network is on the 'A' machine
and all the other machines are updated from this
particular machine.
.PP
The first couple of lines in each section in each makefile is used
to update the local machine
(A machine at Purdue).
The rest of each section gets the information
to other machines.
.sp 2
.ul
.ne 8
Documentation
.sp
.in +5
CD~~~~~$"~"$crc/doc
.br
mkdir~~/src/man/graphics/crc
.br
E~=~/src/man/graphics/crc
.br
for i in *.r
.br
DO
.br
~~~~~~~nroff S|i~>S|E/'basename~S|i'
.br
DONE
.in -5
.sp 2
.ul
.ne 8
Configuration
.PP
In /u/lib/graphics, there should
be four files:
.sp
.nf
FORMAT
hpd.site <machine name>
gd.site <machine name>
gp.site <machine name><size>
gplp.site <-xx>
.fi
.sp
These files tell the respective programs where to send
the graphics output by default.
On the Purdue Network the
<machine name>
is one of the following:
.sp
.nf
.ne 8
local $rarrow$ send output to local device
ve Dual CPU VAX
vm VAX
A 11/70
B 11/45
P 11/70
ARPA 11/45
.fi
.sp
If the <machine name> isn't local,
then the program 'ns'
is used to bring up a 'shell' on the
remote machine.
Set the <machine name> to the default machine.
If you do not have a network,
they should all be set to 'local'.
.PP
For gp/p.site the '-xx' specifies the default
network lineprinter.
.PP
For gp.site the <size> field is either 100 or 132.
This number is the size in 'words'
or 'bytes'
(I forget which one)
of the line length.
Most new Versatecs are 100.
.sp 2
.ul
.ne 8
Update
.PP
All the 'makefiles'
are set up so that all the files are automatically
updated after changes are made.
This is useful on machines where
a network is used.
The program 'cs'
is just another version of the 'ns' routine,
but brings up a long shell.
.sp 2
.ul
.ne 8
Addition of New Network
.PP
This section is useful if you have
a set of machines that use the graphics package and a new one is added.
.PP
Get the following files from an existing machine.
.sp
.nf
.ne 6
/u/bin/gplot
/gp executable
/gplp
/strip7
.fi
.sp
.nf
.ne 6
/u/lib/libG.a
/graphics/font.5x7
/gd
/hpd executable
/gplp.site
/gp.site
/hpd.site
/gd.site
.fi
.sp
Then edit the *.site files to reflect the new machine.
.sp 2
.ul
Closing Remarks
.PP
If all the documentation/sources look confusing,
then I apologize.
The graphics package was originally written for my own use and
then released for general use.
I never expected the wide acceptance of the package.
Only in the past few months,
have changes been made to make it easy to
use at other institutions.
This explains this handwritten document.
.PP
Please do not hesitate to call if you have problems.
.sp 4
.in +35
Carl Crawford
1 Oct., 1981
.in -35
.sp 2
P.S. Good luck and enjoy it once you get it working!
.bp
.BK 12
.ls 2
.nf
Computer File Information:
.in +10
Name of Paper: "The CRC Graphics Package"
Author(s): Carl Crawford
Computer File Name: CRCgraphic
Account Number:
Charges for this version: 2.0 hours
Done by: Jenny Owen
Date: Oct. 13, 1981
.in -10
.fi
SHAR_EOF
cat << \SHAR_EOF > introduction.0g
.TH INTRODUCTION 0g "CRC Graphics Package"
.SH NAME
Introduction to the CRC Graphics Package
.SH DESCRIPTION
The CRC Plotting Package is a device independent graphics
system.
Subroutines for generating graphics exist for
programs written in
FORTRAN or C.
A program called Qplot exists to plot binary vectors
generated as the output of any program.
.PP
The following list indicates the devices currently supported
by this package:
.sp 1
.nf
.ta 1.5i 3i 4.5i
DEVICE MACHINE(S) RESOLUTION DISPLAY SIZE
(bits) (in plot units)
Plot(5) 32768 x 32768 Device Dependent
Comtal ARPA 512 x 512 10 x 10
Grinnel ARPA 512 x 512 10 x 10
Printronix P, EC, PP, MA 512 x 512 10 x 10
Retro-Graphic 512 x 256 10 x 10
HP 7221A EG 10240 x 7800 13.1 x 10
Tektronix 4014 EG 1024 x 780 13.1 x 10
Tektronix 4010 ARPA 1024 x 780 13.1 x 10
.fi
.PP
The MACHINE field indicates which
network computers currently have
one of the specified devices.
The DISPLAY SIZE is the x by y size of the plotting
area for each device.
The units are arbitrary and vary from device to
device.
All distances are measured in plot units.
.PP
The CRC Graphics package is currently in a state of transition.
The original package contained all the support for each device and this
accounted for a large number of lines in the package.
With the addition of a number of new graphics devices to
the network this approach has become unworkable so
now the package supports
.I plot(5)
mode as the preferred output format.
The
.I plot(1)
program is used to translate plot format into the actual
commands needed to drive each graphics device.
.PP
In addition to the
.I plot
format, the CRC package supports two types of output formats.
It is anticipated that support for these two formats
will end sometime in the future and users will use the
.I plot(1g)
program to obtain all output.
The CRC package can talk directly to
Tektronix 4010 (or 4014) displays
and HP 7221A flat-bed plotters.
The Retro-Graphic works the same way as a Tektronix terminal.
Finally, a number of devices can display graphics on
a 512 by 512 bit plane.
This bit map can then be copied to one of the
following devices: Comtal graphics overlay, Comtal image display,
Grinnell graphics overlay, Grinnell image display,
or a Printronix line printer.
.PP
The bit plane can also be written out to a file.
The programs
Gplp (1) can be used to obtain overlayed outputs on
the Printronix.
.sp
The rest of this document is subdivided into four sections. They are:
.sp
.nf
1) Documentation of Qplot, Strip7, Gplp, Hpd, and Gd.
2) Documentation of user callable subroutines.
3) Character font information.
4) Examples.
.fi
.PP
Online, all of this information is available with:
.sp
.nf
$help graphics/crc
.fi
SHAR_EOF
cat << \SHAR_EOF > plot3d.1g
.TH PLOT3D 1 "CRC Graphics Package"
.SH NAME
plot3d - Plot 3 dimensional surfaces
.SH SYNOPSIS
plot3d [arguments...]
.SH DESCRIPTION
.B Plot3d
prints a view of a three dimensional surface.
By using
.B plot3d
with no arguments, a graph
will be generated on the
default Printronix line printer as defined
in
.B gplp(1).
If ARPA is the host machine, the output will appear
on the Comtal graphics overlay bit-plane zero.
.PP
A matrix of binary floating point numbers will
be read from a file called `z' and used as the z value at each point.
This vector will be displayed against a program generated x-y matrix
containing integers from zero to the number of points in each
direction.
The points in the file are assumed
to be rows of values along lines of constant y.
See the appendix of the
.I qplot(1g)
manual page for more information about the data formats.
.PP
The input for
.B plot3d
can be either a binary or an ASCII file.
In a binary file the data is coded in the machine's
internal format.
The file can be generated using the
.B write
statement
in C or an unformatted write in Fortran or Pascal.
This is the most efficient form since it saves on
both file space and machine time.
.PP
For simple applications it is also possible to give
.B plot3d
an ASCII file with the numbers in a readable format.
The user must be careful to edit out any titles or other
non-numeric information before
.B plot3d
is called.
The numbers are read from the file ``free format.''
In other words, spaces, tabs and newlines can all be
used to separate the numbers.
.B Plot3d
will read as many lines as necessary to get enough
data for the plot as specified by the count, skip and
begin parameters.
The numbers that are read from the file must not contain any
spaces.
.PP
.B Plot3d
supports as many of the
.B qplot
options as possible and
in most cases the variables/flags are known by the same
name.
The most significant difference is that the data file
is indicated by the `z' parameter instead of the `y'
parameter (for obvious reasons).
.PP
The input data for
.B plot3d
is a matrix of binary numbers.
The type and location of the data is specified
with the
.I z=
parameter.
The matrix is considered to be size 64 x 64 unless
one of the size parameters is used (
.I size,
.I xsize
and
.I ysize
).
.PP
Data is read from the file along lines of
constant y
(x variable varies fastest).
The first value in the file, file(0),
is z(x=0, y=0), the second is z(x=1, y=0)
and so on.
The second line (y=1) starts at
number `xsize' in the file
(file(xsize) --> z(x=0, y=1)).
It is very important that the variable
.I xsize
be
set properly so that
.B plot3d
can index into the matrix properly.
.PP
With
the `x' and `y' parameters
an arbitrary mapping can be made between points in
the matrix (z) and the x and y axis.
Normally each line of the data is assumed
to be equally spaced in x and y.
With the x and y parameters any arbitrary mapping is
possible.
The results are guaranteed to be meaningful
only for monotonically
increasing mappings.
.PP
With the begin, skip and count parameters
it is possible to specify that part of the
input data be ignored.
If the begin parameters are used,
the first
.I xbegin
data points
of the z and x files
are ignored.
A similar effect is seen if the
.I ybegin
parameter is specified.
The default values are 0.
If the skip variables
.I (skip, xskip
and
.I yskip)
are set
then lines in the input matrix are skipped between
each point that is plotted.
The count parameter is used to set the number of data
lines to plot.
Normally the count parameters default to the largest number
possible, given the size, begin and skip variables.
.PP
Superimposing plots is done differently depending on the type of
output format.
For the HP plotter it is sufficient to use the same piece of
paper for a number of graphs.
For other devices it is necessary to use the
.I -b
option to turn off blanking.
If the output is going to be sent to a bit mapped device (the
Printtronix printers, image processing devices or the Versatec on ARPA)
then it is
necessary to use several
.I plot3d
commands and to put the output in a file with the
.I g=graph
option.
The resulting bit plane will be a logical-or of each picture and
can be sent to the output device using either the
.I gplp(1g), gd(1g)
or
.I gp(1g)
commands.
When using
.I plot(5)
output format it is necessary to use the
.I -P
option and then redirect the output of
.I plot3d
into a file.
Superimposing several graphs is accomplished with a string of commands
like
.nf
plot3d z=file1,f -P > graph.output
plot3d z=file2,f -b -P >> graph.output
plot -Tver graph.output
.fi
.PP
The following options are available to modify the graph:
.sp
.ne 8
**** FILE SPECIFICATION OPTIONS ****
.TP 14
z=file,?
The z matrix will be read from 'file' instead of 'z'.
The letter ? is the data type declaration field and
can be one of the following:
.sp
.RS 14
.TP 5
c
Single bytes, unsigned, fixed precision data.
.TP
cs
Single bytes, signed, fixed precision data.
.TP
s
Two bytes, signed, fixed precision data.
.TP
i
Two bytes (PDP 11's), signed, fixed precision data.
.TP
i
Four bytes (Vax's), signed, fixed precision data.
.TP
l
Four bytes, signed, fixed precision data.
.TP
f
Four bytes, floating point data.
.TP
d
Eight bytes, floating point data.
.TP
a
ASCII data, free format numbers, data is readable,
spaces, tabs and newlines are used to seperate input points.
.sp
.RE
.RS 14
If n isn't specified, a comma is not needed after the file name.
The default for n is `f'.
.RE
.TP 14
z=,n
The z vector is read from the default file `z' but the
byte declaration field is set to n.
.TP 14
-x
Read the x vector from the file `x'.
The data in the file is assumed to be binary integer quantities.
.TP 14
x=file,?
The x vector will be read from the file `file' instead of `x'.
The data in the file is assumed to be binary integer quantities
unless a `,?' is added.
The `?' can be any of the suffixes shown above with the `z=' option.
If the file is binary integer data then it is not necessary to
use the `,i' option.
.TP 14
-y
Read the y vector from the file `y'.
The data in the file is assumed to be binary integer quantities.
.TP 14
y=file,?
The y vector will be read from the file `file' instead of `y'.
The data in the file is assumed to be binary integer quantities
unless a `,?' is added.
The `?' can be any of the suffixes shown above with the `z=' option.
If the file is binary integer data then it is not necessary to
use the `,i' option.
.TP 14
xsize=n
The matrix has `n' elements in the x-direction.
The default value is 64.
It is necessary to specify this variable if the
array is not 64 x 64.
.B Plot3d
interprets the `z' file as an xsize x ysize matrix of values.
.TP 14
ysize=n
The matrix has `n' elements in the y-direction.
The default value is 64.
.B Plot3d
interprets the `z' file as an xsize x ysize matrix of values.
.TP 14
size=n
Set both `xsize' and `ysize' equal to `n'.
.TP 14
n=n
This sets xsize, and ysize variables
equal to n.
This is equivalent to using the
.I size=
parameter.
.HP 0
.sp
.ne 8
**** DATA SELECTION OPTIONS ****
.TP 14
xbegin=n
The first `n' lines of the input in the `z' file
and `n' values in the `x' file are skipped.
This is used to place the origin of the plot
at an arbitrary position in the matrix.
The default value is 0.
.TP 14
ybegin=n
The first `n' lines of the input in the `z' file
and `n' values in the `y' file are skipped.
This is used to place the origin of the plot
at an arbitrary position in the matrix.
The default value is 0.
.TP 14
begin=n
Set the parameters `xbegin' and `ybegin' equal to n.
.TP 14
xskip=n
Skip `n' lines in the `z' file and `n' values in the `x'
file between plotted data points.
The default value is 0.
.TP 14
yskip=n
Skip `n' lines in the `z' file and `n' values in the `y'
file between plotted data points.
The default value is 0.
.TP 14
skip=n
Set the parameters `xskip' and `yskip' equal to n.
.TP 14
xcount=n
Only plot `n' of the lines in the matrix.
Show n values in the matrix for each line
of constant y.
The default value is the largest number of points
that can be plotted for the given
.I xsize, xbegin
and
.I xskip.
.TP 14
ycount=n
Only plot `n' of the lines in the matrix.
Show n values in the matrix for each line
of constant x.
The default value is the largest number of points
that can be plotted for the given
.I ysize, ybegin
and
.I yskip.
.TP 14
count=n
Set the parameters `xcount' and `ycount' equal to n.
.TP 14
zmin=r
All points in the matrix below the level `r'
are set to `r'.
This is useful for seeing details in the
surface.
See also the
.I zmax
parameter.
The default value is negative infinity.
.TP 14
zmax=r
All points in the matrix above the level `r'
are set to `r'.
This is useful for seeing details in the
surface.
See also the
.I zmin
parameter.
The default value is positive infinity.
.HP 0
.sp
.ne 8
**** PLOT POSITIONING AND REDUCING OPTIONS ****
.sp
.TP 14
xp=r
The x starting coordinate of the axes is moved to
position r on the plot plane.
The default value of r is 0.
The plot is 10 units wide.
.TP 14
yp=r
Same as the `xp=r' flag but the y origin is moved to r on the plot plane.
The plot is 10 units high.
.TP 14
scfac=r
The graph is expanded or reduced in size by r.
The default value is 1.0.
.TP 14
phi1=theta
The surface is rotated around the z-axis by an angle
of theta before plotting.
The zero angle corresponds to looking down
the y axis.
The default value
is 40 degrees.
.TP 14
phi2=theta
The observation plane is tilted by theta degrees
from the horizontal.
Zero degrees corresponds to looking at the surface
from the x-y plane;
90 degrees is looking at the object from directly
above.
Neither of the two views at the extremes
provide much information.
The default value is 30 degrees.
.TP 14
-r
Reverse the direction of the `z' axis.
This effectively multiplies each data point by -1.
The default is for this option to be off.
.TP 14
-R
Do not reverse the direction of the `z' axis.
This flag turns off the `-r' flag above.
.sp
.HP 0
.ne 8
**** DEVICE SELECTION OPTIONS ****
.TP 14
-P
Output the graph to standard output in
.I plot (5)
format.
This is a device independent format that can be piped through
the
.I plot(1)
program.
.TP 14
plot=xx
Output the graph in plot format (See section 5 of the UNIX manual)
piping all plotting commands to the plot program.
The
.I xx
argument is used as a type argument to the plot command.
Thus the use of
.I plot3d plot=4014
is equivalent to the command string
.I plot3d -P | plot -T4014.
For example the following are other valid devices:
adm (to send to a terminal), ver (to send to the versatec),
4014 (to send to a Tek 4014 terminal).
See the
.I plot(1)
manual for additional devices.
.TP 14
-p
The plot is sent to the Printronix line printer through
.B gplp
(1).
This is the default output option for all
host machines except for ARPA.
See
.B gplp
(1) to
determine to which network line printer the output
will be sent.
.TP 14
site=XX
The output is sent to the network line printer
specified by XX.
See
.B opr
(1) for more information
about the allowable printer names.
This option invokes
the `-p' option.
.TP 14
-t
Display the plot on a Tektronix 4010 or 4014 display.
Standard output must end up on the specified terminal.
.TP 14
-T
Display the plot on a Retro-Graphics RG-512 in
conjunction with an ADM-3A terminal.
.TP 14
-h
Display the plot on an HP plotter.
.TP 14
pen=n
When using the HP plotter, the pen in bin
.I n
is used to
plot the graph.
The default bin is 1.
This invokes the
.I -h
flag.
.TP 14
speed=n
The HP plotter's pen movement velocity will be changed
to `n' cm/sec.
The valid range for n is [1,36].
The
default value is 36.
This option will invoke the `-h'
flag.
.TP 14
-v
The plot is sent to the Versatec printer/plotter through a
pipe to gp (1).
NOTE: This option is obsolete on all machines except for the DIPL machine.
Users should use the
.I plot=ver
option to obtain versatec output elsewhere on the network.
.TP 14
-o
The graph is written out to standard output.
.TP 14
g=file
The graph is written out to a file named `file'.
This
file can be sent to the ARPA Versatec or Printronix with
.B gp
(1) and
.B gplp
(1), respectively.
.TP 14
op=str
The string is an appended to the call to
.B gplp, gp, hpd,
and
.B gd.
This provides a method to change any of
the options to the driver programs.
.TP 14
-b
The display device is not blanked before plotting.
This
option has no effect when used with the `h', `v', `V',
and `p' flags.
If the `g=file' option is used
and `file' exists in the local directory before plotting
begins, then the new graphics will overlay the graphics
contained in `file'.
.TP 14
-B
Turn off the -b flag.
This option is set by default.
.TP 14
-c
The plot is displayed on the Comtal.
The default action is to display the plot on graphics
overlay 0 unless the -0, -1, -2, -3 or -i flags are used.
The Comtal is the default device if ARPA is the host machine,
or the
.I -i, -g, -0, -1, -2
and
.I -3
flags are used.
The Comtal is connected to the ARPA machine.
.TP 14
-G
Display the plot on the Grinnel connected to the ARPA
machine.
The default action is to display the plot on graphics
overlay 0 unless the -0, -1, -2, -3 or -i flags are used.
A Grinnell is connected to the ARPA and the PB machines.
.TP 14
-i
Display the plot on an image plane instead of a graphics overlay.
This flag is the opposite of the
.I -g
flag.
If this flag is used then the Comtal (
.I -c
) is the default device.
.TP 14
-g
Display the plot on a graphic overlay instead of an image plane.
This flag
is set by default if ARPA is the host machine.
This flag is the opposite of the
.I -i
flag.
If this flag is used then the Comtal (
.I -c
) is the default device.
.TP 14
-n
The plot is displayed on the graphic overlay
or image plane
.I n.
The number
.I n
can be either 0,1, 2, 3.
If this flag is used then the Comtal (
.I -c
) is the default device.
.RS 0
.ne 8
**** AXIS OPTIONS ****
.TP 14
-a
No axes will be plotted.
.TP 14
axis=[xyz]
An axis will be plotted only for axis listed after the equals sign.
The default action is
.I axis=xyz
which labels all three axis of the plot.
The option
.I axis=
is equivalent to the
.I -a
option.
.TP 14
-f
A border will be drawn around the plot.
.TP 14
-F
Do not draw a border around the plot. This is the default.
.TP 14
zaxis=r
The x-y axis of the plot is drawn at
.I z=r.
The default value is -.05.
.TP 14
len=r
Set the length of all axes to
.I r.
The default value is 8.
.TP 14
xlen=r
The length of the x axis is changed from
eight plot units to
.I r
units.
This parameter is relative to the default value of 8.
The actual length of the x axis in the 2-d plot coordinate system
is a function of the angle of view and the
.I scfac.
.TP 14
ylen=r
The length of the y axis
is changed from eight plot units to
.I r
units.
This parameter is relative to the default value of 8.
The actual length of the y axis in the 2-d plot coordinate system
is a function of the angle of view and the
.I scfac.
.TP 14
zlen=r
The length of the z axis
is changed from eight plot units to r units.
This parameter is relative to the default value of 8.
The actual length of the y axis in the 2-d plot coordinate system
is a function of the angle of view and the
.I scfac.
.TP 14
raxis=xyz
Floating point (real) numbers will be used to label the axis.
If just `x' is specified then only the x-axis will be forced to floating
point notation.
If just `y' is specified then only the y-axis will be forced to floating
point notation.
If just `z' is specified then only the z-axis will be forced to floating
point notation.
If `xyz' is used then all axis will be forced to floating
point notation.
If none of the axis are listed then all axis will be labelled with
integers.
Any combination of `xyz' can be specified.
The default notation is determined by the type of data used as input
to the program.
If integer data is used as input then the axis will be labelled with
integers. Otherwise floating point notation is used.
.TP 14
dig=n
The number of significant digits used in the annotation
of the axes will be set to 'n'.
The default value is
six significant digits.
.TP 14
xdig=n
Set the number of significant digits in the x axis to
n.
.TP 14
ydig=n
Set the number of significant digits in the y axis to
n.
.TP 14
zdig=n
Set the number of significant digits in the z axis to
n.
.TP 14
tic=r
The distance between tic marks for both the x, y and z
axes will be changed to r.
The default value of r is
one.
.TP 14
xtic=r
Set only the x tic mark distance.
.TP 14
ytic=r
Set only the y tic mark distance.
.TP 14
ztic=r
Set only the z tic mark distance.
.HP 0
.sp
.ne 8
**** LABEL OPTIONS ****
.TP 14
tl=str
The string will be used as a label at the top of the graph.
.TP 14
bl=str
The string will be used as a label at the bottom of the graph.
.TP 14
xl=str
The character string is used as a label along the x
axis.
.TP 14
yl=str
The character string is used as a label along the y
axis.
.TP 14
zl=str
The character string is used as a label next the z
axis.
.TP 14
-l
The user will be prompted for labels not entered with
the `xl', `yl' and `zl' options.
.TP 14
-L
Don't prompt for labels.
This option is the default.
.HP 0
.sp
.ne 8
**** GRAPH OPTIONS ****
.TP 14
direction=[xy]
Plot lines along the axis (or axes) specified by this parameter.
The default is to plot the lines along the y axes
only or
.I direction=y.
The options
.I direct=
and
.I dir=
are synonyms for this parameter.
Use of the
.I direction=x
or
.I direction=y
parameters is encouraged since half the
CPU time is used to produce the plot.
In addition if a large number of lines are to be drawn,
the graph will often appear simpler if lines are only drawn
in one direction.
.TP 14
resolution=x
This parameter controls the resolution of the ``hide'' subroutine.
The default value is 1.0 and larger values can be used to produce
a more accurate estimate of the line intersections at the expense
of more computer time.
Values larger than one are generally needed only for publication
quality plots of functions with large number of discontinuities.
Conversely a value smaller than one will save computer time at
the expense of small errors in the intersections.
.HP 0
.PP
The parse routines internal to
.B plot3d
allow for
two default mechanisms
to specify options.
The first method is to create a file `.plot3drc'
in
your HOME directory (see environ(5)).
In it, one can place
options and flags that
.B plot3d
will use before it parses your
command line. The syntax is one command or flag string per line.
.PP
As an example, consider the case where the user wishes to always
obtain output on the Versatec and the plot be framed. Also the
length of the axes are desired to be 6 units.
The correct format for
the file `.plot3drc'
would be:
.RS 14
.nf
-vf
len=6
.fi
.RE
.PP
The second method to set default
options is to set the environment variable `PLOT3DARGS'.
The format of `PLOT3DARGS'
is the same as the input command line.
.PP
The options set in the previous example can be set using
the following
procedure:
.RS 14
.nf
For /bin/sh:
$ PLOT3DARGS='-vf len=6'
$ export PLOT3DARGS
For /bin/csh
$ setenv PLOT3DARGS '-vf len=6'
.fi
.RE
If you need to set up labels with
the `bl=', or `tl='
options, surround the respective
option with double quotes. An example:
.RS 14
.nf
$PLOT3DARGS='-vf "tl=this is the title"'
.fi
.RE
There is no way to get a double quote into the label field.
.PP
.B Plot3d
will parse the file `.plot3drc'
first if it exists. Then it
will parse `PLOT3DARGS'
if it exists.
Finally,
.B plot3d
will parse
the command line.
.SH FILES
.TP 14
/etc/cpu
Contains name of host
.SH SEE ALSO
graphics/crc and
.B qplot(1)
documentation
.SH AUTHOR
Mani Azimi assembled the
.B plot3d
program from software written by a couple of people.
Carl Crawford did some of the work when he wrote
.B qplot.
The Fortran program that actually does the plotting was
rewritten by Mani Azimi based on code that was available
in the EE department for several years.
.SH DIAGNOSTICS
Bad command line requests are flagged.
Occasionally an `out of bounds' warning will result
from looking at a surface from too high an angle.
.SH BUGS
Array size is limited on the PDP 11's, especially when using the
bit mapped devices (Grinnel, Comtal, Versatec, Printronix.)
.PP
No check is made to insure
that the number of points to read
from the input file for each line (count*(skip+1)+begin)
is consistent with the `size' parameters.
.PP
The resolution parameter really shouldn't be necessary.
.SH FUTURE
Eventually all devices except for plot format will be phased out.
It is not practical for
.I plot3d
to know about every possible output device.
Instead it is better that
.I plot3d
output a generic format with infinite resolution and
let each device filter produce the best plot possible.
.SH SUPPORT
Funding for the development of this software was provided by
Prof. A.C.Kak of Electrical Engineering.
Bug fixes and enhancements will be made on a time available
basis by the author.
SHAR_EOF
cat << \SHAR_EOF > qplot.1g
.TH QPLOT 1 "CRC Graphics"
.SH NAME
Qplot - Quick Plot
.SH SYNOPSIS
qplot [arguments]
.SH DESCRIPTION
.B Qplot
is used to display one vector versus another on various
graphic devices.
By using
.B Qplot
with no arguments, a graph will
be generated on the default Printronix line printer as defined in
.B gplp
(1).
If ARPA is the host machine, the output will appear on
the Comtal graphics overlay bit-plane zero.
.PP
A set of
numbers will be read from a file called 'y' and used as the
y vector.
This vector will be displayed against a program
generated x vector containing integers from zero to the number of
points in the y vector minus one.
.PP
The input for
.B qplot
can be either a binary or an ASCII file.
In a binary file the data is coded in the machine's
internal format.
The file can be generated using the
.B write
statement
in C or an unformatted
.B write
in Fortran or Pascal.
This is the most efficient form since it saves on
both file space and machine time.
.PP
For simple applications it is also possible to give
qplot an ASCII file with the numbers in a readable format.
The user must be careful to edit out any titles or other
non-numeric information before
.B qplot
is called.
The numbers are read from the file ``free format.''
In other words, spaces, tabs and newlines can all be
used to separate the numbers.
.B Qplot
will read as many lines as necessary to get enough
data for the plot as specified by the count, skip and
begin parameters.
The numbers that are read from the file must not contain any
spaces.
.PP
Superimposing plots is done differently depending on the type of
output format.
For the HP plotter it is sufficient to use the same piece of
paper for a number of graphs.
For other devices it is necessary to use the
.I -b
option to turn off blanking.
If the output is going to be sent to a bit mapped device (the
Printronix printers, image processing devices or the Versatec on ARPA)
then it is
necessary to use several
.I plot3d
commands and to put the output in a file with the
.I g=graph
option.
The resulting bit plane will be a logical-or of each picture and
can be sent to the output device using either the
.I gplp(1g), gd(1g)
or
.I gp(1g)
commands.
When using
.I plot(5)
output format it is necessary to use the
.I -P
option and then redirect the output of
.I plot3d
into a file.
Superimposing several graphs is accomplished with a string of commands
like
.nf
qplot y=file1,f -P > graph.output
qplot y=file2,f -b -P >> graph.output
plot -Tver graph.output
.fi
.PP
The following options are
available to modify the graph:
.RS 0
**** FILE SPECIFICATION OPTIONS ****
.TP 14
y=file,n
The y vector will be read from 'file' instead of 'y'.
The number n is the byte declaration field and can be
one of the following:
.RS 10
.TP 4
c
Single byte, unsigned, fixed precision data.
.TP 4
cs
Single byte, signed, fixed precision data.
.TP 4
s
Two bytes, signed, fixed precision data.
.TP 4
i
Two bytes (PDP 11's), signed, fixed precision data.
.TP 4
i
Four bytes (Vax's), signed, fixed precision data.
.TP 4
l
Four bytes, signed, fixed precision data.
.TP 4
f
Four bytes, floating point data.
.TP 4
d
Eight bytes, floating point data.
.TP 4
a
ASCII numbers, free format data, file is readable,
spaces, tabs and newlines are used
to separate input points.
.RE
.RS 10
If
.I n
isn't specified, a comma is not needed after the
file name.
The default for n is `f'.
.RE
.TP 14
y=,n
The y vector is read from the default file `y' but the
byte declaration field is set to
.I n.
.TP 14
-x
The x vector will be read from a file called `x'
instead of having
.B qplot
generating it for you.
The
default file type is `i'.
.TP 14
-X
Turn off the -x flag.
This option is set by default.
.TP 14
x=file,n
The x vector is read from `file' instead of `x'.
The
byte declaration for this vector is set to n.
The
default type is `i'.
This option invokes the -x flag.
.TP 14
x=,n
The x vector is read from the default input file `x'
but the byte declaration is set to n.
.TP 14
count=n
Up to n points will be read from the input file.
N can
have a maximum value of 512.
The default value of n is
512.
.TP 14
begin=n
The first n points in the x and y files will be
ignored.
If `begin' is negative, then the value
actually used will be given by the product of `count'
and the absolute value of `begin'.
The starting point
on the program generated x vector will be
set to `begin'.
The default value of n is zero.
.TP 14
skip=n
Only every (n+1)'th point will be read from the
input file.
The program generated x vector incremental
value is set to `n' + 1.
The default value of n is
zero.
.RS 0
**** SCALING OPTIONS ****
.TP 14
s=file
.B Qplot
generates the scale values for the x and y
vectors by finding the minimum and maximum values of
each vector.
If `file' exists in the current
directory, the minimum and maximum values used by the
scaling routines will be read from it.
The format of
the file is four numbers on a single line in the
following format: `xmin xmax ymin ymax'.
The default
name for `file' is `xybnd'.
.TP 14
ymin=r
The ymin value read from the scale file or obtained
from the y vector is replaced by r.
.TP 14
ymax=r
The ymax value read from the scale file or obtained
from the y vector is replaced by r.
.TP 14
xmin=r
Works the same as the `ymin=' option when the
.I -x
flag
is used.
Otherwise the program will create the x
vector with a starting value of
.I r.
.TP 14
xmax=r
Works the same as the `ymax=' option when the -x flag
is used.
If the program generates the x vector
and the `xmin=r1'
and `xmax=r2' options are
also used, then the x vector will
be a set of equally spaced point integers
between r1 and r2.
.TP 14
-s
The xmin, xmax, ymin, ymax values used to make the
graph are written out to the
file specified by `s=file'.
This is useful in plotting multiple graphs
with the same scale.
The file has the same format as
the input scale file.
.TP 14
-S
Turn off the -s flag.
This option is set by default.
.ne 8
.RS 0
**** POSITIONING AND REDUCING OPTIONS ****
.TP 14
xp=r
The x starting coordinate of the graph is moved to
position `r'.
The default value of r is zero.
.TP 14
yp=r
Same as the `xp=r' flag but the y origin is moved to `r'.
.TP 14
scfac=r
The graph is expanded or reduced in size by `r'.
The
default value is 1.0.
.RS 0
**** DEVICE SELECTION OPTIONS ****
.TP 14
-P
Output the graph to standard output in
.I plot (5)
format.
This is a device independent format that can be piped through
the
.I plot(1)
program.
.TP 14
plot=xx
Output the graph in plot format (See section 5 of the UNIX manual)
piping all plotting commands to the plot program.
The
.I xx
argument is used as a type argument to the plot command.
Thus the use of
.I qplot plot=4014
is equivalent to the command string
.I qplot -P | plot -T4014.
For example the following are other valid devices:
adm (to send to a terminal), ver (to send to the versatec),
4014 (to send to a Tek 4014 terminal).
See the
.I plot(1)
manual for additional devices.
.TP 14
-p
The plot is sent to the Printronix line printer through
.B gplp
(1).
This is the default output option for all
host machines except for ARPA.
See
.B gplp
(1) to
determine to which network line printer the output
will be sent.
.TP 14
site=XX
The output is sent to the network line printer
specified by XX.
See
.B opr
(1) for more information
about the allowable printer names.
This option invokes
the `-p'
.TP 14
-t
Display the plot on a Tektronix 4010 or 4014 display.
Standard output must end up on the specified terminal.
.TP 14
-T
Display the plot on a Retro-Graphics RG-512 in
conjunction with an ADM-3A terminal.
.TP 14
-h
Display the plot on an HP plotter.
.TP 14
pen=n
When using the HP plotter, the pen in bin n is used to
plot the graph.
The default bin is 1.
This invokes the `-h' flag.
.TP 14
speed=n
The HP plotter's pen movement velocity will be changed
to `n' cm/sec.
The valid range for n is [1,36].
The
default value is 36.
This option will invoke the `-h'
flag.
flag.
.TP 14
-v
The plot is sent to the Versatec printer/plotter through a
pipe to gp (1).
NOTE: This option is obsolete on all machines except for the DIPL machine.
Users should use the
.I plot=ver
option to obtain versatec output elsewhere on the network.
.TP 14
-o
The graph is written out to standard output.
.TP 14
g=file
The graph is written out to a file named `file'.
This
file can be sent to the Versatec or Printronix with
.B gp
(1) and
.B gplp
(1), respectively.
.TP 14
op=str
The string is appended to the call to
.B gplp, gp, hpd,
and
.B gd.
This provides a method to change any of
the options to the driver programs.
.TP 14
-b
The display device is not blanked before plotting.
This
option has no effect when used with the `h', `v', `V',
and `p' flags.
If the `g=file' option is used
and `file' exists in the local directory before plotting
begins, then the new graphics will overlay the graphics
contained in `file'.
.TP 14
-B
Turn off the -b flag.
This option is set by default.
.TP 14
-c
The plot is displayed on the Comtal.
The default action is to display the plot on graphics
overlay 0 unless the -0, -1, -2, -3 or -i flags are used.
The Comtal is the default device if ARPA is the host machine,
or the
.I -i, -g, -0, -1, -2
and
.I -3
flags are used.
The Comtal is connected to the ARPA machine.
.TP 14
-G
Display the plot on the Grinnel connected to the ARPA
machine.
The default action is to display the plot on graphics
overlay 0 unless the -0, -1, -2, -3 or -i flags are used.
A Grinnell is connected to the ARPA and the PB machines.
.TP 14
-i
Display the plot on an image plane instead of a graphics overlay.
This flag is the opposite of the
.I -g
flag.
If this flag is used then the Comtal (
.I -c
) is the default device.
.TP 14
-g
Display the plot on a graphic overlay instead of an image plane.
This flag
is set by default if ARPA is the host machine.
This flag is the opposite of the
.I -i
flag.
If this flag is used then the Comtal (
.I -c
) is the default device.
.TP 14
-n
The plot is displayed on the graphic overlay
or image plane
.I n.
The number
.I n
can be either 0,1, 2, 3.
If this flag is used then the Comtal (
.I -c
) is the default device.
.RS 0
.ne 8
**** AXIS OPTIONS ****
.TP 14
-a
No axes will be plotted.
.TP 14
-A
Plot axes.
This option is set by default.
.TP 14
xlen=r
The length of the x axis will be changed from eight
plot units to r units.
.TP 14
ylen=r
The length of the y axis will be changed from eight
plot units to r units.
.TP 14
len=r
Set the length of both axes to r.
.TP 14
logx=n
The `x' axis will be logarithmic instead of linear.
Valid values for n are -3, -2, -1, 1, 2, and 3.
The
logarithm base ten of the `x' vector will be taken if n
is negative.
No tic marks will be plotted if n is -1
or 1.
A few tic marks will be plotted if n is -2 or 2.
All possible tic marks will be plotted if n is -3 or 3.
.TP 14
logy=n
Same as the `logx=' option except
that it works for the `y' axis.
.TP 14
raxis=xy
Floating point (real) numbers will be used to label the axis.
If just `x' is specified then only the x-axis will be forced to floating
point notation.
If just `y' is specified then only the y-axis will be forced to floating
point notation.
If `xy' is used then both the x and the y-axis will be forced to floating
point notation.
The default notation is determined by the type of data used as input
to the program.
If integer data is used as input then the axis will be labelled with
integers. Otherwise floating point notation is used.
.TP 14
dig=n
The number of significant digits used in the annotation
of the axes will be set to 'n'.
The default value is
six significant digits.
.TP 14
xdig=n
Set the number of significant digits in the x axis to
n.
.TP 14
ydig=n
Set the number of significant digits in the y axis to
n.
.TP 14
tic=r
The distance between tic marks for both the x and the y
axes will be changed to r.
The default value of r is
one.
.TP 14
xtic=r
Set only the x tic mark distance.
.TP 14
ytic=r
Set only the y tic mark distance.
.TP 14
-f
A border will be drawn around the plot.
.TP 14
-F
Don't frame the plot.
This option is set by default.
.RS 0
**** LABEL OPTIONS ****
.TP 14
el=str
The string will be plotted just to the right of the
last point in the line.
.TP 14
tl=str
The string will be used as a label at the top of the
graph.
.TP 14
bl=str
The string will be used as a label at the bottom of the
graph.
.TP 14
xl=str
The character string is used as a label below the x
axis.
.TP 14
yl=str
The character string is used as a label next to the y
axis.
.TP 14
-l
The user will be prompted for labels not entered with
the `xl' and `yl' options.
.TP 14
-L
Don't prompt for labels.
This option is the default.
.RS 0
**** LINE OPTIONS ****
.TP 14
-m
Mark every point in the line with an on-center symbol.
.TP 14
-M
Don't mark the line.
This option is set by default.
.TP 14
j=n
Only every |j|'th point will have an on-center symbol
on it.
If j is negative, then the line connecting
points will not be drawn.
This option invokes the -m
flag.
.TP 14
sym=n
One of 13 different on-center symbols can be selected.
This option invokes the -m flag.
The following on-center symbols can be used.
.ta 1i 2i
.nf
\fIsym on-center symbol\fR
0 no on-center symbol
i $'i-1' i=1,2,...,10
11 $*
12 $+
13 $,
.fi
.TP 14
-d
A dashed line is used instead of a solid line when
drawing the graph.
.TP 14
-D
Don't draw dashed line.
This option is set by default.
.TP 14
dash=r
The length of the visible portion of the dashed line is
set to `r'.
The default value is 0.1.
This option
invokes the `-d' flag.
.TP 14
gap=r
Same as the `dash=' option but affects the invisible
portion of the dashed line.
.TP 14
-z
A bar graph is made instead of connecting vector
elements with a solid line.
.TP 14
-Z
Don't draw bar graph.
This option is set by default.
.PP
The parse routines internal to
.B qplot
allow for two default
mechanisms to specify options.
The first method is to create a
file `.qplotrc' in your HOME directory (see environ (5)).
In it,
one can place options and flags that
.B qplot
will use before it
parses your command line.
The syntax is one command or flag
string per line.
.PP
As an example, consider the case where the user wishes to
always obtain output on the Versatec and the plot be framed.
Also
the length of the axes are desired to be 6 units and the number
of digits in the axes annotation set to 4.
The correct format for
the file `.qplotrc' would be:
.RS 1i
-vf
len=6
dig=4
.RE
.PP
The second method to set default options is to set the
environment variable `QPLOTARGS'. The format of `QPLOTARGS' is the
same as the input command line.
.PP
The options set in the previous example can be set using the
following procedure:
.PP
For /bin/sh:
$QPLOTARGS='-vf len=6 dig=4'
$export QPLOTARGS
.PP
For /bin/csh
$setenv QPLOTARGS '-vf len=6 dig=4'
.PP
If you need to set up labels with the `xl=', `yl=', `bl=', `tl=',
or `el=' options, surround the respective option with double
quotes. An example:
$QPLOTARGS='-vf "xl=this is the x axis label"'
There is no way to get a double quote into the label field.
.PP
.B Qplot
will parse the file `.qplotrc' first, if it exists.
Then
it will parse `QPLOTARGS', if it exists.
Finally,
.B qplot
will parse
the command line.
.SH SEE ALSO:
graphics/crc
.SH FUTURE
Eventually all devices except for plot format will be phased out.
It is not practical for
.I qplot
to know about every possible output device.
Instead it is better that
.I qplot
output a generic format with infinite resolution and
let each device filter produce the best plot possible.
.SH AUTHOR
Carl Crawford
.SH FILES
.TP 14
/etc/cpu
Contains name of host
.SH APPENDIX: Input file conventions
.PP
.B Qplot
users should write the data for the `x' and `y' files
in binary format to make the most efficient use of the machine.
This format will be explained in detail in this appendix for the
benefit of users who have had little or no experience with binary
files.
.PP
The normal output mode from programs is what will be called an
ASCII or displayable format. This type of output can be directed
to the terminal for inspection by the user. The output is
generated with a
.B formatted
write.
This type of data can be read by
.B qplot
using the ',a' modifier to the file name.
.PP
Internally a program assigns a certain number of bytes to each
variable used. When a formatted
.B write
is initiated, the number is
converted from the internal binary representation to a string
containing displayable ASCII characters.
When sending data
between programs, it is a waste of time to convert data from
binary to ASCII and then from ASCII back into binary.
This is the
reason why
.B qplot
encourages binary data as input.
.PP
Each programming language's internal variable types map into a
.B qplot
byte declaration field.
The following list gives the
correspondence between the internal variable types and the
.B qplot
byte declaration for some of the commonly used languages on the
UNIX operating system.
.nf
.ta 0.3i 1.5i 3.4i 4.6i
C: (11's) C: (Vax)
TYPE DECLARATION TYPE DECLARATION
short i or s short s
int i or s int i or l
long l long i or l
float f float f
char c or cs char c or cs
double d double d
.ne 8
FORTRAN:(F77) FORTRAN: (F4P)
TYPE DECLARATION TYPE DECLARATION
integer l byte c or cs
integer*2 s real f
real f double d
double d integer s or i
character*1 c or cs integer*4 l
APL: (APL) APL: (APL2)
TYPE DECLARATION TYPE DECLARATION
numeric d numeric f
character c or cs character c or cs
PASCAL (11's) PASCAL (Vax)
TYPE DECLARATION TYPE DECLARATION
integer s or i integer l or i
real f real f
.fi
.PP
Unformatted writes in C can be obtained using the
.B fwrite
subroutine. See stdio(3) for more information.
.PP
In FORTRAN using the F77 compiler there are two ways to obtain
unformated writes.
The first is to use the
.B ucreat
and
.B uwrite
subroutines.
They are the analog to C's
.B write
and
.B creat
subroutines.
See the documentation for the C versions for more
information on the syntax.
When compiling your program
add `-lU77' to the end of the command line.
.PP
The easiest way to get unformated writes from FORTRAN is to
just write the data without a `format' statement.
An example
would be:
.nf
real x(100),y(100)
write(2)x
write(3)y
.fi
In this example two files would be generated
named `fort.2' and `fort.3'.
The F77 compiler also generates code to produce record
counts in its binary files.
The program strip7(1) will remove
the record counts from binary files generated with F77.
The
output file names can be changed using the
FORTRAN subroutine
.B open.
See the compiler manual for more information.
SHAR_EOF
chdir ..
# End of shell archive
exit 0
--
Rich $alz "Anger is an energy"
Cronus Project, BBN Labs rsalz@bbn.com
Moderator, comp.sources.unix sources@uunet.uu.net