------------------------------------------------------------------------
		 QSlim Surface Simplification Package
			     Version 1.0
			   October 1, 1997

		 Michael Garland <garland@cs.cmu.edu>


See <http://www.cs.cmu.edu/~garland/quadrics/> for the latest version
and up-to-date information.

This software is in the public domain and is provided AS IS.
Use it at YOUR OWN RISK.
------------------------------------------------------------------------


This software is UNSUPPORTED.  I've made it freely available, and
you're free to do whatever you want with it.  However, I don't have the
resources to provide any real support for users, so you're more or
less on your own.

This software package is based on experimental software I developed
for my own research purposes.  As such, the code may be a little ugly
in places, and it doesn't have all the features of industrial strength
software.  And there really isn't much documentation; this is about
it.  However, it's proven quite useful to me, and I hope you'll find
it useful as well.

If you use my software for anything more substantial than toying
around, I'd be interested to hear about it.  Any other comments you'd
like to make are also welcome.  And if you find bugs in the software,
please let me know.  Even better, you can send me a patch if you
decide to fix the problem yourself.



SYSTEM OVERVIEW
---------------

This package contains two components, the GFX library and the QSlim
program.  GFX is just my library for holding various bits of handy
code.  QSlim contains all the actual surface simplification code.  For
instructions on building the programs, please read the INSTALL file.

QSlim can be built as both a command-line only 'qslim' program as well
as an interactive 'qvis' program.  The command-line program should
compile on pretty much any Unix system, as well as Windows 95/NT.  The
interactive program requires X11, OpenGL (or MesaGL), and the XForms
library.


FILE FORMAT
-----------

QSlim uses my SMF file format.  This is similar to the Wavefront .OBJ
format.  For our purpuses here, an SMF file contains a sequence of
lines, each of which can one of the following forms:

    # ....
	Comment

    v <x> <y> <z>
	Defines a new vertex.  Vertices are implicitly numbered
	starting from 1 (NOT 0).

    f <v1> <v2> <v3>
	Defines a new triangular face whose corners are the vertices
	identified by the three numbers <v1> <v2> <v3>.  Faces are
	assumed to be listed in counter-clockwise order.

The 'models' directory contains a couple sample models for you to look
at and experiment with.


RUNNING QSLIM
-------------

QSlim is invoked as 'qslim <options> <filename>'.  It will input the
initial model from the given <filename>, and begin simplifying it.
You can specify options to control when simplification terminates and
where the resulting model is sent.

The command line options which QSlim recognizes are:


	-l <file>	Log operations to the given file
	-L [xqcvfdA]	Selects what information to log

				x = contractions,
				q = quadric matrices,
				c = cost of contractions,
				v = vertex annotations,
				f = face annotations,
				d = initial model definition,
				A = all of the above


	-o <file>	Output final model to the given file
	-s <count>	Sets the number of faces at which
			simplification will terminate.
	-e <thresh>	Sets the maximum error tolerance.  This error
			is compared with the error at each vertex as
			defined by the quadric error metric.

	-t <t>		Sets the proximity tolerance for non-edge pair
			selection.  By default, this is 0.  And I
			generally recommend keeping it that way.
	-O <n>		Selects the level of optimization desired in
			the placement of points after pair
			contraction.

				0 = Consider only the endpoints
				1 = Consider the endpoints or midpoint
				2 = Find best position on the line
				    segment connecting the endpoints.
				3 = Find best position in space [default].

	-B <weight>	Enable boundary preservation using the given
			weight.  I've found a weight of 1000 works
			well.
	-m		Attempts to preserve mesh quality.  At this
			point, it just tries to prevent the mesh from
			folding over on itself.
	-a		Enable area weighting of quadrics.

Here's a couple of examples:


    qslim -s 1000 -o cow-1000.smf cow.smf

Produces a 1000 face approximation of the cow and writes it to a file.

    qslim -s 100 -l cow.log -Lxcd cow.smf

Produces a 100 face approximation of the cow and logs the sequence of
contractions performed to a file.  This is essentially a progressive
mesh in reverse.  It defines the initial model and a sequence of edge
contractions to produce the base mesh.

    qslim -s 100 -o slope-100.smf slope.smf

Produces a horrible approximation of the slope surface.  The slope has
an open boundary, and by default, boundary preservation is turned off.

    qslim -s 100 -B1000 -o slope-100.smf slope.smf

This is much better, since boundary preservation has been enabled.


RUNNNING QVIS
-------------

The interactive version of QSlim 'qvis', uses exactly the same command
line options as 'qslim'.  However, it runs in an interactive window.
When it opens, you will see the initial model and a series of
buttons.  To simplify the model, type a target number of faces in the
text box.  Pressing the '1 Step' button will perform the next edge
contraction.  Pressing 'Target' will simplify the model until it
reaches your stated goal, and it will redisplay the current
approximation after each contraction.  Pressing 'Fast!' will also
simplify the model, but it will only redisplay at the end.

In the model window, you can perform the following interactions:


	Left button:	spins the model
	Right button:	moves the camera in and out
	Middle button:	moves the camera in the image plane

	q: Quit
	g: Toggle Gouraud shading
	s: Toggle drawing of the surface
	m: Toggle drawing of the mesh
	p: Toggle pseudo-coloring of surface based on error
	v: Verify information about the current approximation

	e: Toggle drawing of quadrics at each vertex
	E: Toggle drawing of quadrics for each edge
	,: Decrease size of ellipsoids
	.: Increase size of ellipsoids

NOTE: Drawing quadrics can really slow things down on lower-end
machines.  I suggest that you not draw quadrics on anything with more
than around 500 faces, unless you have a pretty high-end graphics
system (like an SGI Maximum Impact).
