**************************************************************************

	THIS SOFTWARE IS IN THE PUBLIC DOMAIN.  IT IS INTENDED TO
	BE AVAILABLE FREE TO ANYONE WHO WANTS IT.  YOU MAY USE AND
	DISTRIBUTE IT AS YOU LIKE WITH THE FOLLOWING RESTRICTIONS:

	1)  You may not sell this software or charge more than a
	    small copying/hassle fee for distributing it.

	2)  You may not remove this notice from the distribution.

		Tim Mooney
		5904 Vandegrift Ave.
		Rockville, MD 20851

****************************************************************************

    ThreeDPlot - 3-D DATA PLOTTING ROUTINE
   
      ThreeDPlot displays the projection on the screen of a function z(x,y).
   The function must be single-valued, and defined on an x-y grid.

------------------------------------------------------------------------

      To get a quick idea of what is going on here, drop a net over a
   chessboard in the middle of a game: the heights of the various pieces
   are the z coordinates; the positions (row, column) of the pieces are
   the (x, y) coordinates.  ThreeDPlot draws a picture of the net.
   
      Continuing with the chessboard analogy: ThreeDPlot first wants to know
   how many rows (let's call this number "NROWS") and columns ("NCOLS") of
   data to expect.  Then it wants the row coordinates (NROWS of them); then
   the column coordinates; and finally the z coordinates, starting with the
   row nearest you, from left to right, to the row nearest your opponent.
   Further, ThreeDPlot wants all of this in a binary file: 4-byte-int
   (# rows); 4-byte-int (# columns); 4-byte-floats (z coordinates).
   ThreeDPlot does NOT want x or y coordinates in the data file.  (The
   program dat_2_bin exists to convert a text file of x, y, and z data to
   a binary file ThreeDPlot will plot.  See notes below on dat_2_bin.)
   
      You tell ThreeDPlot from what viewing point you wants to see the net.
   Imagine looking at the board "edge-on" -- your eyes level with the
   table -- and facing your opponent.  ThreeDPlot calls this position
   "phi = 0 degrees, theta = 0 degrees".  If you rotate the board clock-
   wise (as seen from above) on the table, you are increasing phi to some
   positive value.  Now with phi fixed, tilt the table toward you so that
   the pieces would fall in your lap.  To ThreeDPlot, this decreases theta
   to some negative angle;  it gives you a view of the top of the board.

      ThreeDPlot uses a very simple algorithm for hidden-line removal: lines
   are plotted from the bottom of the screen up; for each possible horizontal
   position, a record is kept of the topmost point plotted so far.  This
   algorithm is suitable for binned data, chessboards viewed from above,
   and the like.  A command line option ("-2") allows a "bottom view " of
   the data set to be displayed also;  the same algorithm is used in reverse.
   
*************************************************************************
There are two menus, PROJECT and OPTIONS:

*******
PROJECT

Open           not implemented

Make PltFile   ThreeDPlot will write a file which can be sent ("Copy
               myplotfile TO ser:") to any plotter that understands HPGL, the
               Hewlett Packard Graphics Language. Commands in the plot file
               instruct the (serial interface) plotter to use xON/xOFF.

Make TxtFile   ThreeDPlot will write a file that can be converted into an
               IntroCAD drawing.  The program txt_2_icad does this
               conversion.

Quit           Quits to CLI.


*******
OPTIONS  (all are toggles)

BothSides      Draws top and bottom sides of data

Axes           Toggles axes.

NegImage       Swap background and foreground colors.

Net Plot       Toggle between crosshatch plot and simpler line plot



*************************************************************************
   Also, ThreeDPlot reads the keyboard -- specifically, the arrow keys and
the numbers 1-9 on the numeric keypad.  Pressing one of these causes a replot
with one or both viewing angles changed by 10 degrees.  The action of some
of these keys is counter-intuitive if theta is greater than 180 degrees.

*************************************************************************
dat_2_bin
	dat_2_bin reads a text file and makes a binary file that ThreeDPlot
can read.  (It takes a relatively long time to do this.  The read/convert
step has been taken out of ThreeDPlot and made into a separate program for
this reason.)

	dat_2_bin wants a file with the following format:

NX NY	!MUST be on first line of file
x[1]	!Anything may follow a number on a line.  All but the number will
x[2]	!be ignored.
x[3]
 .
 .
 .
x[NX]
y[1]
y[2]
y[3]
 .
 .
 .
y[NY]
z[1]
z[2]
z[3]
 .
 .
 .
z[NX*NY]
end-of-file