Docs for CleanupSlice (cs) program, ©1995 by Milan Pollé
Please read the whole thing before starting.

SHORT

CleanupSlice - cleans up sliced Imagine3.x TDDD objects

INTRODUCTION

Imagine's slice function is a very powerful tool for modeling
all sorts of objects. The only major drawback it has is that 
the objects resulting from a slice are often a bit messy.
Most of the times sliced objects have too many points, edges
and faces. This is a result of the fact that edges which only
exist to make triangular faces (edges making no angle with
connected faces) also participate in a slice.
I like slicing a lot, but cleaning up objects after a slice
is quite tedious and mistakes are often made, resulting in
damaged objects. This is why I decided to make a small 
utilitity that would clean up the objects for me, in a safe
way.

WHY

Not only will cleaned up objects be smaller in point, edge,
face and byte count, they will also look better with phong
shading, as the surplus edges (that mess up the phong 
algorithm) are removed. Also the probability of a next
succesful slice will be greater.

FEATURES

CleanupSlice will remove points, edges and faces within user
specified boundaries. It will only remove points that are on
edges of surfaces, because that is where the points resulting
from a slice are. The user can specify boundaries for point-
edge distances, angles between connected faces and point to
point distances (for no mercy merging, see below). The user
can also specify a savename-suffix for trying different
parameter settings on the same object. CleanupSlice will also
remove some bug-points which only have one edge, but no faces
connected to them.

USAGE

cs [d=max point-edge distance] [a=Max face-face angle]
   [m=Max merging distance] [s=Savename suffix] Filename

CleanupSlice is executed from the shell, with parameters 
describing cleanup boundaries. Just enter cs or cs ? for a
usage description.

Parameters are: (NO SPACES AROUND THE '=' PLEASE)

d=max point edge distance (in Imagine units)

   For every point on the edge of a surface, cs checks the
   distance between that point and the (imaginary) edge
   between its connected points. If the distance is lower
   than the value specified in parameter d, the tested
   point is joined with one of the two connected points.
   A higher value of d, means more points, edges and faces
   will be removed and more object detail will be lost.

a=max face-face angle (in degrees)

   Before removing a point, cs will check the angle between
   the normal vectors of the connected faces against parameter
   a. If the angle is lower than the angle specified with a,
   the point will be removed (joined).
   A higher value of a also means more points etc. will be
   removed, and some detail will be lost, as sharper edges will
   be removed. 

m=max merging distance (in Imagine units)

   This is what I call no mercy merging. I noticed that a slice
   will often leave many points very closely together. With an
   m parameter greater than 0, cs will check distances between
   connected points and if less than specified by m, points will
   be merged regardless of any other parameters.
   A higher value means points farther away from each other will
   be removed and object detail will be lost.

s=savename suffix

   This is an extension that will be added to the given objectname
   to be used a a savename. This will ensure that the original
   object will not be overwritten. Another way is to save the sliced
   object under a certain name (something short :)and overwrite it.
   This way works faster as you don't have to enter a new loadname
   in imagine.

Examples:

cs x

Will clean up an object named x, using default parameters (which
might not be perfect for this object) and save it as x.

REMEMBER YOU CAN ALWAYS ABORT WITH CTRL-C BEFORE THE PROGRAM IS 
FINISHED AND NO HARM WILL BE DONE.

cs d=1.2 x

Will load an Imagine object named x, clean it up with a maximum of
1.2 imagine units for the point edge distance, with all other 
parameters at default presets. After that, the object is saved as x.

cs d=1.02 m=0 a=.5 s=clean ram:slice1.obj

Will load the object slice1.obj from ram: clean it up with max
point-edge distance of 1.02 and max face-face angle of 0.5.
No merging will be done. After cleaning up the object is saved
to ram: as slice1.objclean.

During cleanup, cs will display information on its progress,
of how many points, edges and faces the object consists and
how many are removed. If you don't like this, you can enter
>nil: after cs (I don't mind, really :)

OBJECT FORMAT: IMPORTANT!!!

THE OBJECTS TO BE CLEANED UP MUST BE FRESHLY SLICED; NO EXTRA
ATTRIBUTES LIKE SHARP/QUICK EDGES ETC. MUST EXIST.
OTHERWHISE THE RESULTING OBJECT WILL BE MANGLED!

OBJECTS FROM IMAGINE 2.X OR EARLIER WILL PROBABLY NOT WORK.

You could probably use the strip object function to clean up
the object if it already has some attributes.
Also, cs will work on objects as well as entire slice-groups.
When operating on groups it will process every object in the
group automatically. But you could make a slice, delete any
unwanted objects and cleanup the rest.

LEGAL STUFF

This program is freeware.
Distribute it freely, without making a profit, making sure 
this document is with the program. I am not responsible if 
you mess up your objects with this program.

FEEDBACK, FUTURE AND BUGS

This program is not at all perfect in that it's algorithm
could probably be more efficient (faster). And it would be
possible to make it handle objects with sharp edges etc.
Any future versions depend upon you, finding bugs, having
neat ideas or generally showing enough interest.
Hope you like it, let me know what you think.

Mail me at: 
 milan@bmt.hku.nl

If that doesn't work try: 
 milan@valkieser.nl

Milan Pollé, October 1995