
INFO ABOUT PlotFile3D:

The `PlotFile3D' class is similar to the `PlotFile' class, except that
it draws 3D pictures using a simple orthogonal projection.  Here are
some features and limitations:

    + mono and stereo modes
    + viewport clipping of all lines and curves (but not text)
    - static wireframes only; no real-time rotation or hidden-line removal

For the most part, the methods of PlotFile3D are extensions of their
2D counterparts in PlotFile, with x,y,z arguments substituted for x,y
arguments where appropriate.  Unlike coordinates in the 2D class,
which (by imitation of the standard Unix plot(3) library) are all of
type `int', the coordinates in PlotFile3D are of type double.  As with
the PlotFile class, all user-visible methods return *this.

Exceptions to these rules of thumb are listed in the remainder of this
section.

Constructor
===========

PlotFile3D(FILE *fp,
           const bool stereo =FALSE,
           const double th =PI/12, const double ph =PI/3)

    fp          obtained via fopen() or popen()
    th	        elevation of camera above xy plane (in radians)
    ph          rotation of 3D scene about the z axis (in radians)
    stereo      TRUE if you want a pair of stereo images, side by side

    Once specified, the camera's location cannot be changed.

Specification of picture dimensions
===================================

space(const double x0, const double y0, const double z0
      const double x1, const double y1, const double z1)

    These six coordinates specify a box which would bound the picture
    in 3D space.  PlotFile3D uses this to compute a transformation
    that makes the picture fit nicely in the square 2D viewing frame.

Shape specifications
====================

The methods arc() and dot(), which are available in the PlotFile
class, are not available in PlotFile3D.

The parameter list of circle() is modified to accommodate three
dimensions:

circle(const double cx, const double cy, const double cz,
       const double rx, const double ry, const double rz,
       const int points_per_quadrant =10)

    cx,cy,cz   specify the center of the circle
    rx,ry,rz   form a vector whose direction is normal to the plane of
               the circle and whose magnitude is its radius

    The final optional parameter specifies the number of points to be
    computed in each quadrant.  If (points_per_quadrant == n), then
    the circle that is drawn is a regular (4*n)-gon.

Two of the methods in PlotFile3D have no counterpart in PlotFile.  (Yet
more might be added if it seems appropriate to break with the PlotFile
class philosophy of providing a no-frills package that mirrors the
Unix plot(3) package as closely as possible.)  These are:

sphere(const double cx, const double cy, const double cz,
       const double rx, const double ry, const double rz,
       const int points_per_quadrant =10)

    These arguments are identical to those expected by circle().  The
    circle specified is the equator of the sphere, which is all that
    is needed to specify it completely.

home()

    Moves the cursor to a location close to the upper left corner of
    the viewing frame.  Is automatically called by the constructor and
    by space() and erase().

    This method is useful when plotting on devices which leave a
    visible cursor at the point most recently drawn.  It may also be
    used to place a title label.  It should not be used to specify a
    starting point for a cont() operation since it leaves the 3D
    cursor location undefined.

The remaining methods are completely analogous to their 2D
counterparts in the PlotFile class:  move(), cont(), line(), point(),
box(), erase(), linemod(), label().


When the 3D cursor location is defined
======================================

The cont() and label() methods start drawing at PlotFile3D's internal
notion of the "current" location in three dimensions.  In many
situations, this 3D cursor location is undefined.

    * It is UNDEFINED immediately after construction, space() and erase().
    * It is DEFINED immediately after move(), cont(), line() and point().
    * It is UNDEFINED immediately after box(), circle() and sphere()
      because the manner in which such shapes are drawn is
      implementation-dependent.
    * It is UNDEFINED immediately after home() and label() because
      those are fundamentally 2D operations.
    * It is unaffected after linemod().

The 3D cursor location must be defined before any cont() operation.
If defined, the 3D cursor location determines the location of any text
drawn by label().


