SMOOTH v2.1 - POV Surface Normal Modeling Program Copyright (c) 1993 - Jeff Burton / Master Tech Enterprises ---USERS GUIDE--- ---------------------------------------------------------------------- 1.0 Introduction ---------------------------------------------------------------------- SMOOTH v2.1 is a utility that reads in raw triangle data, and allows the user to manipulate that data using the various commands available. The major function of SMOOTH v2.1 is to calculate the surface normals for each triangle. This "polygon patch" or "smooth triangle" output can be used with a raytracing program to produce smooth looking surfaces, instead of the flat "faceted" look you get with triangles alone. Consider the difference between a geodesic dome and a smooth sphere, and you'll have the idea. (See SMOOTH.GIF for an example) SMOOTH v2.1 has a variety of special features which can be used with it's internal scene file generator to create "ready-to-render" POV files. SMOOTH v2.1 supports POV version 1.0 and 2.0 and can generate scene files in the new version 2.0 language. can also create bounding boxes for the object described by the triangle data set. Some of the advanced features include: - Bounding Boxes. SMOOTH v2.1 can calculate bounding boxes for the triangle data. Proper use of bounding boxes can reduce the rendering time for complex scenes comprised of many objects. - Studio Lighting. SMOOTH v2.1 allows you to select up to ten modeling lights to create lighting for the "ready-to render" scenes. - Field of View Angle. SMOOTH v2.1 allows you to select the Field of View Angle and calculates the new camera position automatically. - Various Output Formats. SMOOTH v2.1 can output triangle or smooth_triangle data for both POV v1.0 and POV v2.0 as well as 'raw' format. - Aspect Ratio. SMOOTH v2.1 allows the user to enter the aspect ratio of their display device to maintain the image quality. - Seperate File Types. SMOOTH v2.1 can create "ready-to-render" scene files with camera and lighting data. SMOOTH v2.1 can also create include files which contain only the triangle data for inclusion in other POV scenes. All of SMOOTH's options are selected via the command line switches (See Command Line Options) and control the operation of SMOOTH v2.1. ---------------------------------------------------------------------- 2.0 Input Requirements ---------------------------------------------------------------------- The input data should consist of raw triangle data in groups of 9; three numbers (x,y,z) per point, and three points per triangle. The data for each triangle should be included on one line (See example below). There is an option to quickly scan an input file to see if it conforms to SMOOTH's input standards (See -c option). You may also have comments in your raw data file indicated by a line that starts with a ; character. These will be ignored by SMOOTH and not passed to the output. In future versions these will be used to pass commands to SMOOTH. Example of SMOOTH input file: ; This is a comment line and will be ignored by SMOOTH. -1.00 2.00 -3.00 4.00 -5.00 6.00 -7.00 8.00 -9.00 10.00 11.00 12.00 13.00 14.00 15.00 16.00 17.00 18.00 ---------------------------------------------------------------------- 3.0 Command Line Options ---------------------------------------------------------------------- This section describes the command line options and their function. An option may be given in upper or lower case, and is preceeded with a dash, forward slash or backslash. The following is an example of a SMOOTH v2.1 command line: C>smooth -lstudio.dat -s -p1 -b image.raw myimage This line instructs SMOOTH v2.1 to read the 'raw' triangle data in the file IMAGE.RAW and create a "ready-to-render" scene in POV v1.0 format using bounding boxes and the lighting described in the file STUDIO.DAT. The scene file is written to the disk as MYIMAGE.POV. The following describes the function of each of the command line options. 3.1 -p1|p2 : Output Formats Two output formats are available via a command line switch and are listed below: -p1 : POV v1.0 -p2 : POV v2.0 An example of each of these formats is given in the accompanying file SAMPLE.DOC. If no command line format option is specified, the output will be in "raw" form; just the triangles and normals without any other text. 3.2 -c : Check Input File Option Due to the rather strict input requirements (hope to have this fixed in the next version) the -c command line option will scan the input file and make sure it conforms to SMOOTH's input requirements. If SMOOTH cannot read the data file the program will stop and the offending line number of the file will be indicated. For example, entering 'SMOOTH -C TEST.DAT' would produce the following results. SMOOTH v2.1 - POV Surface Normal Modeling Program Copyright (c) 1993 - Jeff Burton / Master Tech Enterprises Scanning the input file for errors. 123 triangles processed. File is OK! SMOOTH indicated that it was able to correctly read the file and would be able to process the triangle data. Remember that the only text allowed in the raw triangle data is comments that start with the character ';'. Any other text will cause truncated or strange results if processed. 3.3 -x : Surface Normal Output Mode Sometimes it is desirable to simply convert the raw triangle data to another format without including the surface normals. Using the -x command line option will "turn off" the output of the surface normal data and create regular triangles instead of smooth triangles. Sample output (POV 1.0 format) without -x command line option: // // Persistance of Vision v1.0 Data File // // Created by SMOOTH v2.1 - POV Surface Normal Modeling Program // Copyright (c) 1993 - Jeff Burton / Master Tech Enterprises // smooth_triangle { < 0.0000 8.8000 0.0000 > < 0.0000 -28.8767 -0.0000 > < 6.3900 6.3800 0.0600 > < -24.0002 -19.5635 -3.5556 > < 4.4800 6.3800 4.5600 > < -14.4201 -19.5469 -19.4753 > } With -x command line option: // // Persistance of Vision v1.0 Data File // // Created by SMOOTH v2.1 - POV Surface Normal Modeling Program // Copyright (c) 1993 - Jeff Burton / Master Tech Enterprises // triangle { < 0.0000 8.8000 0.0000 > < 6.3900 6.3800 0.0600 > < 4.4800 6.3800 4.5600 > } 3.4 -b : Bounding Box Output Some raytracers are capable of surrounding a complex object with a simple shape to reduce the time needed to render the object. When a ray is fired at the scene it checks to see if it has intersected the bounding shape first. If not, then the complex object can be skipped. If it does intersect the bounding shape, then the ray is tested against the complex object in side the box. Since the time to check the ray against the simple shape is much less than checking it against complex objects, a time savings is realized. SMOOTH calculates the coordinates of a box shape that surrounds all the triangles found in the input file. Using the -b command line option allows SMOOTH to include that information in the output file. Due to the way SMOOTH calculates the bounding box coordinates, you may have to enlarge the box a little to eliminate any clipping that may occur. 3.5 -q : Quite Mode Option Normally the program will display a count on the screen as the triangles are read in. Using the -q option turns off the count during processing. This is especially useful if you are redirecting the screen output of SMOOTH to another device such as a printer or disk file. 3.6 infile : Input File Option This is the full pathname of the file containing the raw triangle data. 3.7 outfile[.???] : Output File Option This is the full pathname of the file that will contain the data generated by SMOOTH. If you do not supply an extension, SMOOTH will automatically supply an extension that is appropriate for the output format that you are using. For example, a POV v1.0 scene file would have the extension '.pov', a POV v2.0 include file would have the extension '.inc' and a 'raw' triangle file would have the extension '.raw'. 3.8 -?|h : Brief Usage Instructions Using the -? command line option displays a brief help screen. 3.9 -i|s : Output File Type Option This option allows you to specify which type of output file you would like. The -i option tells SMOOTH v2.1 to create a POV include file. This file has the object declaration and triangle data. If selected, the bounding box data is also included. This file is designed to be used as an include file in another POV scene file, therefore no camera or lighting information is included. Be aware that SMOOTH v2.1 creates one object that contains a union of all the triangles found in the input file. SMOOTH v2.1 declares this object with the name 'Image'. You may later edit the file and change this to whatever you would like. Include files have the extension '.inc'. The -s option performs the same functions as the -i option, but it also includes the camera and lighting information allowing the scene to be rendered immediately without any modifications. Scene files have the extension '.pov'. 3.10 -fxxx : Field of View Angle This option allows the user to enter the Field of View Angle. The field of view angle is used to calculate the position of the camera from the center of the object in the scene. SMOOTH v2.1 uses a method that will always calculate the camera position to keep the object in the center of the scene at a predetermined size. Changing the Field of View Angle doesn't change the size of the object, but it does change the distance of the camera from the object. This can have different effects on the lighting of the object. Note that the input is in degrees, SMOOTH v2.1 calculates the distance parameter required in the camera definition. 3.11 -axxxx : Aspect Ratio SMOOTH v2.1 allows the user to define the "aspect ratio" (height to width ratio) of the resulting image. If you wanted a tall skinny image or a short wide panoramic image or a perfectly square image then you should adjust the aspect ratio. Most computer video modes and graphics printers use perfectly square pixels. For example Macintosh displays and IBM S-VGA modes 640x480, 800x600 and 1024x768 all use square pixels. When your intended viewing method uses square pixels then the aspect ratio should be set properly. Note that 640/480=4/3 (or 1.333) so the ratio is proper for this square pixel mode. 3.12 -o : Object Name SMOOTH v2.1 allows the user to define the name of the object used in the POV scene file. If no name is defined, the default name "Smooth_Object" is used. 3.13 -t : Texture Name SMOOTH v2.1 allows the user to select a texture name for the object in the scene file. If no texture is defined the default texture "Brass_Metal" is used. Since only one object is created, the texture name will be used to describe the entire object. 3.14 -l : Studio Lighting File SMOOTH v2.1 allows the user to select any combination of up to ten light sources to light the object in the scene. If no studio file is used then the default "Camera Flash" lighting is used. Camera Flash lighting places one light source slightly above the camera (simulating the flash on a camera) for lighting the scene. The studio file is a simple ASCII file with ten entries (one for each light source) that describe the characteristics of the light. The first five line entries are for each of the five spotlights and the second five lines are for each of the five modeling lights. An example of a studio file is as follows; White <--- Turn on Spotlight 1 and make the color White Gray50 <--- Turn on Spotlight 2 and make the color Gray50 -off <--- Turn off Spotlight 3 -off <--- Turn off Spotlight 4 -off <--- Turn off Spotlight 5 -off <--- Turn off Modeling Light 1 -off <--- Turn off Modeling Light 2 -off <--- Turn off Modeling Light 3 Gray25 <--- Turn on Modeling Light 4 and make the color Gray25 -off <--- Turn of Modeling Light 5 The position of each light is calculated for each scene and will always appear in the same relative position. See the diagram below for the positions of the lighting; O------------------------------------------------O | \__ Model Light 4 | Model Light 1 ___/ | | | | | | | T | | | H | |----> X | |----> X | E | | | | | | |--Spotlight 4 ctr | |--Spotlight 1 ctr | S | | | C |------------------------O-----------------------| E | | \__ Model/Spot Light 5| N | | | E | Spotlight 3 ctr--| | Spotlight 2 ctr--| | | | | | | | X <------| | X <------| | | | | | __ Model Light 3 | Model Light 2 __ | | / | \ | O------------------------------------------------O In the diagram above the scene is divided into 4 sections. The modeling lights are located in each of the corners with one located in the center. The modeling lights are in the same plane (z-axis) as the camera. The spotlights are located slightly below the modeling lights and "point-at" the center of each section, with exception of spotlight 5 which points at the center of the object. (See PART.TGA for an example scene created using the part.raw data and the studio.dat lighting file.) 3.15 -r : Report File Option Acts the same as the -c command line option, but also creates a report describing the bounding box size and the camera parameters. Use this to check and see if the program will handle the number of triangles in the input file. ---------------------------------------------------------------------- 4.0 Memory Considerations ---------------------------------------------------------------------- This information is from the documentation for the original smoothing routine written by Mike Schoenborn. Sorry, it's impossible to say (simply) exactly how much memory is required to run this program. The memory requirements are determined by the number of triangles and number of points, obviously, but also by how the triangles are arranged, the number of points which are unique, which points belong to which triangles... Consider these two figures... _______ _____________________________________ / \ / \ / \ / \ / \ / / \ / \ / \ / \ / \ / /_______\/________\ / \ / \ / \ / \ /\ / ------------------------------------- \ / \ / \/_______\/ 6 triangles 6 triangles 7 unique points 8 unique points 6 points belong to only 2 tri's 2 points belong to only 1 tri 1 point belongs to 6 tri's 2 points belong to 2 tri's 4 points belong to 3 tri's Since the program doesn't know how the input triangles are going to be arranged, it can't plan ahead of time on how to balance the memory allocation for the triangles, points, and (most awkwardly) the "belongs to" information. I've sent a data set of more than 5000 triangles through and the program had no problem with it. It will definately handle a lot, but you just can't be exact as to how much "a lot" actually is. If it does run out of memory, it will abort with a message saying how much it did handle before choking. If you do run out of memory try to split up the data into multiple groups and process each group seperately. If you go this route, consider the layout of your data and keep in mind that the normals are calculated based on adjoining triangles only. You could split your data, allowing a 1 triangle overlap at the split, process each group, then remove the overlap duplicate data when you recombine the outputs. ---------------------------------------------------------------------- 5.0 Error Messages ---------------------------------------------------------------------- Invalid Field of View Angle The Field of View Angle given is not within the accepted range. If you specify a Field of View Angle that is less than 1 degree or more than 179 degrees this error will occur. No Input Filename Found SMOOTH could not find the filename of the input file in the command line. No Output Filename Found SMOOTH could not find the filename of the output file in the command line. Too Many Filenames Specified SMOOTH found more filenames in the command line than required. ---------------------------------------------------------------------- 6.0 Credit Where Credit is Due! ---------------------------------------------------------------------- The original 'C' source code for the surface normal computations was taken from the program 'SANDPAPER' written by Mike Schoenborn. ---------------------------------------------------------------------- 7.0 Legal Stuff (and its a shame to have to do this!) ---------------------------------------------------------------------- SMOOTH v2.1 is copyrighted freeware, and as such, may be used and distributed without charge to the end user. I still retain all copyrights to the source code with the exception of the public-domain code originally written by Mike Schoenborn. DISTRIBUTION You may freely distribute SMOOTH v2.1 in its original package as long as there is no charge for this service. Distribution centers may distribute the original SMOOTH v2.1 package on disk as long as their is a charge of no more than $5.00 US to the end user. DISCLAIMER This software is provided as is without any guarantees or warranty. Although the authors have attempted to find and correct any bugs in the package, they are not responsible for any damage or losses of any kind caused by the use or misuse of the package. The authors are under no obligation to provide service, corrections, or upgrades to this package. ---------------------------------------------------------------------- 8.0 Contacting the Author ---------------------------------------------------------------------- There is no registration fees or costs associated with SMOOTH. However, I would like to here from you, if you find SMOOTH of value, or even if you consider it a waste of disk space, drop me a postcard. If you would like to send me comments, bug reports, or possible enhancements to SMOOTH you can write me at the following address: Jeff Burton 415 Franklin Street Paducah, KY 42003 You can also leave a message to JEFF BURTON in the RIME Ray Trace Forum. Or you can leave a message to JEFF BURTON at the home of SMOOTH, the Midnight BBS (502) 443-7514 14.4/v.42bis 24hrs. ---------------------------------------------------------------------- 9.0 Revision History ---------------------------------------------------------------------- Changes in SMOOTH v2.1 * Added degenrate triangle input detection. * Added the -o object name switch. * Added the -t texture name switch. Changes in SMOOTH v2.0 * Added the -l studio file option which lets the user manipulate up to ten light sources for the scene. Changes in SMOOTH v1.4 * Added the -i|s switch to allow the user to choose the output file type. * Added the -c and -r switches to (C)heck the input file and (R)eport the parameters of the input file. Changes in SMOOTH v1.3 * Added the -x switch to allow the user to "turn-off" the surface normal smoothing if desired. Changes in SMOOTH v1.2 * Added the -a switch to allow the user to enter the aspect ratio of their display device. * Added the -b switch to create a bounding box for the triangle data. Changes in SMOOTH v1.1 * Changed the output files to include decimal data to six places. On some RAW files with decimal data to six places and very small triangles, 'rounding-off' to four decimal places caused "degenerate triangles" to be created. I haven't seen any RAW files with more than six decimal places, so this should take care of the problem. * Changed the code to close any open files more effectively. In certain rare cases an aborted (ctrl-C) file or an error termination would create an invalid file in the FAT table. This caused no real harm other than it was almost impossible to delete the bad file. * Added the -f switch to enter the Field of View Angle for the camera position routine. * Dropped support for all formats except POV. Since I only work with POV, the 'work-arounds' for the other types were becomming bigger than the actual program.