Using BOOLE as a standalone program
-----------------------------------

There are two ways in which one can use BOOLE.  

(1)  As a standalone program that reads two solid files, performs a
boolean operation on them according to a command-line option, and
writes the output to a third file.

(2)  As a library with data structures for sculptured solids, and
functions allowing boolean operations to be performed on them.

This file documents the command-line options and file structure for
usage (1).  The documentation for usage (2) is in the file
DOCS/library. 


Command line
------------

The command-line syntax is

	     boole operator operand1 operand2 outputfile

where `operator' is one of the words `union', `intersection', or
`difference', and the remaining three options are filenames for the
two operands and the result.


File format
-----------

Two example files, cone1 and cone2, are included with the
distribution.  A solid is defined as a list of trimmed rational
tensor-product Bezier patches.  The solid file begins with a
declaration such as

    npatches 5

specifying the number of patches in the file.  The rest of the file
consists of the approprate number of patch structures, which are
implicitly numbered within the file starting with 0.

Patch structure
---------------

A patch structure begins with a declaration such as 

    patchdegree 1 2

which specifies the two degrees of the patch, m and n.  This is
followed by the (m+1)*(n+1) control points of the patch, each given in 
homogeneous-coordinate form

    cp 4.4 2.1 0.10 1.0

Note that for a 1x2 patch, the control points appear in the order

    (0,0), (0,1), (0,2), (1,0), (1,1), (1,2).

that is, the second degree `n' is the direction in which the index
increases in the inner loop of the parser.

Next comes the verbatim line

    splinetrimming 1

since piecewise-linear trimming curves are no longer supported.

Next comes a line such as 

    ntrimregions 1

specifying the number of connected components of the patch which lie
within the trimming curves.

The last thing specified for a patch is a list of trim-region
structures.

Trim-region structure
---------------------

A trim region is specified by a declaration of the number of curves
bounding the trim region:

      ncurves 4

and a list of trim-curve structures.

Trim-curve structure
--------------------

A trimming curve is a 2-D rational Bezier curve in the domain of the
patch, that is, with control points in the unit box.  It is specified
by: first, the index of the patch which is adjacent to the current
patch at the curve.  (Remember, the patches in the file are implicitly 
numbered, starting with 0.)
    
        adjacentpatch 2

Next, its degree and control points are specified in an analogous way
to the control points of the patch:

        uvdegree 1
        uv 0 0 1
        uv 1 0 1

Lastly, we specify the Bezier curve which is computed as the image in
three-space of the trimming curve under the map of the patch.  In an
infinite-precision computer, this information would be redundant; in
BOOLE, each surface-surface intersection is approximated with a
seven-dimensional spline, because numerical errors introduced by
mapping the trimming curve into three-space will make it harder to
match up curves in three-space.  The matching-up is necessary for
determining the combinatorial structure of the solid.

    xyzdegree 1
    xyz 4.46 2.10 0.100 1.0
    xyz 2.73 1.10 10.09 1.0

That's it.  Whitespace is ignored by the file parser.  The file writer 
indents the various fields according to the structures and
substructures, for legibility.

BOOLE comes with functions capable of producing files in
this format for various primitive solids; see DOCS/library to find out 
how.

Note that the file format does not enforce the constraint that the
patches form the boundary of a closed solid.  Nor does BOOLE check for 
the validity of the solid.  However, BOOLE depends on this property in 
many different ways, and will most certainly fail if the solid is not
consistent in this way.

BOOLE does, on the other hand, check very carefully that the resulting 
solids it produces are topologically consistent.  If it cannot produce 
a consistent solid, for whatever reason, then it prints an error and
exits.  Such errors are by far the most common, but only because this
is where the most thorough checking is done.

---------------------------------------------------------------------
Please address all feedback concerning BOOLE to geom@cs.unc.edu, with
the word BOOLE in the subject.