================================================================================
// File:        Readme.htm
// Summary:     Geodesica SFX Distribution Info.
// Author:      Nicholas Shea
// Copyright:   (c) Nicholas Shea 2005-2018
// Email:       nicholasshea@neolithicsphere.com
// Web:         http://www.neolithicsphere.com/geodesica/index.htm
================================================================================
********************************************************************************
                             IMPORTANT NOTICE
                             
Geodesica-SFX comes in two builds: Geodesica-SFX-Mesa and Geodesica-SFX-OpenGL.
Geodesica-SFX-Mesa uses software rendering rather than hardware rendering.
Consequently, Geodesica-SFX-Mesa is slower than Geodesica-SFX-OpenGL but is
still perfectly usable for frequencies (up to 10V).

Only use Geodesica-SFX-Mesa if Geodesica-SFX-OpenGL does not run on your PC.

ONLY USE DISTRIBUTIONS FROM THE GEODESICA HOME PAGE. BEFORE FILING A BUG REPORT
PLEASE VERIFY THAT THE MD5 SUM OF THE ZIP DISTRIBUTION MATCHES THE ONE GIVEN ON 
THE GEODESICA HOME PAGE. PLEASE ALSO VERIFY THE CHECKSUMS IN 'Checksums.txt'.
********************************************************************************

WHAT IS GEODESICA-SFX?

    Geodesica-SFX is an OpenGL(r) quad-edge Geodesic modelling program that is
    designed to make advanced geodesic construction fun and easy to understand. 
    The program can generate a variety of envelopes for both Primal and Dual,
    whilst advanced cross-target tensegrity spaceframes may be built
    between envelopes (for example, the Union Tank Car Dome spaceframe).

    Lengths, angles, dihedrals, e.t.c., can be measured interactively with
    labels identifying the respective components.

    Unique sets can be generated for struts, hubs and cells, with each set being
    coloured individually. Component connectivity is printed to the Log Window.
    Geodesica can distribute vertices over ellipsoidal envelopes using a pseudo-
    magnetic field where field strength is governed by a bezier curve.

    Geodesica was inspired by the work of Franz Dischinger and Buckminster
    Fuller; the program was originally written as my own accompaniment to the 
    book entitled 'Geodesic Math and How To Use It' by Hugh Kenner.

    My intention is to make Geodesica a quality product that implements sound
    numeric methods, with a consistent interface and clear documentation. I hope
    one day to build a life size dome using Geodesica. Until that time the
    program remains untested (by me) in real world applications.

    Geodesica-SFX requires registration to:
    
    1. Export files.
    2. Draw hubs plans (for ring flange and star flange hubs).
    3. Enable full logging functions.

    Geodesica-SFX is the commercial fork of 'Geodesica' which can still be 
    obtained on sourceforge. Geodesica-SFX is NOT open source. Geodesica-SFX can 
    only be downloaded from the Geodesica home page at:

    http://www.neolithicsphere.com/geodesica/index.htm
    
    Geodesica-SFX is programmed in C++ using a modified version of the
    WildMagic(r) 3 graphics engine; the UI was built with the FLTK toolkit.
    Geodesica runs on UNIX(r)/Linux(r) (X11), Microsoft(r) Windows(r).
    Both Linux and Windows versions are 32 bit.

    
INSTALLING AND RUNNING GEODESICA UNDER MICROSOFT WINDOWS

    Unarchive the zip to your chosen directory. Geodesica does not touch the
    Windows registry. The expanded folder should look something like this:
    
       Geodesica
          Data              [folder]
          Export-Tests      [folder]
          ScreenShots       [folder]
          UnitTest-Output   [folder]
          Geodesica.exe     [program binary]
          
    Do not rename any of the folders or mix old Data folders with new ones.
    
    IMPORTANT: If using a version of Windows later than XP, Geodesica must be
    run in 'Compatability Mode' for Windows XP (Service pack 3). Right-click
    on the program icon and choose 'Properties'. Use the following settings:

png


    
    Click 'Apply' then 'OK'.
    Launch Geodesica by double clicking the program icon.

    Please ensure that you have read/write access to the installation directory 
    as Geodesica-SFX must be able to write its logs and preferences.

    Geodesica-SFX has been tested on Windows-XP 32 bit and Windows 7 64 bit.
    If Geodesica-SFX does not run on your machine an e-mail would be
    appreciated.

  
