                                  LODESTAR

                   Level of Detail Generator for VRML 1.0

                                 Release 1.0

----------------------------------------------------------------------------
 Introduction
----------------------------------------------------------------------------

VRML, the Virtual Reality Modeling Language, is a standard format for 3-D
objects and scenes. Complex 3-D objects easily overload even hardware-
assisted rendering and compromise interactive frame rates needed for VR
applications. To overcome this restriction, objects (usually defined as a
polygonal representation) are stored in multiple levels of detail with
progressively decreasing polygon counts. At runtime, an appropriate level of
detail is selected to obtain the maximum image quality, and avoid overload
of the rendering pipeline.

However, manual creation of levels of detail for complex models is too labor
intensive. Therefore, a tool is needed to generate LODs (levels of detail)
automatically.

We have implemented such a tool that supports VRML. It is able to reduce
indexed face sets (polygonal data) and indexed line sets that embody the
bulk of VRML data commonly found in VRML models. The algorithm is based on
octree quantization of vertices (originally developed for color reduction by
Prof. Michael Gervautz already in 1987).

The tool reads a VRML file and generates LODs for each IndexedFaceSet and
IndexedLineSet. Further the tool removes double defined coordinates,
materials, normals, texture coordinates, faces and lines within the VRML
nodes. The resulting VRML scene will be written into a new file.


----------------------------------------------------------------------------
 Usage & Commandline Options
----------------------------------------------------------------------------


lodestar [options] inputfile

