home *** CD-ROM | disk | FTP | other *** search
/ X-Ray / X-Ray.iso / gfx-soft / imagine-stuff / cleanupslice.lha / CleanupSlice.doc next >
Text File  |  1995-10-05  |  6KB  |  160 lines
  1. Docs for CleanupSlice (cs) program, ©1995 by Milan Pollé
  2. Please read the whole thing before starting.
  3.  
  4. SHORT
  5.  
  6. CleanupSlice - cleans up sliced Imagine3.x TDDD objects
  7.  
  8. INTRODUCTION
  9.  
  10. Imagine's slice function is a very powerful tool for modeling
  11. all sorts of objects. The only major drawback it has is that 
  12. the objects resulting from a slice are often a bit messy.
  13. Most of the times sliced objects have too many points, edges
  14. and faces. This is a result of the fact that edges which only
  15. exist to make triangular faces (edges making no angle with
  16. connected faces) also participate in a slice.
  17. I like slicing a lot, but cleaning up objects after a slice
  18. is quite tedious and mistakes are often made, resulting in
  19. damaged objects. This is why I decided to make a small 
  20. utilitity that would clean up the objects for me, in a safe
  21. way.
  22.  
  23. WHY
  24.  
  25. Not only will cleaned up objects be smaller in point, edge,
  26. face and byte count, they will also look better with phong
  27. shading, as the surplus edges (that mess up the phong 
  28. algorithm) are removed. Also the probability of a next
  29. succesful slice will be greater.
  30.  
  31. FEATURES
  32.  
  33. CleanupSlice will remove points, edges and faces within user
  34. specified boundaries. It will only remove points that are on
  35. edges of surfaces, because that is where the points resulting
  36. from a slice are. The user can specify boundaries for point-
  37. edge distances, angles between connected faces and point to
  38. point distances (for no mercy merging, see below). The user
  39. can also specify a savename-suffix for trying different
  40. parameter settings on the same object. CleanupSlice will also
  41. remove some bug-points which only have one edge, but no faces
  42. connected to them.
  43.  
  44. USAGE
  45.  
  46. cs [d=max point-edge distance] [a=Max face-face angle]
  47.    [m=Max merging distance] [s=Savename suffix] Filename
  48.  
  49. CleanupSlice is executed from the shell, with parameters 
  50. describing cleanup boundaries. Just enter cs or cs ? for a
  51. usage description.
  52.  
  53. Parameters are: (NO SPACES AROUND THE '=' PLEASE)
  54.  
  55. d=max point edge distance (in Imagine units)
  56.  
  57.    For every point on the edge of a surface, cs checks the
  58.    distance between that point and the (imaginary) edge
  59.    between its connected points. If the distance is lower
  60.    than the value specified in parameter d, the tested
  61.    point is joined with one of the two connected points.
  62.    A higher value of d, means more points, edges and faces
  63.    will be removed and more object detail will be lost.
  64.  
  65. a=max face-face angle (in degrees)
  66.  
  67.    Before removing a point, cs will check the angle between
  68.    the normal vectors of the connected faces against parameter
  69.    a. If the angle is lower than the angle specified with a,
  70.    the point will be removed (joined).
  71.    A higher value of a also means more points etc. will be
  72.    removed, and some detail will be lost, as sharper edges will
  73.    be removed. 
  74.  
  75. m=max merging distance (in Imagine units)
  76.  
  77.    This is what I call no mercy merging. I noticed that a slice
  78.    will often leave many points very closely together. With an
  79.    m parameter greater than 0, cs will check distances between
  80.    connected points and if less than specified by m, points will
  81.    be merged regardless of any other parameters.
  82.    A higher value means points farther away from each other will
  83.    be removed and object detail will be lost.
  84.  
  85. s=savename suffix
  86.  
  87.    This is an extension that will be added to the given objectname
  88.    to be used a a savename. This will ensure that the original
  89.    object will not be overwritten. Another way is to save the sliced
  90.    object under a certain name (something short :)and overwrite it.
  91.    This way works faster as you don't have to enter a new loadname
  92.    in imagine.
  93.  
  94. Examples:
  95.  
  96. cs x
  97.  
  98. Will clean up an object named x, using default parameters (which
  99. might not be perfect for this object) and save it as x.
  100.  
  101. REMEMBER YOU CAN ALWAYS ABORT WITH CTRL-C BEFORE THE PROGRAM IS 
  102. FINISHED AND NO HARM WILL BE DONE.
  103.  
  104. cs d=1.2 x
  105.  
  106. Will load an Imagine object named x, clean it up with a maximum of
  107. 1.2 imagine units for the point edge distance, with all other 
  108. parameters at default presets. After that, the object is saved as x.
  109.  
  110. cs d=1.02 m=0 a=.5 s=clean ram:slice1.obj
  111.  
  112. Will load the object slice1.obj from ram: clean it up with max
  113. point-edge distance of 1.02 and max face-face angle of 0.5.
  114. No merging will be done. After cleaning up the object is saved
  115. to ram: as slice1.objclean.
  116.  
  117. During cleanup, cs will display information on its progress,
  118. of how many points, edges and faces the object consists and
  119. how many are removed. If you don't like this, you can enter
  120. >nil: after cs (I don't mind, really :)
  121.  
  122. OBJECT FORMAT: IMPORTANT!!!
  123.  
  124. THE OBJECTS TO BE CLEANED UP MUST BE FRESHLY SLICED; NO EXTRA
  125. ATTRIBUTES LIKE SHARP/QUICK EDGES ETC. MUST EXIST.
  126. OTHERWHISE THE RESULTING OBJECT WILL BE MANGLED!
  127.  
  128. OBJECTS FROM IMAGINE 2.X OR EARLIER WILL PROBABLY NOT WORK.
  129.  
  130. You could probably use the strip object function to clean up
  131. the object if it already has some attributes.
  132. Also, cs will work on objects as well as entire slice-groups.
  133. When operating on groups it will process every object in the
  134. group automatically. But you could make a slice, delete any
  135. unwanted objects and cleanup the rest.
  136.  
  137. LEGAL STUFF
  138.  
  139. This program is freeware.
  140. Distribute it freely, without making a profit, making sure 
  141. this document is with the program. I am not responsible if 
  142. you mess up your objects with this program.
  143.  
  144. FEEDBACK, FUTURE AND BUGS
  145.  
  146. This program is not at all perfect in that it's algorithm
  147. could probably be more efficient (faster). And it would be
  148. possible to make it handle objects with sharp edges etc.
  149. Any future versions depend upon you, finding bugs, having
  150. neat ideas or generally showing enough interest.
  151. Hope you like it, let me know what you think.
  152.  
  153. Mail me at: 
  154.  milan@bmt.hku.nl
  155.  
  156. If that doesn't work try: 
  157.  milan@valkieser.nl
  158.  
  159. Milan Pollé, October 1995
  160.