CenterStage Object Class:  Polyhedron
Subclass of the Root class

The Polyhedron class is one of the basic classes in CenterStage.  It allows 
you to specify polyhedra by giving the the vertices and faces that make up 
the polyhedron.  You can create lists of vertices, with optional names to 
use as a reference when creating the faces, and lists of faces constructed 
from these vertices, or you can simply give faces as lists of points.  You 
can specify colors and other characteristics on a face-by-face basis, or 
for groups of faces.

The Polyhedron class has two main directives:

    Vertices {vertex list}

	This specifies a list of vertices that you can use to define
	your faces.  This is simply a list of vertices, and you refer
	to them by index (the first index is 0).  Optionally, any
	vertex can be preceded by an identifying name ending in a
	colon.  For example

		Vertices {
		  (1,0,0) (0,1,0) (0,0,1) Origin: (0,0,0)
 		}

	defines four vertices with indices 0, 1, 2, and 3, but the
	final vertex can also be referred to as "Origin".

	The vertices can include formulas, but since the list is a
	space-separated list of points, you should be careful not to
	include spaces within a vertex, or to enclose the vertex
	within braces.

	Before the vertex list is parsed, CenterStage performs
	variable substitution and command evaluation on it, so you can
	compute the vertex list via a procedure if you wish:

		Vertices {[myVertexList]}

		proc myVertexList {} {
		  (compute list here)
		  return $vertices
		}

	Note that the braces around the square brackets are important
	as they postpone the procedure evaluation until the vertex
	list is actually needed.

	You could also use the Setup script to compute the vertex list
	and set the Vertices from a variable:

		Vertices {$vertices}

		Setup {
		  set vertices {}
		  for {set i 0} {$i < 3} {incr i} {
		    let V = [XY $i*$pi/3] * (1,0,1)
		    lappend vertices $V
		  }
		}

	Here, the vertex list is created algorithmically (it consists
	of three different rotations of the vector (1,0,1)).


    Faces {face list}

	The face list, in its simplest form, is a list of pairs of
	indices into the vertex list, or names of vertices in the
	list.  For example, given the points defined above, you would
	specify faces as follow:

		Faces {
		  {Origin 0 1} {Origin 1 2} {Origin 0 2} {0 1 2}
		}

	This generates a tetrahedron using the four vertices.
	
	Note that faces can be made from any number of vertices.  A face 
	that is a single vertex will be shown as a dot, a face made from 
	two vertices will be shown as a line, and other faces will be shown as 
	filled polygons.  For best results, all the vertices of a polygon should 
	be coplanar.

	You can also intermix actual points with the indices and
	names, e.g.:

		Faces {
		  {Origin 0 (-1,0,0)} {1 (0,-1,0)} {(1,1,1) (-1,-1,-1) (1,2,3)}
		}

	Any face can be followed by "<-" and a list of attributes for
	the face, as in

		Faces {
		  {0 1 2} <- {color {1 .5 0} outline}
		}

	or a list of faces can be followed by attributes:

		Faces {
		  {{0 1} {1 2} {2 3}} <- {color {0 0 0}}
		  {{1 2 3} {0 2 3}} <- {outline}
		}

	The attributes include the following:

            solid        polygonal faces should be filled in.
            outline      polygonal faces should be shown as outlines only.
            normalise    the face color should be included in the 
                          color normalization process.
            noadjust     the face color should not be normalized.
            color c      specifies the color for the face: it is either an 
                          index in to the color table or an RGB color 
                          specification.
            vcolors list specifies a list of color indices or RGB values 
                          that should be used for the colors for the 
                          vertices of the face.  The list should have the 
                          same number of colors as the face has vertices.