
                  POLYHEDRON DATA FORMAT
   
        PolyData file type 152     Version 2.01 7 Dec 97

The data format contains information of how to draw the polyhedron. 
It allows for more than one polyhedron in the one file, 2 views of each
polyhedron: a planar net and a 3D solid. Most data files have both; since
either may be missing, they both carry the same information about the number
of faces and sides of polygons. Faces are listed in the same order for the
3D solid and its net. The original data files were downloaded from the Internet,
but we found their format cumbersome, so we have modified it, corrected a few
errors and added more planar nets. The original data files are on the World 
Wide Web at URL  http://www.netlib.no/netlib/polyhedra/

The PolyData format has a number of 'fields', each with a descriptor header 
line beginning with a ':' followed by the field name in lower case letters, 
usually followed by counts and other information. Subsequent lines, if any, 
have the data for that field, which is terminated by any of the following:

   - a blank line 
   - the : beginning the next field 
   - the end of the file
   - the last field ':end ' 

The 1st field must begin ':name '

The last field must be   ':end '

Blank lines are ignored only between fields.

Other fields can be in any order. Fields marked with a * are ones which are
not currently used by the program, but may be in later versions.  Some files
may have test data for these * fields but you do not need to make up data 
for these fields if you are making a file for your own new polyhedron.
You need only enter data points to draw the 3D solid, the net can be made
for you by the !PolyNet application.

The fields recognised (listed in alphabetic order) are: 

 :alias    an alternative name for this polyhedron 

 :comment  ASCII characters describing the data, usually ones edited from
           older data files. They may be continued on up to seven
           subsequent lines, which should begin with a space in
           the 1st column.  Comments are limited to 80 characters on a line.

 :compound * defines the planes belonging to each part of the compound,
             for example, a compound of 2 tetrahedra.
           The header line begins with the number of parts, followed by
           one line for each part which gives the number of planes in that 
           part, their plane numbers in the :solidp block and their colour
            
 :dih      the header line contains the number of distinct dihedral angles.
           Each one starts on a new line with a count followed by 2 numbers
           which give the numbers of sides on the 2 polygons of the faces
           followed by the value in radians.

 :dual     the name of the dual polyhedron 
        
 :end      the end of the polyhedron's description. (Must be last line)

 :hinges   the header line contains the number of hinges in the planar
           net. The remaining lines are hinge connections.
           The format is face1 side1 face2 side2 dihedral angle (radians). 
           Sides are numbered from 1. If the dihedral angle is
           greater than pi it is a reflex or re-entrant hinge.

 :name     the polyhedron name, all lower case, < 128 characters long.
           This must be the 1st line of the data, otherwise the format
           will not be recognised when files are dropped on to the icon
           on the icon bar.

 :netf     the header line also contains the number of faces and
           the maximum number of vertices in a face. The remaining
           lines are the faces in the planar net. Each face has a
           vertex count followed by the vertex numbers and a colour index
           (0 to 255). Vertices are listed in clockwise order as viewed from
           inside the polyhedron. Since both the net and the solid have the 
           same number of faces only one face count is stored, the 
           faces of the net and the solid MUST BE LISTED IN THE SAME ORDER 

 :netv     the header line also contains the total number of vertices in 
           the net, followed by the (x,y) co-ordinates for each vertex, 
           one per line, separated by spaces.      
           Implicit vertex numbering starts at 1. 

 :npoly  * number of polyhedra in this file, followed by the number of 
           faces for each polyhedron. :npoly may be omitted if there is
           only one polyhedron.

 :number * the polyhedron netlib index number (0-141), >141 our new ones

 :radius * the radius of the circumscribing sphere, may be only relevant 
           to stellations.

 :sfaces * total number of faces followed by entries for each different kind
           of face giving the number of that type of polygon with the type
           enclosed in {}. For example, the truncated icosahedron is:
              32 12{5} 20{6}

 :solidc * defines the components of a polyhedron (e.g. cuboctahedron which
           has components cube and octahedron ) 
           the header line contains the number of components, the following
           lines (one for each component) have the first and last plane 
           numbers of the component in :solidp and its colour.

 :solidf   the header line contains the number of faces and the maximum
           number of vertices in a face and optionally the true number of
           vertices in the solid (only needed when split faces are used, see
           below). The remaining lines are the faces in the 3D polyhedron.
           Each face has a vertex count followed by the vertex numbers and a
           colour index (0 to 255). When the vertex count is negative, the
           first vertex in the list is the centre of a star, and lines will
           not be joined to it. When a vertex number is negative it means
           that the edge joining it to the next vertex is not a true edge
           but is where a face has been split (see below).
                         Restrictions:
             the vertices must lie in a plane;
             the vertices must be listed in clockwise order as viewed from
              inside the polyhedron;
             for non-convex faces, lines from the first listed vertex
              to any of the others should not cross an edge;
             faces can only meet along edges or at a single vertex.

 :solidp * defines the planes of faces (for compounds and stellations); 
           the header line contains the number of planes, following lines
           ( one per plane) have the number of faces, the face numbers in 
           the :solidf block and their colour.

 :solidv   the header line also contains the total number of vertices in  
           the solid and optionally the true number of vertices for solids
           with split faces (see below). This is followed by lines
           containing the (x,y,z) co-ordinates for each vertex separated by
           spaces. 
           Implicit vertex numbering starts at 1. 

 :space  * defines a solid which completely fills space. The header line also
           contains the number of solids needed to fill space, if this is > 1
           the names of the other solids are also given  

 :stella * this polyhedron is a stellation, followed by the stellation number
           and a reference to the polyhedron of which it is a stellation 

 :svertices * the total number of vertices in the polyhedron, 
           then for each different vertex type 
            - a count of how many of this type, then in () the number
                of sides in the polygon at the vertex 
            - the number of these polygons. 
            - the number of sides of the next kind of polygon 
            - the number of this polygon etc.

 :symbol * two polyhedron descriptions separated by a space:
            the Johnson symbol, and the Schlfli symbol

 :symmetry * lists the numbers of axes of rotational symmetry in this solid
           giving its position for each one; the header line gives the
           number of symmetries following. An axis may pass through
           a vertex, the centre of a face, or the centre of an edge; each
           axis is on a separate line:
           - integer number giving the rotational symmetry of the axis,
               (made negative if the plane perpendicular to the axis
                is a reflection plane);
           - two integers <each 0, 1, 2, 3> if the axis passes through
             <nothing, a face, a vertex, the centre of an edge> for the
             forward and backward directions of the axis;
           - two integers giving (nothing, the face number, the vertex number,
             the vertex numbers of the edge) for the forward direction
           - two similar integers for the backward direction
           - three direction cosines of the forward direction 
           e.g the cube has:
             6 2-fold symmetries about the 12 edges (with reflections)
             4 3-fold symmetries about the 8 vertices
             3 4-fold symmetries about the 6 faces (with reflections)
          :symmetry 13
          -2 3 3 2 4 5 7 -0.707107 0.0 0.707107
          -2 3 3 5 6 3 4 0.707107 -0.707107 0.0
          -2 3 3 2 6 3 7 0.0 -0.707107 0.707107
          -2 3 3 6 8 1 3 0.707107 0.0 0.707107
          -2 3 3 1 5 4 8 0.0 -0.707107 -0.707107
          -2 3 3 1 2 7 8 -0.707107 -0.707107 0.0
          3 2 2 1 0 8 0 -0.57735 -0.57735 -0.57735
          3 2 2 2 0 7 0 -0.57735 -0.57735 0.57735
          3 2 2 3 0 6 0 -0.57735 0.57735 -0.57735
          3 2 2 4 0 5 0 -0.57735 0.57735 0.57735
          -4 1 1 3 0 5 0 -1.0 0.0 0.0
          -4 1 1 2 0 4 0 0.0 0.0 1.0
          -4 1 1 1 0 6 0 0.0 -1.0 0.0

 :type   This field is only needed by !PolyDraw if you want to use the
         'Selection' window to limit the number of polyhedra seen in your
         list of possible polyhedra. It is not used by !PolyNet

         It begins with the letter T, followed immediately by the number of
         polyhedra in this data file. For each one, the number of different
         polygons and number of sides they each have follows, possibly
         followed by letters giving polyhedron type. 
         Example: T1 4,6 4,3  
           means for the 1st polyhedron there are 2 face types, 
              4 hexagons and 4 triangles.

         The type letters may be combined in any order. Some are followed 
         by an integer. Example: W52 
            means the 52nd polyhedron in Wenninger's book

         Note: the letters labelled '--unused' in the list below will cause
         an error if they are used in a 'Polylist' file. A few other letters
         are read, but cannot yet be seen in the 'Selection' window.

         Letter  meaning

          A      Archimedean solid
          B      Archimedean dual
          C      Convex polyhedron
          D      Deltahedron
          E      Space filling solid (e.g. a cube)
          F      --unused
          G      Non-Convex ( non-Hemi )
          H      Hemis  (non-convex with some planes going through its centre)
          I      --unused
          Jnnn   Johnson solid, followed by the integer number nnn
          K      Kepler/Poinsot solids
          L      Several polyhedra in a single file
          M      Compound, multiple polyhedra making a single new one
          N      Anti prism
          O      --unused
          P      Platonic (regular) solid
          Q      Single piece from a dissection
          R      Prism
          S      Stellation of some solid, may be defined in the alias
          Tn a,b type; see above
          U      Uniform polyhedron followed (optionally and immediately)
                 by the Coxeter index of the 75 possible solids
          V      --unused
          Wnnn   Number of the solid in Wenninger's book 'Polyhedron models'
          X      extra solids made by the user
          Y,Z    --unused

          
          Examples: the cube is T1 6,4 W3 P E C U 
              the snub cube is T1 32,3 6,4 A U C W17
 :wythoff The Wythoff symbol for uniform solids.

