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
[email protected]


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.