QUICK START

      MOUSE
      
      LEFT MOUSE BUTTON
      -----------------
      Select, Analyse or Modify, depending on the Pick mode. Set the pick mode
      on the toolbar. There are three tabs corresponding to each mode. Each
      mode has a sub-mode. For example, on the 'Select' tab there are buttons
      for single item selection and group selection. The other buttons on the
      'Select' tab determine what gets picked, i.e., Vetices, Edges, Cells, etc.
      
      Measured dimensions are displayed in the log window.
      
      Click an object to select, click again to deselect.
      Passive highlighting can be turned off in the Select menu.
      
      MIDDLE MOUSE BUTTON
      -------------------
      Click and drag for Trackball rotation.
      
      RIGHT MOUSE BUTTON
      ------------------
      Click in a viewport to change the camera.
      Hold down ALT key and right-click on vertex or hub for a context menu.
      

      NOTE: 
      There are 36 different viewport configurations ranging from a single port
      up to 6. The more viewports that are open, the slower the app will run.
      Select a viewport configuration from the View menu.

      All data pertaining to a camera can be changed in the Navigator window.
      Choose menu Window->Navigator. Expand the Navigator window by clicking on
      the small arrows at the bottom left. There are three levels of expansion,
      for Location, Orientation and Fustrums.
      
 
 GENERAL OVERVIEW
        
       The Modify tab on the Toolbar has eight options for changing the geometry
       of a primal lattice:
       
       1. Make Edge.
       2. Kill Edge.
       3. Kill Vertex.
       4. Collapse Edge.
       5. Divide Edge.
       6. Truncate Vertex.
       7. Split & Bevel.
       8. Stellate.
       
       The modelling tools have not been stress tested, but if the program 
       detects an illegal operation, it will warn the user.
       
       IMPORTANT: If you see a Topology Warning message, take heed.
       
       Random deletion tests succeed in removing vertices in 12V spheres until
       only a few remain, and the program correctly handles each case. However,
       the program will eventually crash if the sphere isn't closed. This will
       happen if you delete a vertex or edge that 'splits' the sphere in half,
       or if you create an "island" of edges that are not connected to the
       surrounding manifold. In this instance the lattice can no longer be
       traversed by the Quad-Edge operators. Checks have been put in place to
       try and ensure this does not happen.
       
       In most cases, Geodesica will label the offending vertex with appropriate
       instructions. You can then use the modelling tools to rememedy the
       situation. If all else fails, please rebuid the sphere by changing the
       subdivision frequency.
       
       NOTE: Editing the Primal model when 'Generate Dual' is ON may be slow on
       legacy CPU's. And even slower if 'Generate Space Frame' is on also. It is
       best to edit the Primal with 'Generate Dual' OFF.
       -------------------------------------------------------------------------
       
 2. EXPORT

         Wavefron OBJ
         DXF 14 ascii
         
       Only visible cells are exported.
         
   2a. DXF ascii export notes.
       Cells are trifanned and grouped as layers with the following options:
        
       1. Layer cells by parent group.
       2. Layer cells by parent lattice.
       3. Layer cells individually.
        
       User is informed if the layers required exceed 20. They usually do.
        
       When cells are layered individually...
       The cell trifan layer prefix is 'CT_' followed by the cell count
        
       Cell skeletons are always layered per cell.
       The cell skeleton layer prefix is 'CS_' followed by the cell count.
        
       Cell spaceframe struts are always layered per cell.
       A spaceframe strut layer prefix is 'SS_' followed by the cell count.
        
       Only visible cells are exported.
        
       Currently there is only support for creating cell trifans with DXF.
       Whilst this increases the triangle count for coplanar cells with 3 or
       4 vertices, subdividing a geodesic cell around its centroid is more
       useful than using an arbitrary perimeter vertex.
        
       As trifans are created during DXF export, user must ensure that cell
       perimeters form 'convex' polygons as in Fig A.
         
                       A                B
                     _____            ____
                    /     \          |    |
                   /       \         |    |
                   \       /        /   __|
                    \_____/        /   |__
                                  /_______|
        
       Trifans are formed around the cell centroid, so the cell in Fig B. will
       not export as a trifan.
        
       The DXF file currently omits HEADER, TABLES, BLOCKS, and LAYERS.
       According to the AutoCAD DXF reference manual, the following is allowed:
        
       The entire HEADER section can be omitted if header variables are not set.
       The TABLES section can be omitted if nothing in it is required.
       The BLOCKS section can be omitted if no block definitions are used.
       Layers can be referenced within the ENTITIES section.
       
       -------------------------------------------------------------------------
       
 3. SELECTIONS
       The menus 'Select->All' and 'Select->None' operate according to the
       current Pick Mode. If the 'Pick Vertices' button is on, then all vertices 
       get selected / deselected. If the 'Pick Cells' button is on, then all 
       cells get selected / deselected etc.
       
       -------------------------------------------------------------------------
       
 4. PICKING
       You cannot pick invisible elements. So to pick vertices, for example,
       the 'Pick Vertices' button must be ON in the 'Select' tab, and vertices
       must be visible in the 'Attributes' window.
       
       Use the toggle buttons 'P', 'D' & 'S' on toolbar to set the pick
       target - Primal, Dual or Spaceframe. When you change to the MODIFY tab,
       the pick target is the Primal only.
       
       Picking Caveats
       ---------------
       1. Pick mode 'Vertex' when Faces are visible.
       If faces are visible on the Attributes window and the pick mode is
       'Vertex', you can only pick vertices where the pick ray intersects with a
       visble face. In other words, if some faces are hidden so revealing the
       underlying manifold, you cannot pick vertices of that manifold without
       first turning off Show Faces in the Attributes window.
       
       2. Pick mode 'Edge' when Faces are visible.
       If faces are visible on the Attributes window and the pick mode is
       'Edge', you can only pick edges where the pick ray intersects with a
       visble face. In other words, if some faces are hidden so revealing the
       underlying manifold, you cannot pick edges of that manifold without
       first turning off Show Edges in the Attributes window.
       
       3. If both Targets A and B are coincident (id est, they have the same
       frequency, breakdown, class and envelopes), the Pick Manager will have
       trouble selecting concident strut and hub meshes of the same type and
       dimension. This should not be an issue as the whole purpose of the
       Target mechanism is to set different envelope extents for each Target.
       However, if for some reason you have a need for coincident Targets, hide
       one Target with the 'Target' menu, then you can then safely pick the
       other.
       
       A Picking Example
       -----------------
       The spherical coordinates of a picked vertex are displayed in the
       VERTEX EDITOR on the toolbar. You can modify Phi, Theta or Radius by
       editing the field(s) and pressing return. This works for multiple vertex
       selections. For example, you can create an egg shape by setting the
       PRIMAL ENVELOPE to an 'Ellipse profile' with an expansion in Y of 1.5.
       You can then switch to FRONT view by right clicking in the OpenGL view
       and choosing the front camera. Use the AREA-SELECT tool on the toolbar to
       select all PRIMAL vertices below Theta = 90 (negative Y values).
       Then enter 1.0 in Radius field of the VERTEX EDITOR and press return.
       Be sure to use the menu Select->None afterwards.
       If the DUAL ENVELOPE 'Project' option is OFF, the dual will follow the
       same egg profile as the PRIMAL.
       
       When picking elements, it is preferable to set one PICK TARGET only
       (Primal or Dual, but not both), otherwise confusion may result using
       high frequencies: you might think you've picked an element on the PRIMAL
       hull, when in fact you've picked the DUAL. Note: the hierarchy of the
       picked element is also displayed on the VERTEX EDITOR.
       
       Be careful picking Vertices or Edges in QuadEdge mode when Facets are
       invisible; if the pick ray does not find an element on the front of the
       sphere, it will travel between Edges and pick elements on the rear
       interior of the sphere. This is a feature, not a bug.
       -------------------------------------------------------------------------
       
 5. MEASURING

       You can log cell dimensions / angles  strut dimensions / axial angles /
       dihedral angles etc. Please note that results have not been extensively
       verified but match data in 'Geodesic Math and How to Use It' by
       Hugh Kenner. Please consult the file 'Verifying-Output.txt' for details.
       
       When measuring angles/lengths at a vertex, please make sure that Vertices
       are visible. The button for the corresponding lattice must be down in the
       Attributes window. You cannot pick an invisible vertex. This helps if you
       only want to select Dual vertices or vice-versa.
       
       IMPORTANT: Before reading off your measurements in the Log Window, please
       consult 'ACCURACY' below.
       -------------------------------------------------------------------------
       
 6. ACCURACY
       The program appears to be accurate and great lengths have been undertaken
       to maintain floating point accuarcy, especially when converting between
       spherical and cartesian coordinates and when projecting to envelopes.
       However, output has only been tested on models and not in a real world
       applications. Please see the page 'Verifying Output' on the website.
       
       It is best to model a dome with a unit radius (or expansion in Y thereof)
       and then scale the unit radius to the desired dimension. This is done
       using the 'Units' tab which is located on the 'Precision and Units' tab
       of the Preferences Window.
       
       Scaling the unit radius is far more accurate than making the dome
       life-size by changing the envelope extents. The larger the envelope, the
       greater the probability of errors in projected rays. A ray might only be
       0.0000001 degrees off true, but by the time it intersects with a large
       envelope, the error becomes appreciable. This is rather like plotting a
       course that is, say, 0.2 degrees off: by the time you've flown 20 miles,
       the error is great.
       
       You can set the working units to anything you like: feet, meters, inches,
       yards etc, and then optionaly convert the logged result to any other
       unit. Then when you measure a length, the log will print something like:
       
        <----------------------------------------------------->
              LINEAR DISTANCE BETWEEN TWO POINTS
          Scale Factor = 3.0000000000
          Units = Meters and Inches
           Radius    A =  3.0000000000 Meters, or 118.1102362200 Inches.
           Radius    B =  3.0000000000 Meters, or 118.1102362200 Inches.
           Distance AB =  3.1543866727 Meters, or 124.1884516812 Inches.
           Central angle = 63.4349488
                = 063 26' 5.8156800"
        <----------------------------------------------------->
       
       Imperial units are currently represented as decimals. This will be fixed
       in a future release, when I can find a font that represents fractions. In
       the meantime, if you are working in Feet, you can view decimal inches and
       their equivalent fractions by printing up a 'Decimal Inches Table', which
       is accessedin the Log Window's menu.
       
       It will be interesting to see what difference using MPFR makes to the
       accuracy of modelling life size domes. Depending on available memory and
       processor power, it is possible to work with high target precisions of
       thirty or more decimal places. However, MPFR is currently only implmented
       for the Utilities.
       -------------------------------------------------------------------------
       
 7. ATTRIBUTES
 
       Colours and morphs may be applied to single cells or cell groups. Group
       attributes are persistent when a sphere is re-built but individual cell
       attributes are lost.
      
       Changes in applied colours are not visible until objects are de-selected.
      
       The application tries to follow the convention of "Select then effect"
       but this behaviour needs refining.
       
       Example 1
       To colour edges, choose the Group Select tool and click on an edge. The
       edges turn red to show they are selected. Change their colour using the
       colour-well in the Attributes window. Click the edges again to delesect
       them, or choose 'Select->None'. Alternatively, us the 'SELECT ALL' toggle
       on the Attributes window.
       
       Drawing Round points
       If you have problems drawing round points with your graphics card
       (The selected vertex goes black, for example), then please un-check this
       option. The round poiints checkbox only activates with the 'Group' select
       tool.
       -------------------------------------------------------------------------
       
 8. THETA DISTRIBUTION CURVE
       Changing my code to use a scene graph has slowed this down. Nevertheless,
       it is still usable and makes an interesting experiment on distributing
       vertices on ellipsoidal envelopes when standard Root-E correction fails
       to give desired results.
       -------------------------------------------------------------------------
            
 9. VERIFYING OUTPUT

       Please consult the file 'Verifying-Output.txt' which describes how to use
       the measuring tools, how to change envelope profiles, and how to log dome
       data to the Log Window. The principal source for verifying output was the
       classic publication 'GEODESIC MATH AND HOW TO USE IT' By Hugh Kenner.
       -------------------------------------------------------------------------
     
      
