**************************************************************************
**************************************************************************
         GEODESIC SHAPE GENERATOR FOR PERSISTENCE OF VISION 3.1x
                               v 2.0
**************************************************************************
**************************************************************************

Created by Uwe Zimmermann, Stockholm, Sweden 1999

1.0  INSTALLATION
2.0  INTRODUCTION
3.0  CREATING GEODESIC SPHERES
4.0  CONTACTING THE AUTHOR
5.0  HISTORY    

**************************************************************************


1.0  INSTALLATION
**************************************************************************
Just copy the POVRay include file "geodesic.inc" into one of the 
directories (folders) in your POVRay library path or the path of 
your POVRay main scene file.  


2.0  INTRODUCTION
**************************************************************************
The macros defined in the include file "geodesic.inc" allow you to
create geodesic spherical objects. These objects consists of a sphere, 
subdivided by triangles as sometimes seen in architectural spheres or 
domes often made as a steel/glas construction. In these cases the faces 
are made of glas supported by a steel framework.

The shapes themselves are build by subdividing the triangular faces 
of one of the three regular polyhedra tetrahedron, octahedron or
icosahedron in smaller triangles. Using a high enough "frequency" of 
subdivisons, the resulting objects appear as spheres with a more or 
less regularly divided surface.

The two main macros defined in the include file "geodesic.inc" use
this subdivision algorithm to produce POVRay scene objects, either
as CSG UNION or triangular MESH:
  
  In case of the CSG UNION the geodesic sphere is assembled by 
  executing user-definable base macros at the location of 
  corners, edges and faces of the shape respectively.
  
  In case of the triangular MESH only a user-definable macro for
  the creation of each single triangular faces is executed.
  
The vertex (i.e. corner) positions are calculated separately from the
creation of either the CSG UNION object and the MESH object. Thus the 
same set of calculated vertices can be used in different geodesical 
objects in the same scene ( different refers to the structuring of
the corners, edges and faces, not to the number or symmetry of the 
vertex points). See the file "geodesic.pov" for examples.
                               
As an addition to the default subdivision of the polyhedron on the
triangular faces of the basic shape, in version 2.0 the 'mode' parameter 
was introduced. By specifying 'mode=1' the planar mode of the old version
is selected, by choosing 'mode=2' the subdivision takes place on the
unit sphere instead, resulting in less divergent trinagular faces of 
the final geodesic shape, especially when a body with tetrahedral
or octahedral geometry is choosen. The difference between both modes 
is neglectible for icosahedron based shapes.

3.0  CREATING GEODESIC SPHERES
**************************************************************************
To create a geodesic sphere object, first the vertex points (or corners)
have to be calculated. This is done by calling the macro 'geodesic', 
defined in the include file "geodesic.inc". This macro returns an array
containing the vertex coordinates for a specific geodesic sphere. The
sphere itself is defined by two parameters:

   - the symmetry of the basic polyhedron  'A'
   - the frequency of subdivision          'freq'
   - the mode of subdivision               'mode'
   
There are three allowed values for the symmetry of the basic polyhedron,
namely

    A = 3   tetrahedron, four   triangular faces
    A = 4   octahedron,  eight  triangular faces   
    A = 5   icosahedron, twenty triangular faces   
    
As the geodesic shape bases on these polyhedra by subdivision and 
projection, using the icosahedron results in the smoothest, most 
evenly spaced structures.

Using the vertex array created by the macro 'geodesic', the final 
POVRay scene object can be created by using either one of the two 
macros                                            

   'geodesic_sphere'    creates a CSG UNION object
   'geodesic_mesh'      creates a triangular mesh
                                                 
