##################################################################
##################################################################
#
# DOCUMENTATION OF THE NATIVE FILE FORMAT
#
# written by Oliver Sander on 12.18.2001
# revision by Oliver Sander on 26.6.2009
# revision by Oliver Sander on 3.5.2013
#
##################################################################
##################################################################

This is a brief text explaining some details about the native
file format for psurface objects.

############################################################
# THE FILE FORMAT
############################################################

Amira saves parametrized surfaces using a subformat of AmiraMesh.
Since the files are usually very large, only the binary AmiraMesh
format is used.  Files can be read and written by using the appropriate
member functions of the Parametrization class.
We'll describe the exact format here:

- The ContentType needs to be 'Parametrization'

- The file contains seven data sections:

  1) 'Patches'
     This section contains information about the different patches
     occuring in the base grid.  Each entry consists of three ints,
     describing the innerRegion material, the outerRegion material,
     and the boundary conditions.

  2) 'BaseGridVertexCoords'
     The coordinates of the base grid vertices.  Simply x, y, and z
     for each vertex.

  3) 'BaseGridTriangles'
     Three ints for each base grid triangle, each giving the index
     of one corner vertex.  Vertex indices are counted starting from
     zero!

  The remaining sections describe the plane graphs on each base grid
  triangle. Each graph is saved as a list of nodes and a list of edges.  
  Since all information about corner nodes can be deduced from the base
  grid vertices, they are never saved and a file-format reader
  has to 'invent' them.  This saves a considerable amount of
  disk-space, especially when storing parametrized surface where
  base grid and image surface have similar resolutions.

  4) 'NumNodesAndParameterEdgesPerTriangle'
     General information on the plane graph on each triangle. For 
     each triangle, there are eight integers specifying
   
       1) The total number of intersection nodes
       2) The total number of touching nodes
       3) The total number of interior nodes

       Note that the number of corner nodes is not saved, since it
       is always equal to three.

       4) The number of edges of the plane graph
       5) The patch number of the triangle

       6-8) For each of the three triangle edges, these three entries
          give the number of graph nodes on the respective edge
          NOT counting the two corner nodes!

  5) 'Nodes'
     This section contains the position information for all nodes on all
     base grid triangles.  For each triangle, first all intersection nodes
     are saved, then all touching nodes and then all interior nodes.  The
     previous sections contains the sizes of the blocks.  For each
     node, five floats are stored containing first the local position in
     barycentric coordinates on the respective triangle and 
     x, y, and z-coordinates of the image position.

  6) 'ParameterEdges'
     All edges of the graphs on all triangles.  Each entry is a tuple of
     two integers storing the indices of the two endnodes of the edge.
     The counting starts anew for each triangle.  The three invented
     corner nodes always have the indices 0, 1, and 2, respectively.

  7) 'EdgePoints'
     For each edge on each triangle, a list of all nodes that are situated
     on that edge.


Good Luck!