LICENSING

    Geodesica-SFX is NOT open source and is the commercial fork of 'Geodesica'.
    You can still download the open source version 'Geodesica' from the
    SourceForge server. I regret that help cannot be provided with compilation
    as the program links to a modified version of WildMagic 3.


ON-LINE DOCUMENTATION
    
    http://www.neolithicsphere.com/geodesica/index.htm

    
SUPPORT

    Documentation will be uploaded as the program develops. Please be sure to
    read the file 'Development-Status.txt' for any new features/changes.


TRADEMARKS

    Microsoft and Windows are registered trademarks of Microsoft
    Corporation. UNIX is a registered trademark of the X/Open
    Group, Inc.  OpenGL is a registered trademark of Silicon
    Graphics, Inc.  MacOS is a registered trademark of Apple
    Computers, Inc.


COPYRIGHT

    Geodesica is copyright 2005-2018 by Nicholas Shea
    Geodesica-SFX is copyright 2005-2018 by Nicholas Shea   
    
    
DISCLAIMER OF WARRANTY AND LIMITATION OF LIABILITY.

 Geodesica is distributed in the hope that it will be useful, but WITHOUT ANY
 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
 FOR A PARTICULAR PURPOSE. Balazar Geodesics shall not be liable for any loss
 of profits, loss of business, loss of information, personal injury, indirect,
 special, incidental or consequential damages, expressly or not set forth
 herein incurred before, during or after the use of Geodesica. Any liability
 of Balazar Geodesics will be limited exclusively to bug fixes or program
 replacement. Except as set forth above, no other warranties, either express
 or implied, including the warranties or conditions of merchantability and
 fitness for a particular purpose are applicable to this product or any of
 the other products which are created by Balazar Geodesics.