The structures returned by these two macros are a geodesic shape
projected onto a POVRay unitsphere ( radius = 1 ). Both macros
return objects that are assembled by funtion calls to primary macros
for the definition of the corner, edge and face objects respectively
( Creating the MESH object only takes advantage of the face defining
sub-macro ). These sub-macros are completely user-definable to 
result in completely customizable final objects. The syntax of the
sub-macros is:

    #macro do_corner( position )                  
      // draw the corner object at vector 'position'
    #end

    #macro do_edge  ( corner_1, corner_2 )
      // draw the edge object between vector 'corner_1' and 'corner_2'
    #end

    #macro do_face  ( corner_1, corner_2, corner_3 )
      // draw the triangular face object with the vectors 'corner_1', 'corner_2' and 'corner_3'
    #end

(See the example file for some definitons). FOr the use of triangles 
( especially smooth_triangles ) on the faces of the figure it is 
nice to know that the corner coordinates given to the 'do_face' macro
are normalized and pointing out from the center (=origin). Also the 
surface normal on these faces ( i.e. the normal at the 
center-of-mass ) points outwards, seen from the origin.
To prevent fatal errors due to not-defined macros, the main macros 
have the ability to use pre-defined dummy macros instead.

/!\ Be careful: Using the MESH creating macro overwrites edge- and 
--- corner defining user macros!
    
As outlined above the process of creation is divided into two parts.
However, the user is responsible to provide both, the calculated
vertex array and the defining parameters 'a' and 'freq' for subsequent
calls to the object creating macros.

EXAMPLE structure:
                             
  #include "geodesic.inc"
                             
  #declare symmetry     = 4;   // use octahedron
  #declare freq         = 5;   // subdivide faces into 5^2=25 triangles                       
  #declare mode         = 2;   // use spherical subdivision
  
  #declare vertex_array = geodesic(symmetry, freq, mode)  // calculate the vertex positions
  
  #macro do_corner(position)
    sphere { position 0.02 texture { pigment { color rgb <1,0,0> } } }
  #end                                                          
  
  #macro do_edge( corner_1, corner_2 )
    cylinder { corner_1, corner_2, 0.02 texture { pigment { color rgb <0,0,1> } } }
  #end
  
  #macro do_face( corner_1, corner_2, corner_3 )
    triangle { corner_1, corner_2, corner_3 texture { pigment { color rgbf <0.4,0.9,0.4,0.8> } } }
  #end
                                                                                            
  object { geodesic_sphere ( symmetry, freq, vertex_array ) scale <2,2,2> translate <2,2,2> }                                                                                               
                                                                        
  #declare mesh_texture = texture { pigment { color rgb <1,1,0> } }                                                                        
  #macro do_face( corner_1, corner_2, corner_3 )
    triangle { corner_1, corner_2, corner_3 texture { mesh_texture } }
  #end

  object { geodesic_mesh ( symmetry, freq, vertex_array ) scale <2,2,2> translate <-2,-2,2> }                                                                                               
                                                                                            

4.0  CONTACTING THE AUTHOR
**************************************************************************
If you wish to contact me with bug reports, bug fixes, criticisms, 
comments, suggested improvements, questions, etc. you can reach me by 
email at:

   uwezi@geocities.com

or by regular mail at:

   Uwe Zimmermann
   Dept. of Electronics
   Royal Institute of Technology
   Electrum 229
   S-16440 Stockholm
   Sweden
 
 
5.0  HISTORY
**************************************************************************

   v2.0 July 1999 After some feedback about "irregularly shaped" faces on
                  some geodesic shapes, the additional paramter "mode" was 
                  introduced, allowing for a more even triangular subdivision
                  performed on the surface of the unit sphere.
                  - call to the macro "geodesic" has become incompatible,
                    the third parameter must be explicitely given. Using 
                    "mode=1" results in 100% compatible shapes to the prior
                    version
                  - intensive bug testing and elimination
                  - minor changes in source code to increase readability  
   
   v1.0 July 1999 First release, inspired by a discussion in the newsgroup
                  "povray.advanced-users" at news.povray.org
                  about "spheres made of triangles"
   
**************************************************************************

POV-Ray(tm) and Persistence of Vision(tm) are registered trademarks of the
POV-Ray Team(tm)
