POLY3D - 3d polygonal display program ------------------------------------- BECAUSE POLY3D IS LICENSED FREE OF CHARGE, I PROVIDE ABSOLUTELY NO WARRANTY, TO THE EXTENT PERMITTED BY APPLICABLE STATE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING, I GERSHON ELBER PROVIDE POLY3D PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE POLY3D PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW WILL GERSHON ELBER, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY LOST PROFITS, LOST MONIES, OR OTHER SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR A FAILURE OF THE PROGRAM TO OPERATE WITH PROGRAMS NOT DISTRIBUTED BY GERSHON ELBER) THE PROGRAM, EVEN IF YOU HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, OR FOR ANY CLAIM BY ANY OTHER PARTY. This program reads polygonal text data files and displays them on graphics devices. Format of the text files is briefly explained in the end (appendix A). Options: -------- poly3d [-c] [-m] [-i] [-e #Edges] [-n] [-N] [-o Objects...] [-v ViewFile] [-z] DFiles -c : Closed object - if an object is closed (such as objects created by irit solid medeller) each edge is actually displayed twice - once for each adjacent polygon. This flag will ensure every edge will be displayed only once. -m : More - give some more information on the data file(s) parsed. -i : Internal edges (created by IRIT) - default is not to display them, and this option will force displaying them also. -e n : # Edges to use from each given polygon (default all). Very handy to do '-e 2' on data created from DRAWFN3D. -n : Draw vertices normals if data file has them. -N : Draw polygon normals if data has them (PLANE definition). -o Object(s) : Objects to display (all by default). Object is the name as appears after the OBJECT key word the data files (do 'grep OBJECT datafile'...). -v ViewFile : View file - file of the view matrix transformation -z : Print version number and current defaults. Configuration: -------------- The program can be configured using a configuration file named poly3d.cfg. This is a plain ascii file you can edit directly and set the parameters according to the comments there. executing 'poly3d -z' will show the current configuration as read from the configuration file. This file can be in any directory which is in your path - the same place as poly3d.exe is probably a good choice. MSDOS version only: The program supports VGA/EGA, CGA & HERCULES graphics card, and uses the Turbo C autodetect feature. If this fails you can always coerce it to a specific card - see the poly3d.cfg file. The program will use 80?87 if it detects one - again uses the Turbo C 80?87 autodetect, or will run (much!) slower withoutit... The program will use the mouse, if detected. If this detection fails you can coerce it (to TRUE - exists, or FALSE) in the poly3d.cfg configuration file. Note msdos has different configuration file than unix (poly3dms.cfg). Unix version only: Add the following options to your .Xdefaults. Most are self explanatory. The Trans attributes control the transformation window, while View control the view window. SubWin control the subwindows within the Transformation window. poly3d*Trans*BackGround: CornflowerBlue poly3d*Trans*BorderColor: Red poly3d*Trans*BorderWidth: 3 poly3d*Trans*TextColor: cyan poly3d*Trans*SubWin*BackGround: salmon poly3d*Trans*SubWin*BorderColor: yellow poly3d*Trans*Geometry: =150x500+550+50 poly3d*Trans*CursorColor: green poly3d*View*BackGround: CornflowerBlue poly3d*View*BorderColor: Red poly3d*View*BorderWidth: 3 poly3d*View*Geometry: =500x500+50+50 poly3d*View*CursorColor: green Also note the configuration file is shorter (poly3dun.cfg) Usage: ------ The control of the program is performed by moving the graphical cursor along the menu and performing EXECUTE operation (see below). Moving the cursor can be made using the numerical keypad/arrows (shifted for faster movement) or if mouse is available, using the mouse. Two operation are defined and allowed: EXECUTE - the key on the keyboard, or left mouse button if exists. ABORT - the key on the keyboard, or right mouse button if exists. The EXECUTE operation is used to request performing the selected menu item. The ABORT operation is used to request abortion of current operation (handy for big data files). ALT-Q can be used at any time for program abortion exactly as 'Quit' menu item. Output: ------- Poly3d can save viewing matrix (to be used by poly3d-h or poly3d-r for example), PostScript file of the current view and the msdos version can save gif image of the screen as well (in VGA/EGA and Hercules modes). All files will be named genericX.EXT where EXT can be '.mat', '.ps' and '.gif' respectively. X is single digit so up to 10 distinguished files of each type can be saved each time. Bugs: ----- O.k. if you do have any question, suggestion, or even want to report a bug feel free to send me email (see below) Feel free to make copies of this program, and distribute them FREE of charge, provided that all this package is distributed. I am not going to be responsible for any damage of any kind, that this package may cause (I always wanted to say that...), but I hope you will enjoy it as I did my best you will. At list I enjoyed writing it. Have Fun Gershon Elber gershon@cs.utah.edu Appendix A (Polygonal text file format) - As of IRIT version 2.x: ----------------------------------------------------------------- This appendix defines the polygonal text file as defined to communicate between the various C utilities. Note this format is more strict than old releases and which should be considered obsolete ('.ply' should be regenerated from the '.irt' files). This strictness is mainly related to polygonal normals and vertices order - see POLYGON definition below. Each structure in the text file must be within brackets ( [ ] ), anything outside should be considered comments, while structures can be nested. Keywords: 1. VERTEX - a vertex keyword will always be followed by vertex name and 3 floats defining the xyz coordinates of this vertex. For example: [VERTEX V123 1.0 2.0 3.0]. If VERTEX has NORMAL attribute defined, it will always point INTO the model. 2. POLYGON - a polygon keyword will always be follows by polygon name and list of vertices forming this polygon. The polygon includes the line from last vertex in list to first one. For example: [POLYGON P11 V123 V11 V45 V22] At the time the polygon is defined all vertices in its list should be known (No forward referencing). A POLYGON should order its vertices (if it is a convex polygon) such that cross product of 3 consecutive vertices will point INTO the model. If the POLYGON has PLANE definition, the PLANE definition will point INTO the object as well. 3. POLYLINE - same as POLYGON, but the line from last vertex to first is excluded. 4. POINTLIST - same as POLYGON, but only the vertices are drawn as points (no edges are drawn at all). 5. OBJECT - an object keyword will always be follows by object name and list of polygons forming this object. For example: [OBJECT cube P3 P4 P5 P7] At the time the object is defined all polygons in its list should be known (No forward referencing). Notes: 1. Any number of vertices/polygons/object can be in one file. 2. As the intities above may have attributes (such as colors etc.) an attribute can appear only immediately after the entity name. If more than one attribute should appear, they will appear one after the other. For example: [VERTEX V123 [COLOR ...] [NORMAL ...] 1.0 2.0 3.0]. 3. This definition of the text format is open to extensions, such that a program reading undefined keyword, should ignore and attempt to continue and parse the structure from the point the undefined keyword structure ends. For example if a polygon has new attribute named TEXTURE, the whole TEXTURE structure ( [TEXTURE wood.txt] ) should be skipped: [POLYGON P101 [TEXTURE wood.txt] V1 V3 V44] and should be read as: [POLYGON P101 V1 V3 V44] That includes also new keywords such as [SURFACE ...] (a hint!). A warning that such undefined entity was detected may be proper. 4. No entity should be shared. I.e. although one vertex can belong to few polygons, it should appear for each polygon seperatly. This sharing may be supported, but it is not guaranteed, and discourage. This was done for the sole reason of simplicity. 5. The keyword/entity names are case sensitive: "Cube" and "cube" are two different names. 6. The following atributes are current used: a. [PLANE A B C D] - plane equation of the POLYGON. Normal of the plane equation (A B C) should point INTO the model. b. [NORMAL A B C] - normal of a VERTEX. Should point INTO the model. c. [COLOR C] - Color of the model. C is between 0 and 15 and corresponds to colors in IRIT solid modeler (see irit.cfg for colors). d. [RGB R G B] - Full RGB Color, where each element is in the range of 0..255. e. [INTERNAL] - signals that this edge (from this vertex to the next) has been created internaly and should not be visible usually. Such edge can be created, for example, when a non convex polygon is decomposed in convex ones: The splitting edges are tagged INTERNAL.