----------------------------------------------------------------------------

   * general options

          (-o | --output) outputfile

               Place the output in file with name outputfile. If you do not
               specify this parameter the program generates an output
               filename by inserting some characters into the input
               filename. By default ".lod" will be inserted before the
               ".wrl" extension, if the option -n is specified ".opt" will
               be inserted and if the option -x is specified the number of
               the LOD to extract will be inserted.

          (-v | --verbose) section['+'section]*

               Causes the program to print out information to stdout. You
               can specify one or more sections separated by '+' (no
               spaces!). The following values are allowed for section:

               coord        information related to Coordinate3 nodes
               material     information related to Material nodes
               normal       information related to Normal nodes
               texcoord     information related to TextureCoordinate2 nodes
               face         information related to IndexedFaceSet nodes
                            including LOD generation
               line         information related to IndexedLineSet node
                            including LOD generation
               join         if the parameter -j is specified, the program
                            tries to join nodes - if this section is
                            specified, information about this process will
                            be printed
               tree         print out a scheme of the VRML node tree
               triangulator information related to the triangulator (used
                            for polygons with more than four vertices)
               default      equal to
                            coord+material+normal+texcoord+face+line
               all          all sections (not recommended)

          (-n | --nolods)

               No Levels of Detail will be generated ! The program only
               removes double defined coordinates, materials, normals,
               texture coordinates, faces and lines and eliminates (some)
               useless nodes with no references.

          (-j | --join)

               The program tries to join nodes.
               e.g. IndexedFaceSet nodes, Coordinate3 nodes, ...
               This is usefull e.g. if an object consists of many many
               IndexedFaceSets with only few faces inside. Without joining
               the LOD-generator can't produce proper LODs and the objects
               tend to get holes. On the other side separate
               IndexedFaceSet nodes have separate LODs with separate ranges
               for switching.

   * lod options

          (-1 | --errorarea) weight

          (-2 | --errorvolume) weight

          (-3 | --weightedmean) weight

               The program uses a weighted mean of three algorithms for
               selecting a representative of some points. With this three
               parameters you can change the default weights. The errorarea
               algorithm tries to minimize the change in the surface area of
               the involved polygons (this is the best algorithm). The
               errorvolume algorithm tries to minimize the volume which is
               calculated as the sum of tetraeders (the base areas are the
               involved faces, the tops are the selected representatives).
               The weightedmean algorithm simply calculates the deviation to
               the weighted mean of the points (the weight is the count of
               points for which a point is already the representative). For
               IndexedLineSet nodes the weightedmean algorithm is always
               used.

          (-c | --cameraheightangle) radian

               This parameter defines the total vertical angle of the
               viewing volume (see VRML-specification: PerspectiveCamera).
               This angle is needed for calculating the ranges of the LODs.
               Unfortunately in VRML this ranges are not independent from
               the camera. If this parameter is not specified, the program
               takes the first perspective camera found in the inputfile. If
               no camera was found, the default camera is taken (height
               angle = pi/4).

          (-e | --errorrange) percentage

               This parameter affects the calculation of the ranges of the
               LODs for switching. With this parameter you can specifiy the
               maximum deferral of the points on screen in percent of the
               height of the viewing window. With a high errorrange value
               LOD switching is performed at lesser distances but the image
               quality is lower.

          (-m | --mindiff) percentage

               The count of the LODs of an IndexedFaceSet or IndexedLineSet
               can't be set directly. You can only specify the minimal
               difference of points between two LODs in percent. This
               doesn't mean that the difference is exactly equal to this
               value - the difference can be much higher. e.g. if LOD n uses
               100 points, LOD n+1 uses a maximum of 80 points.

          (-x | --extract) lod

               Used for extracting a specified LOD. Only LODs with this
               number will be printed. If this parameter is specified the
               program doesn't create VRML LOD nodes only the IndexedFaceSet
               respectively IndexedLineSet node of the specified LOD number
               will be printed. If a node doesn't have a LOD with this
               number (not enough LODs) nothing will be printed. LOD 0 is
               the original data (-x 0 is equivalent to -n ).

          (-l | --nolines)

               While generating LODs faces can collapse into lines. If such
               a line is equal to an egde of a face or the line is equal to
               a line already in the set, the line will be eliminated. For
               each LOD the remainding lines will be witten out into an
               extra IndexedLineSet node. If this parameter is specified all
               lines will be eliminated. Note: this parameter has absolutely
               nothing to do with generating LODs of IndexedLineSet nodes.

          (-q | --noquads)

               Normaly quadrangles will be split into triangles only if they
               are not convex or too much distorted in 3D (see parameter
               -s). If this parameter is specified, quadrangles will always
               be split into two triangles. Polygons with more than four
               vertices will always be split into triangles independent from
               this parameter.

          (-s | --quadsplitangle) radian

               If a quadrangle is too much distorted in 3D it will be split
               into two triangles (see also parameter -q). A quadrangle will
               be split if one of the angles between the normals (calculated
               by the program) of the vertices in opposite side is greater
               than the quadsplitangle. The action will be performed so that
               the angle between the two new triangles is minimal. If this
               parameter is not specified a default value of 0.174533 (10
               degree) will be used.

   * format options

          (-I | --indent) count

               With this option you can set the indention used for
               (sub)nodes and fields. The default indention is 4.

          (-T | --tab) count

               The program uses optimal fill. This means count spaces will
               be replaced by a tab. By default 8 spaces will be replaced by
               one tab. You need this option only if your system
               respectively editor uses an other definition.

          (-N | --noindent)

               No indention of the output is made. This is not equal to
               option -I 0 because the values of fields also won't be
               indented.

          (-D | --decimalcountperline) count

               With this option you can specify the maximum count of integer
               values per line in the outputfile. Per default a count of 8
               is used.

          (-F | --floatcountperline) count

               With this option you can specifiy the maximum count of
               floatingpoint values per line. Per default a count of 6 is
               used.

----------------------------------------------------------------------------
 Default Values
----------------------------------------------------------------------------

If a option is not specified the following default values will be used:

 short name      long name               default value

     -1        --errorarea                  8
     -2        --errorvolume                1
     -3        --weightedmean               0
     -c        --cameraheightangle          0.785398 radian (90 degree)
     -e        --errorrange                 2 %
     -m        --mindiff                   20 %
     -s        --quadsplitangle             0.174533 radian (10 degree)
     -I        --indent                     4
     -T        --tab                        8
     -D        --decimalcountperline        8
     -F        --floatcountperline          6

