THE CONTOUR LIBRARY
			    ===================

		 Emilio Camahort - ecamahor@cs.utexas.edu

				 March 1999
			    Updated 9 April 1999

This README file briefly describes the contour library, a library for fast
isocontouring of both unstructured and regular datasets of scalar data. The
interface to the library is designed so that it can be used by both C and
C++ programs. It has no class definitions, but only structure and function
definitions. However, programs in C need to be compiled with the CC compiler
in order to be properly linked to the library. The library is stored in just
two files:

  contour.h	is the header file containing data structure definitions and
		prototype function declarations
  libcontour.a	is the library file containing the object files implementing
		the library functions

The following is a list of the functions available in the library:

  newDatasetUnstr	create a new dataset for unstructured data
  newDatasetReg		create a new dataset for a regular grid of data
  loadDataset		load from a new dataset from disk
  getVariableNames	obtain the variable names for multi-variate data
  getSeedCells		extract seed cells for variable and timestep
  getNumberOfSignatures	compute signature functions for variable and timestep
  getSignatureFunctions	compute signature functions for variable and timestep
  getSignatureValues	obtain signature values for isovalue, variable, etc
  getSlice		extract a dataset slice from a 3D regular grid
  getContour2d		extract a 2d isocontour from a 2D dataset
  getContour3d		extract a 3d isocontour from a 3D dataset
  clearDataset		clear (delete) dataset from memory

A more detailed description can be found in the header file: contour.h .
The library routines are located in the file: libcontour.a  Note that the
interface is similar to the contour client/server system. Only there are
two new constructors that allow creating a new dataset from a arrays of 
data. The parameters to the new constructors are the same as the parameters
located in the header of a .raw dataset file, except for those that can be
computed from the data themselves.

When creating a new dataset, none of the arrays passed as pointers to the
library routines  newDatasetUnstr()  and  newDatasetReg()  are replicated.
Furthermore, for timevarying data the mesh structures are not replicated, 
either. Instead, the same mesh structure is used for all timesteps. An 
important related assumption is that the base mesh does not change over 
time, but only its associated scalar field. This is particularly important
for regular grids, since the contour client/server system allows for dif-
ferent timesteps to contain different amounts of grid data.

The data pointer passed to the newDataset*() library routines points to a
single array that stores all the scalar field data. From slowest to fastest
growing index, the data is stored in the following order:

	1st by timestep
	2nd by variable
	3rd for unstructured meshes:	by vertex
	    for regular grids:		by coordinate z, y, x

That is, the indices vary as follows:

       t0 v0 z0 y0 x0 .... t0 v0 z0 y0 xn, t0 v0 z0 y1 x0, ....
       t0 v0 z0 ym x0 .... t0 v0 z0 ym xn, t0 v0 z1 y0 x0, etc 

Failure to store the data in that order will result in incorrect program
results. 

Storage for all data structures returned by the library routines is allocated
internally by the library. Such data structures should not be deallocated
by the calling program. The routine  clearDataset()  deallocates them once
done with the given dataset.

				------//------