ok, the first step is to build a description of the objects
you are interested in; an Sobj2 or Sobj3 depending on the dimension of the
problem - (lets assume 3D).  The template for doing this is

bgnsobj3();

	spoint3();
	sline3();
	stri3();
	spoly3();
	ssobj3();
	....
	....

s = endsobj3();

bgnsobj3: starts a new object

You then make multiple calls specifying the desired primitives that
make up the object.  All these primitives take a radius r that expands
the object by the given radius (a point becomes a sphere, a line
becomes a cylinder with rounded end caps, etc) and a void* pointer for
attaching user data. The primitives are

spoint3:  add a point to the object
sline3: add a line, rmax is the maximum radius of spheres used to
	cover the object - this does not effect the accuracy of the results
	but determines the balance between comparison of spheres and
	calls to the underlying convex distance algorithm (in this case gilberts
	algorithm).  
stri3: add a triangular polygon. rmax as above.
spoly3: add a convex 2D polygon. rmax as above.
ssobj3: add another sobj3 with a given homogeneous transformation.  This is
	used to build hierarchies of objects (see below).

After specifying all the desired primitives, endsobj3 builds the hierarchical
description of the object and returns a pointer to the sobj3.

After building the objects, use sdist3 to determine the distance
between two objects, after displacing by the given frames.  The
parameter err specifies the relative error in the result.
err should be in the range [0, 1).
The routine returns a Sdist3 structure that includes:
	d:	the distance between the objects.  This value may
		overestimate the distance by up to err*d.  If err is approx
		1 then the value of d is not much use except that d>0 means
		the object are not in contact.  (see the paper).
	p[2]:	points on the objects from which d was determined.
		These points are in the coordinate space of the objects
		as they where built.
	f[2]:	Frames that map the above points into the global coordinate
		system.
	sobj3[2]: When using hierarchical objects, this points to the subobject
		that the points are on.
	prim[2]: the polygonal primitives where used for the computation of d.

	n, npp: number of spherical comparisons and the number of calls
		to the underlying algorithm (gilbert's).

scollide3 is much the same as sdist3 with err set to nearly 1.  There are
a few small optimizations that make this routine preferable is you
are only interested in collision.

scontact3 can be used to find up to n points of contact.

General strategies:
The building objects is relatively time consuming compared to
the distance computation.  Depending on the problem you
are trying to solve there are several strategies

One moving object in a static environment:
	Create an sobj3 for the moving object and one for the environment.
	Call sdist3 repeatably with the frame describing the current
	position and orientation of the moving object.
A few moving objects (say three or four).
	Same as above but now you need n*(n-1)/2 calls to sdist3.
Many moving objects. (Method 1) (determining the distance between each object
	and all the other objects, i.e., n distances)

	Create an sobj3 for each of the rigid bodies.
	For each configuration of the objects
		For each of the objects
			Create a single object that represents the
			union of all the other objects.  This is
			done by using the ssobj3 primitive and is much
			fast than building from the underlying primitives
		
			Call sdist3 for the object and the above union object.

			Free the union object

Many moving objects. (Method 2)
	This is a slight variation of the above that is often faster.
	The idea is, for each configuration of the objects,
	create one union object containing everything, then ignore 
	part of the union object when determining the distance between
	a given object and the union.
	
	Create an sobj3 for each of the rigid bodies.
	For each configuration of the objects
		Create a single object that represents the
		union of all the objects.  This is
		done by using the ssobj3 primitive.  Note that
		ssobj3 returns a pointer to a structure Ssobj3.
		You need to record this pointer for each of the
		objects you add to this union object.

		For each of the objects
				
			set the ignore field in the Ssobj3 structure
			that corresponds to this object.

			call sdist3 for the object and the union object
		
			clear the ignore field in the ssobj3 structure.

		Free the union object