An example complete data file with the minimum number of fields is:

:name my new cube
:comment designed by me on 22 June 97
:solidf 6 4
4 1 2 3 4 1
4 4 5 6 1 2
4 2 1 6 7 7
4 8 3 2 7 5
4 8 5 4 3 3
4 6 5 8 7 4
:solidv 8
0  0.8 0.58
-0.8 0 0.58
0 -0.8 0.58
0.8 0 0.58
0.8 0 -0.58
0 0.8 -0.58
-0.8 0  -0.58
0 -0.8 -0.58
:end
           
        Split faces.
   These were introduced in !Stellate to allow certain polyhedra with
overlapping faces to be plotted correctly. Some faces are plotted in two
pieces. These faces have two entries in the ':solidf' list each with the
last vertex set negative; e.g. in the :solidf list the square:
 4 1 2 3 4 12
  might become:
 3 1 2 -3 12
 3 3 4 -1 12
  so that it is plotted as two triangles with the diagonal (1 to 3) not
outlined; the result appears as as square.

    If the points of a star face are split, the pieces from each point come
first in the list followed by the remains of the central star. E.g. from the
Inverted snub dodecadodecahedron the indented five-pointed star is:
 4 3 4 5 -6 17
 4 8 9 10 -11 17
 4 13 14 15 -16 17
 4 18 19 20 -21 17
 4 23 24 25 -1 17
 15 1 2 -3 6 7 -8 11 12 -13 16 17 -18 21 22 -23 17
  Before splitting this face had the points 1 to 25.
