File: UsersManual
Authors: David Meyers,
         K.R. Sloan
Last Modified: 13 November 1990
Purpose: Instructions for producing a surface from a set of contours.

INSTRUCTIONS FOR USE OF THE SURFACES FROM CONTOURS SYSTEM

OVERVIEW

The steps needed to generate a surface from some serial section data are as 
follows:

	1) Create a file describing the sections using the input format
	   supported by the system. See INPUT FILE FORMAT below for a 
	   description of the format.  See EDITTING CONTOURS below.

	2) Generate a mesh from the input file using the ContourFitter
	   program.  A mesh is a connected set of triangles.

Strictly speaking - this is all that you can do with the "Contours"
package.  Obviously, you will want to do more.  One way to proceed is to
puzzle out the format of a "mesh" file, and do with it what you will.
Another is to acquire the SurfacePipeline, SGP, and wff packages (see
CONTACTS in ContoursRelease/README.)  

	3) Optionally, add normals to the mesh using the SloanNormals
	   program.  This is part of the SurfacePipeline package.  It
           annotates a "mesh" file, adding surface normals at each vertex.

	4) Fit a surface to the mesh using the fitter of your choice. The
	   requirements of your choice of fitters will determine whether step
	   3 (above) needs to be done.  The SurfacePipeline contains
           several surface fitters.  For starters, use "Fitter0", which
           simply produces a single, flat, triangular patch for every
           triangle in the mesh file.  Other fitters produce
           higher-order patches.
 
	5) Tesselate the surface using the program Tess.  This produces
           a set of triangles for each surface patch.  Some fitters may
	   incorporate this step, so it may not be necessary.  Fitter0
           DOES require Tess - but only to change the format of the file.

	6) Add rendering information.  For example, the Mat0 program
           allows you to specify the surface material properties.

Strictly speaking - this is the end of the SurfacePipeline, per se.
But, you probably want to produce an image.  The default way to do that
is to use the programs Render/XRender.

	7) Convert to the SGP world using the Sgp program.  The program
           "Sgp" is part of the SurfacePipeline package, and produces
           a file which is suitable for input to Render.

	8) Display using XRender, Render.  These are part of the SGP
           package.  Render requires the wff package, and produces an
           image file.  See the wff documentation for information on the
           format.  XRender produces simplified ("graphic") views, using
           X11.  If you have neither wff nor X, but DO have SGP, it is
           relatively simple to produce a version of Render which will
           work in your local graphics environment.  See the SGP package
           for details.
 
PREVIEWING

A fast preview of the sections specified by a given input file can be
had using the DrawContours or XDrawContours programs (NOTE: as with
Render/XRender these require the "SGP" package, and perhaps wff, as
well) - see the top-level README file).

Previewing  provides a check of the corrrectness of the input file
specification, since the same routines are used to read the file as in the
ContourFitter program. The programs also allow a quick determination of
viewing point and direction, since they take the same command line
viewing specifications as do Render and XRender.

INPUT FILE FORMAT

The input file format looks like this:
--------------------------------------------------------------------------
  { SECTION SectionName NContours
    { CONTOUR ContourName Npts
      { x1 y1 z1 }
      { x2 y2 z2 }
       ...
      { xn yn zn }

      { ADJPREVIOUS { AdjContourName ThisContourIndex AdjacentContourIndex }
                     ...
		    { AdjContourName ThisContourIndex AdjacentContourIndex }
      }
      { ADJNEXT { AdjContourName ThisContourIndex AdjacentContourIndex }
                 ...
		{ AdjContourName ThisContourIndex AdjacentContourIndex }
      }
      { ALIAS NAliases
        { Name0 }
	{ Name1 }
	...
	{ NameNAliases-1 }
      }
    }
    ...
    { CONTOUR ContourName Npts
      { x1 y1 z1 } ... { xn yn zn } }
  }

  { SECTION SectionName NContours
    { CONTOUR ContourName Npts
      { x1 y1 z1 } ... { xn yn zn } }
    ...
    { CONTOUR ContourName Npts
      { x1 y1 z1 } ... { xn yn zn } }
  }
-------------------------------------------------------------------------

The symbols {, }, SECTION, CONTOUR, ADJPREVIOUS, ADJNEXT, and ALIAS
appear exactly as shown.

Each file consists of a number of SECTION's.  The model is that each
SECTION is a planar cross-section through an object.  The SectionName 
is simply a tag - values such as "S1", "S2", ... are good choices.
 
Each SECTION consists of a number of CONTOURS.  To make life simple
(for us - not you!), you must specify the number of CONTOURS
(NContours).  Multiple CONTOURS in a single SECTION are the result of
slicing a non-convex object.  There is currently no good support for
multiple, distinct objects. 

