=== About the .poly file format ===

(originally written early 1993 by Pat Flynn - revised 1/96 PJF)

The .poly files contain three sections: a vertex list, a polygon list, and
a surface list.  The format is a little kinky but easily parsed.
As a matter of fact, the libpolyhedron library contains a YACC/LEX
parser for these files, plus handy macros to access the various pieces of the
polyhedron.

Vertex list:  Each vertex appears on its own line.  The format is
`pnt %d: %f %f %f' .  Points are numbered starting at zero.  There is no
sentinel indicating the end of the  points and the beginning of the
polygons; your program logic can easily detect it.

Polygon list:  Each polygon appears on its own line.  The format is
`poly %d: [%d] %d %d %d .... '
The number on the left of the colon is the index of the polygon (numbered
from zero).  The number inside the [square brackets] is the number of vertices.
The remaining numbers are the indices of the vertices.  The vertices proceed
clockwise around the polygon as you look at it from `outside' the object.

Surface list:  The surface list allows us to logically group polygons.  We
need to group polygons if our object has a curved surface (like a cylinder)
which is fragmented into several approximating polygons.  In the IGES decription
of the object, there is only one surface entity.  We want a corresponding
surface entity in the polygon file as well.

The format for a surface entry is:
`surf %d: [%d] %d'
The first number is the index of the surface (numbered from zero).  The second
number [inside square brackets] is the number of polygons belonging to that
surface.  The third number is the index of the FIRST polygon in the group.
The polygons grouped into a surface must occupy a contiguous sublist
of the polygon list.  While not completely general, this description is
adequate for all my objects, and owes much to the style of the I-deas
universal file.  Note that for polyhedra, each polygon is its own surface.

Here aret a couple of examples.
grnblk3.poly:
pnt 0: 0.000000 0.000000 2.870000
pnt 1: 4.370000 0.000000 2.870000
pnt 2: 0.000000 3.150000 2.870000
pnt 3: 0.000000 0.000000 0.000000
pnt 4: 4.370000 0.000000 0.000000
pnt 5: 0.000000 3.150000 0.000000
pnt 6: 1.650000 1.570000 2.870000
pnt 7: 4.370000 1.570000 2.870000
pnt 8: 1.650000 1.570000 0.000000
pnt 9: 1.650000 3.150000 2.870000
pnt 10: 1.650000 3.150000 0.000000
pnt 11: 3.100000 1.570000 0.000000
poly 0: [4] 8 6 7 11 
poly 1: [4] 6 8 10 9 
poly 2: [6] 0 1 7 6 9 2 
poly 3: [6] 4 3 5 10 8 11 
poly 4: [4] 3 0 2 5 
poly 5: [3] 1 4 7 
poly 6: [4] 3 4 1 0 
poly 7: [4] 2 9 10 5 
poly 8: [3] 4 11 7 
surf 0: [1] 0
surf 1: [1] 1
surf 2: [1] 2
surf 3: [1] 3
surf 4: [1] 4
surf 5: [1] 5
surf 6: [1] 6
surf 7: [1] 7
surf 8: [1] 8

grnblk3 is a polyhedron with 12 vertices (numbered 0 through 11), 9 polygons,
and nine surfaces.  polygon 6 has [4] vertices, namely 3, 4, 1, and 0.
Surface N is polygon N for all N < 9.

taperoll.poly (abbreviated):
pnt 0: 2.500000 0.750000 0.000000
pnt 1: 2.451963 0.750000 -0.487726
... etc etc ...
pnt 520: 1.619866 -0.750000 -1.141018
pnt 521: 1.358544 -0.750000 -1.220594
poly 0: [4] 131 66 128 132 
poly 1: [4] 130 67 131 132 
poly 2: [4] 129 65 130 132 
... etc etc ...
poly 519: [4] 454 36 519 521 
poly 520: [4] 243 121 454 521 
poly 521: [4] 519 123 243 521 
surf 0: [128] 0
surf 1: [128] 128
surf 2: [134] 256
surf 3: [132] 390

The taperoll object has four surfaces, two planar and two cylindrical.
After the list of 522 vertices follows the 522 polygons and four surfaces.
Surface 1 consists of the 128 polygons starting with polygon 0.
Surface two consists of the next 128 surfaces, and so on.
Even though two of the four surfaces of the taperoll are planar, they consist
of many polygons (because they are nonconvex surfaces).

Comments/questions can be directed to Patrick Flynn (flynn@eecs.wsu.edu)