home *** CD-ROM | disk | FTP | other *** search
/ Current Shareware 1994 January / SHAR194.ISO / graphuti / smooth10.zip / SMOOTH.DOC < prev    next >
Text File  |  1993-10-13  |  11KB  |  271 lines
  1.  
  2.                SMOOTH v1.0 - Surface Normal Smoothing Program
  3.          Copyright (c) 1993 - Jeff Burton / Master Tech Enterprises
  4.  
  5.  
  6.                              ---USERS GUIDE---
  7.  
  8.  
  9.  
  10. 1.0   Introduction
  11.  
  12. SMOOTH is a utility that reads in raw triangle data, and calculates the
  13. surface normals for each triangle.  This "polygon patch" or "smooth
  14. triangle" output can be used with a raytracing program to produce smooth
  15. looking surfaces, instead of the flat "faceted" look you get with triangles
  16. alone.  Consider the difference between a geodesic dome and a smooth
  17. sphere, and you'll have the idea.
  18.  
  19. SMOOTH can also create the code necessary for bounding boxes.  Proper use
  20. of bounding boxes can reduce the rendering time for complex scenes
  21. comprised of many objects.
  22.  
  23. 2.0   Input Requirements
  24.  
  25. The input data should consist of raw triangle data in groups of 9; three
  26. numbers (x,y,z) per point, and three points per triangle. The data for each
  27. triangle should be included on one line (See example below). There is an
  28. option to quickly scan an input file to see if it conforms to SMOOTH's
  29. input standards (See -c option). You may also have comments in your raw
  30. data file indicated by a line that starts with a ; character.  These will
  31. be ignored by SMOOTH and not passed to the output.  In future versions
  32. these will be used to pass commands to SMOOTH.
  33.  
  34. Example of SMOOTH input file:
  35.  
  36. ; This is a comment line and will be ignored by SMOOTH.
  37. -1.00 2.00 -3.00 4.00 -5.00 6.00 -7.00 8.00 -9.00
  38. 10.00 11.00 12.00 13.00 14.00 15.00 16.00 17.00 18.00
  39.  
  40.  
  41. 3.0   Command Line Options
  42.  
  43. This section describes the command line options and their function. An
  44. option may be given in upper or lower case, and is preceeded with a dash,
  45. forward slash or backslash.  Options may be grouped, as in "-rq".
  46.  
  47. 3.1   -n|o|v|d|r|s|t|p : Output Formats
  48.  
  49. Several output formats are available via a command line switch and are
  50. listed below:
  51.  
  52.         -n : NFF (MTV)
  53.         -o : Vivid v1.0
  54.         -v : Vivid v2.0
  55.         -d : DKBTrace (STAR)
  56.         -r : Rayshade
  57.         -s : POV v0.5
  58.         -t : POV v1.0
  59.         -p : POV v2.0
  60.  
  61. An example of each of these formats is given in the accompanying file
  62. SAMPLE.DOC. If no command line format option is specified, the output will
  63. be in "raw" form; just the triangles and normals without any other text.
  64. Not all the advanced features are available in every format. Check the
  65. individual options to see if a particular format is supported.
  66.  
  67. (Note: "SMOOTH_TRIANGLES" in the current (2.10) version of DKBTrace don't
  68. work.  It's not this program, honest).
  69.  
  70. 3.2   -c : Check Input File Option
  71.  
  72. Due to the rather strict input requirements (hope to have this fixed in the
  73. next version) the -c command line option will scan the input file and make
  74. sure it conforms to SMOOTH's input requirements. If SMOOTH cannot read the
  75. data file the program will stop and the offending line number of the file
  76. will be indicated. For example, entering 'SMOOTH -C TEST.DAT' would produce
  77. the following results.
  78.  
  79. SMOOTH v1.0 - Surface Normal Smoothing Program
  80. Copyright (c) 1993 - Jeff Burton / Master Tech Enterprises
  81.  
  82. Reading the triangle data in test.dat
  83.  
  84. Scanning the input file for errors.
  85.  
  86. 123 triangles processed.  File is OK!
  87.  
  88. SMOOTH indicated that it was able to correctly read the file and would be
  89. able to process the triangle data.  Remember that the only text allowed in
  90. the raw triangle data is comments that start with the character ';'. Any
  91. other text will cause truncated or strange results if processed.
  92.  
  93. 3.3   -x : Surface Normal Output Mode
  94.  
  95. Sometimes it is desirable to simply convert the raw triangle data to
  96. another format without including the surface normals.  Using the -x command
  97. line option will "turn off" the output of the surface normal data and
  98. create regular triangles instead of smooth triangles.  This feature is only
  99. available in the following formats:
  100.  
  101.         DKBTrace (STAR)
  102.         POV v0.5
  103.         POV v1.0
  104.         POV v2.0
  105.  
  106. Sample output (POV 1.0 format):
  107.  
  108. Without -x command line option:
  109.  
  110. //
  111. // Persistance of Vision v1.0 Data File
  112. //
  113. // Created by SMOOTH v1.0 - Surface Normal Smoothing Program
  114. // Copyright (c) 1993 - Jeff Burton / Master Tech Enterprises
  115. //
  116.  
  117. smooth_triangle { 
  118. <  0.0000  8.8000  0.0000 > <  0.0000 -28.8767 -0.0000 >
  119. <  6.3900  6.3800  0.0600 > < -24.0002 -19.5635 -3.5556 >
  120. <  4.4800  6.3800  4.5600 > < -14.4201 -19.5469 -19.4753 >
  121.  }
  122.  
  123. With -x command line option:
  124.  
  125. //
  126. // Persistance of Vision v1.0 Data File
  127. //
  128. // Created by SMOOTH v1.0 - Surface Normal Smoothing Program
  129. // Copyright (c) 1993 - Jeff Burton / Master Tech Enterprises
  130. //
  131.  
  132. triangle { 
  133. <  0.0000  8.8000  0.0000 > 
  134. <  6.3900  6.3800  0.0600 > 
  135. <  4.4800  6.3800  4.5600 > 
  136.  }
  137.  
  138. 3.4   -b : Bounding Box Output
  139.  
  140. Some raytracers are capable of surrounding a complex object with a simple
  141. shape to reduce the time needed to render the object.  When a ray is fired
  142. at the scene it checks to see if it has intersected the bounding shape
  143. first.  If not, then the complex object can be skipped.  If it does
  144. intersect the bounding shape, then the ray is tested against the complex
  145. object in side the box.  Since the time to check the ray against the simple
  146. shape is much less than checking it against complex objects, a time savings
  147. is realized.
  148.  
  149. SMOOTH calculates the coordinates of a box shape that surrounds all the
  150. triangles found in the input file.  Using the -b command line option allows
  151. SMOOTH to include that information in the output file. SMOOTH includes this
  152. infomation in the comments at the beginning of the output file.  Due to the
  153. way SMOOTH calculates the bounding box coordinates, you may have to enlarge
  154. the box a little to eliminate any clipping that may occur.  This option
  155. only works on POV v1.0 and POV v2.0 output formats.
  156.  
  157. 3.5   -q : Quite Mode Option
  158.  
  159. Normally the program will display a count on the screen as the triangles
  160. are read in.  Using the -q option turns off the count during processing.
  161. This is especially useful if you are redirecting the screen output of
  162. SMOOTH to another device such as a printer or disk file.
  163.  
  164. 3.6   infile : Input File Option
  165.  
  166. This is the full pathname of the file containing the raw triangle data.
  167.  
  168. 3.7   outfile[.???] : Output File Option
  169.  
  170. This is the full pathname of the file that will contain the data generated
  171. by SMOOTH.  If you do not supply an extension, SMOOTH will automatically
  172. supply an extension that is appropriate for the output format that you are
  173. using.  For example, a POV v1.0 output file would have the extension
  174. '.pov', a DKB output file would have the extension '.dat' and a Vivid
  175. output file would have the extension '.v  '.
  176.  
  177. 3.8   -?|h : Brief Usage Instructions
  178.  
  179. Using the -? command line option displays a brief help screen.
  180.  
  181. 4.0   Memory Considerations
  182.  
  183. This information is from the documentation for the original smoothing
  184. routine written by Mike Schoenborn.
  185.  
  186. Sorry, it's impossible to say (simply) exactly how much memory is required
  187. to run this program.  The memory requirements are determined by the number of
  188. triangles and number of points, obviously, but also by how the triangles are
  189. arranged, the number of points which are unique, which points belong to which
  190. triangles...
  191.  
  192. Consider these two figures...
  193.            _______                  _____________________________________
  194.          / \     / \               / \         / \         / \         /
  195.        /    \   /    \           /     \     /     \     /     \     /
  196.      /_______\/________\       /         \ /         \ /         \ /
  197.      \       /\       /       -------------------------------------
  198.        \    /   \    /      
  199.          \/_______\/        
  200.  
  201. 6 triangles                             6 triangles
  202. 7 unique points                         8 unique points
  203. 6 points belong to only 2 tri's         2 points belong to only 1 tri
  204. 1 point belongs to 6 tri's              2 points belong to 2 tri's
  205.                                         4 points belong to 3 tri's
  206.  
  207. Since the program doesn't know how the input triangles are going to be
  208. arranged, it can't plan ahead of time on how to balance the memory
  209. allocation for the triangles, points, and (most awkwardly) the "belongs to"
  210. information.
  211.  
  212. I've sent a data set of more than 5000 triangles through and the program
  213. had no problem with it.  It will definately handle a lot, but you just
  214. can't be exact as to how much "a lot" actually is.  If it does run out of
  215. memory, it will abort with a message saying how much it did handle before
  216. choking.
  217.  
  218. If you do run out of memory try to split up the data into multiple groups
  219. and process each group seperately.  If you go this route, consider the
  220. layout of your data and keep in mind that the normals are calculated based
  221. on adjoining triangles only. You could split your data, allowing a 1
  222. triangle overlap at the split, process each group, then remove the overlap
  223. duplicate data when you recombine the outputs.
  224.  
  225. 5.0   Credit Where Credit is Due!
  226.  
  227. The original 'C' source code for the surface normal computations was taken
  228. from the program 'SANDPAPER' written by Mike Schoenborn.  The Vivid 1.0,
  229. 2.0 and POV v0.5 output formats were later added by Stephen Coy.
  230.  
  231. Many thanks to these people who created some of the code that went into
  232. SMOOTH v1.0.
  233.  
  234. 6.0   Legal Stuff (and its a shame to have to do this!)
  235.  
  236. SMOOTH is copyrighted freeware, and as such, may be used and distributed
  237. without charge to the end user.  I still retain all copyrights to the
  238. source code with the exception of the public-domain code originally written
  239. by Mike Schoenborn and Stephen Coy.
  240.  
  241.                                 DISTRIBUTION
  242.  
  243. You may freely distribute SMOOTH in its original package as long as there
  244. is no charge for this service.  Distribution centers may distribute the
  245. original SMOOTH package on disk as long as their is a charge of no more
  246. than $5.00 US to the end user.
  247.  
  248.                                  DISCLAIMER
  249.  
  250. This software is provided as is without any guarantees or warranty.  
  251. Although the authors have attempted to find and correct any bugs in the 
  252. package, they are not responsible for any damage or losses of any kind 
  253. caused by the use or misuse of the package. The authors are under no 
  254. obligation to provide service, corrections, or upgrades to this package.
  255.  
  256. 7.0   Contacting the Author
  257.  
  258. If you would like to send me comments, bug reports, or possible
  259. enhancements to SMOOTH you can write me at the following address:
  260.  
  261.                                 Jeff Burton
  262.                             415 Franklin Street
  263.                              Paducah, KY 42003
  264.  
  265. You can also leave a message to JEFF BURTON in the RIME Ray Trace Forum.
  266.  
  267. Or you can leave a message to JEFF BURTON at the home of SMOOTH, the
  268. Midnight BBS (502) 443-7514 14.4/v.42bis 24hrs.
  269.  
  270.  
  271.