Each CONTOUR had a name (ContourName).  CONTOUR's in adjacent
SECTIONS will be connected together if they have a ContourName or
Alias in common.  Each CONTOUR has a sequence of points ("Npts" in
length) which define a closed, simple polygon.
The ALIAS information contains the names of contours in adjacent
sections which derive from or merge to form this contour. "NAliases" 
specifies the number of aliases for this contour. For example, if C1 and C2
in Section1 merge to form C3 in Section2, then C3 will have C1 and C2 s 
aliases. If C4 and C5 in Section3 are derived from C3 in Section2, then
C3 will also have C4 and C5 as aliases. There should be no contour in the
same section with the same name as a contour's alias. (In Section2 there
should be no C1, C2, C4 or C5)

The ADJPREVIOUS or ADJNEXT information is required only in cases where
several contours in one section are derived from one contour in a
neighboring section. 

ADJPREVIOUS is used when several contours in one section are derived
from the same contour in the previous section. These contours define a place
where the surface "forks" as viewed in the direction implied by the order
of the sections.

ADJNEXT is used when several contours in one section merge into the same
contour in the next section.

The three items in an adjacency specification have the following
significance: 
  1) "AdjacentContourName" is the name of the contour adjacent to the
     current one.
  2) "ThisContourIndex" is the index (into the list of contour
     points) of the point of the current contour to be linked to the
     adjacent contour in a composite contour. 
  3) "AdjacentContourIndex" is the analogous point of the adjacent
     contour. (The lists are indexed zero based). 

ContourFitter uses this information to produce a composite contour
from the two adjacent contours when tiling with the section in which
the adjacent contours have merged. 
There can be any numbe of adjacencies specified from any given contour, but
they must not produce a circular adjacency set. That is, the adjacencies form
a tree, with no cycles allowed. Relaxing this restriction is a
possible future improvement.

SectionName and ContourName are arbitrary strings < 80 characters
long. Since names are concatenated by some of the routines, a
practical limit is < 20  characters. 

Current implementation limitations also require that the contours be listed 
by decreasing z coordinate, and assumes that contours are at least fairly 
nearly planar with the Z axis as the normal to the plane of sectioning.

Sections must be in order. The routine does not know how to "sort" them. The
points within a contour must be specified in counterclockwise order as seen
from the side of the section away from the next section in the series (or 
toward the previous section if there is no "next section". If this condition
is not met, then the surface will appear to be "inside out".

The ALIAS and ADJPREVIOUS or ADJNEXT information may be specified
in any order within a CONTOUR specification, but must follow the list of
contour points.

Some example input files are in /data. XSections3 is a set
of sections defining the surface of an X formed by two intersecting 
cylinders. The sections involved in the merging and diverging of the 
cylinders provide an example of the way the ADJPREVIOUS, ADJNEXT, and ALIAS
information is specified.


VIEWING CONTOURS

(NOTE: these programs will require SGP and wff)
The application "DrawContours" allows the user to display a set of contours.
The program accepts the same command line flags as does Render, except that
the lighting model options are not supported. Viewing parameters are 
supported, as are the verbose and debug modes. The input file format is as
specified above for the surface from contour package.

  DrawContours [-v][-D][-O x y z][-e x y z][-o dx dy dz][-u x y z][-f f]

Two versions exist: DrawContours, which produces a .wff file, and
                    XDrawContours, which writes to an X window.

The -D option produces postscript output in the form of SGP commands. It can
be concatenated with a header file, and printed on a postscript printer. (The
header file is data/SGP.ps).

EDITTING CONTOURS

The ContourEditor is a primitive tool, written as an undergraduate
project. Surely, you can do better.  When you do, please send the esult
to us!

The ContourEditor can be used to edit existing contours, and with a bit
of practice create new objects.  To create a new object, first create a
file with minimal contours (single points).  Then, add points and
adjacency information using the ContourEditor. Each section will need to
have as many separate contours as needed, since it is not currently
possible to add contours to a section using the contour editor. The same
applies to sections, they cannot be added using the contour editor. The
ContourEditor allows for editing of the x and y coordinates of points
but not the z values, so a manually created minimum file must specify
the correct z values for the sections. The first section specified must
have the highest z value.

PRODUCING A MESH

(NOTE: these programs will require the SurfacePipeline - see the
toplevel README file for details) The application "ContourFitter" reads
an input file of the format documented above and produces a mesh file as
output. It uses stdin and stdout.  Currently, there are no supported
command line options.

The output of ContourFitter has no surface normal information attached.
If normals are needed by the fitter you are using, The application
"SloanNormals" can be used to generate normals from the mesh.

GOING FROM MESH TO PRETTY PICTURE

(NOTE: these programs will require the SurfacePipeline - see the
toplevel README file for details) If you have the SurfacePipeline (and
SGP, and wff): The following pipeline will produce a shaded image from a
section file:

  ContourFitter < FileName | SloanNormals | Fitter0 | Tess | Mat0 -m RedPlastic
        | Sgp | Render > File.wff

There are A LOT of parameters and options that we are not going to try
and describe here.  Good luck.


